Mistake on this page?
Report an issue in GitHub or email us
lctr_int_adv_slave_ae.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief Internal link layer controller slave extended advertising interface file.
6  *
7  * Copyright (c) 2013-2019 Arm Ltd. All Rights Reserved.
8  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 
25 #ifndef LCTR_INT_ADV_SLAVE_AE_H
26 #define LCTR_INT_ADV_SLAVE_AE_H
27 
28 #include "lctr_int_adv_ae.h"
29 #include "lctr_int.h"
30 #include "lctr_api_adv_slave_ae.h"
31 #include "lmgr_api_adv_slave_ae.h"
32 #include "bb_ble_api.h"
33 #include "bb_ble_api_op.h"
34 #include "lctr_pdu_adv.h"
35 #include "wsf_timer.h"
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 /**************************************************************************************************
42  Macros
43 **************************************************************************************************/
44 
45 /*! \brief Maximum value of the AuxPtr offset field. */
46 #define LCTR_AUX_PTR_MAX_OFFSET 0x3FFF
47 
48 /*! \brief Number of shifted bytes for Used PHY field from the AUX Offset. */
49 #define LCTR_AUX_OFFS_USED_PHY_SHIFT 13
50 
51 /*! \brief Extended Advertising packet length. */
52 #define LCTR_EXT_ADVB_LEN(ehLen, dLen) (LL_ADV_HDR_LEN + ehLen + dLen)
53 
54 /*! \brief Extended header common field length. */
55 #define LCTR_EXT_HDR_CMN_LEN 1
56 
57 /*! \brief Extended header flags field length. */
58 #define LCTR_EXT_HDR_FLAG_LEN 1
59 
60 /*! \brief Maximum size of a single complete advertising data buffer. */
61 #define LCTR_COMP_EXT_ADV_DATA_MAX_LEN 251 /* TODO: cfg_mac_ble.h configuration */
62 
63 /*! \brief Resolve the extended advertising index from the context pointer. */
64 #define LCTR_GET_EXT_ADV_INDEX(pAdvSet) (pAdvSet - &pLctrAdvSetTbl[0])
65 
66 /*! \brief Get reservation manager handle for periodic ADV from the context pointer. */
67 #define LCTR_GET_PER_RM_HANDLE(pAdvSet) (LL_MAX_CONN + LCTR_GET_EXT_ADV_INDEX(pAdvSet))
68 
69 /*! \brief Call signature for slave ACAD BIG related function. */
70 typedef void (*lctrAcadBigHdlr_t)(uint8_t advHandle);
71 
72 /*! \brief Call signature for AdvSet Remove event handler. */
73 typedef void (*lctrRemoveHdlr_t)(uint8_t advHandle);
74 
75 /**************************************************************************************************
76  Constants
77 **************************************************************************************************/
78 
79 /*! \brief Slave extended advertising states. */
80 enum
81 {
82  LCTR_EXT_ADV_STATE_DISABLED, /*!< Extended advertising disabled state. */
83  LCTR_EXT_ADV_STATE_ENABLED, /*!< Extended advertising enabled state. */
84  LCTR_EXT_ADV_STATE_SHUTDOWN, /*!< Extended advertising shutdown in progress. */
85  LCTR_EXT_ADV_STATE_RESET, /*!< Extended advertising reset in progress. */
86  LCTR_EXT_ADV_STATE_TOTAL /*!< Total number of extended advertising states. */
87 };
88 
89 /*! \brief Slave periodic advertising states. */
90 enum
91 {
92  LCTR_PER_ADV_STATE_DISABLED, /*!< Periodic advertising disabled state. */
93  LCTR_PER_ADV_STATE_ENABLED, /*!< Periodic advertising enabled state. */
94  LCTR_PER_ADV_STATE_SHUTDOWN, /*!< Periodic advertising shutdown in progress. */
95  LCTR_PER_ADV_STATE_RESET, /*!< Periodic advertising reset in progress. */
96  LCTR_PER_ADV_STATE_TOTAL /*!< Total number of Periodic advertising states. */
97 };
98 
99 /**************************************************************************************************
100  Data Types
101 **************************************************************************************************/
102 
103 /*! \brief Extended advertising parameters. */
104 typedef struct
105 {
106  uint16_t advEventProp; /*!< Advertising Event Properties. */
107  uint32_t priAdvInterMinUsec; /*!< Primary Advertising Interval Minimum in microseconds. */
108  uint32_t priAdvInterMaxUsec; /*!< Primary Advertising Interval Maximum in microseconds. */
109  uint32_t priAdvTermCntDownUsec; /*!< Primary Advertising termination count down in microseconds. */
110  uint64_t peerAddr; /*!< Peer Address. */
111  uint8_t priAdvChanMap; /*!< Primary Advertising Channel Map. */
112  uint8_t ownAddrType; /*!< Own Address Type. */
113  uint8_t peerAddrType; /*!< Peer Address Type. */
114  uint8_t advFiltPolicy; /*!< Advertising Filter Policy. */
115  int8_t advTxPwr; /*!< Advertising Tx Power. */
116  uint8_t priAdvPhy; /*!< Primary Advertising PHY. */
117  uint8_t secAdvMaxSkip; /*!< Secondary Advertising Maximum Skip. */
118  uint8_t secAdvPhy; /*!< Secondary Advertising PHY. */
119  uint16_t advDID; /*!< Advertising Data ID. */
120  uint8_t advSID; /*!< Advertising SID. */
121  uint8_t scanReqNotifEna; /*!< Scan Request Notification Enable. */
123 
124 /*! \brief Periodic advertising parameters. */
125 typedef struct
126 {
127  uint8_t perState; /*!< Current periodic adv state. */
128  bool_t perAdvEnabled; /*!< Periodic advertising enabled or not. */
129  uint32_t perAccessAddr; /*!< Periodic advertising access address. */
130  uint16_t perEventCounter; /*!< Periodic event counter. */
131  bool_t perAuxStart; /*!< True if need to start aux BOD due to periodic adv. */
132 
133  BbOpDesc_t perAdvBod; /*!< Periodic advertising BOD. */
134  BbBleData_t perBleData; /*!< Periodic advertising BLE data. */
135  uint32_t perOffsUsec; /*!< Offset in microseconds to the next periodic PDU. */
136  uint8_t perChHopInc; /*!< Periodic channel hop increment value. */
137  uint8_t perChIdx; /*!< Periodic LL Channel. */
138  bool_t shutdown; /*!< Client initiated shutdown flag. */
139  uint32_t perAdvInterUsec; /*!< Periodic advertising interval in microseconds. */
140 
141  uint32_t advInterMinUsec; /*!< Periodic Advertising Interval Minimum in microseconds. */
142  uint32_t advInterMaxUsec; /*!< Periodic Advertising Interval Maximum in BB ticks. */
143  uint16_t advEventProp; /*!< Periodic Advertising Event Properties. */
144  bool_t advParamReady; /*!< Periodic Advertising Parameter is ready or not. */
145 
146  /* Channel parameters */
147  lmgrChanParam_t perChanParam; /*!< Periodic Advertising Channel parameter. */
148  uint64_t updChanMask; /*!< Last updated channel mask */
150 
151 /*! \brief Advertising data buffer descriptor. */
152 typedef struct
153 {
154  uint16_t len; /*!< Advertising data length. */
155  uint8_t *pBuf; /*!< Advertising data buffer. */
156  bool_t ready; /*!< Advertising data buffer complete. */
157  uint16_t txOffs; /*!< Tx buffer offset. */
158  uint8_t fragPref; /*!< Host fragmentation preference. */
159 
160  union
161  {
162  struct
163  {
164  bool_t modified; /*!< Content modified by host. */
165  uint8_t len; /*!< Advertising data buffer length. */
166  uint16_t did; /*!< Advertising Data ID. */
168  /*!< Advertising data buffer. */
169  uint8_t fragPref; /*!< Host fragmentation preference. */
170  } ext; /*!< Extended advertising data buffer cache (temporary storage during active advertising). */
171 
172  struct
173  {
174  bool_t modified; /*!< Content modified by host. */
175  uint8_t len; /*!< Advertising data buffer length. */
176  uint8_t buf[LL_ADVBU_MAX_LEN];
177  /*!< Advertising data buffer. */
178  } legacy; /*!< Legacy advertising data buffer. */
179  } alt; /*!< Alternate data storage. */
181 
182 /*! \brief Advertising set. */
183 typedef struct
184 {
185  bool_t enabled; /*!< Enable flag. */
186  uint8_t handle; /*!< Advertising handle. */
187 
188  uint8_t state; /*!< Current state. */
189 
190  /* Host parameters */
191  bool_t bdAddrRndMod; /*!< Modified random address. */
192  bool_t bdAddrRndValid; /*!< Random device address valid. */
193  uint64_t bdAddrRnd; /*!< Random device address. */
194  uint64_t advA; /*!< Advertiser address. */
195  uint64_t tgtA; /*!< Target address. */
196  lctrExtAdvParam_t param; /*!< Extended advertising parameters. */
197  uint32_t auxDelayUsec; /*!< Auxiliary advertising event delay. */
198  uint8_t advDataFragLen; /*!< Advertising data fragmentation length. */
199 
200  /* ACAD control block */
201  lctrAcadParam_t acadParams[LCTR_ACAD_NUM_ID]; /*!< ACAD parameters. */
202 
203  /* Periodic advertising parameters */
204  lctrPerAdvParam_t perParam; /*!< Periodic advertising parameters. */
205 
206  /* Enable parameters */
207  wsfTimer_t tmrAdvDur; /*!< Advertising duration timer. */
208  uint8_t maxEvents; /*!< Maximum number of AE. */
209 
210  /* Advertising task context */
211  uint8_t numEvents; /*!< Number of completed AE. */
212  uint8_t termReason; /*!< Termination reason. */
213  uint8_t extHdrFlags; /*!< Extended header flags. */
214  uint8_t *pExtAdvAuxPtr; /*!< Extended advertising PDU buffer location of AuxPtr field. */
215  uint8_t auxChHopInc; /*!< Auxiliary channel hop increment value. */
216  uint32_t auxSkipInterUsec; /*!< Total skip time in microseconds. */
217 
218  /* Buffers */
220  /*!< Primary channel legacy advertising and extended advertising header buffer. */
221  uint8_t scanRspHdrBuf[LL_ADVB_MAX_LEN];
222  /*!< Primary channel legacy scan response buffer. */
223  uint8_t auxAdvHdrBuf[LCTR_EXT_ADVB_LEN(LL_EXT_ADV_HDR_MAX_LEN, 0)];
224  /*!< Auxiliary extended advertising header buffer. */
225  uint8_t auxRspHdrBuf[LCTR_EXT_ADVB_LEN(LL_EXT_ADV_HDR_MAX_LEN, 0)];
226  /*!< Auxiliary scan or connect response header buffer. */
227  uint8_t perAdvHdrBuf[LCTR_EXT_ADVB_LEN(LL_EXT_ADV_HDR_MAX_LEN, 0)];
228  /*!< Periodic advertising header buffer. */
229  lctrAdvDataBuf_t advData; /*!< Advertising data buffer. */
230  lctrAdvDataBuf_t scanRspData; /*!< Scan response data buffer. */
231  lctrAdvDataBuf_t perAdvData; /*!< Periodic advertising data buffer. */
232 
233  /* Connection context. */
234  bool_t isAuxConnReq; /*!< True if AUX_CONN_REQ is received, False if CONN_IND is received. */
235  uint32_t connIndEndTsUsec; /*!< Connection indication end timestamp in microseconds. */
236  bool_t connIndRcvd; /*!< Connection request received flag. */
237  uint8_t usedChSel; /*!< Used channel selection. */
238 
239  /* BB/ISR context */
240  bool_t shutdown; /*!< Client initiated shutdown flag. */
241  uint8_t bodTermCnt; /*!< Number of BOD terminated. */
242  BbOpDesc_t advBod; /*!< Advertising BOD. */
243  BbBleData_t bleData; /*!< BLE data. */
244  BbOpDesc_t auxAdvBod; /*!< Auxiliary advertising BOD. */
245  BbBleData_t auxBleData; /*!< Auxiliary BLE data. */
246  uint32_t auxOffsUsec; /*!< Offset in microseconds to the next auxiliary PDU. */
247  uint8_t auxChIdx; /*!< AUX LL Channel. */
248  bool_t auxBodUsed; /*!< Auxiliary BOD in use flag. */
249  bool_t didPerUpdate; /*!< Data ID update due to periodic enable or disable. */
250  bool_t advBodAbort; /*!< TRUE if extended advertising BOD is aborted. */
251  lctrAdvbPduHdr_t rspPduHdr; /*!< Response PDU header. */
252 
253  /* BIG */
254  lctrAcadBigHdlr_t bigCreated; /*!< Function pointer to the BIG created action function. */
255  lctrAcadBigHdlr_t bigTerminated; /*!< Function pointer to the BIG terminated action function. */
256  lctrRemoveHdlr_t removeCback; /*!< Function pointer to the AdvSet remove action function. */
257 } lctrAdvSet_t;
258 
259 /*! \brief Slave extended advertising state context. */
260 typedef struct
261 {
262  wsfQueue_t rxScanReqQ; /*!< Received SCAN_REQ queue. */
264 
265 /**************************************************************************************************
266  Globals
267 **************************************************************************************************/
268 
269 extern lctrAdvSet_t *pLctrAdvSetTbl;
270 extern LctrExtAdvMsg_t *pLctrSlvExtAdvMsg;
271 extern lctrSlvExtAdvCtx_t lctrSlvExtAdv;
272 extern LctrPerAdvMsg_t *pLctrSlvPerAdvMsg;
273 extern lctrAcadSlvMsg_t *pLctrAcadSlvMsg;
274 
275 /**************************************************************************************************
276  Function Declarations
277 **************************************************************************************************/
278 
279 /* Context */
280 void lctrFreeAdvSet(lctrAdvSet_t *pAdvSet);
281 lctrAdvSet_t *lctrFindAdvSet(uint8_t handle);
282 
283 /* Address selection */
284 void lctrChooseSetAdvA(lctrAdvbPduHdr_t *pPduHdr, BbBleData_t * const pBle, lctrAdvSet_t *pAdvSet);
285 void lctrChooseSetPeerA(lctrAdvbPduHdr_t *pPduHdr, BbBleData_t * const pBle, lctrAdvSet_t *pAdvSet);
286 
287 /* Builder */
288 uint8_t lctrSlvExtAdvBuildOp(lctrAdvSet_t *pAdvSet, uint32_t maxStartMs);
289 void lctrSlvAuxNonConnNonScanBuildOp(lctrAdvSet_t *pAdvSet);
290 void lctrSlvAuxScanBuildOp(lctrAdvSet_t *pAdvSet);
291 void lctrSlvAuxConnBuildOp(lctrAdvSet_t *pAdvSet);
292 void lctrSlvAuxRescheduleOp(lctrAdvSet_t *pAdvSet, BbOpDesc_t * const pOp);
293 uint8_t lctrSlvPeriodicAdvBuildOp(lctrAdvSet_t *pAdvSet);
294 
295 /* Channel */
296 void lctrSelectNextAuxChannel(lctrAdvSet_t *pAdvSet);
297 void lctrSelectNextPerChannel(lctrAdvSet_t *pAdvSet);
298 
299 /* ISR: Packet handlers */
300 void lctrSlvTxSetupExtAdvHandler(BbOpDesc_t *pOp, uint32_t txTime);
301 uint32_t lctrSlvTxSetupAuxAdvDataHandler(BbOpDesc_t *pOp, bool_t isChainInd);
302 uint32_t lctrSlvTxSetupAuxScanRspDataHandler(BbOpDesc_t *pOp, bool_t isChainInd);
303 bool_t lctrSlvRxAuxScanReqHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
304 void lctrSlvRxAuxScanReqPostProcessHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
305 void lctrSlvRxLegacyScanReqPostProcessHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
306 bool_t lctrSlvRxAuxConnReqHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
307 bool_t lctrSlvRxLegacyReqHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
308 void lctrSlvRxLegacyReqPostProcessHandler(BbOpDesc_t *pOp, const uint8_t *pReqBuf);
309 uint32_t lctrSlvTxSetupPeriodicAdvDataHandler(BbOpDesc_t *pOp, bool_t isChainInd);
310 void lctrSlvAcadHandler(lctrAdvSet_t *pAdvSet);
311 void lctrSlvAcadDisable(lctrAcadParam_t *pAcadParam);
312 
313 /* ISR: BOD handlers */
314 void lctrSlvExtAdvEndOp(BbOpDesc_t *pOp);
315 void lctrSlvExtAdvAbortOp(BbOpDesc_t *pOp);
316 void lctrSlvAuxAdvEndOp(BbOpDesc_t *pOp);
317 void lctrSlvPeriodicAdvEndOp(BbOpDesc_t *pOp);
318 void lctrSlvPeriodicAdvAbortOp(BbOpDesc_t *pOp);
319 
320 /* Action routines */
321 void lctrExtAdvActStart(lctrAdvSet_t *pAdvSet);
322 void lctrExtAdvActSelfStart(lctrAdvSet_t *pAdvSet);
323 void lctrExtAdvActRestart(lctrAdvSet_t *pAdvSet);
324 void lctrExtAdvActShutdown(lctrAdvSet_t *pAdvSet);
325 void lctrExtAdvActResetShutdown(lctrAdvSet_t *pAdvSet);
326 void lctrExtAdvActAdvCnf(lctrAdvSet_t *pAdvSet);
327 void lctrExtAdvActDisallowAdvCnf(lctrAdvSet_t *pAdvSet);
328 void lctrExtAdvActSelfTerm(lctrAdvSet_t *pAdvSet);
329 void lctrExtAdvActAdvTerm(lctrAdvSet_t *pAdvSet);
330 void lctrExtAdvActReset(lctrAdvSet_t *pAdvSet);
331 void lctrExtAdvActResetTerm(lctrAdvSet_t *pAdvSet);
332 void lctrExtAdvActDurationExpired(lctrAdvSet_t *pAdvSet);
333 void lctrPeriodicAdvActStart(lctrAdvSet_t *pAdvSet);
334 void lctrPeriodicAdvActUpdate(lctrAdvSet_t *pAdvSet);
335 void lctrPeriodicAdvActDisallowAdvCnf(lctrAdvSet_t *pAdvSet);
336 void lctrPeriodicAdvActShutdown(lctrAdvSet_t *pAdvSet);
337 void lctrPeriodicAdvActResetTerm(lctrAdvSet_t *pAdvSet);
338 void lctrPeriodicAdvActAdvTerm(lctrAdvSet_t *pAdvSet);
339 void lctrSlvAcadActChanMapUpdateStart(lctrAdvSet_t *pAdvSet);
340 void lctrSlvAcadActChanMapUpdateFinish(lctrAdvSet_t *pAdvSet);
341 void lctrSlvAcadActBigCreated(lctrAdvSet_t *pAdvSet);
342 void lctrSlvAcadActBigTerminated(lctrAdvSet_t *pAdvSet);
343 
344 /* Reservation */
345 uint32_t lctrGetPerRefTime(uint8_t perHandle, uint32_t *pDurUsec);
346 
347 /* State machine */
348 void lctrSlvExtAdvExecuteSm(lctrAdvSet_t *pAdvSet, uint8_t event);
349 void lctrSlvPeriodicAdvExecuteSm(lctrAdvSet_t *pAdvSet, uint8_t event);
350 void lctrSlvAcadExecuteSm(lctrAdvSet_t *pAdvSet, uint8_t event);
351 
352 /* Messaging */
353 void lctrSendAdvSetMsg(lctrAdvSet_t *pAdvSet, uint8_t event);
354 void lctrSendPeriodicAdvSetMsg(lctrAdvSet_t *pAdvSet, uint8_t event);
355 
356 #ifdef __cplusplus
357 };
358 #endif
359 
360 #endif /* LCTR_INT_ADV_SLAVE_AE_H */
lmgrChanParam_t perChanParam
Extended advertising common header file.
BLE baseband interface file.
void(* lctrAcadBigHdlr_t)(uint8_t advHandle)
Call signature for slave ACAD BIG related function.
Slave extended advertising state context.
Link layer controller message data.
Periodic Advertising message data.
Periodic advertising parameters.
lctrAdvDataBuf_t perAdvData
Link layer controller advertising channel packet interface file.
#define LL_ADVBU_MAX_LEN
Definition: ll_defs.h:102
lctrExtAdvParam_t param
lctrPerAdvParam_t perParam
Bluetooth Low Energy protocol specific operation parameters.
Channel parameters.
Definition: lmgr_api.h:137
lctrAcadBigHdlr_t bigCreated
Extended Advertising message data.
lctrRemoveHdlr_t removeCback
#define LCTR_COMP_EXT_ADV_DATA_MAX_LEN
Maximum size of a single complete advertising data buffer.
Advertising channel PDU header.
Definition: lctr_pdu_adv.h:50
Queue structure.
Definition: wsf_queue.h:46
lctrAdvDataBuf_t scanRspData
#define LL_EXT_ADV_HDR_MAX_LEN
Definition: ll_defs.h:151
Generic ACAD packet.
lctrAcadBigHdlr_t bigTerminated
Link layer controller extended advertising slave interface file.
Timer structure.
Definition: wsf_timer.h:53
Advertising data buffer descriptor.
lctrAdvDataBuf_t advData
Baseband operation descriptor (BOD).
Definition: bb_api.h:149
void(* lctrRemoveHdlr_t)(uint8_t advHandle)
Call signature for AdvSet Remove event handler.
Timer service.
BbBleData_t auxBleData
#define LCTR_EXT_ADVB_LEN(ehLen, dLen)
Extended Advertising packet length.
BLE baseband interface file.
#define LL_ADVB_MAX_LEN
Definition: ll_defs.h:103
Link layer manager advertising extension interface file.
Extended advertising parameters.
Internal link layer controller interface file.
Advertising set.
lctrAdvbPduHdr_t rspPduHdr
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.