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