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 /* @todo: We need a mechanism to prevent wasting memory in every pbuf 59 (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */ 60 61 #define PBUF_TRANSPORT_HLEN 20 62 #if LWIP_IPV6 63 #define PBUF_IP_HLEN 40 64 #else 65 #define PBUF_IP_HLEN 20 66 #endif 67 68 /** 69 * @ingroup pbuf 70 * Enumeration of pbuf layers 71 */ 72 typedef enum { 73 /** Includes spare room for transport layer header, e.g. UDP header. 74 * Use this if you intend to pass the pbuf to functions like udp_send(). 75 */ 76 PBUF_TRANSPORT, 77 /** Includes spare room for IP header. 78 * Use this if you intend to pass the pbuf to functions like raw_send(). 79 */ 80 PBUF_IP, 81 /** Includes spare room for link layer header (ethernet header). 82 * Use this if you intend to pass the pbuf to functions like ethernet_output(). 83 * @see PBUF_LINK_HLEN 84 */ 85 PBUF_LINK, 86 /** Includes spare room for additional encapsulation header before ethernet 87 * headers (e.g. 802.11). 88 * Use this if you intend to pass the pbuf to functions like netif->linkoutput(). 89 * @see PBUF_LINK_ENCAPSULATION_HLEN 90 */ 91 PBUF_RAW_TX, 92 /** Use this for input packets in a netif driver when calling netif->input() 93 * in the most common case - ethernet-layer netif driver. */ 94 PBUF_RAW, 95 /** pbuf layer for mbuf compatible */ 96 #if LWIP_XR_EXT_MBUF_SUPPORT 97 PBUF_MBUF_RAW /* only used by mbuf, never reserve head and tail space */ 98 #endif 99 } pbuf_layer; 100 101 /** 102 * @ingroup pbuf 103 * Enumeration of pbuf types 104 */ 105 typedef enum { 106 /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload 107 are allocated in one piece of contiguous memory (so the first payload byte 108 can be calculated from struct pbuf). 109 pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might 110 change in future versions). 111 This should be used for all OUTGOING packets (TX).*/ 112 PBUF_RAM, 113 /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in 114 totally different memory areas. Since it points to ROM, payload does not 115 have to be copied when queued for transmission. */ 116 PBUF_ROM, 117 /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change 118 so it has to be duplicated when queued before transmitting, depending on 119 who has a 'ref' to it. */ 120 PBUF_REF, 121 /** pbuf payload refers to RAM. This one comes from a pool and should be used 122 for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct 123 pbuf and its payload are allocated in one piece of contiguous memory (so 124 the first payload byte can be calculated from struct pbuf). 125 Don't use this for TX, if the pool becomes empty e.g. because of TCP queuing, 126 you are unable to receive TCP acks! */ 127 PBUF_POOL 128 } pbuf_type; 129 130 131 /** indicates this packet's data should be immediately passed to the application */ 132 #define PBUF_FLAG_PUSH 0x01U 133 /** indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function() 134 when the last reference is released (plus custom PBUF_RAM cannot be trimmed) */ 135 #define PBUF_FLAG_IS_CUSTOM 0x02U 136 /** indicates this pbuf is UDP multicast to be looped back */ 137 #define PBUF_FLAG_MCASTLOOP 0x04U 138 /** indicates this pbuf was received as link-level broadcast */ 139 #define PBUF_FLAG_LLBCAST 0x08U 140 /** indicates this pbuf was received as link-level multicast */ 141 #define PBUF_FLAG_LLMCAST 0x10U 142 /** indicates this pbuf includes a TCP FIN flag */ 143 #define PBUF_FLAG_TCP_FIN 0x20U 144 145 #if LWIP_XR_EXT_MBUF_SUPPORT 146 /** indicates this pbuf is referred by mbuf */ 147 #define PBUF_FLAG_MBUF_REF 0x01U 148 /** indicates this pbuf includes empty space available at head and tail reserved for mbuf */ 149 #define PBUF_FLAG_MBUF_SPACE 0x02U 150 #if LWIP_XR_EXT_PBUF_POOL_SMALL 151 /** indicates this pbuf is type of MEMP_PBUF_POOL_SMALL */ 152 #define PBUF_FLAG_POOL_SMALL 0x80U 153 #endif /* LWIP_XR_EXT_PBUF_POOL_SMALL */ 154 #endif /* (LWIP_XR_EXT_MBUF_SUPPORT) */ 155 156 /** Main packet buffer struct */ 157 struct pbuf { 158 /** next pbuf in singly linked pbuf chain */ 159 struct pbuf *next; 160 161 /** pointer to the actual data in the buffer */ 162 void *payload; 163 164 /** 165 * total length of this buffer and all next buffers in chain 166 * belonging to the same packet. 167 * 168 * For non-queue packet chains this is the invariant: 169 * p->tot_len == p->len + (p->next? p->next->tot_len: 0) 170 */ 171 u16_t tot_len; 172 173 /** length of this buffer */ 174 u16_t len; 175 176 /** pbuf_type as u8_t instead of enum to save space */ 177 u8_t /*pbuf_type*/ type; 178 179 /** misc flags */ 180 u8_t flags; 181 182 #if LWIP_XR_EXT_MBUF_SUPPORT 183 /** new flags for mbuf */ 184 u8_t mb_flags; 185 186 /** decrease its size to u8_t */ 187 u8_t ref; 188 #else /* LWIP_XR_EXT_MBUF_SUPPORT */ 189 /** 190 * the reference count always equals the number of pointers 191 * that refer to this pbuf. This can be pointers from an application, 192 * the stack itself, or pbuf->next pointers from a chain. 193 */ 194 u16_t ref; 195 #endif 196 }; 197 198 199 /** Helper struct for const-correctness only. 200 * The only meaning of this one is to provide a const payload pointer 201 * for PBUF_ROM type. 202 */ 203 struct pbuf_rom { 204 /** next pbuf in singly linked pbuf chain */ 205 struct pbuf *next; 206 207 /** pointer to the actual data in the buffer */ 208 const void *payload; 209 }; 210 211 #if LWIP_SUPPORT_CUSTOM_PBUF 212 /** Prototype for a function to free a custom pbuf */ 213 typedef void (*pbuf_free_custom_fn)(struct pbuf *p); 214 215 /** A custom pbuf: like a pbuf, but following a function pointer to free it. */ 216 struct pbuf_custom { 217 /** The actual pbuf */ 218 struct pbuf pbuf; 219 /** This function is called when pbuf_free deallocates this pbuf(_custom) */ 220 pbuf_free_custom_fn custom_free_function; 221 }; 222 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */ 223 224 /** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */ 225 #ifndef PBUF_POOL_FREE_OOSEQ 226 #define PBUF_POOL_FREE_OOSEQ 1 227 #endif /* PBUF_POOL_FREE_OOSEQ */ 228 #if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ 229 extern volatile u8_t pbuf_free_ooseq_pending; 230 void pbuf_free_ooseq(void); 231 /** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ() 232 at regular intervals from main level to check if ooseq pbufs need to be 233 freed! */ 234 #define PBUF_CHECK_FREE_OOSEQ() do { if(pbuf_free_ooseq_pending) { \ 235 /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \ 236 ooseq queued pbufs now */ \ 237 pbuf_free_ooseq(); }}while(0) 238 #else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */ 239 /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */ 240 #define PBUF_CHECK_FREE_OOSEQ() 241 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ*/ 242 243 /* Initializes the pbuf module. This call is empty for now, but may not be in future. */ 244 #define pbuf_init() 245 246 #if (LWIP_XR_EXT_MBUF_SUPPORT && LWIP_XR_EXT_PBUF_POOL_SMALL) 247 struct pbuf *pbuf_alloc_ext(pbuf_layer layer, u16_t length, pbuf_type type, u8_t pbuf_pool_small); 248 #define pbuf_alloc(l, len, t) pbuf_alloc_ext(l, len, t, 0) 249 #else /* (LWIP_XR_EXT_MBUF_SUPPORT && LWIP_XR_EXT_PBUF_POOL_SMALL) */ 250 struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type); 251 #endif /* (LWIP_MBUF_SUPPORT && LWIP_PBUF_POOL_SMALL) */ 252 #if (LWIP_XR_EXT_MBUF_SUPPORT) 253 s32_t pbuf_head_space(struct pbuf *p); 254 #endif /* (LWIP_XR_EXT_MBUF_SUPPORT) */ 255 256 #if LWIP_SUPPORT_CUSTOM_PBUF 257 struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type, 258 struct pbuf_custom *p, void *payload_mem, 259 u16_t payload_mem_len); 260 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */ 261 void pbuf_realloc(struct pbuf *p, u16_t size); 262 u8_t pbuf_header(struct pbuf *p, s16_t header_size); 263 u8_t pbuf_header_force(struct pbuf *p, s16_t header_size); 264 void pbuf_ref(struct pbuf *p); 265 u8_t pbuf_free(struct pbuf *p); 266 u16_t pbuf_clen(const struct pbuf *p); 267 void pbuf_cat(struct pbuf *head, struct pbuf *tail); 268 void pbuf_chain(struct pbuf *head, struct pbuf *tail); 269 struct pbuf *pbuf_dechain(struct pbuf *p); 270 err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from); 271 u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset); 272 err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len); 273 err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset); 274 struct pbuf *pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset); 275 struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer); 276 #if LWIP_CHECKSUM_ON_COPY 277 err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr, 278 u16_t len, u16_t *chksum); 279 #endif /* LWIP_CHECKSUM_ON_COPY */ 280 #if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE 281 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest); 282 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */ 283 284 u8_t pbuf_get_at(const struct pbuf* p, u16_t offset); 285 int pbuf_try_get_at(const struct pbuf* p, u16_t offset); 286 void pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data); 287 u16_t pbuf_memcmp(const struct pbuf* p, u16_t offset, const void* s2, u16_t n); 288 u16_t pbuf_memfind(const struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset); 289 u16_t pbuf_strstr(const struct pbuf* p, const char* substr); 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif /* LWIP_HDR_PBUF_H */ 296