1/**
2 * @file
3 * pbuf API
4 */
5
6/*
7 * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
8 * All rights reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without modification,
11 * are permitted provided that the following conditions are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright notice,
14 *    this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 *    this list of conditions and the following disclaimer in the documentation
17 *    and/or other materials provided with the distribution.
18 * 3. The name of the author may not be used to endorse or promote products
19 *    derived from this software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30 * OF SUCH DAMAGE.
31 *
32 * This file is part of the lwIP TCP/IP stack.
33 *
34 * Author: Adam Dunkels <adam@sics.se>
35 *
36 */
37
38#ifndef LWIP_HDR_PBUF_H
39#define LWIP_HDR_PBUF_H
40
41#include "lwip/opt.h"
42#include "lwip/err.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/** LWIP_SUPPORT_CUSTOM_PBUF==1: Custom pbufs behave much like their pbuf type
49 * but they are allocated by external code (initialised by calling
50 * pbuf_alloced_custom()) and when pbuf_free gives up their last reference, they
51 * are freed by calling pbuf_custom->custom_free_function().
52 * Currently, the pbuf_custom code is only needed for one specific configuration
53 * of IP_FRAG, unless required by external driver/application code. */
54#ifndef LWIP_SUPPORT_CUSTOM_PBUF
55#define LWIP_SUPPORT_CUSTOM_PBUF ((IP_FRAG && !LWIP_NETIF_TX_SINGLE_PBUF) || (LWIP_IPV6 && LWIP_IPV6_FRAG))
56#endif
57
58/* @todo: We need a mechanism to prevent wasting memory in every pbuf
59   (TCP vs. UDP, IPv4 vs. IPv6: UDP/IPv4 packets may waste up to 28 bytes) */
60
61#define PBUF_TRANSPORT_HLEN 20
62#if LWIP_IPV6
63#define PBUF_IP_HLEN        40
64#else
65#define PBUF_IP_HLEN        20
66#endif
67
68/**
69 * @ingroup pbuf
70 * Enumeration of pbuf layers
71 */
72typedef enum {
73  /** Includes spare room for transport layer header, e.g. UDP header.
74   * Use this if you intend to pass the pbuf to functions like udp_send().
75   */
76  PBUF_TRANSPORT,
77  /** Includes spare room for IP header.
78   * Use this if you intend to pass the pbuf to functions like raw_send().
79   */
80  PBUF_IP,
81  /** Includes spare room for link layer header (ethernet header).
82   * Use this if you intend to pass the pbuf to functions like ethernet_output().
83   * @see PBUF_LINK_HLEN
84   */
85  PBUF_LINK,
86  /** Includes spare room for additional encapsulation header before ethernet
87   * headers (e.g. 802.11).
88   * Use this if you intend to pass the pbuf to functions like netif->linkoutput().
89   * @see PBUF_LINK_ENCAPSULATION_HLEN
90   */
91  PBUF_RAW_TX,
92  /** Use this for input packets in a netif driver when calling netif->input()
93   * in the most common case - ethernet-layer netif driver. */
94  PBUF_RAW
95} pbuf_layer;
96
97/**
98 * @ingroup pbuf
99 * Enumeration of pbuf types
100 */
101typedef enum {
102  /** pbuf data is stored in RAM, used for TX mostly, struct pbuf and its payload
103      are allocated in one piece of contiguous memory (so the first payload byte
104      can be calculated from struct pbuf).
105      pbuf_alloc() allocates PBUF_RAM pbufs as unchained pbufs (although that might
106      change in future versions).
107      This should be used for all OUTGOING packets (TX).*/
108  PBUF_RAM,
109  /** pbuf data is stored in ROM, i.e. struct pbuf and its payload are located in
110      totally different memory areas. Since it points to ROM, payload does not
111      have to be copied when queued for transmission. */
112  PBUF_ROM,
113  /** pbuf comes from the pbuf pool. Much like PBUF_ROM but payload might change
114      so it has to be duplicated when queued before transmitting, depending on
115      who has a 'ref' to it. */
116  PBUF_REF,
117  /** pbuf payload refers to RAM. This one comes from a pool and should be used
118      for RX. Payload can be chained (scatter-gather RX) but like PBUF_RAM, struct
119      pbuf and its payload are allocated in one piece of contiguous memory (so
120      the first payload byte can be calculated from struct pbuf).
121      Don't use this for TX, if the pool becomes empty e.g. because of TCP queuing,
122      you are unable to receive TCP acks! */
123  PBUF_POOL
124} pbuf_type;
125
126
127/** indicates this packet's data should be immediately passed to the application */
128#define PBUF_FLAG_PUSH      0x01U
129/** indicates this is a custom pbuf: pbuf_free calls pbuf_custom->custom_free_function()
130    when the last reference is released (plus custom PBUF_RAM cannot be trimmed) */
131#define PBUF_FLAG_IS_CUSTOM 0x02U
132/** indicates this pbuf is UDP multicast to be looped back */
133#define PBUF_FLAG_MCASTLOOP 0x04U
134/** indicates this pbuf was received as link-level broadcast */
135#define PBUF_FLAG_LLBCAST   0x08U
136/** indicates this pbuf was received as link-level multicast */
137#define PBUF_FLAG_LLMCAST   0x10U
138/** indicates this pbuf includes a TCP FIN flag */
139#define PBUF_FLAG_TCP_FIN   0x20U
140
141/** Main packet buffer struct */
142struct pbuf {
143  /** next pbuf in singly linked pbuf chain */
144  struct pbuf *next;
145
146  /** pointer to the actual data in the buffer */
147  void *payload;
148
149  /**
150   * total length of this buffer and all next buffers in chain
151   * belonging to the same packet.
152   *
153   * For non-queue packet chains this is the invariant:
154   * p->tot_len == p->len + (p->next? p->next->tot_len: 0)
155   */
156  u16_t tot_len;
157
158  /** length of this buffer */
159  u16_t len;
160
161  /** pbuf_type as u8_t instead of enum to save space */
162  u8_t /*pbuf_type*/ type;
163
164  /** misc flags */
165  u8_t flags;
166
167  /**
168   * the reference count always equals the number of pointers
169   * that refer to this pbuf. This can be pointers from an application,
170   * the stack itself, or pbuf->next pointers from a chain.
171   */
172  u16_t ref;
173};
174
175
176/** Helper struct for const-correctness only.
177 * The only meaning of this one is to provide a const payload pointer
178 * for PBUF_ROM type.
179 */
180struct pbuf_rom {
181  /** next pbuf in singly linked pbuf chain */
182  struct pbuf *next;
183
184  /** pointer to the actual data in the buffer */
185  const void *payload;
186};
187
188#if LWIP_SUPPORT_CUSTOM_PBUF
189/** Prototype for a function to free a custom pbuf */
190typedef void (*pbuf_free_custom_fn)(struct pbuf *p);
191
192/** A custom pbuf: like a pbuf, but following a function pointer to free it. */
193struct pbuf_custom {
194  /** The actual pbuf */
195  struct pbuf pbuf;
196  /** This function is called when pbuf_free deallocates this pbuf(_custom) */
197  pbuf_free_custom_fn custom_free_function;
198};
199#endif /* LWIP_SUPPORT_CUSTOM_PBUF */
200
201/** Define this to 0 to prevent freeing ooseq pbufs when the PBUF_POOL is empty */
202#ifndef PBUF_POOL_FREE_OOSEQ
203#define PBUF_POOL_FREE_OOSEQ 1
204#endif /* PBUF_POOL_FREE_OOSEQ */
205#if LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ
206extern volatile u8_t pbuf_free_ooseq_pending;
207void pbuf_free_ooseq(void);
208/** When not using sys_check_timeouts(), call PBUF_CHECK_FREE_OOSEQ()
209    at regular intervals from main level to check if ooseq pbufs need to be
210    freed! */
211#define PBUF_CHECK_FREE_OOSEQ() do { if(pbuf_free_ooseq_pending) { \
212  /* pbuf_alloc() reported PBUF_POOL to be empty -> try to free some \
213     ooseq queued pbufs now */ \
214  pbuf_free_ooseq(); }}while(0)
215#else /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ */
216  /* Otherwise declare an empty PBUF_CHECK_FREE_OOSEQ */
217  #define PBUF_CHECK_FREE_OOSEQ()
218#endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && NO_SYS && PBUF_POOL_FREE_OOSEQ*/
219
220/* Initializes the pbuf module. This call is empty for now, but may not be in future. */
221#define pbuf_init()
222
223struct pbuf *pbuf_alloc(pbuf_layer l, u16_t length, pbuf_type type);
224#if LWIP_SUPPORT_CUSTOM_PBUF
225struct pbuf *pbuf_alloced_custom(pbuf_layer l, u16_t length, pbuf_type type,
226                                 struct pbuf_custom *p, void *payload_mem,
227                                 u16_t payload_mem_len);
228#endif /* LWIP_SUPPORT_CUSTOM_PBUF */
229void pbuf_realloc(struct pbuf *p, u16_t size);
230u8_t pbuf_header(struct pbuf *p, s16_t header_size);
231u8_t pbuf_header_force(struct pbuf *p, s16_t header_size);
232void pbuf_ref(struct pbuf *p);
233u8_t pbuf_free(struct pbuf *p);
234u16_t pbuf_clen(const struct pbuf *p);
235void pbuf_cat(struct pbuf *head, struct pbuf *tail);
236void pbuf_chain(struct pbuf *head, struct pbuf *tail);
237struct pbuf *pbuf_dechain(struct pbuf *p);
238err_t pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from);
239u16_t pbuf_copy_partial(const struct pbuf *p, void *dataptr, u16_t len, u16_t offset);
240err_t pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len);
241err_t pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset);
242struct pbuf *pbuf_skip(struct pbuf* in, u16_t in_offset, u16_t* out_offset);
243struct pbuf *pbuf_coalesce(struct pbuf *p, pbuf_layer layer);
244#if LWIP_CHECKSUM_ON_COPY
245err_t pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
246                       u16_t len, u16_t *chksum);
247#endif /* LWIP_CHECKSUM_ON_COPY */
248#if LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE
249void pbuf_split_64k(struct pbuf *p, struct pbuf **rest);
250#endif /* LWIP_TCP && TCP_QUEUE_OOSEQ && LWIP_WND_SCALE */
251
252u8_t pbuf_get_at(const struct pbuf* p, u16_t offset);
253int pbuf_try_get_at(const struct pbuf* p, u16_t offset);
254void pbuf_put_at(struct pbuf* p, u16_t offset, u8_t data);
255u16_t pbuf_memcmp(const struct pbuf* p, u16_t offset, const void* s2, u16_t n);
256u16_t pbuf_memfind(const struct pbuf* p, const void* mem, u16_t mem_len, u16_t start_offset);
257u16_t pbuf_strstr(const struct pbuf* p, const char* substr);
258
259#ifdef __cplusplus
260}
261#endif
262
263#endif /* LWIP_HDR_PBUF_H */
264