1 /** @file
2 * @brief Bluetooth data buffer API
3 */
4
5 /*
6 * Copyright (c) 2016 Intel Corporation
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10
11 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_BUF_H_
12 #define ZEPHYR_INCLUDE_BLUETOOTH_BUF_H_
13
14 /**
15 * @brief Data buffers
16 * @defgroup bt_buf Data buffers
17 * @ingroup bluetooth
18 * @{
19 */
20
21 #include <stdint.h>
22
23 #include <zephyr/net_buf.h>
24 #include <zephyr/bluetooth/hci.h>
25 #include <zephyr/sys/util.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /** Possible types of buffers passed around the Bluetooth stack in a form of bitmask. */
32 enum bt_buf_type {
33 /** HCI command */
34 BT_BUF_CMD = BIT(0),
35 /** HCI event */
36 BT_BUF_EVT = BIT(1),
37 /** Outgoing ACL data */
38 BT_BUF_ACL_OUT = BIT(2),
39 /** Incoming ACL data */
40 BT_BUF_ACL_IN = BIT(3),
41 /** Outgoing ISO data */
42 BT_BUF_ISO_OUT = BIT(4),
43 /** Incoming ISO data */
44 BT_BUF_ISO_IN = BIT(5),
45 /** H:4 data */
46 BT_BUF_H4 = BIT(6),
47 };
48
49 /** @brief This is a base type for bt_buf user data. */
50 struct bt_buf_data {
51 uint8_t type;
52 };
53
54 /* Headroom reserved in buffers, primarily for HCI transport encoding purposes */
55 #define BT_BUF_RESERVE 1
56
57 /** Helper to include reserved HCI data in buffer calculations */
58 #define BT_BUF_SIZE(size) (BT_BUF_RESERVE + (size))
59
60 /** Helper to calculate needed buffer size for HCI ACL packets */
61 #define BT_BUF_ACL_SIZE(size) BT_BUF_SIZE(BT_HCI_ACL_HDR_SIZE + (size))
62
63 /** Helper to calculate needed buffer size for HCI Event packets. */
64 #define BT_BUF_EVT_SIZE(size) BT_BUF_SIZE(BT_HCI_EVT_HDR_SIZE + (size))
65
66 /** Helper to calculate needed buffer size for HCI Command packets. */
67 #define BT_BUF_CMD_SIZE(size) BT_BUF_SIZE(BT_HCI_CMD_HDR_SIZE + (size))
68
69 /** Helper to calculate needed buffer size for HCI ISO packets. */
70 #define BT_BUF_ISO_SIZE(size) BT_BUF_SIZE(BT_HCI_ISO_HDR_SIZE + \
71 BT_HCI_ISO_SDU_TS_HDR_SIZE + \
72 (size))
73
74 /** Data size needed for HCI ACL RX buffers */
75 #define BT_BUF_ACL_RX_SIZE BT_BUF_ACL_SIZE(CONFIG_BT_BUF_ACL_RX_SIZE)
76
77 /** Data size needed for HCI Event RX buffers */
78 #define BT_BUF_EVT_RX_SIZE BT_BUF_EVT_SIZE(CONFIG_BT_BUF_EVT_RX_SIZE)
79
80 #if defined(CONFIG_BT_ISO)
81 #define BT_BUF_ISO_RX_SIZE BT_BUF_ISO_SIZE(CONFIG_BT_ISO_RX_MTU)
82 #define BT_BUF_ISO_RX_COUNT CONFIG_BT_ISO_RX_BUF_COUNT
83 #else
84 #define BT_BUF_ISO_RX_SIZE 0
85 #define BT_BUF_ISO_RX_COUNT 0
86 #endif /* CONFIG_BT_ISO */
87
88 /* see Core Spec v6.0 vol.4 part E 7.4.5 */
89 #define BT_BUF_ACL_RX_COUNT_MAX 65535
90
91 #if defined(CONFIG_BT_CONN) && defined(CONFIG_BT_HCI_HOST)
92 /* The host needs more ACL buffers than maximum ACL links. This is because of
93 * the way we re-assemble ACL packets into L2CAP PDUs.
94 *
95 * We keep around the first buffer (that comes from the driver) to do
96 * re-assembly into, and if all links are re-assembling, there will be no buffer
97 * available for the HCI driver to allocate from.
98 *
99 * TODO: When CONFIG_BT_BUF_ACL_RX_COUNT is removed,
100 * remove the MAX and only keep the 1.
101 */
102 #define BT_BUF_ACL_RX_COUNT_EXTRA CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA
103 #define BT_BUF_ACL_RX_COUNT (MAX(CONFIG_BT_BUF_ACL_RX_COUNT, 1) + BT_BUF_ACL_RX_COUNT_EXTRA)
104 #else
105 #define BT_BUF_ACL_RX_COUNT_EXTRA 0
106 #define BT_BUF_ACL_RX_COUNT 0
107 #endif /* CONFIG_BT_CONN && CONFIG_BT_HCI_HOST */
108
109 #if defined(CONFIG_BT_BUF_ACL_RX_COUNT) && CONFIG_BT_BUF_ACL_RX_COUNT > 0
110 #warning "CONFIG_BT_BUF_ACL_RX_COUNT is deprecated, see Zephyr 4.1 migration guide"
111 #endif /* CONFIG_BT_BUF_ACL_RX_COUNT && CONFIG_BT_BUF_ACL_RX_COUNT > 0 */
112
113 BUILD_ASSERT(BT_BUF_ACL_RX_COUNT <= BT_BUF_ACL_RX_COUNT_MAX,
114 "Maximum number of ACL RX buffer is 65535, reduce CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA");
115
116 /** Data size needed for HCI ACL, HCI ISO or Event RX buffers */
117 #define BT_BUF_RX_SIZE (MAX(MAX(BT_BUF_ACL_RX_SIZE, BT_BUF_EVT_RX_SIZE), \
118 BT_BUF_ISO_RX_SIZE))
119
120 /* Controller can generate up to CONFIG_BT_BUF_ACL_TX_COUNT number of unique HCI Number of Completed
121 * Packets events.
122 */
123 BUILD_ASSERT(CONFIG_BT_BUF_EVT_RX_COUNT > CONFIG_BT_BUF_ACL_TX_COUNT,
124 "Increase Event RX buffer count to be greater than ACL TX buffer count");
125
126 /** Buffer count needed for HCI ACL or HCI ISO plus Event RX buffers */
127 #define BT_BUF_RX_COUNT (CONFIG_BT_BUF_EVT_RX_COUNT + \
128 MAX(BT_BUF_ACL_RX_COUNT, BT_BUF_ISO_RX_COUNT))
129
130 /** Data size needed for HCI Command buffers. */
131 #define BT_BUF_CMD_TX_SIZE BT_BUF_CMD_SIZE(CONFIG_BT_BUF_CMD_TX_SIZE)
132
133 /** Allocate a buffer for incoming data
134 *
135 * This will set the buffer type so bt_buf_set_type() does not need to
136 * be explicitly called.
137 *
138 * @param type Type of buffer. Only BT_BUF_EVT, BT_BUF_ACL_IN and BT_BUF_ISO_IN
139 * are allowed.
140 * @param timeout Non-negative waiting period to obtain a buffer or one of the
141 * special values K_NO_WAIT and K_FOREVER.
142 * @return A new buffer.
143 */
144 struct net_buf *bt_buf_get_rx(enum bt_buf_type type, k_timeout_t timeout);
145
146 /** A callback to notify about freed buffer in the incoming data pool.
147 *
148 * This callback is called when a buffer of a given type is freed and can be requested through the
149 * @ref bt_buf_get_rx function. However, this callback is called from the context of the buffer
150 * freeing operation and must not attempt to allocate a new buffer from the same pool.
151 *
152 * @warning When this callback is called, the scheduler is locked and the callee must not perform
153 * any action that makes the current thread unready. This callback must only be used for very
154 * short non-blocking operation (e.g. submitting a work item).
155 *
156 * @param type_mask A bit mask of buffer types that have been freed.
157 */
158 typedef void (*bt_buf_rx_freed_cb_t)(enum bt_buf_type type_mask);
159
160 /** Set the callback to notify about freed buffer in the incoming data pool.
161 *
162 * @param cb Callback to notify about freed buffer in the incoming data pool. If NULL, the callback
163 * is disabled.
164 */
165 void bt_buf_rx_freed_cb_set(bt_buf_rx_freed_cb_t cb);
166
167 /** Allocate a buffer for outgoing data
168 *
169 * This will set the buffer type so bt_buf_set_type() does not need to
170 * be explicitly called.
171 *
172 * @param type Type of buffer. Only BT_BUF_CMD, BT_BUF_ACL_OUT or
173 * BT_BUF_H4, when operating on H:4 mode, are allowed.
174 * @param timeout Non-negative waiting period to obtain a buffer or one of the
175 * special values K_NO_WAIT and K_FOREVER.
176 * @param data Initial data to append to buffer.
177 * @param size Initial data size.
178 * @return A new buffer.
179 */
180 struct net_buf *bt_buf_get_tx(enum bt_buf_type type, k_timeout_t timeout,
181 const void *data, size_t size);
182
183 /** Allocate a buffer for an HCI Event
184 *
185 * This will set the buffer type so bt_buf_set_type() does not need to
186 * be explicitly called.
187 *
188 * @param evt HCI event code
189 * @param discardable Whether the driver considers the event discardable.
190 * @param timeout Non-negative waiting period to obtain a buffer or one of
191 * the special values K_NO_WAIT and K_FOREVER.
192 * @return A new buffer.
193 */
194 struct net_buf *bt_buf_get_evt(uint8_t evt, bool discardable, k_timeout_t timeout);
195
196 /** Set the buffer type
197 *
198 * @param buf Bluetooth buffer
199 * @param type The BT_* type to set the buffer to
200 */
bt_buf_set_type(struct net_buf * buf,enum bt_buf_type type)201 static inline void bt_buf_set_type(struct net_buf *buf, enum bt_buf_type type)
202 {
203 ((struct bt_buf_data *)net_buf_user_data(buf))->type = type;
204 }
205
206 /** Get the buffer type
207 *
208 * @param buf Bluetooth buffer
209 *
210 * @return The BT_* type to of the buffer
211 */
bt_buf_get_type(struct net_buf * buf)212 static inline enum bt_buf_type bt_buf_get_type(struct net_buf *buf)
213 {
214 return (enum bt_buf_type)((struct bt_buf_data *)net_buf_user_data(buf))
215 ->type;
216 }
217
218 /**
219 * @}
220 */
221
222 #ifdef __cplusplus
223 }
224 #endif
225
226 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_BUF_H_ */
227
