1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
|
/*
* Copyright (c) 2011 - 2018, Nordic Semiconductor ASA
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form, except as embedded into a Nordic
* Semiconductor ASA integrated circuit in a product or a software update for
* such product, must reproduce the above copyright notice, this list of
* conditions and the following disclaimer in the documentation and/or other
* materials provided with the distribution.
*
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* 4. This software, with or without modification, must only be used with a
* Nordic Semiconductor ASA integrated circuit.
*
* 5. Any software provided in binary form under this license must not be reverse
* engineered, decompiled, modified and/or disassembled.
*
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
@addtogroup BLE_L2CAP Logical Link Control and Adaptation Protocol (L2CAP)
@{
@brief Definitions and prototypes for the L2CAP interface.
*/
#ifndef BLE_L2CAP_H__
#define BLE_L2CAP_H__
#include <stdint.h>
#include "nrf_svc.h"
#include "nrf_error.h"
#include "ble_ranges.h"
#include "ble_types.h"
#include "ble_err.h"
#ifdef __cplusplus
extern "C" {
#endif
/**@addtogroup BLE_L2CAP_TERMINOLOGY Terminology
* @{
* @details
*
* L2CAP SDU
* - A data unit that the application can send/receive to/from a peer.
*
* L2CAP PDU
* - A data unit that is exchanged between local and remote L2CAP entities.
* It consists of L2CAP protocol control information and payload fields.
* The payload field can contain an L2CAP SDU or a part of an L2CAP SDU.
*
* L2CAP MTU
* - The maximum length of an L2CAP SDU.
*
* L2CAP MPS
* - The maximum length of an L2CAP PDU payload field.
*
* Credits
* - A value indicating the number of L2CAP PDUs that the receiver of the credit can send to the peer.
* @} */
/**@addtogroup BLE_L2CAP_ENUMERATIONS Enumerations
* @{ */
/**@brief L2CAP API SVC numbers. */
enum BLE_L2CAP_SVCS
{
SD_BLE_L2CAP_CH_SETUP = BLE_L2CAP_SVC_BASE + 0, /**< Set up an L2CAP channel. */
SD_BLE_L2CAP_CH_RELEASE = BLE_L2CAP_SVC_BASE + 1, /**< Release an L2CAP channel. */
SD_BLE_L2CAP_CH_RX = BLE_L2CAP_SVC_BASE + 2, /**< Receive an SDU on an L2CAP channel. */
SD_BLE_L2CAP_CH_TX = BLE_L2CAP_SVC_BASE + 3, /**< Transmit an SDU on an L2CAP channel. */
SD_BLE_L2CAP_CH_FLOW_CONTROL = BLE_L2CAP_SVC_BASE + 4, /**< Advanced SDU reception flow control. */
};
/**@brief L2CAP Event IDs. */
enum BLE_L2CAP_EVTS
{
BLE_L2CAP_EVT_CH_SETUP_REQUEST = BLE_L2CAP_EVT_BASE + 0, /**< L2CAP Channel Setup Request event.
\n See @ref ble_l2cap_evt_ch_setup_request_t. */
BLE_L2CAP_EVT_CH_SETUP_REFUSED = BLE_L2CAP_EVT_BASE + 1, /**< L2CAP Channel Setup Refused event.
\n See @ref ble_l2cap_evt_ch_setup_refused_t. */
BLE_L2CAP_EVT_CH_SETUP = BLE_L2CAP_EVT_BASE + 2, /**< L2CAP Channel Setup Completed event.
\n See @ref ble_l2cap_evt_ch_setup_t. */
BLE_L2CAP_EVT_CH_RELEASED = BLE_L2CAP_EVT_BASE + 3, /**< L2CAP Channel Released event.
\n No additional event structure applies. */
BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED = BLE_L2CAP_EVT_BASE + 4, /**< L2CAP Channel SDU data buffer released event.
\n See @ref ble_l2cap_evt_ch_sdu_buf_released_t. */
BLE_L2CAP_EVT_CH_CREDIT = BLE_L2CAP_EVT_BASE + 5, /**< L2CAP Channel Credit received.
\n See @ref ble_l2cap_evt_ch_credit_t. */
BLE_L2CAP_EVT_CH_RX = BLE_L2CAP_EVT_BASE + 6, /**< L2CAP Channel SDU received.
\n See @ref ble_l2cap_evt_ch_rx_t. */
BLE_L2CAP_EVT_CH_TX = BLE_L2CAP_EVT_BASE + 7, /**< L2CAP Channel SDU transmitted.
\n See @ref ble_l2cap_evt_ch_tx_t. */
};
/** @} */
/**@addtogroup BLE_L2CAP_DEFINES Defines
* @{ */
/**@brief Maximum number of L2CAP channels per connection. */
#define BLE_L2CAP_CH_COUNT_MAX (64)
/**@brief Minimum L2CAP MTU, in bytes. */
#define BLE_L2CAP_MTU_MIN (23)
/**@brief Minimum L2CAP MPS, in bytes. */
#define BLE_L2CAP_MPS_MIN (23)
/**@brief Invalid CID. */
#define BLE_L2CAP_CID_INVALID (0x0000)
/**@brief Default number of credits for @ref sd_ble_l2cap_ch_flow_control. */
#define BLE_L2CAP_CREDITS_DEFAULT (1)
/**@defgroup BLE_L2CAP_CH_SETUP_REFUSED_SRCS L2CAP channel setup refused sources
* @{ */
#define BLE_L2CAP_CH_SETUP_REFUSED_SRC_LOCAL (0x01) /**< Local. */
#define BLE_L2CAP_CH_SETUP_REFUSED_SRC_REMOTE (0x02) /**< Remote. */
/** @} */
/** @defgroup BLE_L2CAP_CH_STATUS_CODES L2CAP channel status codes
* @{ */
#define BLE_L2CAP_CH_STATUS_CODE_SUCCESS (0x0000) /**< Success. */
#define BLE_L2CAP_CH_STATUS_CODE_LE_PSM_NOT_SUPPORTED (0x0002) /**< LE_PSM not supported. */
#define BLE_L2CAP_CH_STATUS_CODE_NO_RESOURCES (0x0004) /**< No resources available. */
#define BLE_L2CAP_CH_STATUS_CODE_INSUFF_AUTHENTICATION (0x0005) /**< Insufficient authentication. */
#define BLE_L2CAP_CH_STATUS_CODE_INSUFF_AUTHORIZATION (0x0006) /**< Insufficient authorization. */
#define BLE_L2CAP_CH_STATUS_CODE_INSUFF_ENC_KEY_SIZE (0x0007) /**< Insufficient encryption key size. */
#define BLE_L2CAP_CH_STATUS_CODE_INSUFF_ENC (0x0008) /**< Insufficient encryption. */
#define BLE_L2CAP_CH_STATUS_CODE_INVALID_SCID (0x0009) /**< Invalid Source CID. */
#define BLE_L2CAP_CH_STATUS_CODE_SCID_ALLOCATED (0x000A) /**< Source CID already allocated. */
#define BLE_L2CAP_CH_STATUS_CODE_UNACCEPTABLE_PARAMS (0x000B) /**< Unacceptable parameters. */
#define BLE_L2CAP_CH_STATUS_CODE_NOT_UNDERSTOOD (0x8000) /**< Command Reject received instead of LE Credit Based Connection Response. */
#define BLE_L2CAP_CH_STATUS_CODE_TIMEOUT (0xC000) /**< Operation timed out. */
/** @} */
/** @} */
/**@addtogroup BLE_L2CAP_STRUCTURES Structures
* @{ */
/**
* @brief BLE L2CAP connection configuration parameters, set with @ref sd_ble_cfg_set.
*
* @note These parameters are set per connection, so all L2CAP channels created on this connection
* will have the same parameters.
*
* @retval ::NRF_ERROR_INVALID_PARAM One or more of the following is true:
* - rx_mps is smaller than @ref BLE_L2CAP_MPS_MIN.
* - tx_mps is smaller than @ref BLE_L2CAP_MPS_MIN.
* - ch_count is greater than @ref BLE_L2CAP_CH_COUNT_MAX.
* @retval ::NRF_ERROR_NO_MEM rx_mps or tx_mps is set too high.
*/
typedef struct
{
uint16_t rx_mps; /**< The maximum L2CAP PDU payload size, in bytes, that L2CAP shall
be able to receive on L2CAP channels on connections with this
configuration. The minimum value is @ref BLE_L2CAP_MPS_MIN. */
uint16_t tx_mps; /**< The maximum L2CAP PDU payload size, in bytes, that L2CAP shall
be able to transmit on L2CAP channels on connections with this
configuration. The minimum value is @ref BLE_L2CAP_MPS_MIN. */
uint8_t rx_queue_size; /**< Number of SDU data buffers that can be queued for reception per
L2CAP channel. The minimum value is one. */
uint8_t tx_queue_size; /**< Number of SDU data buffers that can be queued for transmission
per L2CAP channel. The minimum value is one. */
uint8_t ch_count; /**< Number of L2CAP channels the application can create per connection
with this configuration. The default value is zero, the maximum
value is @ref BLE_L2CAP_CH_COUNT_MAX.
@note if this parameter is set to zero, all other parameters in
@ref ble_l2cap_conn_cfg_t are ignored. */
} ble_l2cap_conn_cfg_t;
/**@brief L2CAP channel RX parameters. */
typedef struct
{
uint16_t rx_mtu; /**< The maximum L2CAP SDU size, in bytes, that L2CAP shall be able to
receive on this L2CAP channel.
- Must be equal to or greater than @ref BLE_L2CAP_MTU_MIN. */
uint16_t rx_mps; /**< The maximum L2CAP PDU payload size, in bytes, that L2CAP shall be
able to receive on this L2CAP channel.
- Must be equal to or greater than @ref BLE_L2CAP_MPS_MIN.
- Must be equal to or less than @ref ble_l2cap_conn_cfg_t::rx_mps. */
ble_data_t sdu_buf; /**< SDU data buffer for reception.
- If @ref ble_data_t::p_data is non-NULL, initial credits are
issued to the peer.
- If @ref ble_data_t::p_data is NULL, no initial credits are
issued to the peer. */
} ble_l2cap_ch_rx_params_t;
/**@brief L2CAP channel setup parameters. */
typedef struct
{
ble_l2cap_ch_rx_params_t rx_params; /**< L2CAP channel RX parameters. */
uint16_t le_psm; /**< LE Protocol/Service Multiplexer. Used when requesting
setup of an L2CAP channel, ignored otherwise. */
uint16_t status; /**< Status code, see @ref BLE_L2CAP_CH_STATUS_CODES.
Used when replying to a setup request of an L2CAP
channel, ignored otherwise. */
} ble_l2cap_ch_setup_params_t;
/**@brief L2CAP channel TX parameters. */
typedef struct
{
uint16_t tx_mtu; /**< The maximum L2CAP SDU size, in bytes, that L2CAP is able to
transmit on this L2CAP channel. */
uint16_t peer_mps; /**< The maximum L2CAP PDU payload size, in bytes, that the peer is
able to receive on this L2CAP channel. */
uint16_t tx_mps; /**< The maximum L2CAP PDU payload size, in bytes, that L2CAP is able
to transmit on this L2CAP channel. This is effective tx_mps,
selected by the SoftDevice as
MIN( @ref ble_l2cap_ch_tx_params_t::peer_mps, @ref ble_l2cap_conn_cfg_t::tx_mps ) */
uint16_t credits; /**< Initial credits given by the peer. */
} ble_l2cap_ch_tx_params_t;
/**@brief L2CAP Channel Setup Request event. */
typedef struct
{
ble_l2cap_ch_tx_params_t tx_params; /**< L2CAP channel TX parameters. */
uint16_t le_psm; /**< LE Protocol/Service Multiplexer. */
} ble_l2cap_evt_ch_setup_request_t;
/**@brief L2CAP Channel Setup Refused event. */
typedef struct
{
uint8_t source; /**< Source, see @ref BLE_L2CAP_CH_SETUP_REFUSED_SRCS */
uint16_t status; /**< Status code, see @ref BLE_L2CAP_CH_STATUS_CODES */
} ble_l2cap_evt_ch_setup_refused_t;
/**@brief L2CAP Channel Setup Completed event. */
typedef struct
{
ble_l2cap_ch_tx_params_t tx_params; /**< L2CAP channel TX parameters. */
} ble_l2cap_evt_ch_setup_t;
/**@brief L2CAP Channel SDU Data Buffer Released event. */
typedef struct
{
ble_data_t sdu_buf; /**< Returned reception or transmission SDU data buffer. The SoftDevice
returns SDU data buffers supplied by the application, which have
not yet been returned previously via a @ref BLE_L2CAP_EVT_CH_RX or
@ref BLE_L2CAP_EVT_CH_TX event. */
} ble_l2cap_evt_ch_sdu_buf_released_t;
/**@brief L2CAP Channel Credit received event. */
typedef struct
{
uint16_t credits; /**< Additional credits given by the peer. */
} ble_l2cap_evt_ch_credit_t;
/**@brief L2CAP Channel received SDU event. */
typedef struct
{
uint16_t sdu_len; /**< Total SDU length, in bytes. */
ble_data_t sdu_buf; /**< SDU data buffer.
@note If there is not enough space in the buffer
(sdu_buf.len < sdu_len) then the rest of the SDU will be
silently discarded by the SoftDevice. */
} ble_l2cap_evt_ch_rx_t;
/**@brief L2CAP Channel transmitted SDU event. */
typedef struct
{
ble_data_t sdu_buf; /**< SDU data buffer. */
} ble_l2cap_evt_ch_tx_t;
/**@brief L2CAP event structure. */
typedef struct
{
uint16_t conn_handle; /**< Connection Handle on which the event occured. */
uint16_t local_cid; /**< Local Channel ID of the L2CAP channel, or
@ref BLE_L2CAP_CID_INVALID if not present. */
union
{
ble_l2cap_evt_ch_setup_request_t ch_setup_request; /**< L2CAP Channel Setup Request Event Parameters. */
ble_l2cap_evt_ch_setup_refused_t ch_setup_refused; /**< L2CAP Channel Setup Refused Event Parameters. */
ble_l2cap_evt_ch_setup_t ch_setup; /**< L2CAP Channel Setup Completed Event Parameters. */
ble_l2cap_evt_ch_sdu_buf_released_t ch_sdu_buf_released;/**< L2CAP Channel SDU Data Buffer Released Event Parameters. */
ble_l2cap_evt_ch_credit_t credit; /**< L2CAP Channel Credit Received Event Parameters. */
ble_l2cap_evt_ch_rx_t rx; /**< L2CAP Channel SDU Received Event Parameters. */
ble_l2cap_evt_ch_tx_t tx; /**< L2CAP Channel SDU Transmitted Event Parameters. */
} params; /**< Event Parameters. */
} ble_l2cap_evt_t;
/** @} */
/**@addtogroup BLE_L2CAP_FUNCTIONS Functions
* @{ */
/**@brief Set up an L2CAP channel.
*
* @details This function is used to:
* - Request setup of an L2CAP channel: sends an LE Credit Based Connection Request packet to a peer.
* - Reply to a setup request of an L2CAP channel (if called in response to a
* @ref BLE_L2CAP_EVT_CH_SETUP_REQUEST event): sends an LE Credit Based Connection
* Response packet to a peer.
*
* @note A call to this function will require the application to keep the SDU data buffer alive
* until the SDU data buffer is returned in @ref BLE_L2CAP_EVT_CH_RX or
* @ref BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
*
* @events
* @event{@ref BLE_L2CAP_EVT_CH_SETUP, Setup successful.}
* @event{@ref BLE_L2CAP_EVT_CH_SETUP_REFUSED, Setup failed.}
* @endevents
*
* @mscs
* @mmsc{@ref BLE_L2CAP_CH_SETUP_MSC}
* @endmscs
*
* @param[in] conn_handle Connection Handle.
* @param[in,out] p_local_cid Pointer to a uint16_t containing Local Channel ID of the L2CAP channel:
* - As input: @ref BLE_L2CAP_CID_INVALID when requesting setup of an L2CAP
* channel or local_cid provided in the @ref BLE_L2CAP_EVT_CH_SETUP_REQUEST
* event when replying to a setup request of an L2CAP channel.
* - As output: local_cid for this channel.
* @param[in] p_params L2CAP channel parameters.
*
* @retval ::NRF_SUCCESS Successfully queued request or response for transmission.
* @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry.
* @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
* @retval ::NRF_ERROR_INVALID_LENGTH Supplied higher rx_mps than has been configured on this link.
* @retval ::NRF_ERROR_INVALID_STATE Invalid State to perform operation (L2CAP channel already set up).
* @retval ::NRF_ERROR_NOT_FOUND CID not found.
* @retval ::NRF_ERROR_RESOURCES The limit has been reached for available L2CAP channels,
* see @ref ble_l2cap_conn_cfg_t::ch_count.
*/
SVCALL(SD_BLE_L2CAP_CH_SETUP, uint32_t, sd_ble_l2cap_ch_setup(uint16_t conn_handle, uint16_t *p_local_cid, ble_l2cap_ch_setup_params_t const *p_params));
/**@brief Release an L2CAP channel.
*
* @details This sends a Disconnection Request packet to a peer.
*
* @events
* @event{@ref BLE_L2CAP_EVT_CH_RELEASED, Release complete.}
* @endevents
*
* @mscs
* @mmsc{@ref BLE_L2CAP_CH_RELEASE_MSC}
* @endmscs
*
* @param[in] conn_handle Connection Handle.
* @param[in] local_cid Local Channel ID of the L2CAP channel.
*
* @retval ::NRF_SUCCESS Successfully queued request for transmission.
* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_STATE Invalid State to perform operation (Setup or release is
* in progress for the L2CAP channel).
* @retval ::NRF_ERROR_NOT_FOUND CID not found.
*/
SVCALL(SD_BLE_L2CAP_CH_RELEASE, uint32_t, sd_ble_l2cap_ch_release(uint16_t conn_handle, uint16_t local_cid));
/**@brief Receive an SDU on an L2CAP channel.
*
* @details This may issue additional credits to the peer using an LE Flow Control Credit packet.
*
* @note A call to this function will require the application to keep the memory pointed by
* @ref ble_data_t::p_data alive until the SDU data buffer is returned in @ref BLE_L2CAP_EVT_CH_RX
* or @ref BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
*
* @note The SoftDevice can queue up to @ref ble_l2cap_conn_cfg_t::rx_queue_size SDU data buffers
* for reception per L2CAP channel.
*
* @events
* @event{@ref BLE_L2CAP_EVT_CH_RX, The SDU is received.}
* @endevents
*
* @mscs
* @mmsc{@ref BLE_L2CAP_CH_RX_MSC}
* @endmscs
*
* @param[in] conn_handle Connection Handle.
* @param[in] local_cid Local Channel ID of the L2CAP channel.
* @param[in] p_sdu_buf Pointer to the SDU data buffer.
*
* @retval ::NRF_SUCCESS Buffer accepted.
* @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_STATE Invalid State to perform operation (Setup or release is
* in progress for an L2CAP channel).
* @retval ::NRF_ERROR_NOT_FOUND CID not found.
* @retval ::NRF_ERROR_RESOURCES Too many SDU data buffers supplied. Wait for a
* @ref BLE_L2CAP_EVT_CH_RX event and retry.
*/
SVCALL(SD_BLE_L2CAP_CH_RX, uint32_t, sd_ble_l2cap_ch_rx(uint16_t conn_handle, uint16_t local_cid, ble_data_t const *p_sdu_buf));
/**@brief Transmit an SDU on an L2CAP channel.
*
* @note A call to this function will require the application to keep the memory pointed by
* @ref ble_data_t::p_data alive until the SDU data buffer is returned in @ref BLE_L2CAP_EVT_CH_TX
* or @ref BLE_L2CAP_EVT_CH_SDU_BUF_RELEASED event.
*
* @note The SoftDevice can queue up to @ref ble_l2cap_conn_cfg_t::tx_queue_size SDUs for
* transmission per L2CAP channel.
*
* @note The application can keep track of the available credits for transmission by following
* the procedure below:
* - Store initial credits given by the peer in a variable.
* (Initial credits are provided in a @ref BLE_L2CAP_EVT_CH_SETUP event.)
* - Decrement the variable, which stores the currently available credits, by
* ceiling((@ref ble_data_t::len + 2) / tx_mps) when a call to this function returns
* @ref NRF_SUCCESS. (tx_mps is provided in a @ref BLE_L2CAP_EVT_CH_SETUP event.)
* - Increment the variable, which stores the currently available credits, by additional
* credits given by the peer in a @ref BLE_L2CAP_EVT_CH_CREDIT event.
*
* @events
* @event{@ref BLE_L2CAP_EVT_CH_TX, The SDU is transmitted.}
* @endevents
*
* @mscs
* @mmsc{@ref BLE_L2CAP_CH_TX_MSC}
* @endmscs
*
* @param[in] conn_handle Connection Handle.
* @param[in] local_cid Local Channel ID of the L2CAP channel.
* @param[in] p_sdu_buf Pointer to the SDU data buffer.
*
* @retval ::NRF_SUCCESS Successfully queued L2CAP SDU for transmission.
* @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_STATE Invalid State to perform operation (Setup or release is
* in progress for the L2CAP channel).
* @retval ::NRF_ERROR_NOT_FOUND CID not found.
* @retval ::NRF_ERROR_DATA_SIZE Invalid SDU length supplied, must not be more than
* @ref ble_l2cap_ch_tx_params_t::tx_mtu provided in
* @ref BLE_L2CAP_EVT_CH_SETUP event.
* @retval ::NRF_ERROR_RESOURCES Too many SDUs queued for transmission. Wait for a
* @ref BLE_L2CAP_EVT_CH_TX event and retry.
*/
SVCALL(SD_BLE_L2CAP_CH_TX, uint32_t, sd_ble_l2cap_ch_tx(uint16_t conn_handle, uint16_t local_cid, ble_data_t const *p_sdu_buf));
/**@brief Advanced SDU reception flow control.
*
* @details Adjust the way the SoftDevice issues credits to the peer.
* This may issue additional credits to the peer using an LE Flow Control Credit packet.
*
* @mscs
* @mmsc{@ref BLE_L2CAP_CH_FLOW_CONTROL_MSC}
* @endmscs
*
* @param[in] conn_handle Connection Handle.
* @param[in] local_cid Local Channel ID of the L2CAP channel or @ref BLE_L2CAP_CID_INVALID to set
* the value that will be used for newly created channels.
* @param[in] credits Number of credits that the SoftDevice will make sure the peer has every
* time it starts using a new reception buffer.
* - @ref BLE_L2CAP_CREDITS_DEFAULT is the default value the SoftDevice will
* use if this function is not called.
* - If set to zero, the SoftDevice will stop issuing credits for new reception
* buffers the application provides or has provided. SDU reception that is
* currently ongoing will be allowed to complete.
* @param[out] p_credits NULL or pointer to a uint16_t. If a valid pointer is provided, it will be
* written by the SoftDevice with the number of credits that is or will be
* available to the peer. If the value written by the SoftDevice is 0 when
* credits parameter was set to 0, the peer will not be able to send more
* data until more credits are provided by calling this function again with
* credits > 0. This parameter is ignored when local_cid is set to
* @ref BLE_L2CAP_CID_INVALID.
*
* @note Application should take care when setting number of credits higher than default value. In
* this case the application must make sure that the SoftDevice always has reception buffers
* available (see @ref sd_ble_l2cap_ch_rx) for that channel. If the SoftDevice does not have
* such buffers available, packets may be NACKed on the Link Layer and all Bluetooth traffic
* on the connection handle may be stalled until the SoftDevice again has an available
* reception buffer. This applies even if the application has used this call to set the
* credits back to default, or zero.
*
* @retval ::NRF_SUCCESS Flow control parameters accepted.
* @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
* @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
* @retval ::NRF_ERROR_INVALID_STATE Invalid State to perform operation (Setup or release is
* in progress for an L2CAP channel).
* @retval ::NRF_ERROR_NOT_FOUND CID not found.
*/
SVCALL(SD_BLE_L2CAP_CH_FLOW_CONTROL, uint32_t, sd_ble_l2cap_ch_flow_control(uint16_t conn_handle, uint16_t local_cid, uint16_t credits, uint16_t *p_credits));
/** @} */
#ifdef __cplusplus
}
#endif
#endif // BLE_L2CAP_H__
/**
@}
*/
|
