1 /** @file
2 * @brief Buffer management.
3 */
4
5 /*
6 * Copyright (c) 2015 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef __NET_BUF_H
11 #define __NET_BUF_H
12 #include <ble_types/types.h>
13 #include <ble_os_port.h>
14 #include <ble_default_config.h>
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 /**
21 * @brief Network buffer library
22 * @defgroup net_buf Network Buffer Library
23 * @ingroup networking
24 * @{
25 */
26
27 /* Alignment needed for various parts of the buffer definition */
28 #define __net_buf_align __aligned(sizeof(void *))
29
30 /**
31 * @def NET_BUF_SIMPLE_DEFINE
32 * @brief Define a net_buf_simple stack variable.
33 *
34 * This is a helper macro which is used to define a net_buf_simple object
35 * on the stack.
36 *
37 * @param _name Name of the net_buf_simple object.
38 * @param _size Maximum data storage for the buffer.
39 */
40 #define NET_BUF_SIMPLE_DEFINE(_name, _size) \
41 u8_t net_buf_data_##_name[_size]; \
42 struct net_buf_simple _name = { \
43 .data = net_buf_data_##_name, \
44 .len = 0, \
45 .size = _size, \
46 .__buf = net_buf_data_##_name, \
47 }
48
49 /**
50 * @def NET_BUF_SIMPLE_DEFINE_STATIC
51 * @brief Define a static net_buf_simple variable.
52 *
53 * This is a helper macro which is used to define a static net_buf_simple
54 * object.
55 *
56 * @param _name Name of the net_buf_simple object.
57 * @param _size Maximum data storage for the buffer.
58 */
59 #define NET_BUF_SIMPLE_DEFINE_STATIC(_name, _size) \
60 static __noinit u8_t net_buf_data_##_name[_size]; \
61 static struct net_buf_simple _name = { \
62 .data = net_buf_data_##_name, \
63 .len = 0, \
64 .size = _size, \
65 .__buf = net_buf_data_##_name, \
66 }
67
68 /**
69 * @brief Simple network buffer representation.
70 *
71 * This is a simpler variant of the net_buf object (in fact net_buf uses
72 * net_buf_simple internally). It doesn't provide any kind of reference
73 * counting, user data, dynamic allocation, or in general the ability to
74 * pass through kernel objects such as FIFOs.
75 *
76 * The main use of this is for scenarios where the meta-data of the normal
77 * net_buf isn't needed and causes too much overhead. This could be e.g.
78 * when the buffer only needs to be allocated on the stack or when the
79 * access to and lifetime of the buffer is well controlled and constrained.
80 */
81 struct net_buf_simple {
82 /** Pointer to the start of data in the buffer. */
83 u8_t *data;
84
85 /** Length of the data behind the data pointer. */
86 u16_t len;
87
88 /** Amount of data that this buffer can store. */
89 u16_t size;
90
91 /** Start of the data storage. Not to be accessed directly
92 * (the data pointer should be used instead).
93 */
94 u8_t *__buf;
95 };
96
97 /**
98 * @def NET_BUF_SIMPLE
99 * @brief Define a net_buf_simple stack variable and get a pointer to it.
100 *
101 * This is a helper macro which is used to define a net_buf_simple object on
102 * the stack and the get a pointer to it as follows:
103 *
104 * struct net_buf_simple *my_buf = NET_BUF_SIMPLE(10);
105 *
106 * After creating the object it needs to be initialized by calling
107 * net_buf_simple_init().
108 *
109 * @param _size Maximum data storage for the buffer.
110 *
111 * @return Pointer to stack-allocated net_buf_simple object.
112 */
113 #define NET_BUF_SIMPLE(_size) \
114 ((struct net_buf_simple *)(&(struct { \
115 struct net_buf_simple buf; \
116 u8_t data[_size]; \
117 }) { \
118 .buf.size = _size, \
119 }))
120
121 /**
122 * @brief Initialize a net_buf_simple object.
123 *
124 * This needs to be called after creating a net_buf_simple object using
125 * the NET_BUF_SIMPLE macro.
126 *
127 * @param buf Buffer to initialize.
128 * @param reserve_head Headroom to reserve.
129 */
net_buf_simple_init(struct net_buf_simple * buf,size_t reserve_head)130 static inline void net_buf_simple_init(struct net_buf_simple *buf,
131 size_t reserve_head)
132 {
133 if (!buf->__buf) {
134 buf->__buf = (u8_t *)buf + sizeof(*buf);
135 }
136
137 buf->data = buf->__buf + reserve_head;
138 buf->len = 0U;
139 }
140
141 /**
142 * @brief Initialize a net_buf_simple object with data.
143 *
144 * Initialized buffer object with external data.
145 *
146 * @param buf Buffer to initialize.
147 * @param data External data pointer
148 * @param size Amount of data the pointed data buffer if able to fit.
149 */
150 void net_buf_simple_init_with_data(struct net_buf_simple *buf,
151 void *data, size_t size);
152
153 /**
154 * @brief Reset buffer
155 *
156 * Reset buffer data so it can be reused for other purposes.
157 *
158 * @param buf Buffer to reset.
159 */
net_buf_simple_reset(struct net_buf_simple * buf)160 static inline void net_buf_simple_reset(struct net_buf_simple *buf)
161 {
162 buf->len = 0U;
163 buf->data = buf->__buf;
164 }
165
166 /**
167 * Clone buffer state, using the same data buffer.
168 *
169 * Initializes a buffer to point to the same data as an existing buffer.
170 * Allows operations on the same data without altering the length and
171 * offset of the original.
172 *
173 * @param original Buffer to clone.
174 * @param clone The new clone.
175 */
176 void net_buf_simple_clone(const struct net_buf_simple *original,
177 struct net_buf_simple *clone);
178
179 /**
180 * @brief Prepare data to be added at the end of the buffer
181 *
182 * Increments the data length of a buffer to account for more data
183 * at the end.
184 *
185 * @param buf Buffer to update.
186 * @param len Number of bytes to increment the length with.
187 *
188 * @return The original tail of the buffer.
189 */
190 void *net_buf_simple_add(struct net_buf_simple *buf, size_t len);
191
192 /**
193 * @brief Copy given number of bytes from memory to the end of the buffer
194 *
195 * Increments the data length of the buffer to account for more data at the
196 * end.
197 *
198 * @param buf Buffer to update.
199 * @param mem Location of data to be added.
200 * @param len Length of data to be added
201 *
202 * @return The original tail of the buffer.
203 */
204 void *net_buf_simple_add_mem(struct net_buf_simple *buf, const void *mem,
205 size_t len);
206
207 /**
208 * @brief Add (8-bit) byte at the end of the buffer
209 *
210 * Increments the data length of the buffer to account for more data at the
211 * end.
212 *
213 * @param buf Buffer to update.
214 * @param val byte value to be added.
215 *
216 * @return Pointer to the value added
217 */
218 u8_t *net_buf_simple_add_u8(struct net_buf_simple *buf, u8_t val);
219
220 /**
221 * @brief Add 16-bit value at the end of the buffer
222 *
223 * Adds 16-bit value in little endian format at the end of buffer.
224 * Increments the data length of a buffer to account for more data
225 * at the end.
226 *
227 * @param buf Buffer to update.
228 * @param val 16-bit value to be added.
229 */
230 void net_buf_simple_add_le16(struct net_buf_simple *buf, u16_t val);
231
232 /**
233 * @brief Add 16-bit value at the end of the buffer
234 *
235 * Adds 16-bit value in big endian format at the end of buffer.
236 * Increments the data length of a buffer to account for more data
237 * at the end.
238 *
239 * @param buf Buffer to update.
240 * @param val 16-bit value to be added.
241 */
242 void net_buf_simple_add_be16(struct net_buf_simple *buf, u16_t val);
243
244 /**
245 * @brief Add 24-bit value at the end of the buffer
246 *
247 * Adds 24-bit value in little endian format at the end of buffer.
248 * Increments the data length of a buffer to account for more data
249 * at the end.
250 *
251 * @param buf Buffer to update.
252 * @param val 24-bit value to be added.
253 */
254 void net_buf_simple_add_le24(struct net_buf_simple *buf, bt_u32_t val);
255
256 /**
257 * @brief Add 24-bit value at the end of the buffer
258 *
259 * Adds 24-bit value in big endian format at the end of buffer.
260 * Increments the data length of a buffer to account for more data
261 * at the end.
262 *
263 * @param buf Buffer to update.
264 * @param val 24-bit value to be added.
265 */
266 void net_buf_simple_add_be24(struct net_buf_simple *buf, bt_u32_t val);
267
268 /**
269 * @brief Add 32-bit value at the end of the buffer
270 *
271 * Adds 32-bit value in little endian format at the end of buffer.
272 * Increments the data length of a buffer to account for more data
273 * at the end.
274 *
275 * @param buf Buffer to update.
276 * @param val 32-bit value to be added.
277 */
278 void net_buf_simple_add_le32(struct net_buf_simple *buf, bt_u32_t val);
279
280 /**
281 * @brief Add 32-bit value at the end of the buffer
282 *
283 * Adds 32-bit value in big endian format at the end of buffer.
284 * Increments the data length of a buffer to account for more data
285 * at the end.
286 *
287 * @param buf Buffer to update.
288 * @param val 32-bit value to be added.
289 */
290 void net_buf_simple_add_be32(struct net_buf_simple *buf, bt_u32_t val);
291
292 /**
293 * @brief Add 48-bit value at the end of the buffer
294 *
295 * Adds 48-bit value in little endian format at the end of buffer.
296 * Increments the data length of a buffer to account for more data
297 * at the end.
298 *
299 * @param buf Buffer to update.
300 * @param val 48-bit value to be added.
301 */
302 void net_buf_simple_add_le48(struct net_buf_simple *buf, u64_t val);
303
304 /**
305 * @brief Add 48-bit value at the end of the buffer
306 *
307 * Adds 48-bit value in big endian format at the end of buffer.
308 * Increments the data length of a buffer to account for more data
309 * at the end.
310 *
311 * @param buf Buffer to update.
312 * @param val 48-bit value to be added.
313 */
314 void net_buf_simple_add_be48(struct net_buf_simple *buf, u64_t val);
315
316 /**
317 * @brief Add 64-bit value at the end of the buffer
318 *
319 * Adds 64-bit value in little endian format at the end of buffer.
320 * Increments the data length of a buffer to account for more data
321 * at the end.
322 *
323 * @param buf Buffer to update.
324 * @param val 64-bit value to be added.
325 */
326 void net_buf_simple_add_le64(struct net_buf_simple *buf, u64_t val);
327
328 /**
329 * @brief Add 64-bit value at the end of the buffer
330 *
331 * Adds 64-bit value in big endian format at the end of buffer.
332 * Increments the data length of a buffer to account for more data
333 * at the end.
334 *
335 * @param buf Buffer to update.
336 * @param val 64-bit value to be added.
337 */
338 void net_buf_simple_add_be64(struct net_buf_simple *buf, u64_t val);
339
340 /**
341 * @brief Push data to the beginning of the buffer.
342 *
343 * Modifies the data pointer and buffer length to account for more data
344 * in the beginning of the buffer.
345 *
346 * @param buf Buffer to update.
347 * @param len Number of bytes to add to the beginning.
348 *
349 * @return The new beginning of the buffer data.
350 */
351 void *net_buf_simple_push(struct net_buf_simple *buf, size_t len);
352
353 /**
354 * @brief Push 16-bit value to the beginning of the buffer
355 *
356 * Adds 16-bit value in little endian format to the beginning of the
357 * buffer.
358 *
359 * @param buf Buffer to update.
360 * @param val 16-bit value to be pushed to the buffer.
361 */
362 void net_buf_simple_push_le16(struct net_buf_simple *buf, u16_t val);
363
364 /**
365 * @brief Push 16-bit value to the beginning of the buffer
366 *
367 * Adds 16-bit value in big endian format to the beginning of the
368 * buffer.
369 *
370 * @param buf Buffer to update.
371 * @param val 16-bit value to be pushed to the buffer.
372 */
373 void net_buf_simple_push_be16(struct net_buf_simple *buf, u16_t val);
374
375 /**
376 * @brief Push 8-bit value to the beginning of the buffer
377 *
378 * Adds 8-bit value the beginning of the buffer.
379 *
380 * @param buf Buffer to update.
381 * @param val 8-bit value to be pushed to the buffer.
382 */
383 void net_buf_simple_push_u8(struct net_buf_simple *buf, u8_t val);
384
385 /**
386 * @brief Push 24-bit value to the beginning of the buffer
387 *
388 * Adds 24-bit value in little endian format to the beginning of the
389 * buffer.
390 *
391 * @param buf Buffer to update.
392 * @param val 24-bit value to be pushed to the buffer.
393 */
394 void net_buf_simple_push_le24(struct net_buf_simple *buf, bt_u32_t val);
395
396 /**
397 * @brief Push 24-bit value to the beginning of the buffer
398 *
399 * Adds 24-bit value in big endian format to the beginning of the
400 * buffer.
401 *
402 * @param buf Buffer to update.
403 * @param val 24-bit value to be pushed to the buffer.
404 */
405 void net_buf_simple_push_be24(struct net_buf_simple *buf, bt_u32_t val);
406
407 /**
408 * @brief Push 32-bit value to the beginning of the buffer
409 *
410 * Adds 32-bit value in little endian format to the beginning of the
411 * buffer.
412 *
413 * @param buf Buffer to update.
414 * @param val 32-bit value to be pushed to the buffer.
415 */
416 void net_buf_simple_push_le32(struct net_buf_simple *buf, bt_u32_t val);
417
418 /**
419 * @brief Push 32-bit value to the beginning of the buffer
420 *
421 * Adds 32-bit value in big endian format to the beginning of the
422 * buffer.
423 *
424 * @param buf Buffer to update.
425 * @param val 32-bit value to be pushed to the buffer.
426 */
427 void net_buf_simple_push_be32(struct net_buf_simple *buf, bt_u32_t val);
428
429 /**
430 * @brief Push 48-bit value to the beginning of the buffer
431 *
432 * Adds 48-bit value in little endian format to the beginning of the
433 * buffer.
434 *
435 * @param buf Buffer to update.
436 * @param val 48-bit value to be pushed to the buffer.
437 */
438 void net_buf_simple_push_le48(struct net_buf_simple *buf, u64_t val);
439
440 /**
441 * @brief Push 48-bit value to the beginning of the buffer
442 *
443 * Adds 48-bit value in big endian format to the beginning of the
444 * buffer.
445 *
446 * @param buf Buffer to update.
447 * @param val 48-bit value to be pushed to the buffer.
448 */
449 void net_buf_simple_push_be48(struct net_buf_simple *buf, u64_t val);
450
451 /**
452 * @brief Push 64-bit value to the beginning of the buffer
453 *
454 * Adds 64-bit value in little endian format to the beginning of the
455 * buffer.
456 *
457 * @param buf Buffer to update.
458 * @param val 64-bit value to be pushed to the buffer.
459 */
460 void net_buf_simple_push_le64(struct net_buf_simple *buf, u64_t val);
461
462 /**
463 * @brief Push 64-bit value to the beginning of the buffer
464 *
465 * Adds 64-bit value in big endian format to the beginning of the
466 * buffer.
467 *
468 * @param buf Buffer to update.
469 * @param val 64-bit value to be pushed to the buffer.
470 */
471 void net_buf_simple_push_be64(struct net_buf_simple *buf, u64_t val);
472
473 /**
474 * @brief Remove data from the beginning of the buffer.
475 *
476 * Removes data from the beginning of the buffer by modifying the data
477 * pointer and buffer length.
478 *
479 * @param buf Buffer to update.
480 * @param len Number of bytes to remove.
481 *
482 * @return New beginning of the buffer data.
483 */
484 void *net_buf_simple_pull(struct net_buf_simple *buf, size_t len);
485
486 /**
487 * @brief Remove data from the beginning of the buffer.
488 *
489 * Removes data from the beginning of the buffer by modifying the data
490 * pointer and buffer length.
491 *
492 * @param buf Buffer to update.
493 * @param len Number of bytes to remove.
494 *
495 * @return Pointer to the old location of the buffer data.
496 */
497 void *net_buf_simple_pull_mem(struct net_buf_simple *buf, size_t len);
498
499 /**
500 * @brief Remove a 8-bit value from the beginning of the buffer
501 *
502 * Same idea as with net_buf_simple_pull(), but a helper for operating
503 * on 8-bit values.
504 *
505 * @param buf A valid pointer on a buffer.
506 *
507 * @return The 8-bit removed value
508 */
509 u8_t net_buf_simple_pull_u8(struct net_buf_simple *buf);
510
511 /**
512 * @brief Remove and convert 16 bits from the beginning of the buffer.
513 *
514 * Same idea as with net_buf_simple_pull(), but a helper for operating
515 * on 16-bit little endian data.
516 *
517 * @param buf A valid pointer on a buffer.
518 *
519 * @return 16-bit value converted from little endian to host endian.
520 */
521 u16_t net_buf_simple_pull_le16(struct net_buf_simple *buf);
522
523 /**
524 * @brief Remove and convert 16 bits from the beginning of the buffer.
525 *
526 * Same idea as with net_buf_simple_pull(), but a helper for operating
527 * on 16-bit big endian data.
528 *
529 * @param buf A valid pointer on a buffer.
530 *
531 * @return 16-bit value converted from big endian to host endian.
532 */
533 u16_t net_buf_simple_pull_be16(struct net_buf_simple *buf);
534
535 /**
536 * @brief Remove and convert 24 bits from the beginning of the buffer.
537 *
538 * Same idea as with net_buf_simple_pull(), but a helper for operating
539 * on 24-bit little endian data.
540 *
541 * @param buf A valid pointer on a buffer.
542 *
543 * @return 24-bit value converted from little endian to host endian.
544 */
545 bt_u32_t net_buf_simple_pull_le24(struct net_buf_simple *buf);
546
547 /**
548 * @brief Remove and convert 24 bits from the beginning of the buffer.
549 *
550 * Same idea as with net_buf_simple_pull(), but a helper for operating
551 * on 24-bit big endian data.
552 *
553 * @param buf A valid pointer on a buffer.
554 *
555 * @return 24-bit value converted from big endian to host endian.
556 */
557 bt_u32_t net_buf_simple_pull_be24(struct net_buf_simple *buf);
558
559 /**
560 * @brief Remove and convert 32 bits from the beginning of the buffer.
561 *
562 * Same idea as with net_buf_simple_pull(), but a helper for operating
563 * on 32-bit little endian data.
564 *
565 * @param buf A valid pointer on a buffer.
566 *
567 * @return 32-bit value converted from little endian to host endian.
568 */
569 bt_u32_t net_buf_simple_pull_le32(struct net_buf_simple *buf);
570
571 /**
572 * @brief Remove and convert 32 bits from the beginning of the buffer.
573 *
574 * Same idea as with net_buf_simple_pull(), but a helper for operating
575 * on 32-bit big endian data.
576 *
577 * @param buf A valid pointer on a buffer.
578 *
579 * @return 32-bit value converted from big endian to host endian.
580 */
581 bt_u32_t net_buf_simple_pull_be32(struct net_buf_simple *buf);
582
583 /**
584 * @brief Remove and convert 48 bits from the beginning of the buffer.
585 *
586 * Same idea as with net_buf_simple_pull(), but a helper for operating
587 * on 48-bit little endian data.
588 *
589 * @param buf A valid pointer on a buffer.
590 *
591 * @return 48-bit value converted from little endian to host endian.
592 */
593 u64_t net_buf_simple_pull_le48(struct net_buf_simple *buf);
594
595 /**
596 * @brief Remove and convert 48 bits from the beginning of the buffer.
597 *
598 * Same idea as with net_buf_simple_pull(), but a helper for operating
599 * on 48-bit big endian data.
600 *
601 * @param buf A valid pointer on a buffer.
602 *
603 * @return 48-bit value converted from big endian to host endian.
604 */
605 u64_t net_buf_simple_pull_be48(struct net_buf_simple *buf);
606
607 /**
608 * @brief Remove and convert 64 bits from the beginning of the buffer.
609 *
610 * Same idea as with net_buf_simple_pull(), but a helper for operating
611 * on 64-bit little endian data.
612 *
613 * @param buf A valid pointer on a buffer.
614 *
615 * @return 64-bit value converted from little endian to host endian.
616 */
617 u64_t net_buf_simple_pull_le64(struct net_buf_simple *buf);
618
619 /**
620 * @brief Remove and convert 64 bits from the beginning of the buffer.
621 *
622 * Same idea as with net_buf_simple_pull(), but a helper for operating
623 * on 64-bit big endian data.
624 *
625 * @param buf A valid pointer on a buffer.
626 *
627 * @return 64-bit value converted from big endian to host endian.
628 */
629 u64_t net_buf_simple_pull_be64(struct net_buf_simple *buf);
630
631 /**
632 * @brief Get the tail pointer for a buffer.
633 *
634 * Get a pointer to the end of the data in a buffer.
635 *
636 * @param buf Buffer.
637 *
638 * @return Tail pointer for the buffer.
639 */
net_buf_simple_tail(struct net_buf_simple * buf)640 static inline u8_t *net_buf_simple_tail(struct net_buf_simple *buf)
641 {
642 return buf->data + buf->len;
643 }
644
645 /**
646 * @brief Check buffer headroom.
647 *
648 * Check how much free space there is in the beginning of the buffer.
649 *
650 * buf A valid pointer on a buffer
651 *
652 * @return Number of bytes available in the beginning of the buffer.
653 */
654 size_t net_buf_simple_headroom(struct net_buf_simple *buf);
655
656 /**
657 * @brief Check buffer tailroom.
658 *
659 * Check how much free space there is at the end of the buffer.
660 *
661 * @param buf A valid pointer on a buffer
662 *
663 * @return Number of bytes available at the end of the buffer.
664 */
665 size_t net_buf_simple_tailroom(struct net_buf_simple *buf);
666
667 /**
668 * @brief Parsing state of a buffer.
669 *
670 * This is used for temporarily storing the parsing state of a buffer
671 * while giving control of the parsing to a routine which we don't
672 * control.
673 */
674 struct net_buf_simple_state {
675 /** Offset of the data pointer from the beginning of the storage */
676 u16_t offset;
677 /** Length of data */
678 u16_t len;
679 };
680
681 /**
682 * @brief Save the parsing state of a buffer.
683 *
684 * Saves the parsing state of a buffer so it can be restored later.
685 *
686 * @param buf Buffer from which the state should be saved.
687 * @param state Storage for the state.
688 */
net_buf_simple_save(struct net_buf_simple * buf,struct net_buf_simple_state * state)689 static inline void net_buf_simple_save(struct net_buf_simple *buf,
690 struct net_buf_simple_state *state)
691 {
692 state->offset = net_buf_simple_headroom(buf);
693 state->len = buf->len;
694 }
695
696 /**
697 * @brief Restore the parsing state of a buffer.
698 *
699 * Restores the parsing state of a buffer from a state previously stored
700 * by net_buf_simple_save().
701 *
702 * @param buf Buffer to which the state should be restored.
703 * @param state Stored state.
704 */
net_buf_simple_restore(struct net_buf_simple * buf,struct net_buf_simple_state * state)705 static inline void net_buf_simple_restore(struct net_buf_simple *buf,
706 struct net_buf_simple_state *state)
707 {
708 buf->data = buf->__buf + state->offset;
709 buf->len = state->len;
710 }
711
712 /**
713 * Flag indicating that the buffer has associated fragments. Only used
714 * internally by the buffer handling code while the buffer is inside a
715 * FIFO, meaning this never needs to be explicitly set or unset by the
716 * net_buf API user. As long as the buffer is outside of a FIFO, i.e.
717 * in practice always for the user for this API, the buf->frags pointer
718 * should be used instead.
719 */
720 #define NET_BUF_FRAGS BIT(0)
721 /**
722 * Flag indicating that the buffer's associated data pointer, points to
723 * externally allocated memory. Therefore once ref goes down to zero, the
724 * pointed data will not need to be deallocated. This never needs to be
725 * explicitly set or unet by the net_buf API user. Such net_buf is
726 * exclusively instantiated via net_buf_alloc_with_data() function.
727 * Reference count mechanism however will behave the same way, and ref
728 * count going to 0 will free the net_buf but no the data pointer in it.
729 */
730 #define NET_BUF_EXTERNAL_DATA BIT(1)
731
732 /**
733 * @brief Network buffer representation.
734 *
735 * This struct is used to represent network buffers. Such buffers are
736 * normally defined through the NET_BUF_POOL_*_DEFINE() APIs and allocated
737 * using the net_buf_alloc() API.
738 */
739 struct net_buf {
740 union {
741 /** Allow placing the buffer into sys_slist_t */
742 sys_snode_t node;
743
744 /** Fragments associated with this buffer. */
745 struct net_buf *frags;
746 };
747
748 /** Reference count. */
749 u8_t ref;
750
751 /** Bit-field of buffer flags. */
752 u8_t flags;
753
754 /** Where the buffer should go when freed up. */
755 u8_t pool_id;
756
757 /* Union for convenience access to the net_buf_simple members, also
758 * preserving the old API.
759 */
760 union {
761 /* The ABI of this struct must match net_buf_simple */
762 struct {
763 /** Pointer to the start of data in the buffer. */
764 u8_t *data;
765
766 /** Length of the data behind the data pointer. */
767 u16_t len;
768
769 /** Amount of data that this buffer can store. */
770 u16_t size;
771
772 /** Start of the data storage. Not to be accessed
773 * directly (the data pointer should be used
774 * instead).
775 */
776 u8_t *__buf;
777 };
778
779 struct net_buf_simple b;
780 };
781
782 /** System metadata for this buffer. */
783 u8_t user_data[CONFIG_NET_BUF_USER_DATA_SIZE] __net_buf_align;
784 };
785
786 struct net_buf_data_cb {
787 u8_t * (*alloc)(struct net_buf *buf, size_t *size, k_timeout_t timeout);
788 u8_t * (*ref)(struct net_buf *buf, u8_t *data);
789 void (*unref)(struct net_buf *buf, u8_t *data);
790 };
791
792 struct net_buf_data_alloc {
793 const struct net_buf_data_cb *cb;
794 void *alloc_data;
795 };
796
797 /**
798 * @brief Network buffer pool representation.
799 *
800 * This struct is used to represent a pool of network buffers.
801 */
802 struct net_buf_pool {
803 /** LIFO to place the buffer into when free */
804 struct k_lifo free;
805
806 /** Number of buffers in pool */
807 const u16_t buf_count;
808
809 /** Number of uninitialized buffers */
810 u16_t uninit_count;
811
812 #if defined(CONFIG_NET_BUF_POOL_USAGE)
813 /** Amount of available buffers in the pool. */
814 s16_t avail_count;
815
816 /** Total size of the pool. */
817 const u16_t pool_size;
818
819 /** Name of the pool. Used when printing pool information. */
820 const char *name;
821 #endif /* CONFIG_NET_BUF_POOL_USAGE */
822
823 /** Optional destroy callback when buffer is freed. */
824 void (*const destroy)(struct net_buf *buf);
825
826 /** Data allocation handlers. */
827 const struct net_buf_data_alloc *alloc;
828
829 /** Start of buffer storage array */
830 struct net_buf * const __bufs;
831 };
832
833 int net_buf_pool_init(struct net_buf_pool *pool);
834
835 #define NET_BUF_POOL_INIT(_name)\
836 net_buf_pool_init(&_name)
837
838 /** @cond INTERNAL_HIDDEN */
839 #if defined(CONFIG_NET_BUF_POOL_USAGE)
840 #define NET_BUF_POOL_INITIALIZER(_pool, _alloc, _bufs, _count, _destroy) \
841 { \
842 .alloc = _alloc, \
843 .free = _K_LIFO_INITIALIZER(_pool.free), \
844 .__bufs = _bufs, \
845 .buf_count = _count, \
846 .uninit_count = _count, \
847 .avail_count = _count, \
848 .destroy = _destroy, \
849 .name = STRINGIFY(_pool), \
850 }
851 #else
852 #define NET_BUF_POOL_INITIALIZER(_pool, _alloc, _bufs, _count, _destroy) \
853 { \
854 .alloc = _alloc, \
855 .free = _K_LIFO_INITIALIZER(_pool.free), \
856 .__bufs = _bufs, \
857 .buf_count = _count, \
858 .uninit_count = _count, \
859 .destroy = _destroy, \
860 }
861 #endif /* CONFIG_NET_BUF_POOL_USAGE */
862
863 extern const struct net_buf_data_alloc net_buf_heap_alloc;
864 /** @endcond */
865
866 /**
867 * @def NET_BUF_POOL_HEAP_DEFINE
868 * @brief Define a new pool for buffers using the heap for the data.
869 *
870 * Defines a net_buf_pool struct and the necessary memory storage (array of
871 * structs) for the needed amount of buffers. After this, the buffers can be
872 * accessed from the pool through net_buf_alloc. The pool is defined as a
873 * static variable, so if it needs to be exported outside the current module
874 * this needs to happen with the help of a separate pointer rather than an
875 * extern declaration.
876 *
877 * The data payload of the buffers will be allocated from the heap using
878 * k_malloc, so CONFIG_HEAP_MEM_POOL_SIZE must be set to a positive value.
879 * This kind of pool does not support blocking on the data allocation, so
880 * the timeout passed to net_buf_alloc will be always treated as K_NO_WAIT
881 * when trying to allocate the data. This means that allocation failures,
882 * i.e. NULL returns, must always be handled cleanly.
883 *
884 * If provided with a custom destroy callback, this callback is
885 * responsible for eventually calling net_buf_destroy() to complete the
886 * process of returning the buffer to the pool.
887 *
888 * @param _name Name of the pool variable.
889 * @param _count Number of buffers in the pool.
890 * @param _destroy Optional destroy callback when buffer is freed.
891 */
892 #define NET_BUF_POOL_HEAP_DEFINE(_name, _count, _destroy) \
893 static struct net_buf net_buf_##_name[_count] __noinit; \
894 struct net_buf_pool _name __net_buf_align \
895 __in_section(_net_buf_pool, static, _name) = \
896 NET_BUF_POOL_INITIALIZER(_name, &net_buf_heap_alloc, \
897 net_buf_##_name, _count, _destroy)
898
899 struct net_buf_pool_fixed {
900 size_t data_size;
901 u8_t *data_pool;
902 };
903
904 /** @cond INTERNAL_HIDDEN */
905 extern const struct net_buf_data_cb net_buf_fixed_cb;
906 /** @endcond */
907
908 /**
909 * @def NET_BUF_POOL_FIXED_DEFINE
910 * @brief Define a new pool for buffers based on fixed-size data
911 *
912 * Defines a net_buf_pool struct and the necessary memory storage (array of
913 * structs) for the needed amount of buffers. After this, the buffers can be
914 * accessed from the pool through net_buf_alloc. The pool is defined as a
915 * static variable, so if it needs to be exported outside the current module
916 * this needs to happen with the help of a separate pointer rather than an
917 * extern declaration.
918 *
919 * The data payload of the buffers will be allocated from a byte array
920 * of fixed sized chunks. This kind of pool does not support blocking on
921 * the data allocation, so the timeout passed to net_buf_alloc will be
922 * always treated as K_NO_WAIT when trying to allocate the data. This means
923 * that allocation failures, i.e. NULL returns, must always be handled
924 * cleanly.
925 *
926 * If provided with a custom destroy callback, this callback is
927 * responsible for eventually calling net_buf_destroy() to complete the
928 * process of returning the buffer to the pool.
929 *
930 * @param _name Name of the pool variable.
931 * @param _count Number of buffers in the pool.
932 * @param _data_size Maximum data payload per buffer.
933 * @param _destroy Optional destroy callback when buffer is freed.
934 */
935 #ifdef CONFIG_BT_USE_MM
936 #define NET_BUF_POOL_FIXED_DEFINE(_name, _count, _data_size, _destroy) \
937 static struct net_buf net_buf_##_name[_count] __noinit; \
938 static const struct net_buf_pool_fixed net_buf_fixed_##_name = { \
939 .data_size = _data_size, \
940 .data_pool = NULL, \
941 }; \
942 static const struct net_buf_data_alloc net_buf_fixed_alloc_##_name = {\
943 .cb = &net_buf_fixed_cb, \
944 .alloc_data = (void *)&net_buf_fixed_##_name, \
945 }; \
946 struct net_buf_pool _name __net_buf_align \
947 __in_section(_net_buf_pool, static, _name) = \
948 NET_BUF_POOL_INITIALIZER(_name, &net_buf_fixed_alloc_##_name, \
949 net_buf_##_name, _count, _destroy)
950 #else
951 #define NET_BUF_POOL_FIXED_DEFINE(_name, _count, _data_size, _destroy) \
952 static struct net_buf net_buf_##_name[_count] __noinit; \
953 static u8_t __noinit net_buf_data_##_name[_count][_data_size]; \
954 static const struct net_buf_pool_fixed net_buf_fixed_##_name = { \
955 .data_size = _data_size, \
956 .data_pool = (u8_t *)net_buf_data_##_name, \
957 }; \
958 static const struct net_buf_data_alloc net_buf_fixed_alloc_##_name = {\
959 .cb = &net_buf_fixed_cb, \
960 .alloc_data = (void *)&net_buf_fixed_##_name, \
961 }; \
962 struct net_buf_pool _name __net_buf_align \
963 __in_section(_net_buf_pool, static, _name) = \
964 NET_BUF_POOL_INITIALIZER(_name, &net_buf_fixed_alloc_##_name, \
965 net_buf_##_name, _count, _destroy)
966
967 #endif
968 /** @cond INTERNAL_HIDDEN */
969 extern const struct net_buf_data_cb net_buf_var_cb;
970 /** @endcond */
971
972 /**
973 * @def NET_BUF_POOL_VAR_DEFINE
974 * @brief Define a new pool for buffers with variable size payloads
975 *
976 * Defines a net_buf_pool struct and the necessary memory storage (array of
977 * structs) for the needed amount of buffers. After this, the buffers can be
978 * accessed from the pool through net_buf_alloc. The pool is defined as a
979 * static variable, so if it needs to be exported outside the current module
980 * this needs to happen with the help of a separate pointer rather than an
981 * extern declaration.
982 *
983 * The data payload of the buffers will be based on a memory pool from which
984 * variable size payloads may be allocated.
985 *
986 * If provided with a custom destroy callback, this callback is
987 * responsible for eventually calling net_buf_destroy() to complete the
988 * process of returning the buffer to the pool.
989 *
990 * @param _name Name of the pool variable.
991 * @param _count Number of buffers in the pool.
992 * @param _data_size Total amount of memory available for data payloads.
993 * @param _destroy Optional destroy callback when buffer is freed.
994 */
995 #define NET_BUF_POOL_VAR_DEFINE(_name, _count, _data_size, _destroy) \
996 static struct net_buf _net_buf_##_name[_count] __noinit; \
997 K_MEM_POOL_DEFINE(net_buf_mem_pool_##_name, 16, _data_size, 1, 4); \
998 static const struct net_buf_data_alloc net_buf_data_alloc_##_name = { \
999 .cb = &net_buf_var_cb, \
1000 .alloc_data = &net_buf_mem_pool_##_name, \
1001 }; \
1002 struct net_buf_pool _name __net_buf_align \
1003 __in_section(_net_buf_pool, static, _name) = \
1004 NET_BUF_POOL_INITIALIZER(_name, &net_buf_data_alloc_##_name, \
1005 _net_buf_##_name, _count, _destroy)
1006
1007 /**
1008 * @def NET_BUF_POOL_DEFINE
1009 * @brief Define a new pool for buffers
1010 *
1011 * Defines a net_buf_pool struct and the necessary memory storage (array of
1012 * structs) for the needed amount of buffers. After this,the buffers can be
1013 * accessed from the pool through net_buf_alloc. The pool is defined as a
1014 * static variable, so if it needs to be exported outside the current module
1015 * this needs to happen with the help of a separate pointer rather than an
1016 * extern declaration.
1017 *
1018 * If provided with a custom destroy callback this callback is
1019 * responsible for eventually calling net_buf_destroy() to complete the
1020 * process of returning the buffer to the pool.
1021 *
1022 * @param _name Name of the pool variable.
1023 * @param _count Number of buffers in the pool.
1024 * @param _size Maximum data size for each buffer.
1025 * @param _ud_size Amount of user data space to reserve.
1026 * @param _destroy Optional destroy callback when buffer is freed.
1027 */
1028 #define NET_BUF_POOL_DEFINE(_name, _count, _size, _ud_size, _destroy) \
1029 BUILD_ASSERT(_ud_size <= CONFIG_NET_BUF_USER_DATA_SIZE); \
1030 NET_BUF_POOL_FIXED_DEFINE(_name, _count, _size, _destroy)
1031
1032 /**
1033 * @brief Looks up a pool based on its ID.
1034 *
1035 * @param id Pool ID (e.g. from buf->pool_id).
1036 *
1037 * @return Pointer to pool.
1038 */
1039 struct net_buf_pool *net_buf_pool_get(int id);
1040
1041 /**
1042 * @brief Get a zero-based index for a buffer.
1043 *
1044 * This function will translate a buffer into a zero-based index,
1045 * based on its placement in its buffer pool. This can be useful if you
1046 * want to associate an external array of meta-data contexts with the
1047 * buffers of a pool.
1048 *
1049 * @param buf Network buffer.
1050 *
1051 * @return Zero-based index for the buffer.
1052 */
1053 int net_buf_id(struct net_buf *buf);
1054
1055 /**
1056 * @brief Allocate a new fixed buffer from a pool.
1057 *
1058 * @param pool Which pool to allocate the buffer from.
1059 * @param timeout Affects the action taken should the pool be empty.
1060 * If K_NO_WAIT, then return immediately. If K_FOREVER, then
1061 * wait as long as necessary. Otherwise, wait until the specified
1062 * timeout. Note that some types of data allocators do not support
1063 * blocking (such as the HEAP type). In this case it's still possible
1064 * for net_buf_alloc() to fail (return NULL) even if it was given
1065 * K_FOREVER.
1066 *
1067 * @return New buffer or NULL if out of buffers.
1068 */
1069 #if defined(CONFIG_NET_BUF_LOG)
1070 struct net_buf *net_buf_alloc_fixed_debug(struct net_buf_pool *pool,
1071 k_timeout_t timeout, const char *func,
1072 int line);
1073 #define net_buf_alloc_fixed(_pool, _timeout) \
1074 net_buf_alloc_fixed_debug(_pool, _timeout, __func__, __LINE__)
1075 #else
1076 struct net_buf *net_buf_alloc_fixed(struct net_buf_pool *pool,
1077 k_timeout_t timeout);
1078 #endif
1079
1080 /**
1081 * @def net_buf_alloc
1082 *
1083 * @copydetails net_buf_alloc_fixed
1084 */
1085 #define net_buf_alloc(pool, timeout) net_buf_alloc_fixed(pool, timeout)
1086
1087 /**
1088 * @brief Allocate a new variable length buffer from a pool.
1089 *
1090 * @param pool Which pool to allocate the buffer from.
1091 * @param size Amount of data the buffer must be able to fit.
1092 * @param timeout Affects the action taken should the pool be empty.
1093 * If K_NO_WAIT, then return immediately. If K_FOREVER, then
1094 * wait as long as necessary. Otherwise, wait until the specified
1095 * timeout. Note that some types of data allocators do not support
1096 * blocking (such as the HEAP type). In this case it's still possible
1097 * for net_buf_alloc() to fail (return NULL) even if it was given
1098 * K_FOREVER.
1099 *
1100 * @return New buffer or NULL if out of buffers.
1101 */
1102 #if defined(CONFIG_NET_BUF_LOG)
1103 struct net_buf *net_buf_alloc_len_debug(struct net_buf_pool *pool, size_t size,
1104 k_timeout_t timeout, const char *func,
1105 int line);
1106 #define net_buf_alloc_len(_pool, _size, _timeout) \
1107 net_buf_alloc_len_debug(_pool, _size, _timeout, __func__, __LINE__)
1108 #else
1109 struct net_buf *net_buf_alloc_len(struct net_buf_pool *pool, size_t size,
1110 k_timeout_t timeout);
1111 #endif
1112
1113 /**
1114 * @brief Allocate a new buffer from a pool but with external data pointer.
1115 *
1116 * Allocate a new buffer from a pool, where the data pointer comes from the
1117 * user and not from the pool.
1118 *
1119 * @param pool Which pool to allocate the buffer from.
1120 * @param data External data pointer
1121 * @param size Amount of data the pointed data buffer if able to fit.
1122 * @param timeout Affects the action taken should the pool be empty.
1123 * If K_NO_WAIT, then return immediately. If K_FOREVER, then
1124 * wait as long as necessary. Otherwise, wait until the specified
1125 * timeout. Note that some types of data allocators do not support
1126 * blocking (such as the HEAP type). In this case it's still possible
1127 * for net_buf_alloc() to fail (return NULL) even if it was given
1128 * K_FOREVER.
1129 *
1130 * @return New buffer or NULL if out of buffers.
1131 */
1132 #if defined(CONFIG_NET_BUF_LOG)
1133 struct net_buf *net_buf_alloc_with_data_debug(struct net_buf_pool *pool,
1134 void *data, size_t size,
1135 k_timeout_t timeout,
1136 const char *func, int line);
1137 #define net_buf_alloc_with_data(_pool, _data_, _size, _timeout) \
1138 net_buf_alloc_with_data_debug(_pool, _data_, _size, _timeout, \
1139 __func__, __LINE__)
1140 #else
1141 struct net_buf *net_buf_alloc_with_data(struct net_buf_pool *pool,
1142 void *data, size_t size,
1143 k_timeout_t timeout);
1144 #endif
1145
1146 /**
1147 * @brief Get a buffer from a FIFO.
1148 *
1149 * @param fifo Which FIFO to take the buffer from.
1150 * @param timeout Affects the action taken should the FIFO be empty.
1151 * If K_NO_WAIT, then return immediately. If K_FOREVER, then wait as
1152 * long as necessary. Otherwise, wait until the specified timeout.
1153 *
1154 * @return New buffer or NULL if the FIFO is empty.
1155 */
1156 #if defined(CONFIG_NET_BUF_LOG)
1157 struct net_buf *net_buf_get_debug(struct kfifo *fifo, k_timeout_t timeout,
1158 const char *func, int line);
1159 #define net_buf_get(_fifo, _timeout) \
1160 net_buf_get_debug(_fifo, _timeout, __func__, __LINE__)
1161 #else
1162 struct net_buf *net_buf_get(struct kfifo *fifo, k_timeout_t timeout);
1163 #endif
1164
1165 /**
1166 * @brief Destroy buffer from custom destroy callback
1167 *
1168 * This helper is only intended to be used from custom destroy callbacks.
1169 * If no custom destroy callback is given to NET_BUF_POOL_*_DEFINE() then
1170 * there is no need to use this API.
1171 *
1172 * @param buf Buffer to destroy.
1173 */
net_buf_destroy(struct net_buf * buf)1174 static inline void net_buf_destroy(struct net_buf *buf)
1175 {
1176 struct net_buf_pool *pool = net_buf_pool_get(buf->pool_id);
1177
1178 k_lifo_put(&pool->free, buf);
1179 }
1180
1181 /**
1182 * @brief Reset buffer
1183 *
1184 * Reset buffer data and flags so it can be reused for other purposes.
1185 *
1186 * @param buf Buffer to reset.
1187 */
1188 void net_buf_reset(struct net_buf *buf);
1189
1190 /**
1191 * @brief Initialize buffer with the given headroom.
1192 *
1193 * The buffer is not expected to contain any data when this API is called.
1194 *
1195 * @param buf Buffer to initialize.
1196 * @param reserve How much headroom to reserve.
1197 */
1198 void net_buf_simple_reserve(struct net_buf_simple *buf, size_t reserve);
1199
1200 /**
1201 * @brief Put a buffer into a list
1202 *
1203 * If the buffer contains follow-up fragments this function will take care of
1204 * inserting them as well into the list.
1205 *
1206 * @param list Which list to append the buffer to.
1207 * @param buf Buffer.
1208 */
1209 void net_buf_slist_put(sys_slist_t *list, struct net_buf *buf);
1210
1211 /**
1212 * @brief Get a buffer from a list.
1213 *
1214 * If the buffer had any fragments, these will automatically be recovered from
1215 * the list as well and be placed to the buffer's fragment list.
1216 *
1217 * @param list Which list to take the buffer from.
1218 *
1219 * @return New buffer or NULL if the FIFO is empty.
1220 */
1221 struct net_buf *net_buf_slist_get(sys_slist_t *list);
1222
1223 /**
1224 * @brief Put a buffer to the end of a FIFO.
1225 *
1226 * If the buffer contains follow-up fragments this function will take care of
1227 * inserting them as well into the FIFO.
1228 *
1229 * @param fifo Which FIFO to put the buffer to.
1230 * @param buf Buffer.
1231 */
1232 void net_buf_put(struct kfifo *fifo, struct net_buf *buf);
1233
1234 /**
1235 * @brief Decrements the reference count of a buffer.
1236 *
1237 * The buffer is put back into the pool if the reference count reaches zero.
1238 *
1239 * @param buf A valid pointer on a buffer
1240 */
1241 #if defined(CONFIG_NET_BUF_LOG)
1242 void net_buf_unref_debug(struct net_buf *buf, const char *func, int line);
1243 #define net_buf_unref(_buf) \
1244 net_buf_unref_debug(_buf, __func__, __LINE__)
1245 #else
1246 void net_buf_unref(struct net_buf *buf);
1247 #endif
1248
1249 /**
1250 * @brief Increment the reference count of a buffer.
1251 *
1252 * @param buf A valid pointer on a buffer
1253 *
1254 * @return the buffer newly referenced
1255 */
1256 struct net_buf *net_buf_ref(struct net_buf *buf);
1257
1258 /**
1259 * @brief Clone buffer
1260 *
1261 * Duplicate given buffer including any data and headers currently stored.
1262 *
1263 * @param buf A valid pointer on a buffer
1264 * @param timeout Affects the action taken should the pool be empty.
1265 * If K_NO_WAIT, then return immediately. If K_FOREVER, then
1266 * wait as long as necessary. Otherwise, wait until the specified
1267 * timeout.
1268 *
1269 * @return Cloned buffer or NULL if out of buffers.
1270 */
1271 struct net_buf *net_buf_clone(struct net_buf *buf, k_timeout_t timeout);
1272
1273 /**
1274 * @brief Get a pointer to the user data of a buffer.
1275 *
1276 * @param buf A valid pointer on a buffer
1277 *
1278 * @return Pointer to the user data of the buffer.
1279 */
net_buf_user_data(const struct net_buf * buf)1280 static inline void *net_buf_user_data(const struct net_buf *buf)
1281 {
1282 return (void *)buf->user_data;
1283 }
1284
1285 /**
1286 * @def net_buf_reserve
1287 * @brief Initialize buffer with the given headroom.
1288 *
1289 * The buffer is not expected to contain any data when this API is called.
1290 *
1291 * @param buf Buffer to initialize.
1292 * @param reserve How much headroom to reserve.
1293 */
1294 #define net_buf_reserve(buf, reserve) net_buf_simple_reserve(&(buf)->b, \
1295 reserve)
1296
1297 /**
1298 * @def net_buf_add
1299 * @brief Prepare data to be added at the end of the buffer
1300 *
1301 * Increments the data length of a buffer to account for more data
1302 * at the end.
1303 *
1304 * @param buf Buffer to update.
1305 * @param len Number of bytes to increment the length with.
1306 *
1307 * @return The original tail of the buffer.
1308 */
1309 #define net_buf_add(buf, len) net_buf_simple_add(&(buf)->b, len)
1310
1311 /**
1312 * @def net_buf_add_mem
1313 * @brief Copies the given number of bytes to the end of the buffer
1314 *
1315 * Increments the data length of the buffer to account for more data at
1316 * the end.
1317 *
1318 * @param buf Buffer to update.
1319 * @param mem Location of data to be added.
1320 * @param len Length of data to be added
1321 *
1322 * @return The original tail of the buffer.
1323 */
1324 #define net_buf_add_mem(buf, mem, len) net_buf_simple_add_mem(&(buf)->b, \
1325 mem, len)
1326
1327 /**
1328 * @def net_buf_add_u8
1329 * @brief Add (8-bit) byte at the end of the buffer
1330 *
1331 * Increments the data length of the buffer to account for more data at
1332 * the end.
1333 *
1334 * @param buf Buffer to update.
1335 * @param val byte value to be added.
1336 *
1337 * @return Pointer to the value added
1338 */
1339 #define net_buf_add_u8(buf, val) net_buf_simple_add_u8(&(buf)->b, val)
1340
1341 /**
1342 * @def net_buf_add_le16
1343 * @brief Add 16-bit value at the end of the buffer
1344 *
1345 * Adds 16-bit value in little endian format at the end of buffer.
1346 * Increments the data length of a buffer to account for more data
1347 * at the end.
1348 *
1349 * @param buf Buffer to update.
1350 * @param val 16-bit value to be added.
1351 */
1352 #define net_buf_add_le16(buf, val) net_buf_simple_add_le16(&(buf)->b, val)
1353
1354 /**
1355 * @def net_buf_add_be16
1356 * @brief Add 16-bit value at the end of the buffer
1357 *
1358 * Adds 16-bit value in big endian format at the end of buffer.
1359 * Increments the data length of a buffer to account for more data
1360 * at the end.
1361 *
1362 * @param buf Buffer to update.
1363 * @param val 16-bit value to be added.
1364 */
1365 #define net_buf_add_be16(buf, val) net_buf_simple_add_be16(&(buf)->b, val)
1366
1367 /**
1368 * @def net_buf_add_le24
1369 * @brief Add 24-bit value at the end of the buffer
1370 *
1371 * Adds 24-bit value in little endian format at the end of buffer.
1372 * Increments the data length of a buffer to account for more data
1373 * at the end.
1374 *
1375 * @param buf Buffer to update.
1376 * @param val 24-bit value to be added.
1377 */
1378 #define net_buf_add_le24(buf, val) net_buf_simple_add_le24(&(buf)->b, val)
1379
1380 /**
1381 * @def net_buf_add_be24
1382 * @brief Add 24-bit value at the end of the buffer
1383 *
1384 * Adds 24-bit value in big endian format at the end of buffer.
1385 * Increments the data length of a buffer to account for more data
1386 * at the end.
1387 *
1388 * @param buf Buffer to update.
1389 * @param val 24-bit value to be added.
1390 */
1391 #define net_buf_add_be24(buf, val) net_buf_simple_add_be24(&(buf)->b, val)
1392
1393 /**
1394 * @def net_buf_add_le32
1395 * @brief Add 32-bit value at the end of the buffer
1396 *
1397 * Adds 32-bit value in little endian format at the end of buffer.
1398 * Increments the data length of a buffer to account for more data
1399 * at the end.
1400 *
1401 * @param buf Buffer to update.
1402 * @param val 32-bit value to be added.
1403 */
1404 #define net_buf_add_le32(buf, val) net_buf_simple_add_le32(&(buf)->b, val)
1405
1406 /**
1407 * @def net_buf_add_be32
1408 * @brief Add 32-bit value at the end of the buffer
1409 *
1410 * Adds 32-bit value in big endian format at the end of buffer.
1411 * Increments the data length of a buffer to account for more data
1412 * at the end.
1413 *
1414 * @param buf Buffer to update.
1415 * @param val 32-bit value to be added.
1416 */
1417 #define net_buf_add_be32(buf, val) net_buf_simple_add_be32(&(buf)->b, val)
1418
1419 /**
1420 * @def net_buf_add_le48
1421 * @brief Add 48-bit value at the end of the buffer
1422 *
1423 * Adds 48-bit value in little endian format at the end of buffer.
1424 * Increments the data length of a buffer to account for more data
1425 * at the end.
1426 *
1427 * @param buf Buffer to update.
1428 * @param val 48-bit value to be added.
1429 */
1430 #define net_buf_add_le48(buf, val) net_buf_simple_add_le48(&(buf)->b, val)
1431
1432 /**
1433 * @def net_buf_add_be48
1434 * @brief Add 48-bit value at the end of the buffer
1435 *
1436 * Adds 48-bit value in big endian format at the end of buffer.
1437 * Increments the data length of a buffer to account for more data
1438 * at the end.
1439 *
1440 * @param buf Buffer to update.
1441 * @param val 48-bit value to be added.
1442 */
1443 #define net_buf_add_be48(buf, val) net_buf_simple_add_be48(&(buf)->b, val)
1444
1445 /**
1446 * @def net_buf_add_le64
1447 * @brief Add 64-bit value at the end of the buffer
1448 *
1449 * Adds 64-bit value in little endian format at the end of buffer.
1450 * Increments the data length of a buffer to account for more data
1451 * at the end.
1452 *
1453 * @param buf Buffer to update.
1454 * @param val 64-bit value to be added.
1455 */
1456 #define net_buf_add_le64(buf, val) net_buf_simple_add_le64(&(buf)->b, val)
1457
1458 /**
1459 * @def net_buf_add_be64
1460 * @brief Add 64-bit value at the end of the buffer
1461 *
1462 * Adds 64-bit value in big endian format at the end of buffer.
1463 * Increments the data length of a buffer to account for more data
1464 * at the end.
1465 *
1466 * @param buf Buffer to update.
1467 * @param val 64-bit value to be added.
1468 */
1469 #define net_buf_add_be64(buf, val) net_buf_simple_add_be64(&(buf)->b, val)
1470
1471 /**
1472 * @def net_buf_push
1473 * @brief Push data to the beginning of the buffer.
1474 *
1475 * Modifies the data pointer and buffer length to account for more data
1476 * in the beginning of the buffer.
1477 *
1478 * @param buf Buffer to update.
1479 * @param len Number of bytes to add to the beginning.
1480 *
1481 * @return The new beginning of the buffer data.
1482 */
1483 #define net_buf_push(buf, len) net_buf_simple_push(&(buf)->b, len)
1484
1485 /**
1486 * @def net_buf_push_le16
1487 * @brief Push 16-bit value to the beginning of the buffer
1488 *
1489 * Adds 16-bit value in little endian format to the beginning of the
1490 * buffer.
1491 *
1492 * @param buf Buffer to update.
1493 * @param val 16-bit value to be pushed to the buffer.
1494 */
1495 #define net_buf_push_le16(buf, val) net_buf_simple_push_le16(&(buf)->b, val)
1496
1497 /**
1498 * @def net_buf_push_be16
1499 * @brief Push 16-bit value to the beginning of the buffer
1500 *
1501 * Adds 16-bit value in little endian format to the beginning of the
1502 * buffer.
1503 *
1504 * @param buf Buffer to update.
1505 * @param val 16-bit value to be pushed to the buffer.
1506 */
1507 #define net_buf_push_be16(buf, val) net_buf_simple_push_be16(&(buf)->b, val)
1508
1509 /**
1510 * @def net_buf_push_u8
1511 * @brief Push 8-bit value to the beginning of the buffer
1512 *
1513 * Adds 8-bit value the beginning of the buffer.
1514 *
1515 * @param buf Buffer to update.
1516 * @param val 8-bit value to be pushed to the buffer.
1517 */
1518 #define net_buf_push_u8(buf, val) net_buf_simple_push_u8(&(buf)->b, val)
1519
1520 /**
1521 * @def net_buf_push_le24
1522 * @brief Push 24-bit value to the beginning of the buffer
1523 *
1524 * Adds 24-bit value in little endian format to the beginning of the
1525 * buffer.
1526 *
1527 * @param buf Buffer to update.
1528 * @param val 24-bit value to be pushed to the buffer.
1529 */
1530 #define net_buf_push_le24(buf, val) net_buf_simple_push_le24(&(buf)->b, val)
1531
1532 /**
1533 * @def net_buf_push_be24
1534 * @brief Push 24-bit value to the beginning of the buffer
1535 *
1536 * Adds 24-bit value in little endian format to the beginning of the
1537 * buffer.
1538 *
1539 * @param buf Buffer to update.
1540 * @param val 24-bit value to be pushed to the buffer.
1541 */
1542 #define net_buf_push_be24(buf, val) net_buf_simple_push_be24(&(buf)->b, val)
1543
1544 /**
1545 * @def net_buf_push_le32
1546 * @brief Push 32-bit value to the beginning of the buffer
1547 *
1548 * Adds 32-bit value in little endian format to the beginning of the
1549 * buffer.
1550 *
1551 * @param buf Buffer to update.
1552 * @param val 32-bit value to be pushed to the buffer.
1553 */
1554 #define net_buf_push_le32(buf, val) net_buf_simple_push_le32(&(buf)->b, val)
1555
1556 /**
1557 * @def net_buf_push_be32
1558 * @brief Push 32-bit value to the beginning of the buffer
1559 *
1560 * Adds 32-bit value in little endian format to the beginning of the
1561 * buffer.
1562 *
1563 * @param buf Buffer to update.
1564 * @param val 32-bit value to be pushed to the buffer.
1565 */
1566 #define net_buf_push_be32(buf, val) net_buf_simple_push_be32(&(buf)->b, val)
1567
1568 /**
1569 * @def net_buf_push_le48
1570 * @brief Push 48-bit value to the beginning of the buffer
1571 *
1572 * Adds 48-bit value in little endian format to the beginning of the
1573 * buffer.
1574 *
1575 * @param buf Buffer to update.
1576 * @param val 48-bit value to be pushed to the buffer.
1577 */
1578 #define net_buf_push_le48(buf, val) net_buf_simple_push_le48(&(buf)->b, val)
1579
1580 /**
1581 * @def net_buf_push_be48
1582 * @brief Push 48-bit value to the beginning of the buffer
1583 *
1584 * Adds 48-bit value in little endian format to the beginning of the
1585 * buffer.
1586 *
1587 * @param buf Buffer to update.
1588 * @param val 48-bit value to be pushed to the buffer.
1589 */
1590 #define net_buf_push_be48(buf, val) net_buf_simple_push_be48(&(buf)->b, val)
1591
1592 /**
1593 * @def net_buf_push_le64
1594 * @brief Push 64-bit value to the beginning of the buffer
1595 *
1596 * Adds 64-bit value in little endian format to the beginning of the
1597 * buffer.
1598 *
1599 * @param buf Buffer to update.
1600 * @param val 64-bit value to be pushed to the buffer.
1601 */
1602 #define net_buf_push_le64(buf, val) net_buf_simple_push_le64(&(buf)->b, val)
1603
1604 /**
1605 * @def net_buf_push_be64
1606 * @brief Push 64-bit value to the beginning of the buffer
1607 *
1608 * Adds 64-bit value in little endian format to the beginning of the
1609 * buffer.
1610 *
1611 * @param buf Buffer to update.
1612 * @param val 64-bit value to be pushed to the buffer.
1613 */
1614 #define net_buf_push_be64(buf, val) net_buf_simple_push_be64(&(buf)->b, val)
1615
1616 /**
1617 * @def net_buf_pull
1618 * @brief Remove data from the beginning of the buffer.
1619 *
1620 * Removes data from the beginning of the buffer by modifying the data
1621 * pointer and buffer length.
1622 *
1623 * @param buf Buffer to update.
1624 * @param len Number of bytes to remove.
1625 *
1626 * @return New beginning of the buffer data.
1627 */
1628 #define net_buf_pull(buf, len) net_buf_simple_pull(&(buf)->b, len)
1629
1630 /**
1631 * @def net_buf_pull_mem
1632 * @brief Remove data from the beginning of the buffer.
1633 *
1634 * Removes data from the beginning of the buffer by modifying the data
1635 * pointer and buffer length.
1636 *
1637 * @param buf Buffer to update.
1638 * @param len Number of bytes to remove.
1639 *
1640 * @return Pointer to the old beginning of the buffer data.
1641 */
1642 #define net_buf_pull_mem(buf, len) net_buf_simple_pull_mem(&(buf)->b, len)
1643
1644 /**
1645 * @def net_buf_pull_u8
1646 * @brief Remove a 8-bit value from the beginning of the buffer
1647 *
1648 * Same idea as with net_buf_pull(), but a helper for operating on
1649 * 8-bit values.
1650 *
1651 * @param buf A valid pointer on a buffer.
1652 *
1653 * @return The 8-bit removed value
1654 */
1655 #define net_buf_pull_u8(buf) net_buf_simple_pull_u8(&(buf)->b)
1656
1657 /**
1658 * @def net_buf_pull_le16
1659 * @brief Remove and convert 16 bits from the beginning of the buffer.
1660 *
1661 * Same idea as with net_buf_pull(), but a helper for operating on
1662 * 16-bit little endian data.
1663 *
1664 * @param buf A valid pointer on a buffer.
1665 *
1666 * @return 16-bit value converted from little endian to host endian.
1667 */
1668 #define net_buf_pull_le16(buf) net_buf_simple_pull_le16(&(buf)->b)
1669
1670 /**
1671 * @def net_buf_pull_be16
1672 * @brief Remove and convert 16 bits from the beginning of the buffer.
1673 *
1674 * Same idea as with net_buf_pull(), but a helper for operating on
1675 * 16-bit big endian data.
1676 *
1677 * @param buf A valid pointer on a buffer.
1678 *
1679 * @return 16-bit value converted from big endian to host endian.
1680 */
1681 #define net_buf_pull_be16(buf) net_buf_simple_pull_be16(&(buf)->b)
1682
1683 /**
1684 * @def net_buf_pull_le24
1685 * @brief Remove and convert 24 bits from the beginning of the buffer.
1686 *
1687 * Same idea as with net_buf_pull(), but a helper for operating on
1688 * 24-bit little endian data.
1689 *
1690 * @param buf A valid pointer on a buffer.
1691 *
1692 * @return 24-bit value converted from little endian to host endian.
1693 */
1694 #define net_buf_pull_le24(buf) net_buf_simple_pull_le24(&(buf)->b)
1695
1696 /**
1697 * @def net_buf_pull_be24
1698 * @brief Remove and convert 24 bits from the beginning of the buffer.
1699 *
1700 * Same idea as with net_buf_pull(), but a helper for operating on
1701 * 24-bit big endian data.
1702 *
1703 * @param buf A valid pointer on a buffer.
1704 *
1705 * @return 24-bit value converted from big endian to host endian.
1706 */
1707 #define net_buf_pull_be24(buf) net_buf_simple_pull_be24(&(buf)->b)
1708
1709 /**
1710 * @def net_buf_pull_le32
1711 * @brief Remove and convert 32 bits from the beginning of the buffer.
1712 *
1713 * Same idea as with net_buf_pull(), but a helper for operating on
1714 * 32-bit little endian data.
1715 *
1716 * @param buf A valid pointer on a buffer.
1717 *
1718 * @return 32-bit value converted from little endian to host endian.
1719 */
1720 #define net_buf_pull_le32(buf) net_buf_simple_pull_le32(&(buf)->b)
1721
1722 /**
1723 * @def net_buf_pull_be32
1724 * @brief Remove and convert 32 bits from the beginning of the buffer.
1725 *
1726 * Same idea as with net_buf_pull(), but a helper for operating on
1727 * 32-bit big endian data.
1728 *
1729 * @param buf A valid pointer on a buffer
1730 *
1731 * @return 32-bit value converted from big endian to host endian.
1732 */
1733 #define net_buf_pull_be32(buf) net_buf_simple_pull_be32(&(buf)->b)
1734
1735 /**
1736 * @def net_buf_pull_le48
1737 * @brief Remove and convert 48 bits from the beginning of the buffer.
1738 *
1739 * Same idea as with net_buf_pull(), but a helper for operating on
1740 * 48-bit little endian data.
1741 *
1742 * @param buf A valid pointer on a buffer.
1743 *
1744 * @return 48-bit value converted from little endian to host endian.
1745 */
1746 #define net_buf_pull_le48(buf) net_buf_simple_pull_le48(&(buf)->b)
1747
1748 /**
1749 * @def net_buf_pull_be48
1750 * @brief Remove and convert 48 bits from the beginning of the buffer.
1751 *
1752 * Same idea as with net_buf_pull(), but a helper for operating on
1753 * 48-bit big endian data.
1754 *
1755 * @param buf A valid pointer on a buffer
1756 *
1757 * @return 48-bit value converted from big endian to host endian.
1758 */
1759 #define net_buf_pull_be48(buf) net_buf_simple_pull_be48(&(buf)->b)
1760
1761 /**
1762 * @def net_buf_pull_le64
1763 * @brief Remove and convert 64 bits from the beginning of the buffer.
1764 *
1765 * Same idea as with net_buf_pull(), but a helper for operating on
1766 * 64-bit little endian data.
1767 *
1768 * @param buf A valid pointer on a buffer.
1769 *
1770 * @return 64-bit value converted from little endian to host endian.
1771 */
1772 #define net_buf_pull_le64(buf) net_buf_simple_pull_le64(&(buf)->b)
1773
1774 /**
1775 * @def net_buf_pull_be64
1776 * @brief Remove and convert 64 bits from the beginning of the buffer.
1777 *
1778 * Same idea as with net_buf_pull(), but a helper for operating on
1779 * 64-bit big endian data.
1780 *
1781 * @param buf A valid pointer on a buffer
1782 *
1783 * @return 64-bit value converted from big endian to host endian.
1784 */
1785 #define net_buf_pull_be64(buf) net_buf_simple_pull_be64(&(buf)->b)
1786
1787 /**
1788 * @def net_buf_tailroom
1789 * @brief Check buffer tailroom.
1790 *
1791 * Check how much free space there is at the end of the buffer.
1792 *
1793 * @param buf A valid pointer on a buffer
1794 *
1795 * @return Number of bytes available at the end of the buffer.
1796 */
1797 #define net_buf_tailroom(buf) net_buf_simple_tailroom(&(buf)->b)
1798
1799 /**
1800 * @def net_buf_headroom
1801 * @brief Check buffer headroom.
1802 *
1803 * Check how much free space there is in the beginning of the buffer.
1804 *
1805 * buf A valid pointer on a buffer
1806 *
1807 * @return Number of bytes available in the beginning of the buffer.
1808 */
1809 #define net_buf_headroom(buf) net_buf_simple_headroom(&(buf)->b)
1810
1811 /**
1812 * @def net_buf_tail
1813 * @brief Get the tail pointer for a buffer.
1814 *
1815 * Get a pointer to the end of the data in a buffer.
1816 *
1817 * @param buf Buffer.
1818 *
1819 * @return Tail pointer for the buffer.
1820 */
1821 #define net_buf_tail(buf) net_buf_simple_tail(&(buf)->b)
1822
1823 /**
1824 * @brief Find the last fragment in the fragment list.
1825 *
1826 * @return Pointer to last fragment in the list.
1827 */
1828 struct net_buf *net_buf_frag_last(struct net_buf *frags);
1829
1830 /**
1831 * @brief Insert a new fragment to a chain of bufs.
1832 *
1833 * Insert a new fragment into the buffer fragments list after the parent.
1834 *
1835 * Note: This function takes ownership of the fragment reference so the
1836 * caller is not required to unref.
1837 *
1838 * @param parent Parent buffer/fragment.
1839 * @param frag Fragment to insert.
1840 */
1841 void net_buf_frag_insert(struct net_buf *parent, struct net_buf *frag);
1842
1843 /**
1844 * @brief Add a new fragment to the end of a chain of bufs.
1845 *
1846 * Append a new fragment into the buffer fragments list.
1847 *
1848 * Note: This function takes ownership of the fragment reference so the
1849 * caller is not required to unref.
1850 *
1851 * @param head Head of the fragment chain.
1852 * @param frag Fragment to add.
1853 *
1854 * @return New head of the fragment chain. Either head (if head
1855 * was non-NULL) or frag (if head was NULL).
1856 */
1857 struct net_buf *net_buf_frag_add(struct net_buf *head, struct net_buf *frag);
1858
1859 /**
1860 * @brief Delete existing fragment from a chain of bufs.
1861 *
1862 * @param parent Parent buffer/fragment, or NULL if there is no parent.
1863 * @param frag Fragment to delete.
1864 *
1865 * @return Pointer to the buffer following the fragment, or NULL if it
1866 * had no further fragments.
1867 */
1868 #if defined(CONFIG_NET_BUF_LOG)
1869 struct net_buf *net_buf_frag_del_debug(struct net_buf *parent,
1870 struct net_buf *frag,
1871 const char *func, int line);
1872 #define net_buf_frag_del(_parent, _frag) \
1873 net_buf_frag_del_debug(_parent, _frag, __func__, __LINE__)
1874 #else
1875 struct net_buf *net_buf_frag_del(struct net_buf *parent, struct net_buf *frag);
1876 #endif
1877
1878 /**
1879 * @brief Copy bytes from net_buf chain starting at offset to linear buffer
1880 *
1881 * Copy (extract) @a len bytes from @a src net_buf chain, starting from @a
1882 * offset in it, to a linear buffer @a dst. Return number of bytes actually
1883 * copied, which may be less than requested, if net_buf chain doesn't have
1884 * enough data, or destination buffer is too small.
1885 *
1886 * @param dst Destination buffer
1887 * @param dst_len Destination buffer length
1888 * @param src Source net_buf chain
1889 * @param offset Starting offset to copy from
1890 * @param len Number of bytes to copy
1891 * @return number of bytes actually copied
1892 */
1893 size_t net_buf_linearize(void *dst, size_t dst_len,
1894 struct net_buf *src, size_t offset, size_t len);
1895
1896 /**
1897 * @typedef net_buf_allocator_cb
1898 * @brief Network buffer allocator callback.
1899 *
1900 * @details The allocator callback is called when net_buf_append_bytes
1901 * needs to allocate a new net_buf.
1902 *
1903 * @param timeout Affects the action taken should the net buf pool be empty.
1904 * If K_NO_WAIT, then return immediately. If K_FOREVER, then
1905 * wait as long as necessary. Otherwise, wait until the specified
1906 * timeout.
1907 * @param user_data The user data given in net_buf_append_bytes call.
1908 * @return pointer to allocated net_buf or NULL on error.
1909 */
1910 typedef struct net_buf *(*net_buf_allocator_cb)(k_timeout_t timeout,
1911 void *user_data);
1912
1913 /**
1914 * @brief Append data to a list of net_buf
1915 *
1916 * @details Append data to a net_buf. If there is not enough space in the
1917 * net_buf then more net_buf will be added, unless there are no free net_buf
1918 * and timeout occurs.
1919 *
1920 * @param buf Network buffer.
1921 * @param len Total length of input data
1922 * @param value Data to be added
1923 * @param timeout Timeout is passed to the net_buf allocator callback.
1924 * @param allocate_cb When a new net_buf is required, use this callback.
1925 * @param user_data A user data pointer to be supplied to the allocate_cb.
1926 * This pointer is can be anything from a mem_pool or a net_pkt, the
1927 * logic is left up to the allocate_cb function.
1928 *
1929 * @return Length of data actually added. This may be less than input
1930 * length if other timeout than K_FOREVER was used, and there
1931 * were no free fragments in a pool to accommodate all data.
1932 */
1933 size_t net_buf_append_bytes(struct net_buf *buf, size_t len,
1934 const void *value, k_timeout_t timeout,
1935 net_buf_allocator_cb allocate_cb, void *user_data);
1936
1937 /**
1938 * @brief Skip N number of bytes in a net_buf
1939 *
1940 * @details Skip N number of bytes starting from fragment's offset. If the total
1941 * length of data is placed in multiple fragments, this function will skip from
1942 * all fragments until it reaches N number of bytes. Any fully skipped buffers
1943 * are removed from the net_buf list.
1944 *
1945 * @param buf Network buffer.
1946 * @param len Total length of data to be skipped.
1947 *
1948 * @return Pointer to the fragment or
1949 * NULL and pos is 0 after successful skip,
1950 * NULL and pos is 0xffff otherwise.
1951 */
net_buf_skip(struct net_buf * buf,size_t len)1952 static inline struct net_buf *net_buf_skip(struct net_buf *buf, size_t len)
1953 {
1954 while (buf && len--) {
1955 net_buf_pull_u8(buf);
1956 if (!buf->len) {
1957 buf = net_buf_frag_del(NULL, buf);
1958 }
1959 }
1960
1961 return buf;
1962 }
1963
1964 /**
1965 * @brief Calculate amount of bytes stored in fragments.
1966 *
1967 * Calculates the total amount of data stored in the given buffer and the
1968 * fragments linked to it.
1969 *
1970 * @param buf Buffer to start off with.
1971 *
1972 * @return Number of bytes in the buffer and its fragments.
1973 */
net_buf_frags_len(struct net_buf * buf)1974 static inline size_t net_buf_frags_len(struct net_buf *buf)
1975 {
1976 size_t bytes = 0;
1977
1978 while (buf) {
1979 bytes += buf->len;
1980 buf = buf->frags;
1981 }
1982
1983 return bytes;
1984 }
1985
1986 /**
1987 * @}
1988 */
1989
1990 #ifdef __cplusplus
1991 }
1992 #endif
1993
1994 #endif /* __NET_BUF_H */
1995