Mistake on this page?
Report an issue in GitHub or email us
pal_bb_ble.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief BLE Baseband 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 PAL_BB_BLE_H
26 #define PAL_BB_BLE_H
27 
28 #include "pal_bb.h"
29 #include "pal_crypto.h"
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /**************************************************************************************************
36  Macros
37 **************************************************************************************************/
38 
39 #ifndef LL_ENABLE_TESTER
40 #define LL_ENABLE_TESTER 0 /*!< Enable LL tester extensions. */
41 #endif
42 
43 /**************************************************************************************************
44  Data Types
45 **************************************************************************************************/
46 
47 /*! \brief Nonce modes. */
48 enum
49 {
50  PAL_BB_NONCE_MODE_PKT_CNTR, /*!< Packet counter mode (default). */
51  PAL_BB_NONCE_MODE_EXT16_CNTR, /*!< 16-bit counter mode, PalCryptoEnc_t::pEventCounter must be non-NULL. */
52  PAL_BB_NONCE_MODE_EXT64_CNTR /*!< 64-bit counter mode, PalCryptoEnc_t::pTxPktCounter/pRxPktCounter must be non-NULL. */
53 };
54 
55 /*! \brief Connection type. */
56 enum
57 {
58  PAL_BB_TYPE_ACL, /*!< ACL. */
59  PAL_BB_TYPE_CIS, /*!< CIS. */
60  PAL_BB_TYPE_BIS /*!< BIS. */
61 };
62 
63 /*! \addtogroup PAL_BB_BLE_CHAN
64  * \{ */
65 
66 /*! \brief BLE channelization parameters. */
67 typedef struct
68 {
69  uint8_t opType; /*!< Operation type. */
70  uint8_t chanIdx; /*!< Channel index. */
71  int8_t txPower; /*!< Active transmit power, unit is dBm. */
72  uint32_t accAddr; /*!< Access address. */
73  uint32_t crcInit; /*!< CRC initialization value. */
74  uint8_t txPhy; /*!< Transmitter PHY. */
75  uint8_t rxPhy; /*!< Receiver PHY. */
76  uint8_t initTxPhyOptions; /*!< Initial Tx PHY options. */
77  uint8_t tifsTxPhyOptions; /*!< TIFS Tx PHY options. */
78  bool_t peerTxStableModIdx; /*!< Peer uses stable modulation index on transmitter. */
79  bool_t peerRxStableModIdx; /*!< Peer uses stable modulation index on receiver. */
80  PalCryptoEnc_t enc; /*!< Encryption parameters (NULL if disabled). */
81 
82 #if (LL_ENABLE_TESTER)
83  uint32_t accAddrRx; /*!< Access address override for receptions. */
84  uint32_t accAddrTx; /*!< Access address override for transmissions. */
85  uint32_t crcInitRx; /*!< CRC initialization override for receptions. */
86  uint32_t crcInitTx; /*!< CRC initialization override for transmissions. */
87  int8_t txPwrOffset; /*!< override offset for txPower. */
88 #endif
90 
91 /*! \} */ /* PAL_BB_BLE_CHAN */
92 
93 /*! \addtogroup PAL_BB_BLE_DATA
94  * \{
95  * This section contains driver routines used for packet transmission.
96  */
97 
98 /*! \brief Transmit complete ISR callback signature. */
99 typedef void (*PalBbBleTxIsr_t)(uint8_t status);
100 
101 /*! \brief Receive complete ISR callback signature. */
102 typedef void (*PalBbBleRxIsr_t)(uint8_t status, int8_t rssi, uint32_t crc, uint32_t timestamp, uint8_t rxPhyOptions);
103 
104 /*! \brief IFS modes. */
105 typedef enum
106 {
107  PAL_BB_IFS_MODE_CLR, /*!< Clear IFS (last packet). */
108  PAL_BB_IFS_MODE_TOGGLE_TIFS, /*!< Toggle operation with TIFS timing. */
109  PAL_BB_IFS_MODE_SAME_ABS /*!< Same operation with absolute timing. */
111 
112 /*! \brief BLE data transfer parameters. */
113 typedef struct
114 {
115  PalBbBleTxIsr_t txCback; /*!< Transmit completion callback. */
116  PalBbBleRxIsr_t rxCback; /*!< Receive completion callback. */
117 
118  uint32_t dueUsec; /*!< Due time of the first packet in microseconds. */
119  uint32_t rxTimeoutUsec; /*!< Receive timeout in microseconds. */
121 
122 /*! \brief Operation parameters. */
123 typedef struct
124 {
125  PalBbIfsMode_t ifsMode:8; /*!< IFS mode for next operation. */
126  uint32_t ifsTime; /*!< Absolute time of next PDU. */
127  PalBbBleChan_t *pIfsChan; /*!< Channel of next PDU, NULL for no change. */
129 
130 /*! \brief Transmit buffer descriptor. */
131 typedef struct
132 {
133  uint16_t len; /*!< Length of buffer. */
134  uint8_t *pBuf; /*!< Pointer to buffer. */
136 
137 /*! \} */ /* PAL_BB_BLE_DATA */
138 
139 /**************************************************************************************************
140  Function Declarations
141 **************************************************************************************************/
142 
143 /*! \addtogroup PAL_BB_BLE_INIT
144  * \{
145  * This section contains driver routines which initialize as well as enable the BLE mode of the
146  * BB hardware.
147  */
148 
149 /*************************************************************************************************/
150 /*!
151  * \brief Initialize the BLE baseband driver.
152  *
153  * One-time initialization of BLE baseband driver.
154  */
155 /*************************************************************************************************/
156 void PalBbBleInit(void);
157 
158 /*************************************************************************************************/
159 /*!
160  * \brief Enable the BB hardware.
161  *
162  * Wake the BB hardware out of sleep and enable for operation. All BB functionality is
163  * available when this routine completes. BB clock is set to zero and started.
164  */
165 /*************************************************************************************************/
166 void PalBbBleEnable(void);
167 
168 /*************************************************************************************************/
169 /*!
170  * \brief Disable the BB hardware.
171  *
172  * Disable the baseband and put radio hardware to sleep. Must be called from an idle state.
173  * A radio operation cannot be in progress.
174  */
175 /*************************************************************************************************/
176 void PalBbBleDisable(void);
177 
178 /*! \} */ /* PAL_BB_BLE_INIT */
179 
180 /*! \addtogroup PAL_BB_BLE_CHAN
181  * \{
182  * This section contains the driver routine used to set the chanelization parameters.
183  */
184 
185 /*************************************************************************************************/
186 /*!
187  * \brief Set channelization parameters.
188  *
189  * \param pChan Channelization parameters.
190  *
191  * Calling this routine will set parameters for all future transmit and receive operations
192  * until this routine is called again providing new parameters.
193  *
194  * The setting of channelization parameters influence the operations of the following listed
195  * routines. Therefore, this routine is called to set the channel characteristics before
196  * the use of data routines described in \a PAL_BB_BLE_DATA.
197  *
198  * \note The \a pParam contents are not guaranteed to be static and is only valid in the
199  * context of the call to this routine. Therefore parameters requiring persistence
200  * should be copied.
201  */
202 /*************************************************************************************************/
204 
205 /*! \} */ /* PAL_BB_BLE_CHAN */
206 
207 /*! \addtogroup PAL_BB_BLE_DATA
208  * \{
209  * This section contains driver routines used for packet transmission.
210  */
211 
212 /*************************************************************************************************/
213 /*!
214  * \brief Set the data packet exchange parameters.
215  *
216  * \param pParam Data exchange parameters.
217  *
218  * Calling this routine will set parameters for all future transmit and receive operations
219  * until this routine is called again providing new parameters.
220  */
221 /*************************************************************************************************/
222 void PalBbBleSetDataParams(const PalBbBleDataParam_t *pParam);
223 
224 /*************************************************************************************************/
225 /*!
226  * \brief Set the operation parameters.
227  *
228  * \param pOpParam Operations parameters.
229  *
230  * Calling this routine will set parameters for the next transmit or receive operations.
231  */
232 /*************************************************************************************************/
233 void PalBbBleSetOpParams(const PalBbBleOpParam_t *pOpParam);
234 
235 /*************************************************************************************************/
236 /*!
237  * \brief Transmit a packet.
238  *
239  * \param descs Array of transmit buffer descriptors.
240  * \param cnt Number of descriptors.
241  *
242  * Set the first data buffer for the first packet of an alternating Tx-Rx data exchange cycle.
243  */
244 /*************************************************************************************************/
245 void PalBbBleTxData(PalBbBleTxBufDesc_t descs[], uint8_t cnt);
246 
247 /*************************************************************************************************/
248 /*!
249  * \brief Transmit packet at TIFS after the last packet received.
250  *
251  * \param descs Array of transmit buffer descriptor.
252  * \param cnt Number of descriptors.
253  *
254  * If possible, the transmit will occur at the TIFS timing. If not possible, the callback status
255  * will indicate this.
256  */
257 /*************************************************************************************************/
258 void PalBbBleTxTifsData(PalBbBleTxBufDesc_t descs[], uint8_t cnt);
259 
260 /*************************************************************************************************/
261 /*!
262  * \brief Receive packet.
263  *
264  * \param pBuf Receive data buffer.
265  * \param len Length of data buffer.
266  *
267  * Set the first data buffer for the first packet of an alternating Rx-Tx data exchange cycle.
268  */
269 /*************************************************************************************************/
270 void PalBbBleRxData(uint8_t *pBuf, uint16_t len);
271 
272 /*************************************************************************************************/
273 /*!
274  * \brief Receive packet at TIFS after the last packet transmitted.
275  *
276  * \param pBuf Receive data buffer.
277  * \param len Length of data buffer.
278  *
279  * If possible, the receive will occur on the TIFS timing. If not possible, the callback status
280  * will indicate this.
281  */
282 /*************************************************************************************************/
283 void PalBbBleRxTifsData(uint8_t *pBuf, uint16_t len);
284 
285 /*************************************************************************************************/
286 /*!
287  * \brief Cancel TIFS timer.
288  *
289  * This stops any active TIFS timer operation. This routine is always called in the callback
290  * (i.e. ISR) context.
291  */
292 /*************************************************************************************************/
293 void PalBbBleCancelTifs(void);
294 
295 /*************************************************************************************************/
296 /*!
297  * \brief Cancel a pending transmit or receive.
298  *
299  * This stops any active radio operation. This routine is never called in the callback
300  * (i.e. ISR) context.
301  */
302 /*************************************************************************************************/
303 void PalBbBleCancelData(void);
304 
305 /*! \} */ /* PAL_BB_BLE_DATA */
306 
307 /*! \addtogroup PAL_BB_BLE_TEST
308  * \{
309  * This section contains driver routines used for test modes.
310  */
311 
312 /*************************************************************************************************/
313 /*!
314  * \brief Enable or disable data whitening.
315  *
316  * \param enable Flag to indicate data whitening.
317  *
318  * Sets an internal variable that indicates if data whitening is enabled or not.
319  */
320 /*************************************************************************************************/
321 void PalBbBleEnableDataWhitening(bool_t enable);
322 
323 /*************************************************************************************************/
324 /*!
325  * \brief Enable or disable PRBS15.
326  *
327  * \param enable Flag to indicate PRBS15.
328  *
329  * Immediately enable or disable continuous PRBS15 bitstream. Setting the channelization
330  * parameters with \a PalBbBleSetChannelParam() must precede enabling PRBS15.
331  *
332  * Use of \a PAL_BB_BLE_DATA routines is not allowed while PRBS15 is enabled.
333  */
334 /*************************************************************************************************/
335 void PalBbBleEnablePrbs15(bool_t enable);
336 
337 /*************************************************************************************************/
338 /*!
339  * \brief Set inline encryption/decryption direction bit.
340  *
341  * \param dir 0=slave, non-zero=master
342  *
343  */
344 /*************************************************************************************************/
346 
347 /*************************************************************************************************/
348 /*!
349  * \brief Set the inline encryption packet count for transmit.
350  *
351  * \param count Packet counter value, a 39-bit value
352  *
353  */
354 /*************************************************************************************************/
355 void PalBbBleInlineEncryptSetPacketCount(uint64_t count);
356 
357 /*************************************************************************************************/
358 /*!
359  * \brief Low power operation.
360  *
361  * \note Called by upper baseband code.
362  */
363 /*************************************************************************************************/
364 void PalBbBleLowPower(void);
365 
366 /*! \} */ /* PAL_BB_BLE_TEST */
367 
368 #ifdef __cplusplus
369 };
370 #endif
371 
372 #endif /* PAL_BB_BLE_H */
void PalBbBleTxTifsData(PalBbBleTxBufDesc_t descs[], uint8_t cnt)
Transmit packet at TIFS after the last packet received.
void PalBbBleSetDataParams(const PalBbBleDataParam_t *pParam)
Set the data packet exchange parameters.
uint8_t initTxPhyOptions
Definition: pal_bb_ble.h:76
int8_t txPower
Definition: pal_bb_ble.h:71
void PalBbBleEnableDataWhitening(uint8_t enable)
Enable or disable data whitening.
uint8_t peerTxStableModIdx
Definition: pal_bb_ble.h:78
Encryption data.
Definition: pal_crypto.h:73
uint32_t ifsTime
Definition: pal_bb_ble.h:126
uint32_t crcInit
Definition: pal_bb_ble.h:73
void(* PalBbBleTxIsr_t)(uint8_t status)
Transmit complete ISR callback signature.
Definition: pal_bb_ble.h:99
uint8_t opType
Definition: pal_bb_ble.h:69
void PalBbBleEnable(void)
Enable the BB hardware.
Crypto driver definition.
void PalBbBleInlineEncryptDecryptSetDirection(uint8_t dir)
Set inline encryption/decryption direction bit.
void PalBbBleTxData(PalBbBleTxBufDesc_t descs[], uint8_t cnt)
Transmit a packet.
uint32_t rxTimeoutUsec
Definition: pal_bb_ble.h:119
void PalBbBleRxData(uint8_t *pBuf, uint16_t len)
Receive packet.
uint8_t rxPhy
Definition: pal_bb_ble.h:75
uint8_t txPhy
Definition: pal_bb_ble.h:74
Operation parameters.
Definition: pal_bb_ble.h:123
PalBbBleRxIsr_t rxCback
Definition: pal_bb_ble.h:116
void PalBbBleInlineEncryptSetPacketCount(uint64_t count)
Set the inline encryption packet count for transmit.
void PalBbBleLowPower(void)
Low power operation.
void PalBbBleRxTifsData(uint8_t *pBuf, uint16_t len)
Receive packet at TIFS after the last packet transmitted.
PalBbBleTxIsr_t txCback
Definition: pal_bb_ble.h:115
void PalBbBleEnablePrbs15(uint8_t enable)
Enable or disable PRBS15.
PalCryptoEnc_t enc
Definition: pal_bb_ble.h:80
uint8_t peerRxStableModIdx
Definition: pal_bb_ble.h:79
void PalBbBleSetChannelParam(PalBbBleChan_t *pChan)
Set channelization parameters.
void(* PalBbBleRxIsr_t)(uint8_t status, int8_t rssi, uint32_t crc, uint32_t timestamp, uint8_t rxPhyOptions)
Receive complete ISR callback signature.
Definition: pal_bb_ble.h:102
BLE channelization parameters.
Definition: pal_bb_ble.h:67
void PalBbBleSetOpParams(const PalBbBleOpParam_t *pOpParam)
Set the operation parameters.
uint32_t accAddr
Definition: pal_bb_ble.h:72
uint8_t chanIdx
Definition: pal_bb_ble.h:70
void PalBbBleInit(void)
Initialize the BLE baseband driver.
PalBbBleChan_t * pIfsChan
Definition: pal_bb_ble.h:127
void PalBbBleCancelTifs(void)
Cancel TIFS timer.
uint8_t tifsTxPhyOptions
Definition: pal_bb_ble.h:77
BLE data transfer parameters.
Definition: pal_bb_ble.h:113
Baseband interface file.
void PalBbBleCancelData(void)
Cancel a pending transmit or receive.
Transmit buffer descriptor.
Definition: pal_bb_ble.h:131
void PalBbBleDisable(void)
Disable the BB hardware.
PalBbIfsMode_t
IFS modes.
Definition: pal_bb_ble.h:105
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.