1.. _net_buf_interface:
2
3Network Buffers
4###############
5
6.. contents::
7    :local:
8    :depth: 2
9
10
11Overview
12********
13
14Network buffers are a core concept of how the networking stack
15(as well as the Bluetooth stack) pass data around. The API for them is
16defined in :zephyr_file:`include/zephyr/net_buf.h`:.
17
18Creating buffers
19****************
20
21Network buffers are created by first defining a pool of them:
22
23.. code-block:: c
24
25   NET_BUF_POOL_DEFINE(pool_name, buf_count, buf_size, user_data_size, NULL);
26
27The pool is a static variable, so if it's needed to be exported to
28another module a separate pointer is needed.
29
30Once the pool has been defined, buffers can be allocated from it with:
31
32.. code-block:: c
33
34   buf = net_buf_alloc(&pool_name, timeout);
35
36There is no explicit initialization function for the pool or its
37buffers, rather this is done implicitly as :c:func:`net_buf_alloc` gets
38called.
39
40If there is a need to reserve space in the buffer for protocol headers
41to be prepended later, it's possible to reserve this headroom with:
42
43.. code-block:: c
44
45   net_buf_reserve(buf, headroom);
46
47In addition to actual protocol data and generic parsing context, network
48buffers may also contain protocol-specific context, known as user data.
49Both the maximum data and user data capacity of the buffers is
50compile-time defined when declaring the buffer pool.
51
52The buffers have native support for being passed through k_fifo kernel
53objects. Use :c:func:`k_fifo_put` and :c:func:`k_fifo_get` to pass buffer
54from one thread to another.
55
56Special functions exist for dealing with buffers in single linked lists,
57where the :c:func:`net_buf_slist_put` and :c:func:`net_buf_slist_get`
58functions must be used instead of :c:func:`sys_slist_append` and
59:c:func:`sys_slist_get`.
60
61Common Operations
62*****************
63
64The network buffer API provides some useful helpers for encoding and
65decoding data in the buffers. To fully understand these helpers it's
66good to understand the basic names of operations used with them:
67
68Add
69  Add data to the end of the buffer. Modifies the data length value
70  while leaving the actual data pointer intact. Requires that there is
71  enough tailroom in the buffer. Some examples of APIs for adding data:
72
73  .. code-block:: c
74
75     void *net_buf_add(struct net_buf *buf, size_t len);
76     void *net_buf_add_mem(struct net_buf *buf, const void *mem, size_t len);
77     uint8_t *net_buf_add_u8(struct net_buf *buf, uint8_t value);
78     void net_buf_add_le16(struct net_buf *buf, uint16_t value);
79     void net_buf_add_le32(struct net_buf *buf, uint32_t value);
80
81Remove
82  Remove data from the end of the buffer. Modifies the data length value
83  while leaving the actual data pointer intact. Some examples of APIs for
84  removing data:
85
86  .. code-block:: c
87
88     void *net_buf_remove_mem(struct net_buf *buf, size_t len);
89     uint8_t net_buf_remove_u8(struct net_buf *buf);
90     uint16_t net_buf_remove_le16(struct net_buf *buf);
91     uint32_t net_buf_remove_le32(struct net_buf *buf);
92
93Push
94  Prepend data to the beginning of the buffer. Modifies both the data
95  length value as well as the data pointer. Requires that there is
96  enough headroom in the buffer. Some examples of APIs for pushing data:
97
98  .. code-block:: c
99
100     void *net_buf_push(struct net_buf *buf, size_t len);
101     void *net_buf_push_mem(struct net_buf *buf, const void *mem, size_t len);
102     void net_buf_push_u8(struct net_buf *buf, uint8_t value);
103     void net_buf_push_le16(struct net_buf *buf, uint16_t value);
104
105Pull
106  Remove data from the beginning of the buffer. Modifies both the data
107  length value as well as the data pointer. Some examples of APIs for
108  pulling data:
109
110  .. code-block:: c
111
112     void *net_buf_pull(struct net_buf *buf, size_t len);
113     void *net_buf_pull_mem(struct net_buf *buf, size_t len);
114     uint8_t net_buf_pull_u8(struct net_buf *buf);
115     uint16_t net_buf_pull_le16(struct net_buf *buf);
116     uint32_t net_buf_pull_le32(struct net_buf *buf);
117
118The Add and Push operations are used when encoding data into the buffer,
119whereas the Remove and Pull operations are used when decoding data from a
120buffer.
121
122Reference Counting
123******************
124
125Each network buffer is reference counted. The buffer is initially
126acquired from a free buffers pool by calling :c:func:`net_buf_alloc()`,
127resulting in a buffer with reference count 1. The reference count can be
128incremented with :c:func:`net_buf_ref()` or decremented with
129:c:func:`net_buf_unref()`. When the count drops to zero the buffer is
130automatically placed back to the free buffers pool.
131
132
133API Reference
134*************
135
136.. doxygengroup:: net_buf
137