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 (CONFIG_BT_MAX_CONN + 1)
101 */
102 #define BT_BUF_ACL_RX_COUNT \
103 (MAX(CONFIG_BT_BUF_ACL_RX_COUNT, (CONFIG_BT_MAX_CONN + 1)) + \
104 CONFIG_BT_BUF_ACL_RX_COUNT_EXTRA)
105 #else
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 /** Buffer count needed for HCI ACL, HCI ISO or Event RX buffers */
121 #define BT_BUF_RX_COUNT (MAX(MAX(CONFIG_BT_BUF_EVT_RX_COUNT, \
122 BT_BUF_ACL_RX_COUNT), \
123 BT_BUF_ISO_RX_COUNT))
124
125 /** Data size needed for HCI Command buffers. */
126 #define BT_BUF_CMD_TX_SIZE BT_BUF_CMD_SIZE(CONFIG_BT_BUF_CMD_TX_SIZE)
127
128 /** Allocate a buffer for incoming data
129 *
130 * This will set the buffer type so bt_buf_set_type() does not need to
131 * be explicitly called.
132 *
133 * @param type Type of buffer. Only BT_BUF_EVT, BT_BUF_ACL_IN and BT_BUF_ISO_IN
134 * are allowed.
135 * @param timeout Non-negative waiting period to obtain a buffer or one of the
136 * special values K_NO_WAIT and K_FOREVER.
137 * @return A new buffer.
138 */
139 struct net_buf *bt_buf_get_rx(enum bt_buf_type type, k_timeout_t timeout);
140
141 /** A callback to notify about freed buffer in the incoming data pool.
142 *
143 * This callback is called when a buffer of a given type is freed and can be requested through the
144 * @ref bt_buf_get_rx function. However, this callback is called from the context of the buffer
145 * freeing operation and must not attempt to allocate a new buffer from the same pool.
146 *
147 * @warning When this callback is called, the scheduler is locked and the callee must not perform
148 * any action that makes the current thread unready. This callback must only be used for very
149 * short non-blocking operation (e.g. submitting a work item).
150 *
151 * @param type_mask A bit mask of buffer types that have been freed.
152 */
153 typedef void (*bt_buf_rx_freed_cb_t)(enum bt_buf_type type_mask);
154
155 /** Set the callback to notify about freed buffer in the incoming data pool.
156 *
157 * @param cb Callback to notify about freed buffer in the incoming data pool. If NULL, the callback
158 * is disabled.
159 */
160 void bt_buf_rx_freed_cb_set(bt_buf_rx_freed_cb_t cb);
161
162 /** Allocate a buffer for outgoing data
163 *
164 * This will set the buffer type so bt_buf_set_type() does not need to
165 * be explicitly called.
166 *
167 * @param type Type of buffer. Only BT_BUF_CMD, BT_BUF_ACL_OUT or
168 * BT_BUF_H4, when operating on H:4 mode, are allowed.
169 * @param timeout Non-negative waiting period to obtain a buffer or one of the
170 * special values K_NO_WAIT and K_FOREVER.
171 * @param data Initial data to append to buffer.
172 * @param size Initial data size.
173 * @return A new buffer.
174 */
175 struct net_buf *bt_buf_get_tx(enum bt_buf_type type, k_timeout_t timeout,
176 const void *data, size_t size);
177
178 /** Allocate a buffer for an HCI Event
179 *
180 * This will set the buffer type so bt_buf_set_type() does not need to
181 * be explicitly called.
182 *
183 * @param evt HCI event code
184 * @param discardable Whether the driver considers the event discardable.
185 * @param timeout Non-negative waiting period to obtain a buffer or one of
186 * the special values K_NO_WAIT and K_FOREVER.
187 * @return A new buffer.
188 */
189 struct net_buf *bt_buf_get_evt(uint8_t evt, bool discardable, k_timeout_t timeout);
190
191 /** Set the buffer type
192 *
193 * @param buf Bluetooth buffer
194 * @param type The BT_* type to set the buffer to
195 */
bt_buf_set_type(struct net_buf * buf,enum bt_buf_type type)196 static inline void bt_buf_set_type(struct net_buf *buf, enum bt_buf_type type)
197 {
198 ((struct bt_buf_data *)net_buf_user_data(buf))->type = type;
199 }
200
201 /** Get the buffer type
202 *
203 * @param buf Bluetooth buffer
204 *
205 * @return The BT_* type to of the buffer
206 */
bt_buf_get_type(struct net_buf * buf)207 static inline enum bt_buf_type bt_buf_get_type(struct net_buf *buf)
208 {
209 return (enum bt_buf_type)((struct bt_buf_data *)net_buf_user_data(buf))
210 ->type;
211 }
212
213 /**
214 * @}
215 */
216
217 #ifdef __cplusplus
218 }
219 #endif
220
221 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_BUF_H_ */
222
