Mistake on this page?
Report an issue in GitHub or email us
pbuf.h
Go to the documentation of this file.
1 /**
2  * @file
3  * pbuf API
4  */
5 
6 /*
7  * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without modification,
11  * are permitted provided that the following conditions are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright notice,
14  * this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote products
19  * derived from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30  * OF SUCH DAMAGE.
31  *
32  * This file is part of the lwIP TCP/IP stack.
33  *
34  * Author: Adam Dunkels <adam@sics.se>
35  *
36  */
37 
38 #ifndef LWIP_HDR_PBUF_H
39 #define LWIP_HDR_PBUF_H
40 
41 #include "lwip/opt.h"
42 #include "lwip/err.h"
43 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 /** LWIP_SUPPORT_CUSTOM_PBUF==1: Custom pbufs behave much like their pbuf type
49  * but they are allocated by external code (initialised by calling
50  * pbuf_alloced_custom()) and when pbuf_free gives up their last reference, they
51  * are freed by calling pbuf_custom->custom_free_function().
52  * Currently, the pbuf_custom code is only needed for one specific configuration
53  * of IP_FRAG, unless required by external driver/application code. */
54 #ifndef LWIP_SUPPORT_CUSTOM_PBUF
55 #define LWIP_SUPPORT_CUSTOM_PBUF ((IP_FRAG && !LWIP_NETIF_TX_SINGLE_PBUF) || (LWIP_IPV6 && LWIP_IPV6_FRAG))
56 #endif
57 
58 /** @ingroup pbuf
59  * PBUF_NEEDS_COPY(p): return a boolean value indicating whether the given
60  * pbuf needs to be copied in order to be kept around beyond the current call
61  * stack without risking being corrupted. The default setting provides safety:
62  * it will make a copy iof any pbuf chain that does not consist entirely of
63  * PBUF_ROM type pbufs. For setups with zero-copy support, it may be redefined
64  * to evaluate to true in all cases, for example. However, doing so also has an
65  * effect on the application side: any buffers that are *not* copied must also
66  * *not* be reused by the application after passing them to lwIP. For example,
67  * when setting PBUF_NEEDS_COPY to (0), after using udp_send() with a PBUF_RAM
68  * pbuf, the application must free the pbuf immediately, rather than reusing it
69  * for other purposes. For more background information on this, see tasks #6735
70  * and #7896, and bugs #11400 and #49914. */
71 #ifndef PBUF_NEEDS_COPY
72 #define PBUF_NEEDS_COPY(p) ((p)->type_internal & PBUF_TYPE_FLAG_DATA_VOLATILE)
73 #endif /* PBUF_NEEDS_COPY */
74 
75 /* @todo: We need a mechanism to prevent wasting memory in every pbuf
76  (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */
77 
78 #define PBUF_TRANSPORT_HLEN 20
79 #if LWIP_IPV6
80 #define PBUF_IP_HLEN 40
81 #else
82 #define PBUF_IP_HLEN 20
83 #endif
84 
85 /**
86  * @ingroup pbuf
87  * Enumeration of pbuf layers
88  */
89 typedef enum {
90  /** Includes spare room for transport layer header, e.g. UDP header.
91  * Use this if you intend to pass the pbuf to functions like udp_send().
92  */
93  PBUF_TRANSPORT = PBUF_LINK_ENCAPSULATION_HLEN + PBUF_LINK_HLEN + PBUF_IP_HLEN + PBUF_TRANSPORT_HLEN,
94  /** Includes spare room for IP header.
95  * Use this if you intend to pass the pbuf to functions like raw_send().
96  */
98  /** Includes spare room for link layer header (ethernet header).
99  * Use this if you intend to pass the pbuf to functions like ethernet_output().
100  * @see PBUF_LINK_HLEN
101  */
103  /** Includes spare room for additional encapsulation header before ethernet
104  * headers (e.g. 802.11).
105  * Use this if you intend to pass the pbuf to functions like netif->linkoutput().
106  * @see PBUF_LINK_ENCAPSULATION_HLEN
107  */
109  /** Use this for input packets in a netif driver when calling netif->input()
110  * in the most common case - ethernet-layer netif driver. */
112 } pbuf_layer;
113 
114 
115 /* Base flags for pbuf_type definitions: */
116 
117 /** Indicates that the payload directly follows the struct pbuf.
118  * This makes @ref pbuf_header work in both directions. */
119 #define PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS 0x80
120 /** Indicates the data stored in this pbuf can change. If this pbuf needs
121  * to be queued, it must be copied/duplicated. */
122 #define PBUF_TYPE_FLAG_DATA_VOLATILE 0x40
123 /** 4 bits are reserved for 16 allocation sources (e.g. heap, pool1, pool2, etc)
124  * Internally, we use: 0=heap, 1=MEMP_PBUF, 2=MEMP_PBUF_POOL -> 13 types free*/
125 #define PBUF_TYPE_ALLOC_SRC_MASK 0x0F
126 /** Indicates this pbuf is used for RX (if not set, indicates use for TX).
127  * This information can be used to keep some spare RX buffers e.g. for
128  * receiving TCP ACKs to unblock a connection) */
129 #define PBUF_ALLOC_FLAG_RX 0x0100
130 /** Indicates the application needs the pbuf payload to be in one piece */
131 #define PBUF_ALLOC_FLAG_DATA_CONTIGUOUS 0x0200
132 
133 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP 0x00
134 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF 0x01
135 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL 0x02
136 /** First pbuf allocation type for applications */
137 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MIN 0x03
138 /** Last pbuf allocation type for applications */
139 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MAX PBUF_TYPE_ALLOC_SRC_MASK
140 
141 /**
142  * @ingroup pbuf
143  * Enumeration of pbuf types
144  */
145 typedef enum {
146  /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload
147  are allocated in one piece of contiguous memory (so the first payload byte
148  can be calculated from struct pbuf).
149  pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might
150  change in future versions).
151  This should be used for all OUTGOING packets (TX).*/
153  /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in
154  totally different memory areas. Since it points to ROM, payload does not
155  have to be copied when queued for transmission. */
156  PBUF_ROM = PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF,
157  /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change
158  so it has to be duplicated when queued before transmitting, depending on
159  who has a 'ref' to it. */
160  PBUF_REF = (PBUF_TYPE_FLAG_DATA_VOLATILE | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF),
161  /** pbuf payload refers to RAM. This one comes from a pool and should be used
162  for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct
163  pbuf and its payload are allocated in one piece of contiguous memory (so
164  the first payload byte can be calculated from struct pbuf).
165  Don't use this for TX, if the pool becomes empty e.g. because of TCP queuing,
166  you are unable to receive TCP acks! */
167  PBUF_POOL = (PBUF_ALLOC_FLAG_RX | PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL)
168 } pbuf_type;
169 
170 
171 /** indicates this packet's data should be immediately passed to the application */
172 #define PBUF_FLAG_PUSH 0x01U
173 /** indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function()
174  when the last reference is released (plus custom PBUF_RAM cannot be trimmed) */
175 #define PBUF_FLAG_IS_CUSTOM 0x02U
176 /** indicates this pbuf is UDP multicast to be looped back */
177 #define PBUF_FLAG_MCASTLOOP 0x04U
178 /** indicates this pbuf was received as link-level broadcast */
179 #define PBUF_FLAG_LLBCAST 0x08U
180 /** indicates this pbuf was received as link-level multicast */
181 #define PBUF_FLAG_LLMCAST 0x10U
182 /** indicates this pbuf includes a TCP FIN flag */
183 #define PBUF_FLAG_TCP_FIN 0x20U
184 
185 /** Main packet buffer struct */
186 struct pbuf {
187  /** next pbuf in singly linked pbuf chain */
188  struct pbuf *next;
189 
190  /** pointer to the actual data in the buffer */
191  void *payload;
192 
193  /**
194  * total length of this buffer and all next buffers in chain
195  * belonging to the same packet.
196  *
197  * For non-queue packet chains this is the invariant:
198  * p->tot_len == p->len + (p->next? p->next->tot_len: 0)
199  */
200  u16_t tot_len;
201 
202  /** length of this buffer */
203  u16_t len;
204 
205  /** a bit field indicating pbuf type and allocation sources
206  (see PBUF_TYPE_FLAG_*, PBUF_ALLOC_FLAG_* and PBUF_TYPE_ALLOC_SRC_MASK)
207  */
209 
210  /** misc flags */
211  u8_t flags;
212 
213  /**
214  * the reference count always equals the number of pointers
215  * that refer to this pbuf. This can be pointers from an application,
216  * the stack itself, or pbuf->next pointers from a chain.
217  */
219 
220  /** For incoming packets, this contains the input netif's index */
221  u8_t if_idx;
222 };
223 
224 
225 /** Helper struct for const-correctness only.
226  * The only meaning of this one is to provide a const payload pointer
227  * for PBUF_ROM type.
228  */
229 struct pbuf_rom {
230  /** next pbuf in singly linked pbuf chain */
231  struct pbuf *next;
232 
233  /** pointer to the actual data in the buffer */
234  const void *payload;
235 };
236 
237 #if LWIP_SUPPORT_CUSTOM_PBUF
238 /** Prototype for a function to free a custom pbuf */
239 typedef void (*pbuf_free_custom_fn)(struct pbuf *p);
240 
241 /** A custom pbuf: like a pbuf, but following a function pointer to free it. */
242 struct pbuf_custom {
243  /** The actual pbuf */
244  struct pbuf pbuf;
245  /** This function is called when pbuf_free deallocates this pbuf(_custom) */
246  pbuf_free_custom_fn custom_free_function;
247 };
248 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
249 
250 /** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */
251 #ifndef PBUF_POOL_FREE_OOSEQ
252 #define PBUF_POOL_FREE_OOSEQ 1
253 #endif /* PBUF_POOL_FREE_OOSEQ */
254 #if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ
255 extern volatile u8_t pbuf_free_ooseq_pending;
256 void pbuf_free_ooseq(void);
257 /** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ()
258  at regular intervals from main level to check if ooseq pbufs need to be
259  freed! */
260 #define PBUF_CHECK_FREE_OOSEQ() do { if(pbuf_free_ooseq_pending) { \
261  /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \
262  ooseq queued pbufs now */ \
263  pbuf_free_ooseq(); }}while(0)
264 #else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */
265  /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */
266  #define PBUF_CHECK_FREE_OOSEQ()
267 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ*/
268 
269 /* Initializes the pbuf module. This call is empty for now, but may not be in future. */
270 #define pbuf_init()
271 
272 struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type);
273 struct pbuf *pbuf_alloc_reference(void *payload, u16_t length, pbuf_type type);
274 #if LWIP_SUPPORT_CUSTOM_PBUF
275 struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type,
276  struct pbuf_custom *p, void *payload_mem,
277  u16_t payload_mem_len);
278 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
279 void pbuf_realloc(struct pbuf *p, u16_t size);
280 #define pbuf_get_allocsrc(p) ((p)->type_internal & PBUF_TYPE_ALLOC_SRC_MASK)
281 #define pbuf_match_allocsrc(p, type) (pbuf_get_allocsrc(p) == ((type) & PBUF_TYPE_ALLOC_SRC_MASK))
282 #define pbuf_match_type(p, type) pbuf_match_allocsrc(p, type)
283 u8_t pbuf_header(struct pbuf *p, s16_t header_size);
284 u8_t pbuf_header_force(struct pbuf *p, s16_t header_size);
285 u8_t pbuf_add_header(struct pbuf *p, size_t header_size_increment);
286 u8_t pbuf_add_header_force(struct pbuf *p, size_t header_size_increment);
287 u8_t pbuf_remove_header(struct pbuf *p, size_t header_size);
288 struct pbuf *pbuf_free_header(struct pbuf *q, u16_t size);
289 void pbuf_ref(struct pbuf *p);
290 u8_t pbuf_free(struct pbuf *p);
291 u16_t pbuf_clen(const struct pbuf *p);
292 void pbuf_cat(struct pbuf *head, struct pbuf *tail);
293 void pbuf_chain(struct pbuf *head, struct pbuf *tail);
294 struct pbuf *pbuf_dechain(struct pbuf *p);
295 err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from);
296 u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset);
297 void *pbuf_get_contiguous(const struct pbuf *p, void *buffer, size_t bufsize, u16_t len, u16_t offset);
298 err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len);
299 err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset);
300 struct pbuf *pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset);
301 struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer);
302 struct pbuf *pbuf_clone(pbuf_layer l, pbuf_type type, struct pbuf *p);
303 #if LWIP_CHECKSUM_ON_COPY
304 err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
305  u16_t len, u16_t *chksum);
306 #endif /* LWIP_CHECKSUM_ON_COPY */
307 #if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE
308 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest);
309 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
310 
311 u8_t pbuf_get_at(const struct pbuf* p, u16_t offset);
312 int pbuf_try_get_at(const struct pbuf* p, u16_t offset);
313 void pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data);
314 u16_t pbuf_memcmp(const struct pbuf* p, u16_t offset, const void* s2, u16_t n);
315 u16_t pbuf_memfind(const struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset);
316 u16_t pbuf_strstr(const struct pbuf* p, const char* substr);
317 
318 #ifdef __cplusplus
319 }
320 #endif
321 
322 #endif /* LWIP_HDR_PBUF_H */
u8_t type_internal
a bit field indicating pbuf type and allocation sources (see PBUF_TYPE_FLAG_*, PBUF_ALLOC_FLAG_* and ...
Definition: pbuf.h:208
void * payload
pointer to the actual data in the buffer
Includes spare room for additional encapsulation header before ethernet headers (e.g.
Definition: pbuf.h:108
const void * payload
pointer to the actual data in the buffer
Definition: pbuf.h:234
#define LWIP_PBUF_REF_T
LWIP_PBUF_REF_T: Refcount type in pbuf.
Definition: opt.h:1556
#define PBUF_TYPE_FLAG_DATA_VOLATILE
Indicates the data stored in this pbuf can change.
Definition: pbuf.h:122
struct pbuf * next
next pbuf in singly linked pbuf chain
Definition: pbuf.h:231
lwIP Options Configuration
LWIP_PBUF_REF_T ref
the reference count always equals the number of pointers that refer to this pbuf. ...
Definition: pbuf.h:218
u16_t len
length of this buffer
Definition: pbuf.h:203
pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload are allocated in one piec...
Definition: pbuf.h:152
#define PBUF_LINK_HLEN
PBUF_LINK_HLEN: the number of bytes that should be allocated for a link level header.
Definition: opt.h:1530
Includes spare room for link layer header (ethernet header).
Definition: pbuf.h:102
u8_t flags
misc flags
Definition: pbuf.h:211
struct pbuf * next
next pbuf in singly linked pbuf chain
Includes spare room for transport layer header, e.g.
Definition: pbuf.h:93
Helper struct for const-correctness only.
Definition: pbuf.h:229
Use this for input packets in a netif driver when calling netif->input() in the most common case - et...
Definition: pbuf.h:111
u8_t if_idx
For incoming packets, this contains the input netif&#39;s index.
Definition: pbuf.h:221
u16_t tot_len
total length of this buffer and all next buffers in chain belonging to the same packet.
Definition: pbuf.h:200
#define PBUF_ALLOC_FLAG_RX
Indicates this pbuf is used for RX (if not set, indicates use for TX).
Definition: pbuf.h:129
Main packet buffer struct.
pbuf payload refers to RAM.
Definition: pbuf.h:167
lwIP Error codes
pbuf data is stored in ROM, i.e.
Definition: pbuf.h:156
#define PBUF_ALLOC_FLAG_DATA_CONTIGUOUS
Indicates the application needs the pbuf payload to be in one piece.
Definition: pbuf.h:131
#define PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS
Indicates that the payload directly follows the struct pbuf.
Definition: pbuf.h:119
pbuf_type
Enumeration of pbuf types.
Definition: pbuf.h:145
pbuf comes from the pbuf pool.
Definition: pbuf.h:160
Includes spare room for IP header.
Definition: pbuf.h:97
#define PBUF_LINK_ENCAPSULATION_HLEN
PBUF_LINK_ENCAPSULATION_HLEN: the number of bytes that should be allocated for an additional encapsul...
Definition: opt.h:1539
pbuf_layer
Enumeration of pbuf layers.
Definition: pbuf.h:89
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.