pbuf.h

00001 /**
00002  * @file
00003  * pbuf API
00004  */
00005 
00006 /*
00007  * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
00008  * All rights reserved.
00009  *
00010  * Redistribution and use in source and binary forms, with or without modification,
00011  * are permitted provided that the following conditions are met:
00012  *
00013  * 1. Redistributions of source code must retain the above copyright notice,
00014  *    this list of conditions and the following disclaimer.
00015  * 2. Redistributions in binary form must reproduce the above copyright notice,
00016  *    this list of conditions and the following disclaimer in the documentation
00017  *    and/or other materials provided with the distribution.
00018  * 3. The name of the author may not be used to endorse or promote products
00019  *    derived from this software without specific prior written permission.
00020  *
00021  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
00022  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00023  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00024  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00025  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00026  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00027  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00028  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
00029  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
00030  * OF SUCH DAMAGE.
00031  *
00032  * This file is part of the lwIP TCP/IP stack.
00033  *
00034  * Author: Adam Dunkels <adam@sics.se>
00035  *
00036  */
00037 
00038 #ifndef LWIP_HDR_PBUF_H
00039 #define LWIP_HDR_PBUF_H
00040 
00041 #include "lwip/opt.h"
00042 #include "lwip/err.h"
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /** LWIP_SUPPORT_CUSTOM_PBUF==1: Custom pbufs behave much like their pbuf type
00049  * but they are allocated by external code (initialised by calling
00050  * pbuf_alloced_custom()) and when pbuf_free gives up their last reference, they
00051  * are freed by calling pbuf_custom->custom_free_function().
00052  * Currently, the pbuf_custom code is only needed for one specific configuration
00053  * of IP_FRAG, unless required by external driver/application code. */
00054 #ifndef LWIP_SUPPORT_CUSTOM_PBUF
00055 #define LWIP_SUPPORT_CUSTOM_PBUF ((IP_FRAG && !LWIP_NETIF_TX_SINGLE_PBUF) || (LWIP_IPV6 && LWIP_IPV6_FRAG))
00056 #endif
00057 
00058 /** @ingroup pbuf 
00059  * PBUF_NEEDS_COPY(p): return a boolean value indicating whether the given
00060  * pbuf needs to be copied in order to be kept around beyond the current call
00061  * stack without risking being corrupted. The default setting provides safety:
00062  * it will make a copy iof any pbuf chain that does not consist entirely of
00063  * PBUF_ROM type pbufs. For setups with zero-copy support, it may be redefined
00064  * to evaluate to true in all cases, for example. However, doing so also has an
00065  * effect on the application side: any buffers that are *not* copied must also
00066  * *not* be reused by the application after passing them to lwIP. For example,
00067  * when setting PBUF_NEEDS_COPY to (0), after using udp_send() with a PBUF_RAM
00068  * pbuf, the application must free the pbuf immediately, rather than reusing it
00069  * for other purposes. For more background information on this, see tasks #6735
00070  * and #7896, and bugs #11400 and #49914. */
00071 #ifndef PBUF_NEEDS_COPY
00072 #define PBUF_NEEDS_COPY(p)  ((p)->type_internal & PBUF_TYPE_FLAG_DATA_VOLATILE)
00073 #endif /* PBUF_NEEDS_COPY */
00074 
00075 /* @todo: We need a mechanism to prevent wasting memory in every pbuf
00076    (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */
00077 
00078 #define PBUF_TRANSPORT_HLEN 20
00079 #if LWIP_IPV6
00080 #define PBUF_IP_HLEN        40
00081 #else
00082 #define PBUF_IP_HLEN        20
00083 #endif
00084 
00085 /**
00086  * @ingroup pbuf
00087  * Enumeration of pbuf layers
00088  */
00089 typedef enum {
00090   /** Includes spare room for transport layer header, e.g. UDP header.
00091    * Use this if you intend to pass the pbuf to functions like udp_send().
00092    */
00093   PBUF_TRANSPORT = PBUF_LINK_ENCAPSULATION_HLEN + PBUF_LINK_HLEN + PBUF_IP_HLEN + PBUF_TRANSPORT_HLEN,
00094   /** Includes spare room for IP header.
00095    * Use this if you intend to pass the pbuf to functions like raw_send().
00096    */
00097   PBUF_IP = PBUF_LINK_ENCAPSULATION_HLEN + PBUF_LINK_HLEN + PBUF_IP_HLEN,
00098   /** Includes spare room for link layer header (ethernet header).
00099    * Use this if you intend to pass the pbuf to functions like ethernet_output().
00100    * @see PBUF_LINK_HLEN
00101    */
00102   PBUF_LINK = PBUF_LINK_ENCAPSULATION_HLEN + PBUF_LINK_HLEN,
00103   /** Includes spare room for additional encapsulation header before ethernet
00104    * headers (e.g. 802.11).
00105    * Use this if you intend to pass the pbuf to functions like netif->linkoutput().
00106    * @see PBUF_LINK_ENCAPSULATION_HLEN
00107    */
00108   PBUF_RAW_TX = PBUF_LINK_ENCAPSULATION_HLEN,
00109   /** Use this for input packets in a netif driver when calling netif->input()
00110    * in the most common case - ethernet-layer netif driver. */
00111   PBUF_RAW = 0
00112 } pbuf_layer;
00113 
00114 
00115 /* Base flags for pbuf_type definitions: */
00116 
00117 /** Indicates that the payload directly follows the struct pbuf.
00118  *  This makes @ref pbuf_header work in both directions. */
00119 #define PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS       0x80
00120 /** Indicates the data stored in this pbuf can change. If this pbuf needs
00121  * to be queued, it must be copied/duplicated. */
00122 #define PBUF_TYPE_FLAG_DATA_VOLATILE                0x40
00123 /** 4 bits are reserved for 16 allocation sources (e.g. heap, pool1, pool2, etc)
00124  * Internally, we use: 0=heap, 1=MEMP_PBUF, 2=MEMP_PBUF_POOL -> 13 types free*/
00125 #define PBUF_TYPE_ALLOC_SRC_MASK                    0x0F
00126 /** Indicates this pbuf is used for RX (if not set, indicates use for TX).
00127  * This information can be used to keep some spare RX buffers e.g. for
00128  * receiving TCP ACKs to unblock a connection) */
00129 #define PBUF_ALLOC_FLAG_RX                          0x0100
00130 /** Indicates the application needs the pbuf payload to be in one piece */
00131 #define PBUF_ALLOC_FLAG_DATA_CONTIGUOUS             0x0200
00132 
00133 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP           0x00
00134 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF      0x01
00135 #define PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL 0x02
00136 /** First pbuf allocation type for applications */
00137 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MIN            0x03
00138 /** Last pbuf allocation type for applications */
00139 #define PBUF_TYPE_ALLOC_SRC_MASK_APP_MAX            PBUF_TYPE_ALLOC_SRC_MASK
00140 
00141 /**
00142  * @ingroup pbuf
00143  * Enumeration of pbuf types
00144  */
00145 typedef enum {
00146   /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload
00147       are allocated in one piece of contiguous memory (so the first payload byte
00148       can be calculated from struct pbuf).
00149       pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might
00150       change in future versions).
00151       This should be used for all OUTGOING packets (TX).*/
00152   PBUF_RAM = (PBUF_ALLOC_FLAG_DATA_CONTIGUOUS | PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS | PBUF_TYPE_ALLOC_SRC_MASK_STD_HEAP),
00153   /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in
00154       totally different memory areas. Since it points to ROM, payload does not
00155       have to be copied when queued for transmission. */
00156   PBUF_ROM = PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF,
00157   /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change
00158       so it has to be duplicated when queued before transmitting, depending on
00159       who has a 'ref' to it. */
00160   PBUF_REF = (PBUF_TYPE_FLAG_DATA_VOLATILE | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF),
00161   /** pbuf payload refers to RAM. This one comes from a pool and should be used
00162       for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct
00163       pbuf and its payload are allocated in one piece of contiguous memory (so
00164       the first payload byte can be calculated from struct pbuf).
00165       Don't use this for TX, if the pool becomes empty e.g. because of TCP queuing,
00166       you are unable to receive TCP acks! */
00167   PBUF_POOL = (PBUF_ALLOC_FLAG_RX | PBUF_TYPE_FLAG_STRUCT_DATA_CONTIGUOUS | PBUF_TYPE_ALLOC_SRC_MASK_STD_MEMP_PBUF_POOL)
00168 } pbuf_type;
00169 
00170 
00171 /** indicates this packet's data should be immediately passed to the application */
00172 #define PBUF_FLAG_PUSH      0x01U
00173 /** indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function()
00174     when the last reference is released (plus custom PBUF_RAM cannot be trimmed) */
00175 #define PBUF_FLAG_IS_CUSTOM 0x02U
00176 /** indicates this pbuf is UDP multicast to be looped back */
00177 #define PBUF_FLAG_MCASTLOOP 0x04U
00178 /** indicates this pbuf was received as link-level broadcast */
00179 #define PBUF_FLAG_LLBCAST   0x08U
00180 /** indicates this pbuf was received as link-level multicast */
00181 #define PBUF_FLAG_LLMCAST   0x10U
00182 /** indicates this pbuf includes a TCP FIN flag */
00183 #define PBUF_FLAG_TCP_FIN   0x20U
00184 
00185 /** Main packet buffer struct */
00186 struct pbuf {
00187   /** next pbuf in singly linked pbuf chain */
00188   struct pbuf *next;
00189 
00190   /** pointer to the actual data in the buffer */
00191   void *payload;
00192 
00193   /**
00194    * total length of this buffer and all next buffers in chain
00195    * belonging to the same packet.
00196    *
00197    * For non-queue packet chains this is the invariant:
00198    * p->tot_len == p->len + (p->next? p->next->tot_len: 0)
00199    */
00200   u16_t tot_len;
00201 
00202   /** length of this buffer */
00203   u16_t len;
00204 
00205   /** a bit field indicating pbuf type and allocation sources
00206       (see PBUF_TYPE_FLAG_*, PBUF_ALLOC_FLAG_* and PBUF_TYPE_ALLOC_SRC_MASK)
00207     */
00208   u8_t type_internal;
00209 
00210   /** misc flags */
00211   u8_t flags;
00212 
00213   /**
00214    * the reference count always equals the number of pointers
00215    * that refer to this pbuf. This can be pointers from an application,
00216    * the stack itself, or pbuf->next pointers from a chain.
00217    */
00218   LWIP_PBUF_REF_T ref;
00219 
00220   /** For incoming packets, this contains the input netif's index */
00221   u8_t if_idx;
00222 };
00223 
00224 
00225 /** Helper struct for const-correctness only.
00226  * The only meaning of this one is to provide a const payload pointer
00227  * for PBUF_ROM type.
00228  */
00229 struct pbuf_rom {
00230   /** next pbuf in singly linked pbuf chain */
00231   struct pbuf *next;
00232 
00233   /** pointer to the actual data in the buffer */
00234   const void *payload;
00235 };
00236 
00237 #if LWIP_SUPPORT_CUSTOM_PBUF
00238 /** Prototype for a function to free a custom pbuf */
00239 typedef void (*pbuf_free_custom_fn)(struct pbuf *p);
00240 
00241 /** A custom pbuf: like a pbuf, but following a function pointer to free it. */
00242 struct pbuf_custom {
00243   /** The actual pbuf */
00244   struct pbuf pbuf;
00245   /** This function is called when pbuf_free deallocates this pbuf(_custom) */
00246   pbuf_free_custom_fn custom_free_function;
00247 };
00248 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
00249 
00250 /** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */
00251 #ifndef PBUF_POOL_FREE_OOSEQ
00252 #define PBUF_POOL_FREE_OOSEQ 1
00253 #endif /* PBUF_POOL_FREE_OOSEQ */
00254 #if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ
00255 extern volatile u8_t pbuf_free_ooseq_pending;
00256 void pbuf_free_ooseq(void);
00257 /** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ()
00258     at regular intervals from main level to check if ooseq pbufs need to be
00259     freed! */
00260 #define PBUF_CHECK_FREE_OOSEQ() do { if(pbuf_free_ooseq_pending) { \
00261   /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \
00262      ooseq queued pbufs now */ \
00263   pbuf_free_ooseq(); }}while(0)
00264 #else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */
00265   /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */
00266   #define PBUF_CHECK_FREE_OOSEQ()
00267 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ*/
00268 
00269 /* Initializes the pbuf module. This call is empty for now, but may not be in future. */
00270 #define pbuf_init()
00271 
00272 struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type);
00273 struct pbuf *pbuf_alloc_reference(void *payload, u16_t length, pbuf_type type);
00274 #if LWIP_SUPPORT_CUSTOM_PBUF
00275 struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type,
00276                                  struct pbuf_custom *p, void *payload_mem,
00277                                  u16_t payload_mem_len);
00278 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
00279 void pbuf_realloc(struct pbuf *p, u16_t size);
00280 #define pbuf_get_allocsrc(p)          ((p)->type_internal & PBUF_TYPE_ALLOC_SRC_MASK)
00281 #define pbuf_match_allocsrc(p, type)  (pbuf_get_allocsrc(p) == ((type) & PBUF_TYPE_ALLOC_SRC_MASK))
00282 #define pbuf_match_type(p, type)      pbuf_match_allocsrc(p, type)
00283 u8_t pbuf_header(struct pbuf *p, s16_t header_size);
00284 u8_t pbuf_header_force(struct pbuf *p, s16_t header_size);
00285 u8_t pbuf_add_header(struct pbuf *p, size_t header_size_increment);
00286 u8_t pbuf_add_header_force(struct pbuf *p, size_t header_size_increment);
00287 u8_t pbuf_remove_header(struct pbuf *p, size_t header_size);
00288 struct pbuf *pbuf_free_header(struct pbuf *q, u16_t size);
00289 void pbuf_ref(struct pbuf *p);
00290 u8_t pbuf_free(struct pbuf *p);
00291 u16_t pbuf_clen(const struct pbuf *p);
00292 void pbuf_cat(struct pbuf *head, struct pbuf *tail);
00293 void pbuf_chain(struct pbuf *head, struct pbuf *tail);
00294 struct pbuf *pbuf_dechain(struct pbuf *p);
00295 err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from);
00296 u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset);
00297 void *pbuf_get_contiguous(const struct pbuf *p, void *buffer, size_t bufsize, u16_t len, u16_t offset);
00298 err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len);
00299 err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset);
00300 struct pbuf *pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset);
00301 struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer);
00302 struct pbuf *pbuf_clone(pbuf_layer l, pbuf_type type, struct pbuf *p);
00303 #if LWIP_CHECKSUM_ON_COPY
00304 err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
00305                        u16_t len, u16_t *chksum);
00306 #endif /* LWIP_CHECKSUM_ON_COPY */
00307 #if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE
00308 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest);
00309 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
00310 
00311 u8_t pbuf_get_at(const struct pbuf* p, u16_t offset);
00312 int pbuf_try_get_at(const struct pbuf* p, u16_t offset);
00313 void pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data);
00314 u16_t pbuf_memcmp(const struct pbuf* p, u16_t offset, const void* s2, u16_t n);
00315 u16_t pbuf_memfind(const struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset);
00316 u16_t pbuf_strstr(const struct pbuf* p, const char* substr);
00317 
00318 #ifdef __cplusplus
00319 }
00320 #endif
00321 
00322 #endif /* LWIP_HDR_PBUF_H */