Packet buffer

A global network packet buffer.

void gnrc_pktbuf_init(void)

Initializes packet buffer module.

include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_add(include/net/gnrc/pkt.h::gnrc_pktsnip_t * next, const void * data, msp430_types.h::size_t size, nettype.h::gnrc_nettype_t type)

Adds a new gnrc_pktsnip_t and its packet to the packet buffer.

Parameters

next:Next gnrc_pktsnip_t in the packet. Leave NULL if you want to create a new packet.
data:Data of the new gnrc_pktsnip_t. If data is NULL no data will be inserted into result.
size:Length of data. If this value is 0 the include/net/gnrc/pkt.h::gnrc_pktsnip::data field of the newly created snip will be NULL.
type:Protocol type of the gnrc_pktsnip_t.

Return values

  • Pointer to the packet part that represents the new gnrc_pktsnip_t.
  • NULL, if no space is left in the packet buffer.
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_mark(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, msp430_types.h::size_t size, nettype.h::gnrc_nettype_t type)

Marks the first size bytes in a received packet with a new packet snip that is appended to the packet.

Graphically this can be represented as follows:

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

If size == pkt->size then the resulting snip will point to NULL in its include/net/gnrc/pkt.h::gnrc_pktsnip::data field and its include/net/gnrc/pkt.h::gnrc_pktsnip::size field will be 0.

Parameters

pkt:A received packet.
size:The size of the new packet snip.
type:The type of the new packet snip.

Return values

  • 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(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, msp430_types.h::size_t size)

Reallocates include/net/gnrc/pkt.h::gnrc_pktsnip::data of pkt in the packet buffer, without changing the content.

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

Parameters

pkt:A packet part.
size:The size for pkt.

Return values

  • 0, on success
  • ENOMEM, if no space is left in the packet buffer.
void gnrc_pktbuf_hold(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, unsigned int num)

Increases include/net/gnrc/pkt.h::gnrc_pktsnip::users of pkt atomically.

Parameters

pkt:A packet.
num:Number you want to increment include/net/gnrc/pkt.h::gnrc_pktsnip::users of pkt by.

void gnrc_pktbuf_release_error(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, uint32_t err)

Decreases include/net/gnrc/pkt.h::gnrc_pktsnip::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.

Parameters

pkt:A packet.
err:An error code.

void gnrc_pktbuf_release(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Decreases include/net/gnrc/pkt.h::gnrc_pktsnip::users of pkt atomically and removes it if it reaches 0 and reports neterr.h::GNRC_NETERR_SUCCESS.

Parameters

pkt:A packet.

include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_start_write(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Must be called once before there is a write operation on a include/net/gnrc/pkt.h::gnrc_pktsnip_t in a thread.

This function duplicates a packet snip in the packet buffer (both the instance of the gnrc_pktsnip_t and its data) if include/net/gnrc/pkt.h::gnrc_pktsnip::users of pkt > 1.

Parameters

pkt:The packet snip you want to write into.

Return values

include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_get_iovec(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, msp430_types.h::size_t * len)

Create a IOVEC representation of the packet pointed to by pkt

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

pkt:Packet to export as IOVEC
len:Number of elements in the IOVEC

Return values

  • Pointer to the ‘IOVEC packet snip’
  • NULL, if packet is empty of the packet buffer is full
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_remove_snip(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, include/net/gnrc/pkt.h::gnrc_pktsnip_t * snip)

Deletes a snip from a packet and the packet buffer.

Parameters

pkt:A packet.
snip:A snip in the packet.

Return values

  • The new reference to pkt.
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_replace_snip(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, include/net/gnrc/pkt.h::gnrc_pktsnip_t * old, include/net/gnrc/pkt.h::gnrc_pktsnip_t * add)

Replace a snip from a packet and the packet buffer by another snip.

Parameters

pkt:A packet
old:snip currently in the packet
add:snip which will replace old

Return values

  • The new reference to pkt
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_reverse_snips(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Reverses snip order of a packet in a write-protected manner.

This can be used to change the send/receive order of a packet (see include/net/gnrc/pkt.h::gnrc_pktsnip_t)

Note

pkt is released on failure.

Parameters

pkt:A packet. When this function fails (due to a full packet packet buffer) pkt will be released.

Return values

  • The reversed version of pkt on success
  • NULL, when there is not enough space in the packet buffer to reverse the packet in a write-protected manner. pkt is released in that case.
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_pktbuf_duplicate_upto(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, nettype.h::gnrc_nettype_t type)

Duplicates pktsnip chain upto (including) a snip with the given type as a continuous snip.

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 |—+ +—+ +————————+ . .

This function breaks the abstraction of gnrc_pktbuf and its only user within the RIOT code base gnrc_ipv6_ext is going to be reworked so it isn’t needed anymore. It will be removed after the 2019.04 release.

Parameters

pkt:The snip to duplicate.
type:The type of snip to stop duplication.

Return values

  • The duplicated snip, if succeeded.
  • NULL, if no space is left in the packet buffer.
int gnrc_pktbuf_merge(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Merge pktsnip chain to single pktsnip.

Specifically it calls pktbuf.h::gnrc_pktbuf_realloc_data() on pkt, then copies the data of all following packet snips into that reallocated space, and removes the packet snip the data was copied from afterwards.

Example

Input

Output

Note

Packets in receive order need to call pktbuf.h::gnrc_pktbuf_reverse_snips() first to get the data in the correct order.

Parameters

pkt:The snip to merge.

Input

Output

Note

Packets in receive order need to call pktbuf.h::gnrc_pktbuf_reverse_snips() first to get the data in the correct order.

Parameters

pkt:The snip to merge.

Note

Packets in receive order need to call pktbuf.h::gnrc_pktbuf_reverse_snips() first to get the data in the correct order.

Parameters

pkt:The snip to merge.

Return values

  • 0, on success
  • ENOMEM, if no space is left in the packet buffer.
void gnrc_pktbuf_stats(void)

Prints some statistics about the packet buffer to stdout.

Note

Only available with DEVELHELP defined.

Statistics include maximum number of reserved bytes.

bool gnrc_pktbuf_is_empty(void)

Checks if packet buffer is empty.

Return values

  • true, if packet buffer is empty
  • false, if packet buffer is not empty
bool gnrc_pktbuf_is_sane(void)

Checks if the implementation’s internal invariants still uphold.

Return values

  • true, the packet buffer is sane.
  • false, the packet buffer is insane.
GNRC_PKTBUF_SIZE

Maximum size of the static packet buffer. 

1
(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 pktbuf.h::GNRC_PKTBUF_SIZE is 0 the packet buffer will use dynamic memory management to allocate packets.