1/**
2 * @file
3 * Network buffer management
4 *
5 * @defgroup netbuf Network buffers
6 * @ingroup netconn
7 * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally
8 * to avoid copying data around.\n
9 * Buffers must not be shared accross multiple threads, all functions except
10 * netbuf_new() and netbuf_delete() are not thread-safe.
11 */
12
13/*
14 * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
15 * All rights reserved.
16 *
17 * Redistribution and use in source and binary forms, with or without modification,
18 * are permitted provided that the following conditions are met:
19 *
20 * 1. Redistributions of source code must retain the above copyright notice,
21 *    this list of conditions and the following disclaimer.
22 * 2. Redistributions in binary form must reproduce the above copyright notice,
23 *    this list of conditions and the following disclaimer in the documentation
24 *    and/or other materials provided with the distribution.
25 * 3. The name of the author may not be used to endorse or promote products
26 *    derived from this software without specific prior written permission.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
31 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
33 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
34 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
35 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
36 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
37 * OF SUCH DAMAGE.
38 *
39 * This file is part of the lwIP TCP/IP stack.
40 *
41 * Author: Adam Dunkels <adam@sics.se>
42 *
43 */
44
45#include "lwip/opt.h"
46
47#if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */
48
49#include "lwip/netbuf.h"
50#include "lwip/memp.h"
51
52#include <string.h>
53
54/**
55 * @ingroup netbuf
56 * Create (allocate) and initialize a new netbuf.
57 * The netbuf doesn't yet contain a packet buffer!
58 *
59 * @return a pointer to a new netbuf
60 *         NULL on lack of memory
61 */
62struct
63netbuf *netbuf_new(void)
64{
65  struct netbuf *buf;
66
67  buf = (struct netbuf *)memp_malloc(MEMP_NETBUF);
68  if (buf != NULL) {
69    memset(buf, 0, sizeof(struct netbuf));
70  }
71  return buf;
72}
73
74/**
75 * @ingroup netbuf
76 * Deallocate a netbuf allocated by netbuf_new().
77 *
78 * @param buf pointer to a netbuf allocated by netbuf_new()
79 */
80void
81netbuf_delete(struct netbuf *buf)
82{
83  if (buf != NULL) {
84    if (buf->p != NULL) {
85      pbuf_free(buf->p);
86      buf->p = buf->ptr = NULL;
87    }
88    memp_free(MEMP_NETBUF, buf);
89  }
90}
91
92/**
93 * @ingroup netbuf
94 * Allocate memory for a packet buffer for a given netbuf.
95 *
96 * @param buf the netbuf for which to allocate a packet buffer
97 * @param size the size of the packet buffer to allocate
98 * @return pointer to the allocated memory
99 *         NULL if no memory could be allocated
100 */
101void *
102netbuf_alloc(struct netbuf *buf, u16_t size)
103{
104  LWIP_ERROR("netbuf_alloc: invalid buf", (buf != NULL), return NULL;);
105
106  /* Deallocate any previously allocated memory. */
107  if (buf->p != NULL) {
108    pbuf_free(buf->p);
109  }
110  buf->p = pbuf_alloc(PBUF_TRANSPORT, size, PBUF_RAM);
111  if (buf->p == NULL) {
112     return NULL;
113  }
114  LWIP_ASSERT("check that first pbuf can hold size",
115             (buf->p->len >= size));
116  buf->ptr = buf->p;
117  return buf->p->payload;
118}
119
120/**
121 * @ingroup netbuf
122 * Free the packet buffer included in a netbuf
123 *
124 * @param buf pointer to the netbuf which contains the packet buffer to free
125 */
126void
127netbuf_free(struct netbuf *buf)
128{
129  LWIP_ERROR("netbuf_free: invalid buf", (buf != NULL), return;);
130  if (buf->p != NULL) {
131    pbuf_free(buf->p);
132  }
133  buf->p = buf->ptr = NULL;
134}
135
136/**
137 * @ingroup netbuf
138 * Let a netbuf reference existing (non-volatile) data.
139 *
140 * @param buf netbuf which should reference the data
141 * @param dataptr pointer to the data to reference
142 * @param size size of the data
143 * @return ERR_OK if data is referenced
144 *         ERR_MEM if data couldn't be referenced due to lack of memory
145 */
146err_t
147netbuf_ref(struct netbuf *buf, const void *dataptr, u16_t size)
148{
149  LWIP_ERROR("netbuf_ref: invalid buf", (buf != NULL), return ERR_ARG;);
150  if (buf->p != NULL) {
151    pbuf_free(buf->p);
152  }
153  buf->p = pbuf_alloc(PBUF_TRANSPORT, 0, PBUF_REF);
154  if (buf->p == NULL) {
155    buf->ptr = NULL;
156    return ERR_MEM;
157  }
158  ((struct pbuf_rom*)buf->p)->payload = dataptr;
159  buf->p->len = buf->p->tot_len = size;
160  buf->ptr = buf->p;
161  return ERR_OK;
162}
163
164/**
165 * @ingroup netbuf
166 * Chain one netbuf to another (@see pbuf_chain)
167 *
168 * @param head the first netbuf
169 * @param tail netbuf to chain after head, freed by this function, may not be reference after returning
170 */
171void
172netbuf_chain(struct netbuf *head, struct netbuf *tail)
173{
174  LWIP_ERROR("netbuf_chain: invalid head", (head != NULL), return;);
175  LWIP_ERROR("netbuf_chain: invalid tail", (tail != NULL), return;);
176  pbuf_cat(head->p, tail->p);
177  head->ptr = head->p;
178  memp_free(MEMP_NETBUF, tail);
179}
180
181/**
182 * @ingroup netbuf
183 * Get the data pointer and length of the data inside a netbuf.
184 *
185 * @param buf netbuf to get the data from
186 * @param dataptr pointer to a void pointer where to store the data pointer
187 * @param len pointer to an u16_t where the length of the data is stored
188 * @return ERR_OK if the information was retrieved,
189 *         ERR_BUF on error.
190 */
191err_t
192netbuf_data(struct netbuf *buf, void **dataptr, u16_t *len)
193{
194  LWIP_ERROR("netbuf_data: invalid buf", (buf != NULL), return ERR_ARG;);
195  LWIP_ERROR("netbuf_data: invalid dataptr", (dataptr != NULL), return ERR_ARG;);
196  LWIP_ERROR("netbuf_data: invalid len", (len != NULL), return ERR_ARG;);
197
198  if (buf->ptr == NULL) {
199    return ERR_BUF;
200  }
201  *dataptr = buf->ptr->payload;
202  *len = buf->ptr->len;
203  return ERR_OK;
204}
205
206/**
207 * @ingroup netbuf
208 * Move the current data pointer of a packet buffer contained in a netbuf
209 * to the next part.
210 * The packet buffer itself is not modified.
211 *
212 * @param buf the netbuf to modify
213 * @return -1 if there is no next part
214 *         1  if moved to the next part but now there is no next part
215 *         0  if moved to the next part and there are still more parts
216 */
217s8_t
218netbuf_next(struct netbuf *buf)
219{
220  LWIP_ERROR("netbuf_next: invalid buf", (buf != NULL), return -1;);
221  if (buf->ptr->next == NULL) {
222    return -1;
223  }
224  buf->ptr = buf->ptr->next;
225  if (buf->ptr->next == NULL) {
226    return 1;
227  }
228  return 0;
229}
230
231/**
232 * @ingroup netbuf
233 * Move the current data pointer of a packet buffer contained in a netbuf
234 * to the beginning of the packet.
235 * The packet buffer itself is not modified.
236 *
237 * @param buf the netbuf to modify
238 */
239void
240netbuf_first(struct netbuf *buf)
241{
242  LWIP_ERROR("netbuf_first: invalid buf", (buf != NULL), return;);
243  buf->ptr = buf->p;
244}
245
246#endif /* LWIP_NETCONN */
247