Lines Matching refs:pbuf
7 * @defgroup pbuf Packet buffers (PBUF)
10 * Packets are built from the pbuf data structure. It supports dynamic
16 * list. This is called a "pbuf chain".
21 * So, a packet queue consists of one or more pbuf chains, each of
25 * The differences between a pbuf chain and a packet queue are very
28 * The last pbuf of a packet has a ->tot_len field that equals the
30 * pbuf of a packet has a ->next field other than NULL, more packets
33 * Therefore, looping through a pbuf of a single packet, has an
36 * Example of custom pbuf usage: @ref zerocopyrx
73 #include "lwip/pbuf.h"
89 #define SIZEOF_STRUCT_PBUF LWIP_MEM_ALIGN_SIZE(sizeof(struct pbuf))
94 static const struct pbuf *
95 pbuf_skip_const(const struct pbuf *in, u16_t in_offset, u16_t *out_offset);
177 /* Initialize members of struct pbuf after allocation */
179 pbuf_init_alloced_pbuf(struct pbuf *p, void *payload, u16_t tot_len, u16_t len, pbuf_type type, u8_t flags)
192 * @ingroup pbuf
193 * Allocates a pbuf of the given type (possibly a chain for PBUF_POOL type).
195 * The actual memory allocated for the pbuf is determined by the
196 * layer at which the pbuf is allocated and the requested size
200 * @param length size of the pbuf's payload
201 * @param type this parameter decides how and where the pbuf
204 * - PBUF_RAM: buffer memory for pbuf is allocated as one large
206 * - PBUF_ROM: no buffer memory is allocated for the pbuf, even for
208 * by allocating another pbuf and chain in to the front of
209 * the ROM pbuf. It is assumed that the memory used is really
213 * - PBUF_REF: no buffer memory is allocated for the pbuf, even for
214 * protocol headers. It is assumed that the pbuf is only
215 * being used in a single thread. If the pbuf gets queued,
217 * - PBUF_POOL: the pbuf is allocated as a pbuf chain, with pbufs from
218 * the pbuf pool that is allocated during pbuf_init().
220 * @return the allocated pbuf. If multiple pbufs where allocated, this
221 * is the first pbuf of a pbuf chain.
223 struct pbuf *
226 struct pbuf *p;
236 struct pbuf *q, *last;
243 q = (struct pbuf *)memp_malloc(MEMP_PBUF_POOL);
256 LWIP_ASSERT("pbuf_alloc: pbuf q->payload properly aligned",
261 /* allocated head of pbuf chain (into p) */
264 /* make previous pbuf point to this pbuf */
283 /* If pbuf is to be allocated in RAM, allocate memory for it. */
284 p = (struct pbuf *)mem_malloc(alloc_len);
290 LWIP_ASSERT("pbuf_alloc: pbuf->payload properly aligned",
303 * @ingroup pbuf
304 * Allocates a pbuf for referenced data.
307 * The actual memory allocated for the pbuf is determined by the
308 * layer at which the pbuf is allocated and the requested size
312 * @param length size of the pbuf's payload
313 * @param type this parameter decides how and where the pbuf
320 * - PBUF_REF: It is assumed that the pbuf is only
321 * being used in a single thread. If the pbuf gets queued,
324 * @return the allocated pbuf.
326 struct pbuf *
329 struct pbuf *p;
331 /* only allocate memory for the pbuf structure */
332 p = (struct pbuf *)memp_malloc(MEMP_PBUF);
346 * @ingroup pbuf
347 * Initialize a custom pbuf (already allocated).
348 * Example of custom pbuf usage: @ref zerocopyrx
351 * @param length size of the pbuf's payload
352 * @param type type of the pbuf (only used to treat the pbuf accordingly, as
354 * @param p pointer to the custom pbuf to initialize (already allocated)
362 struct pbuf *
380 pbuf_init_alloced_pbuf(&p->pbuf, payload, length, length, type, PBUF_FLAG_IS_CUSTOM);
381 return &p->pbuf;
386 * @ingroup pbuf
387 * Shrink a pbuf chain to a desired length.
389 * @param p pbuf to shrink.
390 * @param new_len desired new length of pbuf chain
393 * be skipped and left unchanged. The new last pbuf in the chain will be
396 * @note If the pbuf is ROM/REF, only the ->tot_len and ->len fields are adjusted.
399 * @note Despite its name, pbuf_realloc cannot grow the size of a pbuf (chain).
402 pbuf_realloc(struct pbuf *p, u16_t new_len)
404 struct pbuf *q;
416 /* the pbuf chain grows by (new_len - p->tot_len) bytes
423 /* should this pbuf be kept? */
425 /* decrease remaining length by pbuf length */
429 /* proceed to next pbuf in chain */
433 /* we have now reached the new last pbuf (in q) */
434 /* rem_len == desired length for pbuf q */
443 /* reallocate and adjust the length of the pbuf that will be split */
444 q = (struct pbuf *)mem_trim(q, (mem_size_t)(((u8_t *)q->payload - (u8_t *)q) + rem_len));
447 /* adjust length fields for new last pbuf */
465 * @param p pbuf to change the header size.
473 pbuf_add_header_impl(struct pbuf *p, size_t header_size_increment, u8_t force)
495 /* pbuf types containing payloads? */
507 /* pbuf types referring to external payloads? */
521 /* modify pbuf fields */
534 * appears in the pbuf payload.
538 * @param p pbuf to change the header size.
540 * increases the size of the pbuf. New space is on the front.
551 pbuf_add_header(struct pbuf *p, size_t header_size_increment)
561 pbuf_add_header_force(struct pbuf *p, size_t header_size_increment)
570 * disappears in the pbuf payload.
574 * @param p pbuf to change the header size.
576 * decreases the size of the pbuf.
582 pbuf_remove_header(struct pbuf *p, size_t header_size_decrement)
596 /* Check that we aren't going to move off the end of the pbuf */
605 /* modify pbuf length fields */
616 pbuf_header_impl(struct pbuf *p, s16_t header_size_increment, u8_t force)
629 * (dis)appears in the pbuf payload.
633 * @param p pbuf to change the header size.
635 * increases the size of the pbuf. New space is on the front.
646 pbuf_header(struct pbuf *p, s16_t header_size_increment)
656 pbuf_header_force(struct pbuf *p, s16_t header_size_increment)
664 * @param size The number of bytes to remove from the beginning of the pbuf list.
668 * @return the new head pbuf
670 struct pbuf *
671 pbuf_free_header(struct pbuf *q, u16_t size)
673 struct pbuf *p = q;
677 struct pbuf *f = p;
691 * @ingroup pbuf
692 * Dereference a pbuf chain or queue and deallocate any no-longer-used
695 * Decrements the pbuf reference count. If it reaches zero, the pbuf is
698 * For a pbuf chain, this is repeated for each pbuf in the chain,
699 * up to the first pbuf which has a non-zero reference count after
703 * @param p The pbuf (chain) to be dereferenced.
709 * @note the reference counter of a pbuf equals the number of pointers
710 * that refer to the pbuf (or into the pbuf).
725 pbuf_free(struct pbuf *p)
728 struct pbuf *q;
754 /* decrease reference count (number of pointers to pbuf) */
757 /* this pbuf is no longer referenced to? */
759 /* remember next pbuf in chain for next iteration */
764 /* is this a custom pbuf? */
772 /* is this a pbuf from the pool? */
775 /* is this a ROM or RAM referencing pbuf? */
783 LWIP_ASSERT("invalid pbuf type", 0);
787 /* proceed to next pbuf */
789 /* p->ref > 0, this pbuf is still referenced to */
805 * @param p first pbuf of chain
809 pbuf_clen(const struct pbuf *p)
822 * @ingroup pbuf
823 * Increment the reference count of the pbuf.
825 * @param p pbuf to increase reference counter of
829 pbuf_ref(struct pbuf *p)
831 /* pbuf given? */
834 LWIP_ASSERT("pbuf ref overflow", p->ref > 0);
839 * @ingroup pbuf
840 * Concatenate two pbufs (each may be a pbuf chain) and take over
841 * the caller's reference of the tail pbuf.
843 * @note The caller MAY NOT reference the tail pbuf afterwards.
853 pbuf_cat(struct pbuf *h, struct pbuf *t)
855 struct pbuf *p;
860 /* proceed to last pbuf of chain */
865 /* { p is last pbuf of first h chain, p->next == NULL } */
866 LWIP_ASSERT("p->tot_len == p->len (of last pbuf in chain)", p->tot_len == p->len);
868 /* add total length of second chain to last pbuf total of first chain */
870 /* chain last pbuf of head (p) with first of tail (t) */
878 * @ingroup pbuf
879 * Chain two pbufs (or pbuf chains) together.
884 * @param h head pbuf (chain)
885 * @param t tail pbuf (chain)
890 * The ->next field of the last pbuf of the head chain is adjusted.
891 * The ->ref field of the first pbuf of the tail chain is adjusted.
895 pbuf_chain(struct pbuf *h, struct pbuf *t)
904 * Dechains the first pbuf from its succeeding pbufs in the chain.
907 * @param p pbuf to dechain
908 * @return remainder of the pbuf chain, or NULL if it was de-allocated.
911 struct pbuf *
912 pbuf_dechain(struct pbuf *p)
914 struct pbuf *q;
918 /* pbuf has successor in chain? */
924 /* decouple pbuf from remainder */
926 /* total length of pbuf p is its own length only */
943 * @ingroup pbuf
953 * @param p_to pbuf destination of the copy
954 * @param p_from pbuf source of the copy
956 * @return ERR_OK if pbuf was copied
961 pbuf_copy(struct pbuf *p_to, const struct pbuf *p_from)
971 * @ingroup pbuf
977 * @param p_to pbuf destination of the copy
978 * @param p_from pbuf source of the copy
980 * @param offset offset in destination pbuf where to copy to
988 pbuf_copy_partial_pbuf(struct pbuf *p_to, const struct pbuf *p_from, u16_t copy_len, u16_t offset)
1003 /* iterate through pbuf chain */
1049 * @ingroup pbuf
1053 * @param buf the pbuf from which to copy data
1061 pbuf_copy_partial(const struct pbuf *buf, void *dataptr, u16_t len, u16_t offset)
1063 const struct pbuf *p;
1071 /* Note some systems use byte copy if dataptr or one of the pbuf payload pointers are unaligned. */
1094 * @ingroup pbuf
1095 * Get part of a pbuf's payload as contiguous memory. The returned memory is
1096 * either a pointer into the pbuf's payload or, if split over multiple pbufs,
1099 * @param p the pbuf from which to copy data
1108 pbuf_get_contiguous(const struct pbuf *p, void *buffer, size_t bufsize, u16_t len, u16_t offset)
1110 const struct pbuf *q;
1120 /* all data in this pbuf, return zero-copy */
1125 /* copying failed: pbuf is too short */
1130 /* pbuf is too short (offset does not fit in) */
1136 * This method modifies a 'pbuf chain', so that its total length is
1137 * smaller than 64K. The remainder of the original pbuf chain is stored
1144 * @param p the pbuf queue to be split
1147 void pbuf_split_64k(struct pbuf *p, struct pbuf **rest)
1152 struct pbuf *i = p;
1153 struct pbuf *r = p->next;
1169 LWIP_ASSERT("tot_len/len mismatch in last pbuf",
1185 static const struct pbuf *
1186 pbuf_skip_const(const struct pbuf *in, u16_t in_offset, u16_t *out_offset)
1189 const struct pbuf *q = in;
1191 /* get the correct pbuf */
1203 * @ingroup pbuf
1204 * Skip a number of bytes at the start of a pbuf
1206 * @param in input pbuf
1208 * @param out_offset resulting offset in the returned pbuf
1209 * @return the pbuf in the queue where the offset is
1211 struct pbuf *
1212 pbuf_skip(struct pbuf *in, u16_t in_offset, u16_t *out_offset)
1214 const struct pbuf *out = pbuf_skip_const(in, in_offset, out_offset);
1215 return LWIP_CONST_CAST(struct pbuf *, out);
1219 * @ingroup pbuf
1220 * Copy application supplied data into a pbuf.
1223 * @param buf pbuf to fill with data
1227 * @return ERR_OK if successful, ERR_MEM if the pbuf is not big enough
1230 pbuf_take(struct pbuf *buf, const void *dataptr, u16_t len)
1232 struct pbuf *p;
1245 /* Note some systems use byte copy if dataptr or one of the pbuf payload pointers are unaligned. */
1247 LWIP_ASSERT("pbuf_take: invalid pbuf", p != NULL);
1250 /* this pbuf cannot hold all remaining data */
1263 * @ingroup pbuf
1266 * @param buf pbuf to fill with data
1269 * @param offset offset in pbuf where to copy dataptr to
1271 * @return ERR_OK if successful, ERR_MEM if the pbuf is not big enough
1274 pbuf_take_at(struct pbuf *buf, const void *dataptr, u16_t len, u16_t offset)
1277 struct pbuf *q = pbuf_skip(buf, offset, &target_offset);
1279 /* return requested data if pbuf is OK */
1283 /* copy the part that goes into the first pbuf */
1299 * @ingroup pbuf
1300 * Creates a single pbuf out of a queue of pbufs.
1302 * @remark: Either the source pbuf 'p' is freed by this function or the original
1303 * pbuf 'p' is returned, therefore the caller has to check the result!
1305 * @param p the source pbuf
1306 * @param layer pbuf_layer of the new pbuf
1308 * @return a new, single pbuf (p->next is NULL)
1309 * or the old pbuf if allocation fails
1311 struct pbuf *
1312 pbuf_coalesce(struct pbuf *p, pbuf_layer layer)
1314 struct pbuf *q;
1328 * @ingroup pbuf
1329 * Allocates a new pbuf of same length (via pbuf_alloc()) and copies the source
1330 * pbuf into this new pbuf (using pbuf_copy()).
1332 * @param layer pbuf_layer of the new pbuf
1333 * @param type this parameter decides how and where the pbuf should be allocated
1335 * @param p the source pbuf
1337 * @return a new pbuf or NULL if allocation fails
1339 struct pbuf *
1340 pbuf_clone(pbuf_layer layer, pbuf_type type, struct pbuf *p)
1342 struct pbuf *q;
1356 * Copies data into a single pbuf (*not* into a pbuf queue!) and updates
1359 * @param p the pbuf to copy data into
1361 * @param dataptr data to copy into the pbuf
1362 * @param len length of data to copy into the pbuf
1365 * within the (first) pbuf (no pbuf queues!)
1368 pbuf_fill_chksum(struct pbuf *p, u16_t start_offset, const void *dataptr,
1396 * @ingroup pbuf
1397 * Get one byte from the specified position in a pbuf
1400 * @param p pbuf to parse
1405 pbuf_get_at(const struct pbuf *p, u16_t offset)
1415 * @ingroup pbuf
1416 * Get one byte from the specified position in a pbuf
1418 * @param p pbuf to parse
1423 pbuf_try_get_at(const struct pbuf *p, u16_t offset)
1426 const struct pbuf *q = pbuf_skip_const(p, offset, &q_idx);
1428 /* return requested data if pbuf is OK */
1436 * @ingroup pbuf
1437 * Put one byte to the specified position in a pbuf
1440 * @param p pbuf to fill
1445 pbuf_put_at(struct pbuf *p, u16_t offset, u8_t data)
1448 struct pbuf *q = pbuf_skip(p, offset, &q_idx);
1450 /* write requested data if pbuf is OK */
1457 * @ingroup pbuf
1458 * Compare pbuf contents at specified offset with memory s2, both of length n
1460 * @param p pbuf to compare
1468 pbuf_memcmp(const struct pbuf *p, u16_t offset, const void *s2, u16_t n)
1471 const struct pbuf *q = p;
1474 /* pbuf long enough to perform check? */
1479 /* get the correct pbuf from chain. We know it succeeds because of p->tot_len check above. */
1485 /* return requested data if pbuf is OK */
1498 * @ingroup pbuf
1499 * Find occurrence of mem (with length mem_len) in pbuf p, starting at offset
1502 * @param p pbuf to search, maximum length is 0xFFFE since 0xFFFF is used as
1510 pbuf_memfind(const struct pbuf *p, const void *mem, u16_t mem_len, u16_t start_offset)
1526 * Find occurrence of substr with length substr_len in pbuf p, start at offset
1529 * the pbuf/source string!
1531 * @param p pbuf to search, maximum length is 0xFFFE since 0xFFFF is used as
1537 pbuf_strstr(const struct pbuf *p, const char *substr)