Mistake on this page?
Report an issue in GitHub or email us
bb_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief Baseband interface file.
6  *
7  * Copyright (c) 2013-2018 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  * \addtogroup BB_API Baseband (BB) API
24  * \{
25  *
26  * The baseband porting layer is a protocol independent BB + radio abstraction layer. It allows
27  * the simultaneous operation of protocol specific schedulers to transport packets across each
28  * medium via a single multi-protocol baseband. This interface describes operations for the
29  * following protocols:
30  *
31  * - Bluetooth low energy: advertising and connections
32  * - ZigBee/802.15.4 (TBD)
33  * - BAN/802.15.6 (TBD)
34  *
35  * \dot
36  * digraph
37  * {
38  * node [shape=record, width=1.0, height=0.5, fontname=Helvetica, fontsize=8];
39  *
40  * ble [label="BLE\nlink layer", style=filled, fillcolor=lightgray];
41  * zigbee [label="802.15.4\nMAC", style=filled, fillcolor=lightgray];
42  * ban [label="802.15.6\nMAC", style=filled, fillcolor=lightgray];
43  * sch [label="Multi-protocol\nscheduler", style=filled, fillcolor=lightgray];
44  * bb_drv [label="{ BB porting layer | BB specific driver }"];
45  * bb_hw [label="BB hardware", style=filled, fillcolor=dimgray];
46  *
47  * ble -> sch;
48  * ble -> bb_drv;
49  * zigbee -> sch;
50  * zigbee -> bb_drv;
51  * ban -> sch;
52  * ban -> bb_drv;
53  * sch -> bb_drv;
54  * bb_drv -> bb_hw [style=dashed];
55  * }
56  * \enddot
57  *
58  * \defgroup BB_API_INIT Initialization
59  * \defgroup BB_API_BOD Baseband Operation Descriptors (BOD)
60  * \defgroup BB_API_CTRL Control interface
61  * \defgroup BB_API_BLE Bluetooth LE Protocol
62  *
63  * \}
64  */
65 /*************************************************************************************************/
66 
67 #ifndef BB_API_H
68 #define BB_API_H
69 
70 #include "wsf_types.h"
71 #include "cfg_mac.h"
72 #include "pal_bb.h"
73 
74 #ifdef __cplusplus
75 extern "C" {
76 #endif
77 
78 /**************************************************************************************************
79  Constants
80 **************************************************************************************************/
81 
82 /*! \addtogroup BB_API_BOD
83  * \{ */
84 
85 /*! \} */ /* BB_API_BOD */
86 
87 /**************************************************************************************************
88  Data Types
89 **************************************************************************************************/
90 
91 /*! \addtogroup BB_API_INIT
92  * \{ */
93 
94 /*! \brief BB runtime configuration parameters. */
95 typedef struct
96 {
97  /* Common */
98  uint16_t clkPpm; /*!< Clock accuracy in PPM. */
99  uint8_t rfSetupDelayUs; /*!< RF setup delay in microseconds. */
100 
101  /* BLE */
102  uint16_t maxScanPeriodMs; /*!< Maximum duration to scan in a scan interval. */
103 
104  /* Scheduler */
105  uint16_t schSetupDelayUs; /*!< Operation setup delay in microseconds. */
106  uint32_t BbTimerBoundaryUs; /*!< BB timer tick boundary translated in microseconds before wraparound. */
107 } BbRtCfg_t;
108 
109 /*! \} */ /* BB_API_INIT */
110 
111 /*! \addtogroup BB_API_BOD
112  * \{ */
113 
114 /* Forward definition of BOD. */
115 struct BbOpDesc_tag;
116 
117 /*! \brief BOD completion event callback signature. */
118 typedef void (*BbBodCompCback_t)(void);
119 
120 /*! \brief BOD event callback signature. */
121 typedef void (*BbBodCback_t)(struct BbOpDesc_tag *pBod);
122 
123 /*! \brief Protocol event callback signature. */
124 typedef void (*BbProtCback_t)(void);
125 
126 /*! \brief Low power callback. */
127 typedef void (*BbLowPowerCback_t)(void);
128 
129 /*! \brief BOD rescheduling policy (listed in priority order). */
130 typedef enum
131 {
132  BB_RESCH_FIXED_PREFERRED, /*!< BOD is fixed (rescheduling has limited recoverable consequences). */
133  BB_RESCH_FIXED, /*!< BOD is fixed (rescheduling has recoverable consequences). */
134  BB_RESCH_MOVEABLE_PREFERRED, /*!< BOD is movable (rescheduling has minor consequences). */
135  BB_RESCH_MOVEABLE, /*!< BOD is movable (rescheduling has no consequences). */
136  BB_RESCH_BACKGROUND /*!< BOD is single background task. */
137 } BbReschPol_t;
138 
139 /*! \} */ /* BB_API_BOD */
140 
141 /*! \addtogroup BB_API_BOD
142  * \{ */
143 
144 /* Forward protocol data definitions. */
145 struct BbBleData_tag;
146 struct Bb154Data_tag;
147 
148 /*! \brief Baseband operation descriptor (BOD). */
149 typedef struct BbOpDesc_tag
150 {
151  struct BbOpDesc_tag *pPrev; /*!< Previous BOD. */
152  struct BbOpDesc_tag *pNext; /*!< Next BOD. */
153 
154  uint32_t dueUsec; /*!< Absolute clock due time in microseconds. */
155  uint32_t minDurUsec; /*!< Minimum required duration in microseconds. */
156  uint32_t maxDurUsec; /*!< Maximum required duration in microseconds. */
157 
158  BbReschPol_t reschPolicy:8; /*!< Rescheduling policy. */
159 
160  PalBbProt_t protId:8; /*!< Protocol type. */
161 
162  BbBodCback_t endCback; /*!< End of BOD callback (when BOD ends). */
163  BbBodCback_t abortCback; /*!< Abort BOD callback (when BOD is removed before beginning). */
164 
165  void *pCtx; /*!< Client defined context. */
166  uint16_t *pDataLen; /*!< Pointer to client data length. */
167 
168  union
169  {
170  struct BbBleData_tag *pBle; /*!< BLE operation data. */
171  struct Bb154Data_tag *p154; /*!< 802.15.4 operation data. */
172  } prot; /*!< Protocol specific data. */
173 } BbOpDesc_t;
174 
175 /*! \} */ /* BB_API_BOD */
176 
177 /**************************************************************************************************
178  Function Declarations
179 **************************************************************************************************/
180 
181 /*! \addtogroup BB_API_INIT
182  * \{ */
183 
184 /*************************************************************************************************/
185 /*!
186  * \brief Initialize runtime configuration.
187  *
188  * \param pCfg Pointer to runtime configuration parameters (data must be static).
189  *
190  * This function initializes the BB subsystem's runtime configuration.
191  *
192  * \note This routine must be called only once before any other initialization routine.
193  */
194 /*************************************************************************************************/
195 void BbInitRunTimeCfg(const BbRtCfg_t *pCfg);
196 
197 /*************************************************************************************************/
198 /*!
199  * \brief Initialize the BB.
200  *
201  * Initialize baseband resources.
202  */
203 /*************************************************************************************************/
204 void BbInit(void);
205 
206 /*************************************************************************************************/
207 /*!
208  * \brief Register operation completion handler.
209  *
210  * \param eventCback Event callback.
211  *
212  * Register operation completion handler.
213  */
214 /*************************************************************************************************/
215 void BbRegister(BbBodCompCback_t eventCback);
216 
217 /*************************************************************************************************/
218 /*!
219  * \brief Register protocol handlers.
220  *
221  * \param protId Protocol ID.
222  * \param execOpCback Execute operation callback.
223  * \param cancelOpCback Cancel operation callback.
224  * \param startProtCback Start protocol callback.
225  * \param stopProtCback Stop protocol callback.
226  */
227 /*************************************************************************************************/
228 void BbRegisterProt(PalBbProt_t protId, BbBodCback_t execOpCback, BbBodCback_t cancelOpCback,
229  BbProtCback_t startProtCback, BbProtCback_t stopProtCback);
230 
231 /*************************************************************************************************/
232 /*!
233  * \brief Register protocol handlers for low power.
234  *
235  * \param protId Protocol ID.
236  * \param lowPowerOpCback Low power operation callback.
237  */
238 /*************************************************************************************************/
240 
241 /*! \} */ /* BB_API_INIT */
242 
243 /*! \addtogroup BB_API_CTRL
244  * \{ */
245 
246 /*************************************************************************************************/
247 /*!
248  * \brief Start BB processing of given protocol.
249  *
250  * \param protId Protocol ID.
251  *
252  * Enable BB and start processing the list of BODs. This routine may be called several times, if
253  * a protocol layers has several simultaneously-enabled operations. However, \ref BbStop() must
254  * be called an equal number of time to disable the baseband.
255  */
256 /*************************************************************************************************/
258 
259 /*************************************************************************************************/
260 /*!
261  * \brief Stop BB processing of given protocol.
262  *
263  * \param protId Protocol ID.
264  *
265  * Disable BB processing of BODs.
266  *
267  * \note For any particular protocol, calls to \ref BbStart() and \ref BbStop() must be
268  * balanced to ensure that the hardware is disabled if and only if appropriate.
269  */
270 /*************************************************************************************************/
272 
273 /*************************************************************************************************/
274 /*!
275  * \brief Execute BOD.
276  *
277  * \param pBod Pointer to the BOD to execute.
278  *
279  * Execute the protocol specific BOD handler.
280  */
281 /*************************************************************************************************/
282 void BbExecuteBod(BbOpDesc_t *pBod);
283 
284 /*************************************************************************************************/
285 /*!
286  * \brief Cancel current executing BOD.
287  */
288 /*************************************************************************************************/
289 void BbCancelBod(void);
290 
291 /*************************************************************************************************/
292 /*!
293  * \brief Get the currently-executing BOD.
294  *
295  * \return Currently-executing BOD.
296  */
297 /*************************************************************************************************/
299 
300 /*************************************************************************************************/
301 /*!
302  * \brief Set termination flag of current executing BOD.
303  *
304  * \note This function is expected to be called during the execution context of the
305  * current executing BOD, typically in the related ISRs. In the end, termination
306  * flag will help to decide if BbTerminateBod() should be called.
307  */
308 /*************************************************************************************************/
309 void BbSetBodTerminateFlag(void);
310 
311 /*************************************************************************************************/
312 /*!
313  * \brief Get termination state of current executing BOD.
314  *
315  * \return TRUE if termination flag set, FALSE otherwise.
316  */
317 /*************************************************************************************************/
318 bool_t BbGetBodTerminateFlag(void);
319 
320 /*************************************************************************************************/
321 /*!
322  * \brief Terminate a BOD immediately.
323  *
324  * \note This function is expected to be called during the execution context of the
325  * current executing BOD, typically in the related ISRs.
326  */
327 /*************************************************************************************************/
328 void BbTerminateBod(void);
329 
330 /*************************************************************************************************/
331 /*!
332  * \brief Get BB clock accuracy.
333  *
334  * \return Clock accuracy in part per million.
335  *
336  * Returns the current BB clock accuracy.
337  */
338 /*************************************************************************************************/
339 uint16_t BbGetClockAccuracy(void);
340 
341 /*************************************************************************************************/
342 /*!
343  * \brief Get BB timer boundary before wraparound.
344  *
345  * \return Time boundary in microseconds.
346  *
347  */
348 /*************************************************************************************************/
349 uint32_t BbGetBbTimerBoundaryUs(void);
350 
351 /*************************************************************************************************/
352 /*!
353  * \brief Get scheduler setup delay.
354  *
355  * \return Scheduler setup delay in microseconds.
356  *
357  * Returns the scheduler setup delay.
358  */
359 /*************************************************************************************************/
360 uint16_t BbGetSchSetupDelayUs(void);
361 
362 /*************************************************************************************************/
363 /*!
364  * \brief Adjust new time tick with wraparound.
365  *
366  * \param dueUsec Time tick without wraparound in microseconds.
367 
368  *
369  * \return Time tick with wraparound.
370  *
371  * \note dueUsec can only be at most +/-(BbTimerBoundaryUs/2) out of range.
372  */
373 /*************************************************************************************************/
374 uint32_t BbAdjustTime(uint32_t dueUsec);
375 
376 /*************************************************************************************************/
377 /*!
378  * \brief Get Delta between target and reference time. Only valid if target time is in the future.
379  *
380  * \param targetUsec Target time in microseconds.
381  * \param refUsec Reference time in microseconds.
382  *
383  * \return Positive number in microseconds if target time is in the future.
384  * Zero if target time is in the past or same compared with reference time.
385  *
386  * \note Caller has to make sure target time and reference time are within SCH_MAX_SPAN.
387  */
388 /*************************************************************************************************/
389 uint32_t BbGetTargetTimeDelta(uint32_t targetUsec, uint32_t refUsec);
390 
391 /*************************************************************************************************/
392 /*!
393  * \brief Returns the ID of the active protocol.
394  *
395  * \return Protocol operation in progress.
396  */
397 /*************************************************************************************************/
398 uint8_t BbGetActiveProtocol(void);
399 
400 /*! \} */ /* BB_API_CTRL */
401 
402 #ifdef __cplusplus
403 };
404 #endif
405 
406 #endif /* BB_API_H */
void(* BbBodCompCback_t)(void)
BOD completion event callback signature.
Definition: bb_api.h:118
void BbTerminateBod(void)
Terminate a BOD immediately.
uint32_t BbGetBbTimerBoundaryUs(void)
Get BB timer boundary before wraparound.
uint16_t BbGetClockAccuracy(void)
Get BB clock accuracy.
BB runtime configuration parameters.
Definition: bb_api.h:95
struct Bb154Data_tag * p154
Definition: bb_api.h:171
uint16_t BbGetSchSetupDelayUs(void)
Get scheduler setup delay.
bool_t BbGetBodTerminateFlag(void)
Get termination state of current executing BOD.
struct BbOpDesc_tag * pNext
Definition: bb_api.h:152
void(* BbProtCback_t)(void)
Protocol event callback signature.
Definition: bb_api.h:124
void BbStart(PalBbProt_t protId)
Start BB processing of given protocol.
uint32_t minDurUsec
Definition: bb_api.h:155
uint8_t BbGetActiveProtocol(void)
Returns the ID of the active protocol.
uint32_t dueUsec
Definition: bb_api.h:154
MAC system configuration.
BbReschPol_t
BOD rescheduling policy (listed in priority order).
Definition: bb_api.h:130
struct BbOpDesc_tag * pPrev
Definition: bb_api.h:151
BbOpDesc_t * BbGetCurrentBod(void)
Get the currently-executing BOD.
Bluetooth Low Energy protocol specific operation parameters.
void BbInitRunTimeCfg(const BbRtCfg_t *pCfg)
Initialize runtime configuration.
uint16_t * pDataLen
Definition: bb_api.h:166
void(* BbBodCback_t)(struct BbOpDesc_tag *pBod)
BOD event callback signature.
Definition: bb_api.h:121
uint32_t BbAdjustTime(uint32_t dueUsec)
Adjust new time tick with wraparound.
Platform-independent data types.
uint8_t rfSetupDelayUs
Definition: bb_api.h:99
void BbRegisterProtLowPower(PalBbProt_t protId, BbLowPowerCback_t lowPowerOpCback)
Register protocol handlers for low power.
void BbCancelBod(void)
Cancel current executing BOD.
PalBbProt_t protId
Definition: bb_api.h:160
void BbRegister(BbBodCompCback_t eventCback)
Register operation completion handler.
uint32_t BbGetTargetTimeDelta(uint32_t targetUsec, uint32_t refUsec)
Get Delta between target and reference time. Only valid if target time is in the future.
PalBbProt_t
Protocol types.
Definition: pal_bb.h:39
BbBodCback_t endCback
Definition: bb_api.h:162
void BbSetBodTerminateFlag(void)
Set termination flag of current executing BOD.
BbBodCback_t abortCback
Definition: bb_api.h:163
uint32_t BbTimerBoundaryUs
Definition: bb_api.h:106
Baseband operation descriptor (BOD).
Definition: bb_api.h:149
void BbExecuteBod(BbOpDesc_t *pBod)
Execute BOD.
void BbRegisterProt(PalBbProt_t protId, BbBodCback_t execOpCback, BbBodCback_t cancelOpCback, BbProtCback_t startProtCback, BbProtCback_t stopProtCback)
Register protocol handlers.
void(* BbLowPowerCback_t)(void)
Low power callback.
Definition: bb_api.h:127
Baseband interface file.
uint16_t schSetupDelayUs
Definition: bb_api.h:105
void BbStop(PalBbProt_t protId)
Stop BB processing of given protocol.
void * pCtx
Definition: bb_api.h:165
struct BbOpDesc_tag BbOpDesc_t
Baseband operation descriptor (BOD).
uint16_t maxScanPeriodMs
Definition: bb_api.h:102
uint32_t maxDurUsec
Definition: bb_api.h:156
void BbInit(void)
Initialize the BB.
union BbOpDesc_tag::@237 prot
uint16_t clkPpm
Definition: bb_api.h:98
BbReschPol_t reschPolicy
Definition: bb_api.h:158
struct BbBleData_tag * pBle
Definition: bb_api.h:170
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.