pbuf.h

pbuf API

Defines

LWIP_SUPPORT_CUSTOM_PBUF

LWIP_SUPPORT_CUSTOM_PBUF==1: Custom pbufs behave much like their pbuf type but they are allocated by external code (initialised by calling pbuf_alloced_custom()) and when pbuf_free gives up their last reference, they are freed by calling pbuf_custom->custom_free_function().

Currently, the pbuf_custom code is only needed for one specific configuration of IP_FRAG, unless required by external driver/application code.

PBUF_NEEDS_COPY(p)

PBUF_NEEDS_COPY(p): return a boolean value indicating whether the given pbuf needs to be copied in order to be kept around beyond the current call stack without risking being corrupted.

The default setting provides safety: it will make a copy iof any pbuf chain that does not consist entirely of PBUF_ROM type pbufs. For setups with zero-copy support, it may be redefined to evaluate to true in all cases, for example. However, doing so also has an effect on the application side: any buffers that are not copied must also not be reused by the application after passing them to lwIP. For example, when setting PBUF_NEEDS_COPY to (0), after using udp_send() with a PBUF_RAM pbuf, the application must free the pbuf immediately, rather than reusing it for other purposes. For more background information on this, see tasks #6735 and #7896, and bugs #11400 and #49914.

PBUF_TRANSPORT_HLEN

PBUF_IP_HLEN

PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS

Indicates that the payload directly follows the struct pbuf.

This makes pbuf_header work in both directions.

PBUF_TYPE_FLAG_DATA_VOLATILE

Indicates the data stored in this pbuf can change.

If this pbuf needs to be queued, it must be copied/duplicated.

PBUF_TYPE_ALLOC_SRC_MASK

4 bits are reserved for 16 allocation sources (e.g.

heap, pool1, pool2, etc) Internally, we use: 0=heap, 1=MEMP_PBUF, 2=MEMP_PBUF_POOL -> 13 types free

PBUF_ALLOC_FLAG_RX

Indicates this pbuf is used for RX (if not set, indicates use for TX).

This information can be used to keep some spare RX buffers e.g. for receiving TCP ACKs to unblock a connection)

PBUF_ALLOC_FLAG_DATA_CONTIGUOUS

Indicates the application needs the pbuf payload to be in one piece.

PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP

PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF

PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL

PBUF_TYPE_ALLOC_SRC_MASK_APP_MIN

First pbuf allocation type for applications.

PBUF_TYPE_ALLOC_SRC_MASK_APP_MAX

Last pbuf allocation type for applications.

PBUF_FLAG_PUSH

indicates this packet’s data should be immediately passed to the application

PBUF_FLAG_IS_CUSTOM

indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function() when the last reference is released (plus custom PBUF_RAM cannot be trimmed)

PBUF_FLAG_MCASTLOOP

indicates this pbuf is UDP multicast to be looped back

PBUF_FLAG_LLBCAST

indicates this pbuf was received as link-level broadcast

PBUF_FLAG_LLMCAST

indicates this pbuf was received as link-level multicast

PBUF_FLAG_TCP_FIN

indicates this pbuf includes a TCP FIN flag

PBUF_POOL_FREE_OOSEQ

Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty.

PBUF_CHECK_FREE_OOSEQ()

pbuf_init()

pbuf_get_allocsrc(p)

pbuf_match_allocsrc(p, type)

pbuf_match_type(p, type)

Enums

enum pbuf_layer

Enumeration of pbuf layers.

Values:

enumerator PBUF_TRANSPORT

Includes spare room for transport layer header, e.g.

UDP header. Use this if you intend to pass the pbuf to functions like udp_send().

enumerator PBUF_IP

Includes spare room for IP header.

Use this if you intend to pass the pbuf to functions like raw_send().

enumerator PBUF_LINK

Includes spare room for link layer header (ethernet header).

Use this if you intend to pass the pbuf to functions like ethernet_output().

See also

PBUF_LINK_HLEN

enumerator PBUF_RAW_TX

Includes spare room for additional encapsulation header before ethernet headers (e.g.

802.11). Use this if you intend to pass the pbuf to functions like netif->linkoutput().

See also

PBUF_LINK_ENCAPSULATION_HLEN

enumerator PBUF_RAW

Use this for input packets in a netif driver when calling netif->input() in the most common case - ethernet-layer netif driver.

enum pbuf_type

Enumeration of pbuf types.

Values:

enumerator PBUF_RAM

pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload are allocated in one piece of contiguous memory (so the first payload byte can be calculated from struct pbuf).

pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might change in future versions). This should be used for all OUTGOING packets (TX).

enumerator PBUF_ROM

pbuf data is stored in ROM, i.e.

struct pbuf and its payload are located in totally different memory areas. Since it points to ROM, payload does not have to be copied when queued for transmission.

enumerator PBUF_REF

pbuf comes from the pbuf pool.

Much like PBUF_ROM but payload might change so it has to be duplicated when queued before transmitting, depending on who has a ‘ref’ to it.

enumerator PBUF_POOL

pbuf payload refers to RAM.

This one comes from a pool and should be used for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct pbuf and its payload are allocated in one piece of contiguous memory (so the first payload byte can be calculated from struct pbuf). Don’t use this for TX, if the pool becomes empty e.g. because of TCP queuing, you are unable to receive TCP acks!

Functions

struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type)

struct pbuf *pbuf_alloc_reference(void *payload, u16_t length, pbuf_type type)

void pbuf_realloc(struct pbuf *p, u16_t size)

u8_t pbuf_header(struct pbuf *p, s16_t header_size)

u8_t pbuf_header_force(struct pbuf *p, s16_t header_size)

u8_t pbuf_add_header(struct pbuf *p, size_t header_size_increment)

u8_t pbuf_add_header_force(struct pbuf *p, size_t header_size_increment)

u8_t pbuf_remove_header(struct pbuf *p, size_t header_size)

struct pbuf *pbuf_free_header(struct pbuf *q, u16_t size)

void pbuf_ref(struct pbuf *p)

u8_t pbuf_free(struct pbuf *p)

u16_t pbuf_clen(const struct pbuf *p)

void pbuf_cat(struct pbuf *head, struct pbuf *tail)

void pbuf_chain(struct pbuf *head, struct pbuf *tail)

struct pbuf *pbuf_dechain(struct pbuf *p)

err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from)

err_t pbuf_copy_partial_pbuf(struct pbuf *p_to, const struct pbuf *p_from, u16_t copy_len, u16_t offset)

u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset)

void *pbuf_get_contiguous(const struct pbuf *p, void *buffer, size_t bufsize, u16_t len, u16_t offset)

err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len)

err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset)

struct pbuf *pbuf_skip(struct pbuf *in, u16_t in_offset, u16_t *out_offset)

struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer)

struct pbuf *pbuf_clone(pbuf_layer l, pbuf_type type, struct pbuf *p)

u8_t pbuf_get_at(const struct pbuf *p, u16_t offset)

int pbuf_try_get_at(const struct pbuf *p, u16_t offset)

void pbuf_put_at(struct pbuf *p, u16_t offset, u8_t data)

u16_t pbuf_memcmp(const struct pbuf *p, u16_t offset, const void *s2, u16_t n)

u16_t pbuf_memfind(const struct pbuf *p, const void *mem, u16_t mem_len, u16_t start_offset)

u16_t pbuf_strstr(const struct pbuf *p, const char *substr)

struct pbuf

#include <pbuf.h>

Main packet buffer struct.

Public Members

struct pbuf *next

next pbuf in singly linked pbuf chain

void *payload

pointer to the actual data in the buffer

u16_t tot_len

total length of this buffer and all next buffers in chain belonging to the same packet.

For non-queue packet chains this is the invariant: p->tot_len == p->len + (p->next? p->next->tot_len: 0)

u16_t len

length of this buffer

u8_t type_internal

a bit field indicating pbuf type and allocation sources (see PBUF_TYPE_FLAG_*, PBUF_ALLOC_FLAG_* and PBUF_TYPE_ALLOC_SRC_MASK)

u8_t flags

misc flags

LWIP_PBUF_REF_T ref

the reference count always equals the number of pointers that refer to this pbuf.

This can be pointers from an application, the stack itself, or pbuf->next pointers from a chain.

u8_t if_idx

For incoming packets, this contains the input netif’s index.

struct pbuf_rom

#include <pbuf.h>

Helper struct for const-correctness only.

The only meaning of this one is to provide a const payload pointer for PBUF_ROM type.

Public Members

struct pbuf *next

next pbuf in singly linked pbuf chain

const void *payload

pointer to the actual data in the buffer