lwip_netbuf.c

00001 /**
00002  * @file
00003  * Network buffer management
00004  *
00005  * @defgroup netbuf Network buffers
00006  * @ingroup netconn
00007  * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally
00008  * to avoid copying data around.\n
00009  * Buffers must not be shared accross multiple threads, all functions except
00010  * netbuf_new() and netbuf_delete() are not thread-safe.
00011  */
00012 
00013 /*
00014  * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
00015  * All rights reserved.
00016  *
00017  * Redistribution and use in source and binary forms, with or without modification,
00018  * are permitted provided that the following conditions are met:
00019  *
00020  * 1. Redistributions of source code must retain the above copyright notice,
00021  *    this list of conditions and the following disclaimer.
00022  * 2. Redistributions in binary form must reproduce the above copyright notice,
00023  *    this list of conditions and the following disclaimer in the documentation
00024  *    and/or other materials provided with the distribution.
00025  * 3. The name of the author may not be used to endorse or promote products
00026  *    derived from this software without specific prior written permission.
00027  *
00028  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
00029  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00030  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00031  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00032  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00033  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
00036  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
00037  * OF SUCH DAMAGE.
00038  *
00039  * This file is part of the lwIP TCP/IP stack.
00040  *
00041  * Author: Adam Dunkels <adam@sics.se>
00042  *
00043  */
00044 
00045 #include "lwip/opt.h"
00046 
00047 #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */
00048 
00049 #include "lwip/netbuf.h"
00050 #include "lwip/memp.h"
00051 
00052 #include <string.h>
00053 
00054 /**
00055  * @ingroup netbuf
00056  * Create (allocate) and initialize a new netbuf.
00057  * The netbuf doesn't yet contain a packet buffer!
00058  *
00059  * @return a pointer to a new netbuf
00060  *         NULL on lack of memory
00061  */
00062 struct
00063 netbuf *netbuf_new(void)
00064 {
00065   struct netbuf *buf;
00066 
00067   buf = (struct netbuf *)memp_malloc(MEMP_NETBUF);
00068   if (buf != NULL) {
00069     memset(buf, 0, sizeof(struct netbuf));
00070   }
00071   return buf;
00072 }
00073 
00074 /**
00075  * @ingroup netbuf
00076  * Deallocate a netbuf allocated by netbuf_new().
00077  *
00078  * @param buf pointer to a netbuf allocated by netbuf_new()
00079  */
00080 void
00081 netbuf_delete(struct netbuf *buf)
00082 {
00083   if (buf != NULL) {
00084     if (buf->p != NULL) {
00085       pbuf_free(buf->p);
00086       buf->p = buf->ptr = NULL;
00087     }
00088     memp_free(MEMP_NETBUF, buf);
00089   }
00090 }
00091 
00092 /**
00093  * @ingroup netbuf
00094  * Allocate memory for a packet buffer for a given netbuf.
00095  *
00096  * @param buf the netbuf for which to allocate a packet buffer
00097  * @param size the size of the packet buffer to allocate
00098  * @return pointer to the allocated memory
00099  *         NULL if no memory could be allocated
00100  */
00101 void *
00102 netbuf_alloc(struct netbuf *buf, u16_t size)
00103 {
00104   LWIP_ERROR("netbuf_alloc: invalid buf", (buf != NULL), return NULL;);
00105 
00106   /* Deallocate any previously allocated memory. */
00107   if (buf->p != NULL) {
00108     pbuf_free(buf->p);
00109   }
00110   buf->p = pbuf_alloc(PBUF_TRANSPORT, size, PBUF_RAM);
00111   if (buf->p == NULL) {
00112     return NULL;
00113   }
00114   LWIP_ASSERT("check that first pbuf can hold size",
00115               (buf->p->len >= size));
00116   buf->ptr = buf->p;
00117   return buf->p->payload;
00118 }
00119 
00120 /**
00121  * @ingroup netbuf
00122  * Free the packet buffer included in a netbuf
00123  *
00124  * @param buf pointer to the netbuf which contains the packet buffer to free
00125  */
00126 void
00127 netbuf_free(struct netbuf *buf)
00128 {
00129   LWIP_ERROR("netbuf_free: invalid buf", (buf != NULL), return;);
00130   if (buf->p != NULL) {
00131     pbuf_free(buf->p);
00132   }
00133   buf->p = buf->ptr = NULL;
00134 #if LWIP_CHECKSUM_ON_COPY
00135   buf->flags = 0;
00136   buf->toport_chksum = 0;
00137 #endif /* LWIP_CHECKSUM_ON_COPY */
00138 }
00139 
00140 /**
00141  * @ingroup netbuf
00142  * Let a netbuf reference existing (non-volatile) data.
00143  *
00144  * @param buf netbuf which should reference the data
00145  * @param dataptr pointer to the data to reference
00146  * @param size size of the data
00147  * @return ERR_OK if data is referenced
00148  *         ERR_MEM if data couldn't be referenced due to lack of memory
00149  */
00150 err_t
00151 netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size)
00152 {
00153   LWIP_ERROR("netbuf_ref: invalid buf", (buf != NULL), return ERR_ARG;);
00154   if (buf->p != NULL) {
00155     pbuf_free(buf->p);
00156   }
00157   buf->p = pbuf_alloc(PBUF_TRANSPORT, 0, PBUF_REF);
00158   if (buf->p == NULL) {
00159     buf->ptr = NULL;
00160     return ERR_MEM;
00161   }
00162   ((struct pbuf_rom *)buf->p)->payload = dataptr;
00163   buf->p->len = buf->p->tot_len = size;
00164   buf->ptr = buf->p;
00165   return ERR_OK;
00166 }
00167 
00168 /**
00169  * @ingroup netbuf
00170  * Chain one netbuf to another (@see pbuf_chain)
00171  *
00172  * @param head the first netbuf
00173  * @param tail netbuf to chain after head, freed by this function, may not be reference after returning
00174  */
00175 void
00176 netbuf_chain(struct netbuf *head, struct netbuf *tail)
00177 {
00178   LWIP_ERROR("netbuf_chain: invalid head", (head != NULL), return;);
00179   LWIP_ERROR("netbuf_chain: invalid tail", (tail != NULL), return;);
00180   pbuf_cat(head->p, tail->p);
00181   head->ptr = head->p;
00182   memp_free(MEMP_NETBUF, tail);
00183 }
00184 
00185 /**
00186  * @ingroup netbuf
00187  * Get the data pointer and length of the data inside a netbuf.
00188  *
00189  * @param buf netbuf to get the data from
00190  * @param dataptr pointer to a void pointer where to store the data pointer
00191  * @param len pointer to an u16_t where the length of the data is stored
00192  * @return ERR_OK if the information was retrieved,
00193  *         ERR_BUF on error.
00194  */
00195 err_t
00196 netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len)
00197 {
00198   LWIP_ERROR("netbuf_data: invalid buf", (buf != NULL), return ERR_ARG;);
00199   LWIP_ERROR("netbuf_data: invalid dataptr", (dataptr != NULL), return ERR_ARG;);
00200   LWIP_ERROR("netbuf_data: invalid len", (len != NULL), return ERR_ARG;);
00201 
00202   if (buf->ptr == NULL) {
00203     return ERR_BUF;
00204   }
00205   *dataptr = buf->ptr->payload;
00206   *len = buf->ptr->len;
00207   return ERR_OK;
00208 }
00209 
00210 /**
00211  * @ingroup netbuf
00212  * Move the current data pointer of a packet buffer contained in a netbuf
00213  * to the next part.
00214  * The packet buffer itself is not modified.
00215  *
00216  * @param buf the netbuf to modify
00217  * @return -1 if there is no next part
00218  *         1  if moved to the next part but now there is no next part
00219  *         0  if moved to the next part and there are still more parts
00220  */
00221 s8_t
00222 netbuf_next(struct netbuf *buf)
00223 {
00224   LWIP_ERROR("netbuf_next: invalid buf", (buf != NULL), return -1;);
00225   if (buf->ptr->next == NULL) {
00226     return -1;
00227   }
00228   buf->ptr = buf->ptr->next;
00229   if (buf->ptr->next == NULL) {
00230     return 1;
00231   }
00232   return 0;
00233 }
00234 
00235 /**
00236  * @ingroup netbuf
00237  * Move the current data pointer of a packet buffer contained in a netbuf
00238  * to the beginning of the packet.
00239  * The packet buffer itself is not modified.
00240  *
00241  * @param buf the netbuf to modify
00242  */
00243 void
00244 netbuf_first(struct netbuf *buf)
00245 {
00246   LWIP_ERROR("netbuf_first: invalid buf", (buf != NULL), return;);
00247   buf->ptr = buf->p;
00248 }
00249 
00250 #endif /* LWIP_NETCONN */