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 && !IP_FRAG_USES_STATIC_BUF && !LWIP_NETIF_TX_SINGLE_PBUF) || (LWIP_IPV6 && LWIP_IPV6_FRAG))
00056 #endif
00057 
00058 /* @todo: We need a mechanism to prevent wasting memory in every pbuf
00059    (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */
00060 
00061 #define PBUF_TRANSPORT_HLEN 20
00062 #if LWIP_IPV6
00063 #define PBUF_IP_HLEN        40
00064 #else
00065 #define PBUF_IP_HLEN        20
00066 #endif
00067 
00068 typedef enum {
00069   PBUF_TRANSPORT,
00070   PBUF_IP,
00071   PBUF_LINK,
00072   PBUF_RAW_TX,
00073   PBUF_RAW
00074 } pbuf_layer;
00075 
00076 /**
00077  * @ingroup pbuf
00078  * Enumeration of pbuf types
00079  */
00080 typedef enum {
00081   /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload
00082       are allocated in one piece of contiguous memory (so the first payload byte
00083       can be calculated from struct pbuf)
00084       pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might
00085       change in future versions) */
00086   PBUF_RAM,
00087   /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in
00088       totally different memory areas. Since it points to ROM, payload does not
00089       have to be copied when queued for transmission. */
00090   PBUF_ROM,
00091   /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change
00092       so it has to be duplicated when queued before transmitting, depending on
00093       who has a 'ref' to it. */
00094   PBUF_REF,
00095   /** pbuf payload refers to RAM. This one comes from a pool and should be used
00096       for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct
00097       pbuf and its payload are allocated in one piece of contiguous memory (so
00098       the first payload byte can be calculated from struct pbuf) */
00099   PBUF_POOL
00100 } pbuf_type;
00101 
00102 
00103 /** indicates this packet's data should be immediately passed to the application */
00104 #define PBUF_FLAG_PUSH      0x01U
00105 /** indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function()
00106     when the last reference is released (plus custom PBUF_RAM cannot be trimmed) */
00107 #define PBUF_FLAG_IS_CUSTOM 0x02U
00108 /** indicates this pbuf is UDP multicast to be looped back */
00109 #define PBUF_FLAG_MCASTLOOP 0x04U
00110 /** indicates this pbuf was received as link-level broadcast */
00111 #define PBUF_FLAG_LLBCAST   0x08U
00112 /** indicates this pbuf was received as link-level multicast */
00113 #define PBUF_FLAG_LLMCAST   0x10U
00114 /** indicates this pbuf includes a TCP FIN flag */
00115 #define PBUF_FLAG_TCP_FIN   0x20U
00116 
00117 /** Main packet buffer struct */
00118 struct pbuf {
00119   /** next pbuf in singly linked pbuf chain */
00120   struct pbuf *next;
00121 
00122   /** pointer to the actual data in the buffer */
00123   void *payload;
00124 
00125   /**
00126    * total length of this buffer and all next buffers in chain
00127    * belonging to the same packet.
00128    *
00129    * For non-queue packet chains this is the invariant:
00130    * p->tot_len == p->len + (p->next? p->next->tot_len: 0)
00131    */
00132   u16_t tot_len;
00133 
00134   /** length of this buffer */
00135   u16_t len;
00136 
00137   /** pbuf_type as u8_t instead of enum to save space */
00138   u8_t /*pbuf_type*/ type;
00139 
00140   /** misc flags */
00141   u8_t flags;
00142 
00143   /**
00144    * the reference count always equals the number of pointers
00145    * that refer to this pbuf. This can be pointers from an application,
00146    * the stack itself, or pbuf->next pointers from a chain.
00147    */
00148   u16_t ref;
00149 };
00150 
00151 
00152 /** Helper struct for const-correctness only.
00153  * The only meaning of this one is to provide a const payload pointer
00154  * for PBUF_ROM type.
00155  */
00156 struct pbuf_rom {
00157   /** next pbuf in singly linked pbuf chain */
00158   struct pbuf *next;
00159 
00160   /** pointer to the actual data in the buffer */
00161   const void *payload;
00162 };
00163 
00164 #if LWIP_SUPPORT_CUSTOM_PBUF
00165 /** Prototype for a function to free a custom pbuf */
00166 typedef void (*pbuf_free_custom_fn)(struct pbuf *p);
00167 
00168 /** A custom pbuf: like a pbuf, but following a function pointer to free it. */
00169 struct pbuf_custom {
00170   /** The actual pbuf */
00171   struct pbuf pbuf;
00172   /** This function is called when pbuf_free deallocates this pbuf(_custom) */
00173   pbuf_free_custom_fn custom_free_function;
00174 };
00175 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
00176 
00177 /** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */
00178 #ifndef PBUF_POOL_FREE_OOSEQ
00179 #define PBUF_POOL_FREE_OOSEQ 1
00180 #endif /* PBUF_POOL_FREE_OOSEQ */
00181 #if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ
00182 extern volatile u8_t pbuf_free_ooseq_pending;
00183 void pbuf_free_ooseq(void);
00184 /** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ()
00185     at regular intervals from main level to check if ooseq pbufs need to be
00186     freed! */
00187 #define PBUF_CHECK_FREE_OOSEQ() do { if(pbuf_free_ooseq_pending) { \
00188   /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \
00189      ooseq queued pbufs now */ \
00190   pbuf_free_ooseq(); }}while(0)
00191 #else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */
00192   /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */
00193   #define PBUF_CHECK_FREE_OOSEQ()
00194 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ*/
00195 
00196 /* Initializes the pbuf module. This call is empty for now, but may not be in future. */
00197 #define pbuf_init()
00198 
00199 struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type);
00200 #if LWIP_SUPPORT_CUSTOM_PBUF
00201 struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type,
00202                                  struct pbuf_custom *p, void *payload_mem,
00203                                  u16_t payload_mem_len);
00204 #endif /* LWIP_SUPPORT_CUSTOM_PBUF */
00205 void pbuf_realloc(struct pbuf *p, u16_t size);
00206 u8_t pbuf_header(struct pbuf *p, s16_t header_size);
00207 u8_t pbuf_header_force(struct pbuf *p, s16_t header_size);
00208 void pbuf_ref(struct pbuf *p);
00209 u8_t pbuf_free(struct pbuf *p);
00210 u8_t pbuf_clen(struct pbuf *p);
00211 void pbuf_cat(struct pbuf *head, struct pbuf *tail);
00212 void pbuf_chain(struct pbuf *head, struct pbuf *tail);
00213 struct pbuf *pbuf_dechain(struct pbuf *p);
00214 err_t pbuf_copy(struct pbuf *p_to, struct pbuf *p_from);
00215 u16_t pbuf_copy_partial(struct pbuf *p, void *dataptr, u16_t len, u16_t offset);
00216 err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len);
00217 err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset);
00218 struct pbuf *pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset);
00219 struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer);
00220 #if LWIP_CHECKSUM_ON_COPY
00221 err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
00222                        u16_t len, u16_t *chksum);
00223 #endif /* LWIP_CHECKSUM_ON_COPY */
00224 #if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE
00225 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest);
00226 #endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
00227 
00228 u8_t pbuf_get_at(struct pbuf* p, u16_t offset);
00229 void pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data);
00230 u16_t pbuf_memcmp(struct pbuf* p, u16_t offset, const void* s2, u16_t n);
00231 u16_t pbuf_memfind(struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset);
00232 u16_t pbuf_strstr(struct pbuf* p, const char* substr);
00233 
00234 #ifdef __cplusplus
00235 }
00236 #endif
00237 
00238 #endif /* LWIP_HDR_PBUF_H */