The friendly Operating System for the Internet of Things

A global network packet buffer. More...

Detailed Description

Note
WARNING!! Do not store data structures that are not packed (defined with __attribute__((packed))) or enforce alignment in in any way in here if GNRC_PKTBUF_SIZE > 0. On some RISC architectures this will lead to alignment problems and can potentially result in segmentation/hard faults and other unexpected behaviour.

Modules

 Packet
 Network packet abstraction type and helper functions.
 

Files

file  pktbuf.h
 Interface definition for the global network buffer.
 

Macros

#define GNRC_PKTBUF_SIZE   (6144)
 Maximum size of the static packet buffer. More...
 

Functions

void gnrc_pktbuf_init (void)
 Initializes packet buffer module.
 
gnrc_pktsnip_tgnrc_pktbuf_add (gnrc_pktsnip_t *next, void *data, size_t size, gnrc_nettype_t type)
 Adds a new gnrc_pktsnip_t and its packet to the packet buffer. More...
 
gnrc_pktsnip_tgnrc_pktbuf_mark (gnrc_pktsnip_t *pkt, size_t size, gnrc_nettype_t type)
 Marks the first size bytes in a received packet with a new packet snip that is appended to the packet. More...
 
int gnrc_pktbuf_realloc_data (gnrc_pktsnip_t *pkt, size_t size)
 Reallocates gnrc_pktsnip_t::data of pkt in the packet buffer, without changing the content. More...
 
void gnrc_pktbuf_hold (gnrc_pktsnip_t *pkt, unsigned int num)
 Increases gnrc_pktsnip_t::users of pkt atomically. More...
 
void gnrc_pktbuf_release_error (gnrc_pktsnip_t *pkt, uint32_t err)
 Decreases gnrc_pktsnip_t::users of pkt atomically and removes it if it reaches 0 and reports a possible error through an error code, if Error reporting is included. More...
 
static void gnrc_pktbuf_release (gnrc_pktsnip_t *pkt)
 Decreases gnrc_pktsnip_t::users of pkt atomically and removes it if it reaches 0 and reports GNRC_NETERR_SUCCESS. More...
 
gnrc_pktsnip_tgnrc_pktbuf_start_write (gnrc_pktsnip_t *pkt)
 Must be called once before there is a write operation in a thread. More...
 
gnrc_pktsnip_tgnrc_pktbuf_get_iovec (gnrc_pktsnip_t *pkt, size_t *len)
 Create a IOVEC representation of the packet pointed to by pkt More...
 
gnrc_pktsnip_tgnrc_pktbuf_remove_snip (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
 Deletes a snip from a packet and the packet buffer. More...
 
gnrc_pktsnip_tgnrc_pktbuf_replace_snip (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *old, gnrc_pktsnip_t *add)
 Replace a snip from a packet and the packet buffer by another snip. More...
 
gnrc_pktsnip_tgnrc_pktbuf_duplicate_upto (gnrc_pktsnip_t *pkt, gnrc_nettype_t type)
 Duplicates pktsnip chain upto (including) a snip with the given type as a continuous snip. More...
 
void gnrc_pktbuf_stats (void)
 Prints some statistics about the packet buffer to stdout. More...
 
bool gnrc_pktbuf_is_empty (void)
 Checks if packet buffer is empty. More...
 
bool gnrc_pktbuf_is_sane (void)
 Checks if the implementation's internal invariants still uphold. More...
 

Macro Definition Documentation

#define GNRC_PKTBUF_SIZE   (6144)

The rational here is to have at least space for 4 full-MTU IPv6 packages (2 incoming, 2 outgoing; 2 * 2 * 1280 B = 5 KiB) + Meta-Data (roughly estimated to 1 KiB; might be smaller). If GNRC_PKTBUF_SIZE is 0 the packet buffer will use dynamic memory management to allocate packets.

Definition at line 58 of file pktbuf.h.

Function Documentation

gnrc_pktsnip_t* gnrc_pktbuf_add ( gnrc_pktsnip_t next,
void *  data,
size_t  size,
gnrc_nettype_t  type 
)
Warning
Do not change the fields of the gnrc_pktsnip_t created by this function externally. This will most likely create memory leaks or not allowed memory access.
Precondition
size < GNRC_PKTBUF_SIZE
Parameters
[in]nextNext gnrc_pktsnip_t in the packet. Leave NULL if you want to create a new packet.
[in]dataData of the new gnrc_pktsnip_t. If data is NULL no data will be inserted into result.
[in]sizeLength of data. If this value is 0 the gnrc_pktsnip::data field of the newly created snip will be NULL.
[in]typeProtocol type of the gnrc_pktsnip_t.
Returns
Pointer to the packet part that represents the new gnrc_pktsnip_t.
NULL, if no space is left in the packet buffer.
gnrc_pktsnip_t* gnrc_pktbuf_duplicate_upto ( gnrc_pktsnip_t pkt,
gnrc_nettype_t  type 
)

Example: Input: buffer +------------------------—+ +---—+ | size = 8 | data +-----—>| | | type = NETTYPE_IPV6_EXT |---------—+ +---—+ +------------------------—+ . . | next . . v . . +------------------------—+ +---—+ | size = 40 | data +--------—>| | | type = NETTYPE_IPV6 |------—+ +---—+ +------------------------—+ . . | next . . v +------------------------—+ +---—+ | size = 14 | data +-----------—>| | | type = NETTYPE_NETIF |---—+ +---—+ +------------------------—+ . .

         Output:
                                                             buffer
         +---------------------------+                      +------+
         | size = 48                 | data       +-------->|      |
         | type = NETTYPE_IPV6       |------------+         |      |
         +---------------------------+                      |      |
               |                                            +------+
               |                                            .      .
               | next                                       .      .
               v
         +---------------------------+                      +------+
         | size = 14                 | data +-------------->|      |
         | type = NETTYPE_NETIF      |------+               +------+
         +---------------------------+                      .      .

   The original snip is keeped as is except `users` decremented.
Parameters
[in,out]pktThe snip to duplicate.
[in]typeThe type of snip to stop duplication.
Returns
The duplicated snip, if succeeded.
NULL, if no space is left in the packet buffer.
gnrc_pktsnip_t* gnrc_pktbuf_get_iovec ( gnrc_pktsnip_t pkt,
size_t *  len 
)
Precondition
(len != NULL)

This function will create a new packet snip in the packet buffer, which points to the given pkt and contains a IOVEC representation of the referenced packet in its data section.

Parameters
[in]pktPacket to export as IOVEC
[out]lenNumber of elements in the IOVEC
Returns
Pointer to the 'IOVEC packet snip'
NULL, if packet is empty of the packet buffer is full
void gnrc_pktbuf_hold ( gnrc_pktsnip_t pkt,
unsigned int  num 
)
Parameters
[in]pktA packet.
[in]numNumber you want to increment gnrc_pktsnip_t::users of pkt by.
bool gnrc_pktbuf_is_empty ( void  )
Returns
true, if packet buffer is empty
false, if packet buffer is not empty
bool gnrc_pktbuf_is_sane ( void  )
Returns
true, the packet buffer is sane.
false, the packet buffer is insane.
gnrc_pktsnip_t* gnrc_pktbuf_mark ( gnrc_pktsnip_t pkt,
size_t  size,
gnrc_nettype_t  type 
)

Graphically this can be represented as follows:

1 Before After
2 ====== =====
3  (next)
4  pkt->data result->data <== pkt->data
5  v v v
6 +--------------------------------+ +----------------+---------------+
7 +--------------------------------+ +----------------+---------------+
8  \__________pkt->size___________/ \_result->size_/ \__pkt->size__/

If size == pkt->size then the resulting snip will point to NULL in its gnrc_pktsnip_t::data field and its gnrc_pktsnip_t::size field will be 0.

Precondition
pkt != NULL && size != 0
Parameters
[in]pktA received packet.
[in]sizeThe size of the new packet snip.
[in]typeThe type of the new packet snip.
Returns
The new packet snip in pkt on success.
NULL, if pkt == NULL or size == 0 or size > pkt->size or pkt->data == NULL.
NULL, if no space is left in the packet buffer.
int gnrc_pktbuf_realloc_data ( gnrc_pktsnip_t pkt,
size_t  size 
)
Precondition
pkt != NULL
(pkt->size > 0) <=> (pkt->data != NULL)
gnrc_pktsnip_t::data of pkt is in the packet buffer if it is not NULL.

If enough memory is available behind it or size is smaller than the original size of the packet then gnrc_pktsnip_t::data of pkt will not be moved. Otherwise, it will be moved. If no space is available nothing happens.

Parameters
[in]pktA packet part.
[in]sizeThe size for pkt.
Returns
0, on success
ENOMEM, if no space is left in the packet buffer.
static void gnrc_pktbuf_release ( gnrc_pktsnip_t pkt)
inlinestatic
Parameters
[in]pktA packet.

Definition at line 169 of file pktbuf.h.

void gnrc_pktbuf_release_error ( gnrc_pktsnip_t pkt,
uint32_t  err 
)
Precondition
All snips of pkt must be in the packet buffer.
Parameters
[in]pktA packet.
[in]errAn error code.
gnrc_pktsnip_t* gnrc_pktbuf_remove_snip ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t snip 
)
Parameters
[in]pktA packet.
[in]snipA snip in the packet.
Returns
The new reference to pkt.
gnrc_pktsnip_t* gnrc_pktbuf_replace_snip ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t old,
gnrc_pktsnip_t add 
)
Parameters
[in]pktA packet
[in]oldsnip currently in the packet
[in]addsnip which will replace old
Returns
The new reference to pkt
gnrc_pktsnip_t* gnrc_pktbuf_start_write ( gnrc_pktsnip_t pkt)

This function duplicates a packet in the packet buffer if gnrc_pktsnip_t::users of pkt > 1.

Note
Do not call this function in a thread twice on the same packet.
Parameters
[in]pktThe packet you want to write into.
Returns
The (new) pointer to the pkt.
NULL, if gnrc_pktsnip_t::users of pkt > 1 and if there is not enough space in the packet buffer.
void gnrc_pktbuf_stats ( void  )
Note
Only available with DEVELHELP defined.

Statistics include maximum number of reserved bytes.