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 "arch/atomic.h" 42 #include "lwip/opt.h" 43 #include "lwip/err.h" 44 45 #if defined (__cplusplus) && __cplusplus 46 extern "C" { 47 #endif 48 49 #define SIZEOF_STRUCT_PBUF LWIP_MEM_ALIGN_SIZE(sizeof(struct pbuf)) 50 51 /** 52 * @defgroup Buffer_Interfaces Buffer Interfaces 53 * @ingroup System_interfaces 54 */ 55 /** 56 * LWIP_SUPPORT_CUSTOM_PBUF==1: Custom pbufs behave similar to its pbuf type, 57 * but it is are allocated by external code (initialized by calling 58 * pbuf_alloced_custom()), and when pbuf_free gives up the last reference, the custom pbufs 59 * are freed by calling pbuf_custom->custom_free_function(). 60 * Currently, the pbuf_custom code is only needed for one specific configuration 61 * of IP_FRAG, unless required by the external driver/application code. */ 62 #ifndef LWIP_SUPPORT_CUSTOM_PBUF 63 #define LWIP_SUPPORT_CUSTOM_PBUF ((IP_FRAG && !LWIP_NETIF_TX_SINGLE_PBUF) || (LWIP_IPV6 && LWIP_IPV6_FRAG)) 64 #endif 65 66 /** PBUF_NEEDS_COPY(p): return a boolean value indicating whether the given 67 * pbuf needs to be copied in order to be kept around beyond the current call 68 * stack without risking being corrupted. The default setting provides safety: 69 * it will make a copy iof any pbuf chain that does not consist entirely of 70 * PBUF_ROM type pbufs. For setups with zero-copy support, it may be redefined 71 * to evaluate to true in all cases, for example. However, doing so also has an 72 * effect on the application side: any buffers that are *not* copied must also 73 * *not* be reused by the application after passing them to lwIP. For example, 74 * when setting PBUF_NEEDS_COPY to (0), after using udp_send() with a PBUF_RAM 75 * pbuf, the application must free the pbuf immediately, rather than reusing it 76 * for other purposes. For more background information on this, see tasks #6735 77 * and #7896, and bugs #11400 and #49914. */ 78 #ifndef PBUF_NEEDS_COPY 79 #define PBUF_NEEDS_COPY(p) (p->type_internal != PBUF_ROM) 80 #endif /* PBUF_NEEDS_COPY */ 81 82 /* @todo: We need a mechanism to prevent wasting memory in every pbuf 83 (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */ 84 85 #define PBUF_TRANSPORT_HLEN 20 86 #if LWIP_IPV6 87 #define PBUF_IP_HLEN 40 88 #else 89 #define PBUF_IP_HLEN 20 90 #endif 91 92 /* for zero copy */ 93 #define PBUF_ZERO_COPY_RESERVE 36 94 95 /** 96 * @ingroup pbuf 97 * Enumeration of pbuf layers 98 */ 99 typedef enum { 100 /** Includes spare room for transport layer headers such as UDP header. 101 * Use this if you intend to pass the pbuf to functions like udp_send(). 102 */ 103 PBUF_TRANSPORT, 104 /** Includes spare room for IP header. 105 * Use this if you intend to pass the pbuf to functions like raw_send(). 106 */ 107 PBUF_IP, 108 /** Includes spare room for link layer header (ethernet header). 109 * Use this if you intend to pass the pbuf to functions like ethernet_output(). 110 * @see PBUF_LINK_HLEN 111 */ 112 PBUF_LINK, 113 /** Includes spare room for additional encapsulation header before ethernet 114 * headers such as 802.11. 115 * Use this if you intend to pass the pbuf to functions like netif->linkoutput(). 116 * @see PBUF_LINK_ENCAPSULATION_HLEN 117 */ 118 PBUF_RAW_TX, 119 /** Use this for input packets in a netif driver when calling netif->input(). 120 * The most common case is ethernet-layer netif driver. */ 121 PBUF_RAW 122 } pbuf_layer; 123 124 125 /* Base flags for pbuf_type definitions: */ 126 127 /** Indicates that the payload directly follows the struct pbuf. 128 * This makes @ref pbuf_header work in both directions. */ 129 #define PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS 0x80 130 /** Indicates the data stored in this pbuf can change. If this pbuf needs 131 * to be queued, it must be copied/duplicated. */ 132 #define PBUF_TYPE_FLAG_DATA_VOLATILE 0x40 133 /** 4 bits are reserved for 16 allocation sources (e.g. heap, pool1, pool2, etc) 134 * Internally, we use: 0=heap, 1=MEMP_PBUF, 2=MEMP_PBUF_POOL -> 13 types free*/ 135 #define PBUF_TYPE_ALLOC_SRC_MASK 0x0F 136 /** Indicates this pbuf is used for RX (if not set, indicates use for TX). 137 * This information can be used to keep some spare RX buffers e.g. for 138 * receiving TCP ACKs to unblock a connection) */ 139 #define PBUF_ALLOC_FLAG_RX 0x0100 140 /** Indicates the application needs the pbuf payload to be in one piece */ 141 #define PBUF_ALLOC_FLAG_DATA_CONTIGUOUS 0x0200 142 143 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP 0x00 144 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF 0x01 145 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL 0x02 146 /** First pbuf allocation type for applications */ 147 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MIN 0x03 148 /** Last pbuf allocation type for applications */ 149 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MAX PBUF_TYPE_ALLOC_SRC_MASK 150 151 /** 152 * @ingroup pbuf 153 * Enumeration of pbuf types 154 */ 155 typedef enum { 156 /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload 157 are allocated in one piece of contiguous memory (so the first payload byte 158 can be calculated from struct pbuf). 159 pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might 160 change in future versions). 161 This should be used for all OUTGOING packets (TX).*/ 162 PBUF_RAM = (PBUF_ALLOC_FLAG_DATA_CONTIGUOUS | PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS | PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP), 163 /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in 164 totally different memory areas. Since it points to ROM, payload does not 165 have to be copied when queued for transmission. */ 166 PBUF_ROM = PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF, 167 /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change 168 so it has to be duplicated when queued before transmitting, depending on 169 who has a 'ref' to it. */ 170 PBUF_REF = (PBUF_TYPE_FLAG_DATA_VOLATILE | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF), 171 /** pbuf payload refers to RAM. This one comes from a pool and should be used 172 for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct 173 pbuf and its payload are allocated in one piece of contiguous memory (so 174 the first payload byte can be calculated from struct pbuf). 175 Don't use this for TX, if the pool becomes empty e.g. because of TCP queuing, 176 you are unable to receive TCP acks! */ 177 PBUF_POOL = (PBUF_ALLOC_FLAG_RX | PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL) 178 } pbuf_type; 179 #define LWIP_MEM_DMA_ALIGN_SIZE(size) (((size) + (MEM_MALLOC_DMA_ALIGN) - 1) & ~(u32_t)((MEM_MALLOC_DMA_ALIGN) - 1)) 180 #if (MEM_MALLOC_DMA_ALIGN != 1) 181 struct pbuf_dma_info { 182 void *dma; 183 /** Pointer to the MAC header in the buffer, used by the driver. */ 184 void *mac_header; 185 186 atomic_t dma_ref; 187 u16_t dma_len; 188 /** Indicates the link layer data totlen, used by the driver. */ 189 u16_t link_len; 190 }; 191 #endif 192 193 /** Indicates that the data of the packet must be immediately passed to the application. */ 194 #define PBUF_FLAG_PUSH 0x01U 195 /** Indicates that this is a custom pbuf. pbuf_free calls pbuf_custom->custom_free_function() 196 when the last reference is released (custom PBUF_RAM cannot be trimmed). */ 197 #define PBUF_FLAG_IS_CUSTOM 0x02U 198 /** Indicates that this pbuf is UDP multicast to be looped back. */ 199 #define PBUF_FLAG_MCASTLOOP 0x04U 200 /** Indicates that this pbuf was received as link-level broadcast. */ 201 #define PBUF_FLAG_LLBCAST 0x08U 202 /** Indicates that this pbuf was received as link-level multicast. */ 203 #define PBUF_FLAG_LLMCAST 0x10U 204 /** Indicates that this pbuf includes a TCP FIN flag. */ 205 #define PBUF_FLAG_TCP_FIN 0x20U 206 /** Flag to denote presence of for HBH-RPI. */ 207 #define PBUF_FLAG_RPI 0x40U 208 209 /** Flag to denote presence of space for HBH. */ 210 #define PBUF_FLAG_HBH_SPACE 0x80U 211 /* NETIF DRIVER STATUS CHANGE BEGIN */ 212 #if DRIVER_STATUS_CHECK 213 /** Indicates this pbuf is from DHCP application. */ 214 #define PBUF_FLAG_DHCP_BUF 0x80U 215 #endif 216 217 #define PBUF_FLAG_HOST 0x100U 218 #define PBUF_FLAG_OUTGOING 0x200U 219 220 #if LWIP_SO_DONTROUTE 221 /** indicates the destination of this pbuf located on directly attached link */ 222 #define PBUF_FLAG_IS_LINK_ONLY 0x400U 223 #endif /* LWIP_SO_DONTROUTE */ 224 225 /** indicates this pbuf need to be sent nonsecure manner */ 226 #define PBUF_FLAG_WITH_ENCRYPTION 0x400U 227 228 #if LWIP_IPV6 && (LWIP_RPL || LWIP_RIPPLE) 229 #define PBUF_FLAG_6LO_PKT 0x1000U 230 #endif /* LWIP_IPV6 && (LWIP_RPL || LWIP_RIPPLE) */ 231 232 #define PBUF_FLAG_CTRL_PKT 0x2000U 233 234 /** Indicates the main packet buffer struct. */ 235 struct pbuf { 236 /** Indicates the next pbuf in singly-linked pbuf chain. */ 237 struct pbuf *next; 238 239 /** Indicates a pointer to the actual data in the buffer. */ 240 void *payload; 241 242 /** 243 * Indicates the total length of the buffer and all next buffers in chain 244 * belonging to the same packet. 245 * 246 * For non-queue packet chains this is the invariant: 247 * p->tot_len == p->len + (p->next? p->next->tot_len: 0) 248 */ 249 u16_t tot_len; 250 251 /** Indicates the length of the buffer. */ 252 u16_t len; 253 254 struct pbuf *list; 255 256 /** 257 * Indicates the reference count. This is always equal to the number of pointers 258 * that refer to this pbuf. The pointers can be pointers from an application, 259 * the stack itself, or pbuf->next pointers from a chain. 260 */ 261 atomic_t ref; 262 #if (MEM_MALLOC_DMA_ALIGN != 1) 263 struct pbuf_dma_info *dma_info; 264 #endif 265 #if MEM_PBUF_RAM_SIZE_LIMIT 266 u16_t malloc_len; 267 #endif 268 269 /** Indicates miscellaneous flags. */ 270 u16_t flags; 271 /** Indicates pbuf_type as u8_t instead of enum to save space. */ 272 u16_t type_internal; /* pbuf_type */ 273 274 /** For incoming packets, this contains the input netif's index */ 275 u8_t if_idx; 276 277 #if LWIP_RIPPLE 278 u8_t pkt_up; 279 u8_t pkt_flags; 280 #endif 281 #if LWIP_RIPPLE && defined(LWIP_NA_PROXY) && LWIP_NA_PROXY 282 u8_t na_proxy; 283 #endif 284 #if LWIP_IPV6 285 #if LWIP_RPL || LWIP_RIPPLE 286 #if LWIP_USE_L2_METRICS 287 u8_t mac_address[NETIF_MAX_HWADDR_LEN]; 288 s8_t pkt_rssi; 289 u8_t pkt_lqi; 290 #endif 291 #endif 292 #endif 293 294 #if LWIP_SO_PRIORITY 295 prio_t priority; 296 #endif /* LWIP_SO_PRIORITY */ 297 298 #if MEM_PBUF_RAM_SIZE_LIMIT 299 #if LWIP_SO_PRIORITY 300 #if LWIP_PLC 301 u8_t pad[2]; 302 #else /* LWIP_PLC */ 303 u8_t pad[1]; 304 #endif /* LWIP_PLC */ 305 #else /* LWIP_SO_PRIORITY */ 306 u8_t pad[2]; 307 #endif /* LWIP_SO_PRIORITY */ 308 #else /* MEM_PBUF_RAM_SIZE_LIMIT */ 309 #if LWIP_SO_PRIORITY 310 #if (LWIP_PLC == 0) 311 u8_t pad[3]; 312 #endif /* LWIP_PLC == 0 */ 313 #endif /* LWIP_SO_PRIORITY */ 314 #endif /* MEM_PBUF_RAM_SIZE_LIMIT */ 315 }; 316 317 /** Helper struct for const-correctness only. 318 * The purpose of this struct is to provide a const payload pointer 319 * for PBUF_ROM type. 320 */ 321 struct pbuf_rom { 322 /** Indicates the next pbuf in singly linked pbuf chain. */ 323 struct pbuf *next; 324 325 /** Indicates a pointer to the actual data in the buffer. */ 326 const void *payload; 327 }; 328 329 #if LWIP_SUPPORT_CUSTOM_PBUF 330 /** Indicates the prototype for a function to free a custom pbuf. */ 331 typedef void (*pbuf_free_custom_fn)(struct pbuf *p); 332 333 /** Indicates a custom pbuf. This is similar to a pbuf, but following a function pointer to free it. */ 334 struct pbuf_custom { 335 /** Indicates the actual pbuf. */ 336 struct pbuf pbuf; 337 /** This function is called when pbuf_free deallocates this pbuf(_custom) */ 338 pbuf_free_custom_fn custom_free_function; 339 }; 340 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */ 341 342 /** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */ 343 #ifndef PBUF_POOL_FREE_OOSEQ 344 #define PBUF_POOL_FREE_OOSEQ 1 345 #endif /* PBUF_POOL_FREE_OOSEQ */ 346 #if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ 347 extern volatile u8_t pbuf_free_ooseq_pending; 348 void pbuf_free_ooseq(void); 349 /** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ() 350 at regular intervals from main level to check if ooseq pbufs need to be 351 freed! */ 352 #define PBUF_CHECK_FREE_OOSEQ() do { if (pbuf_free_ooseq_pending) { \ 353 /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \ 354 ooseq queued pbufs now */ \ 355 pbuf_free_ooseq(); } }while (0) 356 #else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */ 357 /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */ 358 #define PBUF_CHECK_FREE_OOSEQ() 359 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */ 360 361 /* Initializes the pbuf module. This call is empty for now, but may not be in future. */ 362 #define pbuf_init() 363 364 #define pbuf_set_encypted(pbuffer) \ 365 pbuffer->flags |= PBUF_FLAG_WITH_ENCRYPTION 366 367 #if LWIP_IPV6 368 #if LWIP_RPL || LWIP_RIPPLE 369 #if LWIP_USE_L2_METRICS 370 #define PBUF_SET_RSSI(pbuffer, rssi) \ 371 pbuffer->pkt_rssi = rssi 372 373 #define PBUF_GET_RSSI(pbuffer) \ 374 pbuffer->pkt_rssi 375 376 #define PBUF_SET_LQI(pbuffer, lqi) \ 377 pbuffer->pkt_lqi = lqi 378 379 #define PBUF_GET_LQI(pbuffer) \ 380 pbuffer->pkt_lqi 381 #endif /* LWIP_USE_L2_METRICS */ 382 #endif /* LWIP_RPL || LWIP_RIPPLE */ 383 #endif /* LWIP_IPV6 */ 384 385 u8_t pbuf_ram_in_deflation(void); 386 struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type); 387 struct pbuf *pbuf_alloc_for_rx(pbuf_layer layer, u16_t length); 388 389 #if LWIP_SUPPORT_CUSTOM_PBUF 390 struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type, 391 struct pbuf_custom *p, void *payload_mem, 392 u16_t payload_mem_len); 393 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */ 394 void pbuf_realloc(struct pbuf *p, u16_t size); 395 #define pbuf_get_allocsrc(p) ((p)->type_internal & PBUF_TYPE_ALLOC_SRC_MASK) 396 #define pbuf_match_allocsrc(p, type) (pbuf_get_allocsrc(p) == ((type) & PBUF_TYPE_ALLOC_SRC_MASK)) 397 #define pbuf_match_type(p, type) pbuf_match_allocsrc(p, type) 398 u8_t pbuf_header(struct pbuf *p, s16_t header_size); 399 u8_t pbuf_header_force(struct pbuf *p, s16_t header_size); 400 u8_t pbuf_add_header(struct pbuf *p, size_t header_size_increment); 401 u8_t pbuf_add_header_force(struct pbuf *p, size_t header_size_increment); 402 u8_t pbuf_remove_header(struct pbuf *p, size_t header_size); 403 struct pbuf *pbuf_free_header(struct pbuf *q, u16_t size); 404 void pbuf_ref(struct pbuf *p); 405 u8_t pbuf_free(struct pbuf *p); 406 u16_t pbuf_clen(const struct pbuf *p); 407 void pbuf_cat(struct pbuf *head, struct pbuf *tail); 408 void pbuf_chain(struct pbuf *head, struct pbuf *tail); 409 #if LWIP_API_RICH 410 /** 411 * Dechains the first pbuf from its succeeding pbufs in the chain. This function makes p->tot_len field equal to p->len. 412 * @param[in] p Indicates the pbuf to dechain. 413 * @return Returns the remainder of the pbuf chain, or NULL if it was de-allocated. 414 * @note 415 * - Do not call this function on a packet queue. 416 * - The PBUF_API macro must be enabled by the application in case the pbuf APIs are 417 * directly used by the application code. This macro enables NULL validations and can have a performance impact. 418 */ 419 struct pbuf *pbuf_dechain(struct pbuf *p); 420 #endif /* LWIP_API_RICH */ 421 err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from); 422 u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset); 423 #if LWIP_IPV6_DHCP6 424 void *pbuf_get_contiguous(const struct pbuf *p, void *buffer, size_t bufsize, u16_t len, u16_t offset); 425 #endif /* LWIP_IPV6_DHCP6 */ 426 err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len); 427 /** 428 * @ingroup pbuf 429 * @brief This function is the same as pbuf_take(), but puts data at an offset. 430 * 431 * @param buf Indicates the pbuf to fill with data. 432 * @param dataptr Indicates the application supplied data buffer. 433 * @param len Indicates the length of the application supplied data buffer. 434 * @param offset Indicates the offset in pbuf to copy dataptr to. 435 * 436 * @return ERR_OK if successful, ERR_MEM if the pbuf is not big enough. 437 * @note The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly used by 438 * the application code. This macro enables NULL validations and can have a performance impact. 439 */ 440 err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset); 441 struct pbuf *pbuf_skip(struct pbuf *in, u16_t in_offset, u16_t *out_offset); 442 #if LWIP_API_RICH 443 /** 444 * @ingroup pbuf 445 * @brief 446 * Creates a single pbuf from a queue of pbufs. This function either frees or returns the pbuf 'p'. 447 * Therefore, the caller must check the result. 448 * 449 * @param p the Indicates the source pbuf. 450 * @param layer Indicates the pbuf_layer of the new pbuf. 451 * 452 * @return Returns a new, single pbuf (p->next is NULL) or returns the old pbuf if allocation fails. 453 * @note The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly used 454 * by the application code. This macro enables NULL validations and can have a performance impact. 455 */ 456 struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer); 457 #endif /* LWIP_API_RICH */ 458 struct pbuf *pbuf_clone(pbuf_layer l, pbuf_type type, struct pbuf *p); 459 #if (MEM_MALLOC_DMA_ALIGN != 1) 460 #if LWIP_API_RICH 461 struct pbuf *pbuf_dma_alloc(u16_t len); 462 err_t pbuf_dma_ref(struct pbuf_dma_info *dma_info); 463 #endif /* LWIP_API_RICH */ 464 void pbuf_dma_free(struct pbuf_dma_info *dma_info); 465 #endif 466 467 #if LWIP_CHECKSUM_ON_COPY 468 #if LWIP_API_RICH 469 err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr, 470 u16_t len, u16_t *chksum); 471 #endif /* LWIP_API_RICH */ 472 #endif /* LWIP_CHECKSUM_ON_COPY */ 473 #if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE 474 /** 475 * @ingroup pbuf 476 * @brief 477 * This method modifies a pbuf chain, so that its total length is 478 * smaller than 64K. The remainder of the original pbuf chain is stored 479 * in *rest. 480 * This function does not create new pbufs. Instead, it splits an existing chain 481 * in two parts. The total length of the modified packet queue will be 482 * smaller than 64K. This function does not support packet queues. 483 * 484 * @param[in] p Indicates the pbuf queue to be split. 485 * @param[in] rest Indicates the pointer to store the remainder (after the first 64K) of the original pbuf chain. 486 * @note 487 * The PBUF_API macro must be enabled by the application in case the pbuf APIs 488 * are directly used by the application code. This macro enables NULL validations and can have a performance impact. 489 */ 490 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest); 491 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */ 492 /** 493 * @ingroup pbuf 494 * @brief 495 * Gets one byte from the specified position in a pbuf. 496 * 497 * 498 * @param p Indicates the pbuf to parse. 499 * @param offset Indicates the offset into p of the byte to return. 500 * The offset must be set to a value less than p->tot_len. 501 * @return Returns a byte at an offset into p, or zero if offset >= p->tot_len. 502 */ 503 u8_t pbuf_get_at(const struct pbuf *p, u16_t offset); 504 /** 505 * @ingroup pbuf 506 * @brief Gets one byte from the specified position in a pbuf. 507 * 508 * @param p Indicates the pbuf to parse. 509 * @param offset Indicates the offset into p of the byte to return. 510 * @return Returns a byte at an offset into p [0..0xFF] or negative if offset >= p->tot_len. 511 */ 512 int pbuf_try_get_at(const struct pbuf *p, u16_t offset); 513 void pbuf_put_at(struct pbuf *p, u16_t offset, u8_t data); 514 #if LWIP_API_RICH 515 /** 516 * @ingroup pbuf 517 * @brief 518 * Compares pbuf contents at a specified offset with memory s2, both of length n. 519 * 520 * @param p Indicates the pbuf to compare. 521 * @param offset Indicates the offset into p at which to start comparing. 522 * @param s2 Indicates the buffer to compare. 523 * @param n Indicates the length of buffer to compare. 524 * @return Returns zero if equal, nonzero otherwise (0xffff if p is too short, diff offset+1 otherwise) 525 * @note The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly 526 * used by the application code. This macro enables NULL validations and can have a performance impact. 527 */ 528 u16_t pbuf_memcmp(const struct pbuf *p, u16_t offset, const void *s2, u16_t n); 529 /** 530 * @ingroup pbuf 531 * Finds the occurrence of mem (with length mem_len) in pbuf p, starting at offset 532 * start_offset. 533 * 534 * @param p Indicates the pbuf to search. The maximum length is 0xFFFE since 0xFFFF is used as 535 * return value 'not found'. 536 * @param mem Indicates the buffer contents to search for. 537 * @param mem_len Indicates the length of mem. 538 * @param start_offset Indicates the offset into p at which to start searching. 539 * @return Returns the index where mem was found in p, or returns 0xFFFF if mem was not found in p. 540 * @note The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly 541 * used by the application code. This macro enables NULL validations and can have a performance impact. 542 */ 543 u16_t pbuf_memfind(const struct pbuf *p, const void *mem, u16_t mem_len, u16_t start_offset); 544 545 /** 546 * Finds the occurrence of substr with length substr_len in pbuf p, starting at offset 547 * start_offset. 548 * 549 * @param p Indicates the pbuf to search. The maximum length is 0xFFFE since 0xFFFF is used as 550 * return value 'not found'. 551 * @param substr Indicates the string to search for in p, maximum length is 0xFFFE 552 * @return Returns 0xFFFF if substr was not found in p, or returns the index where it was found. 553 * @note The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly 554 * used by the application code. This macro enables NULL validations and can have a performance impact. 555 */ 556 u16_t pbuf_strstr(const struct pbuf *p, const char *substr); 557 #endif /* LWIP_API_RICH */ 558 559 #if MEM_PBUF_RAM_SIZE_LIMIT 560 /* 561 * Func Name: pbuf_ram_size_set 562 */ 563 /** 564 * @ingroup Buffer_Interfaces 565 * @pbrief 566 * This API is used to set the maximum buffer size of PBUF_RAM allocation. 567 * 568 * @param[in] ram_max_size Indicates the maximum RAM buffer size allowed. 569 * [The ram_max_size must be greater than PBUF_RAM_SIZE_MIN and less than 0x7FFFFFFF.] 570 * 571 * @returns 572 * Zero : On failure \n 573 * Non Zero value: Previous maximum RAM buffer size. 574 * @note 575 * The PBUF_API macro must be enabled by the application in case the pbuf APIs are 576 * directly used by the application code. This macro enables NULL validations and can have a performance impact. 577 */ 578 u32_t pbuf_ram_size_set(u32_t ram_max_size); 579 #ifdef LWIP_DEBUG 580 /* 581 * Func Name: pbuf_ram_display 582 */ 583 /** 584 * @ingroup Buffer_Interfaces 585 * @brief 586 * This API is used to display the pbuf RAM details. 587 * 588 * @par Parameter 589 * \n 590 * void 591 * @return 592 * void 593 * @note 594 * This API is enabled only if the LWIP_DEBUG macro is enabled. \n 595 * The PBUF_API macro must be enabled by the application in case the pbuf APIs are directly 596 used by the application code. This macro enables NULL validations and can have a performance impact. 597 */ 598 void pbuf_ram_display(void); 599 #endif 600 #endif 601 #if defined (__cplusplus) && __cplusplus 602 } 603 #endif 604 #endif /* LWIP_HDR_PBUF_H */ 605