Line data Source code
1 1 : /** @file
2 : * @brief Bluetooth L2CAP BR/EDR handling
3 : */
4 :
5 : /*
6 : * Copyright 2025 NXP
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_BR_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_BR_H_
12 :
13 : /**
14 : * @brief L2CAP
15 : * @defgroup bt_l2cap L2CAP
16 : * @ingroup bluetooth
17 : * @{
18 : */
19 :
20 : #include <stddef.h>
21 : #include <stdint.h>
22 :
23 : #include <zephyr/bluetooth/buf.h>
24 : #include <zephyr/bluetooth/conn.h>
25 : #include <zephyr/bluetooth/hci.h>
26 : #include <zephyr/kernel.h>
27 : #include <zephyr/net_buf.h>
28 : #include <zephyr/sys/atomic.h>
29 : #include <zephyr/sys/slist.h>
30 : #include <zephyr/sys/util.h>
31 : #include <sys/types.h>
32 :
33 : #ifdef __cplusplus
34 : extern "C" {
35 : #endif
36 :
37 : /**
38 : * @brief ECHO request/response callback structure.
39 : *
40 : * This structure is used for tracking the ECHO request/response signaling packets of L2CAP BR.
41 : * It is registered with the help of the bt_l2cap_br_echo_cb_register() API.
42 : * It's permissible to register multiple instances of this @ref bt_l2cap_br_echo_cb type, in case
43 : * different modules of an application are interested in tracking the ECHO request/response
44 : * signaling packets. If a callback is not of interest for an instance, it may be set to NULL and
45 : * will as a consequence not be used for that instance.
46 : */
47 1 : struct bt_l2cap_br_echo_cb {
48 : /**
49 : * @brief A ECHO request has been received.
50 : *
51 : * This callback notifies the application of a ECHO request has been received.
52 : * The ECHO response should be performed by calling the bt_l2cap_br_echo_rsp() API.
53 : *
54 : * @param conn The ACL connection object.
55 : * @param identifier The identifier of the ECHO request.
56 : * @param buf Received ECHO data.
57 : */
58 1 : void (*req)(struct bt_conn *conn, uint8_t identifier, struct net_buf *buf);
59 :
60 : /**
61 : * @brief A ECHO response has been received.
62 : *
63 : * This callback notifies the application of a ECHO response has been received.
64 : *
65 : * @param conn The ACL connection object.
66 : * @param buf Received ECHO data.
67 : */
68 1 : void (*rsp)(struct bt_conn *conn, struct net_buf *buf);
69 :
70 : /** @internal Internally used field for list handling */
71 : sys_snode_t _node;
72 : };
73 :
74 : /**
75 : * @brief Register ECHO callbacks.
76 : *
77 : * Register callbacks to monitor the packets of L2CAP BR echo request/response.
78 : *
79 : * @param cb Callback struct. Must point to memory that remains valid.
80 : *
81 : * @retval 0 Success.
82 : * @retval -EEXIST if @p cb was already registered.
83 : */
84 1 : int bt_l2cap_br_echo_cb_register(struct bt_l2cap_br_echo_cb *cb);
85 :
86 : /**
87 : * @brief Unregister ECHO callbacks.
88 : *
89 : * Unregister callbacks that are used to monitor the packets of L2CAP BR echo request/response.
90 : *
91 : * @param cb Callback struct point to memory that remains valid.
92 : *
93 : * @retval 0 Success.
94 : * @retval -EINVAL If @p cb is NULL.
95 : * @retval -ENOENT if @p cb was not registered.
96 : */
97 1 : int bt_l2cap_br_echo_cb_unregister(struct bt_l2cap_br_echo_cb *cb);
98 :
99 : /**
100 : * @brief Headroom needed for outgoing L2CAP ECHO REQ PDUs.
101 : */
102 1 : #define BT_L2CAP_BR_ECHO_REQ_RESERVE BT_L2CAP_BUF_SIZE(4)
103 :
104 : /**
105 : * @brief Headroom needed for outgoing L2CAP ECHO RSP PDUs.
106 : */
107 1 : #define BT_L2CAP_BR_ECHO_RSP_RESERVE BT_L2CAP_BUF_SIZE(4)
108 :
109 : /**
110 : * @brief Send ECHO data through ECHO request
111 : *
112 : * Send ECHO data through ECHO request. The application is required to have reserved
113 : * @ref BT_L2CAP_BR_ECHO_REQ_RESERVE bytes in the buffer before sending.
114 : *
115 : * @param conn The ACL connection object.
116 : * @param buf Sending ECHO data.
117 : *
118 : * @return 0 in case of success or negative value in case of error.
119 : */
120 1 : int bt_l2cap_br_echo_req(struct bt_conn *conn, struct net_buf *buf);
121 :
122 : /**
123 : * @brief Send ECHO data through ECHO response
124 : *
125 : * Send ECHO data through ECHO response. The application is required to have reserved
126 : * @ref BT_L2CAP_BR_ECHO_RSP_RESERVE bytes in the buffer before sending.
127 : *
128 : * @param conn The ACL connection object.
129 : * @param identifier The identifier of the ECHO request.
130 : * @param buf Sending ECHO data.
131 : *
132 : * @return 0 in case of success or negative value in case of error.
133 : */
134 1 : int bt_l2cap_br_echo_rsp(struct bt_conn *conn, uint8_t identifier, struct net_buf *buf);
135 :
136 : /**
137 : * @brief Connectionless data channel callback structure.
138 : *
139 : * This structure is used for tracking the connectionless data channel frames.
140 : * It is registered with the help of the bt_l2cap_br_connless_register() API.
141 : * It's permissible to register multiple instances of this @ref bt_l2cap_br_connless_cb type,
142 : * in case different modules of an application are interested in tracking the connectionless
143 : * data channel frames.
144 : */
145 1 : struct bt_l2cap_br_connless_cb {
146 : /** @brief Register PSM.
147 : *
148 : * For BR, possible values:
149 : *
150 : * The PSM field is at least two octets in length. All PSM values shall have the least
151 : * significant bit of the most significant octet equal to 0 and the least significant bit
152 : * of all other octets equal to 1.
153 : *
154 : * 0 Any connectionless data channel frame will be notified.
155 : *
156 : * 0x0001-0x0eff Standard, Bluetooth SIG-assigned fixed values.
157 : *
158 : * > 0x1000 Dynamically allocated. May be pre-set by the
159 : * application before server registration (not
160 : * recommended however), or auto-allocated by the
161 : * stack if the app gave 0 as the value.
162 : */
163 1 : uint16_t psm;
164 :
165 : /** Required minimum security level */
166 1 : bt_security_t sec_level;
167 :
168 : /**
169 : * @brief A connectionless channel data has been received.
170 : *
171 : * This callback notifies the application of a connectionless channel data has been
172 : * received.
173 : *
174 : * @param conn The ACL connection object.
175 : * @param psm Protocol/Service Multiplexer.
176 : * @param buf Received connectionless channel data.
177 : */
178 1 : void (*recv)(struct bt_conn *conn, uint16_t psm, struct net_buf *buf);
179 :
180 : /** @internal Internally used field for list handling */
181 : sys_snode_t _node;
182 : };
183 :
184 : /**
185 : * @brief Register connectionless data channel callbacks.
186 : *
187 : * Register callbacks to monitor and receive connectionless data channel frames.
188 : * This allows the application to receive data sent to a specific PSM without
189 : * establishing a connection.
190 : *
191 : * @param cb Callback struct. Must point to memory that remains valid.
192 : * The PSM field must be set to the desired Protocol/Service Multiplexer
193 : * value, or 0 to receive all connectionless data frames.
194 : *
195 : * @retval 0 Success.
196 : * @retval -EINVAL If @p cb is NULL, has invalid PSM value, has invalid `recv` callback,
197 : * or has invalid security level.
198 : * @retval -EEXIST If a callback with the same PSM was already registered.
199 : */
200 1 : int bt_l2cap_br_connless_register(struct bt_l2cap_br_connless_cb *cb);
201 :
202 : /**
203 : * @brief Unregister connectionless data channel callbacks.
204 : *
205 : * Unregister callbacks that are used to monitor and receive connectionless data channel frames.
206 : *
207 : * @param cb Registered cb.
208 : *
209 : * @retval 0 Success.
210 : * @retval -EINVAL If @p cb is NULL.
211 : * @retval -ENOENT if @p cb was not registered.
212 : */
213 1 : int bt_l2cap_br_connless_unregister(struct bt_l2cap_br_connless_cb *cb);
214 :
215 : /**
216 : * @brief L2CAP connectionless SDU header size.
217 : */
218 1 : #define BT_L2CAP_CONNLESS_SDU_HDR_SIZE 2
219 :
220 : /**
221 : * @brief Headroom needed for outgoing L2CAP PDU format within a connectionless data channel.
222 : */
223 1 : #define BT_L2CAP_CONNLESS_RESERVE BT_L2CAP_BUF_SIZE(BT_L2CAP_CONNLESS_SDU_HDR_SIZE)
224 :
225 : /**
226 : * @brief Send data over connectionless data channel
227 : *
228 : * Send data over a connectionless data channel. This function allows sending data to
229 : * a specific PSM without establishing the L2CAP channel connection.
230 : *
231 : * The application is required to have reserved @ref BT_L2CAP_CONNLESS_RESERVE bytes
232 : * in the buffer before sending.
233 : *
234 : * @param conn Connection object.
235 : * @param psm Protocol/Service Multiplexer identifying the destination service.
236 : * @param buf Buffer containing the data to be sent. The application is required to
237 : * have reserved enough headroom in the buffer for the L2CAP header.
238 : *
239 : * @retval 0 Success.
240 : * @retval -EINVAL If @p conn or @p buf is NULL, @p psm is invalid, the reference counter of @p buf
241 : * != 1, the head room of @p buf is less than @ref BT_L2CAP_CONNLESS_RESERVE, or
242 : * the `buf->user_data_size` is less than the size of `struct closure`.
243 : * @return -ENOTSUP If the connectionless reception feature is unsupported by remote.
244 : * @return -ENOTCONN If the L2CAP channel with connectionless channel is not found.
245 : * @return -EMSGSIZE If the data size exceeds the peer's connectionless channel MTU.
246 : * @retval -ESHUTDOWN If the L2CAP channel with connectionless channel is NULL in low level.
247 : */
248 1 : int bt_l2cap_br_connless_send(struct bt_conn *conn, uint16_t psm, struct net_buf *buf);
249 :
250 : #ifdef __cplusplus
251 : }
252 : #endif
253 :
254 : /**
255 : * @}
256 : */
257 :
258 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_L2CAP_BR_H_ */
|
