minix/lib/liblwip/dist/src/include/lwip/pbuf.h

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