Rime buffer management
[The Rime communication stack]

The packetbuf module does Rime's buffer management. More...

Files
file	packetbuf.c
	Rime buffer (packetbuf) management.
file	packetbuf.h
	Header file for the Rime buffer (packetbuf) management.
Defines
#define	PACKETBUF_SIZE   128
	The size of the packetbuf, in bytes.
#define	PACKETBUF_HDR_SIZE   48
	The size of the packetbuf header, in bytes.
Functions
void	packetbuf_clear (void)
	Clear and reset the packetbuf.
void	packetbuf_clear_hdr (void)
	Clear and reset the header of the packetbuf.
int	packetbuf_copyfrom (const void *from, uint16_t len)
	Copy from external data into the packetbuf.
void	packetbuf_compact (void)
	Compact the packetbuf.
int	packetbuf_copyto_hdr (uint8_t *to)
	Copy the header portion of the packetbuf to an external buffer.
int	packetbuf_copyto (void *to)
	Copy the entire packetbuf to an external buffer.
int	packetbuf_hdralloc (int size)
	Extend the header of the packetbuf, for outbound packets.
int	packetbuf_hdrreduce (int size)
	Reduce the header in the packetbuf, for incoming packets.
void	packetbuf_set_datalen (uint16_t len)
	Set the length of the data in the packetbuf.
void *	packetbuf_dataptr (void)
	Get a pointer to the data in the packetbuf.
void *	packetbuf_hdrptr (void)
	Get a pointer to the header in the packetbuf, for outbound packets.
void	packetbuf_reference (void *ptr, uint16_t len)
	Point the packetbuf to external data.
int	packetbuf_is_reference (void)
	Check if the packetbuf references external data.
void *	packetbuf_reference_ptr (void)
	Get a pointer to external data referenced by the packetbuf.
uint16_t	packetbuf_datalen (void)
	Get the length of the data in the packetbuf.
uint8_t	packetbuf_hdrlen (void)
	Get the length of the header in the packetbuf, for outbound packets.
uint16_t	packetbuf_totlen (void)
	Get the total length of the header and data in the packetbuf.

---

Detailed Description

The packetbuf module does Rime's buffer management.

---

Function Documentation

void packetbuf_clear

(

void

)

Clear and reset the packetbuf.

This function clears the packetbuf and resets all internal state pointers (header size, header pointer, external data pointer). It is used before preparing a packet in the packetbuf.

Examples:

example-collect.c.

void packetbuf_clear_hdr

(

void

)

Clear and reset the header of the packetbuf.

This function clears the header of the packetbuf and resets all the internal state pointers pertaining to the header (header size, header pointer, but not external data pointer). It is used before after sending a packet in the packetbuf, to be able to reuse the packet buffer for a later retransmission.

void packetbuf_compact

(

void

)

Compact the packetbuf.

This function compacts the packetbuf by copying the data portion of the packetbuf so that becomes consecutive to the header. It also copies external data that has previously been referenced with packetbuf_reference() into the packetbuf.

This function is called by the Rime code before a packet is to be sent by a device driver. This assures that the entire packet is consecutive in memory.

int packetbuf_copyfrom	(	const void *	from,
		uint16_t	len
	)

Copy from external data into the packetbuf.

Parameters:

	from	A pointer to the data from which to copy
	len	The size of the data to copy

Return values:

The

number of bytes that was copied into the packetbuf

This function copies data from a pointer into the packetbuf. If the data that is to be copied is larger than the packetbuf, only the data that fits in the packetbuf is copied. The number of bytes that could be copied into the rimbuf is returned.

Examples:

example-broadcast.c, example-mesh.c, example-multihop.c, example-runicast.c, example-trickle.c, and example-unicast.c.

int packetbuf_copyto

(

void *

to

)

Copy the entire packetbuf to an external buffer.

Parameters:

to

A pointer to the buffer to which the data is to be copied

Return values:

The

number of bytes that was copied to the external buffer

This function copies the packetbuf to an external buffer. Both the data portion and the header portion of the packetbuf is copied. If the packetbuf referenced external data (referenced with packetbuf_reference()) the external data is copied.

The external buffer to which the packetbuf is to be copied must be able to accomodate at least (PACKETBUF_SIZE + PACKETBUF_HDR_SIZE) bytes. The number of bytes that was copied to the external buffer is returned.

int packetbuf_copyto_hdr

(

uint8_t *

to

)

Copy the header portion of the packetbuf to an external buffer.

Parameters:

to

A pointer to the buffer to which the data is to be copied

Return values:

The

number of bytes that was copied to the external buffer

This function copies the header portion of the packetbuf to an external buffer.

The external buffer to which the packetbuf is to be copied must be able to accomodate at least PACKETBUF_HDR_SIZE bytes. The number of bytes that was copied to the external buffer is returned.

uint16_t packetbuf_datalen

(

void

)

Get the length of the data in the packetbuf.

Returns:

Length of the data in the packetbuf

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to get the length of the data in the packetbuf. The data is stored in the packetbuf and accessed via the packetbuf_dataptr() function.

For incoming packets, both the packet header and the packet data is stored in the data portion of the packetbuf. This function is then used to get the total length of the packet - both header and data.

Examples:

example-collect.c, and example-mesh.c.

Referenced by sicslowmac_dataRequest().

void * packetbuf_dataptr

(

void

)

Get a pointer to the data in the packetbuf.

Returns:

Pointer to the packetbuf data

This function is used to get a pointer to the data in the packetbuf. The data is either stored in the packetbuf, or referenced to an external location.

For outbound packets, the packetbuf consists of two parts: header and data. The header is accessed with the packetbuf_hdrptr() function.

For incoming packets, both the packet header and the packet data is stored in the data portion of the packetbuf. Thus this function is used to get a pointer to the header for incoming packets.

Examples:

example-broadcast.c, example-collect.c, example-mesh.c, example-multihop.c, and example-trickle.c.

Referenced by sicslowmac_dataRequest().

int packetbuf_hdralloc

(

int

size

)

Extend the header of the packetbuf, for outbound packets.

Parameters:

size

The number of bytes the header should be extended

Return values:

Non-zero

if the header could be extended, zero otherwise

This function is used to allocate extra space in the header portion in the packetbuf, when preparing outbound packets for transmission. If the function is unable to allocate sufficient header space, the function returns zero and does not allocate anything.

uint8_t packetbuf_hdrlen

(

void

)

Get the length of the header in the packetbuf, for outbound packets.

Returns:

Length of the header in the packetbuf

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to get the length of the header in the packetbuf. The header is stored in the packetbuf and accessed via the packetbuf_hdrptr() function.

void * packetbuf_hdrptr

(

void

)

Get a pointer to the header in the packetbuf, for outbound packets.

Returns:

Pointer to the packetbuf header

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to get a pointer to the header in the packetbuf. The header is stored in the packetbuf.

int packetbuf_hdrreduce

(

int

size

)

Reduce the header in the packetbuf, for incoming packets.

Parameters:

size

The number of bytes the header should be reduced

Return values:

Non-zero

if the header could be reduced, zero otherwise

This function is used to remove the first part of the header in the packetbuf, when processing incoming packets. If the function is unable to remove the requested amount of header space, the function returns zero and does not allocate anything.

int packetbuf_is_reference

(

void

)

Check if the packetbuf references external data.

Return values:

Non-zero

if the packetbuf references external data, zero otherwise.

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to check if the packetbuf points to external data that has previously been referenced with packetbuf_reference().

void packetbuf_reference	(	void *	ptr,
		uint16_t	len
	)

Point the packetbuf to external data.

Parameters:

	ptr	A pointer to the external data
	len	The length of the external data

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to make the packetbuf point to external data. The function also specifies the length of the external data that the packetbuf references.

void * packetbuf_reference_ptr

(

void

)

Get a pointer to external data referenced by the packetbuf.

Return values:

A

pointer to the external data

For outbound packets, the packetbuf consists of two parts: header and data. The data may point to external data that has previously been referenced with packetbuf_reference(). This function is used to get a pointer to the external data.

void packetbuf_set_datalen

(

uint16_t

len

)

Set the length of the data in the packetbuf.

Parameters:

len

The length of the data

For outbound packets, the packetbuf consists of two parts: header and data. This function is used to set the length of the data in the packetbuf.

Examples:

example-collect.c.

uint16_t packetbuf_totlen

(

void

)

Get the total length of the header and data in the packetbuf.

Returns:

Length of data and header in the packetbuf