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 }
00135 
00136 /**
00137  * @ingroup netbuf
00138  * Let a netbuf reference existing (non-volatile) data.
00139  *
00140  * @param buf netbuf which should reference the data
00141  * @param dataptr pointer to the data to reference
00142  * @param size size of the data
00143  * @return ERR_OK if data is referenced
00144  *         ERR_MEM if data couldn't be referenced due to lack of memory
00145  */
00146 err_t
00147 netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size)
00148 {
00149   LWIP_ERROR("netbuf_ref: invalid buf", (buf != NULL), return ERR_ARG;);
00150   if (buf->p != NULL) {
00151     pbuf_free(buf->p);
00152   }
00153   buf->p = pbuf_alloc(PBUF_TRANSPORT, 0, PBUF_REF);
00154   if (buf->p == NULL) {
00155     buf->ptr = NULL;
00156     return ERR_MEM;
00157   }
00158   ((struct pbuf_rom*)buf->p)->payload = dataptr;
00159   buf->p->len = buf->p->tot_len = size;
00160   buf->ptr = buf->p;
00161   return ERR_OK;
00162 }
00163 
00164 /**
00165  * @ingroup netbuf
00166  * Chain one netbuf to another (@see pbuf_chain)
00167  *
00168  * @param head the first netbuf
00169  * @param tail netbuf to chain after head, freed by this function, may not be reference after returning
00170  */
00171 void
00172 netbuf_chain(struct netbuf *head, struct netbuf *tail)
00173 {
00174   LWIP_ERROR("netbuf_chain: invalid head", (head != NULL), return;);
00175   LWIP_ERROR("netbuf_chain: invalid tail", (tail != NULL), return;);
00176   pbuf_cat(head->p, tail->p);
00177   head->ptr = head->p;
00178   memp_free(MEMP_NETBUF, tail);
00179 }
00180 
00181 /**
00182  * @ingroup netbuf
00183  * Get the data pointer and length of the data inside a netbuf.
00184  *
00185  * @param buf netbuf to get the data from
00186  * @param dataptr pointer to a void pointer where to store the data pointer
00187  * @param len pointer to an u16_t where the length of the data is stored
00188  * @return ERR_OK if the information was retrieved,
00189  *         ERR_BUF on error.
00190  */
00191 err_t
00192 netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len)
00193 {
00194   LWIP_ERROR("netbuf_data: invalid buf", (buf != NULL), return ERR_ARG;);
00195   LWIP_ERROR("netbuf_data: invalid dataptr", (dataptr != NULL), return ERR_ARG;);
00196   LWIP_ERROR("netbuf_data: invalid len", (len != NULL), return ERR_ARG;);
00197 
00198   if (buf->ptr == NULL) {
00199     return ERR_BUF;
00200   }
00201   *dataptr = buf->ptr->payload;
00202   *len = buf->ptr->len;
00203   return ERR_OK;
00204 }
00205 
00206 /**
00207  * @ingroup netbuf
00208  * Move the current data pointer of a packet buffer contained in a netbuf
00209  * to the next part.
00210  * The packet buffer itself is not modified.
00211  *
00212  * @param buf the netbuf to modify
00213  * @return -1 if there is no next part
00214  *         1  if moved to the next part but now there is no next part
00215  *         0  if moved to the next part and there are still more parts
00216  */
00217 s8_t
00218 netbuf_next(struct netbuf *buf)
00219 {
00220   LWIP_ERROR("netbuf_next: invalid buf", (buf != NULL), return -1;);
00221   if (buf->ptr->next == NULL) {
00222     return -1;
00223   }
00224   buf->ptr = buf->ptr->next;
00225   if (buf->ptr->next == NULL) {
00226     return 1;
00227   }
00228   return 0;
00229 }
00230 
00231 /**
00232  * @ingroup netbuf
00233  * Move the current data pointer of a packet buffer contained in a netbuf
00234  * to the beginning of the packet.
00235  * The packet buffer itself is not modified.
00236  *
00237  * @param buf the netbuf to modify
00238  */
00239 void
00240 netbuf_first(struct netbuf *buf)
00241 {
00242   LWIP_ERROR("netbuf_first: invalid buf", (buf != NULL), return;);
00243   buf->ptr = buf->p;
00244 }
00245 
00246 #endif /* LWIP_NETCONN */