1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef CHRE_PAL_BLE_H_ 18 #define CHRE_PAL_BLE_H_ 19 20 /** 21 * @file 22 * Defines the interface between the common CHRE core system and the 23 * platform-specific BLE (Bluetooth LE, Bluetooth Low Energy) module. 24 */ 25 26 #include <stdbool.h> 27 #include <stdint.h> 28 29 #include "chre/pal/system.h" 30 #include "chre/pal/version.h" 31 #include "chre_api/chre/ble.h" 32 #include "chre_api/chre/common.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * Initial version of the CHRE BLE PAL, introduced alongside CHRE API v1.6. 40 */ 41 #define CHRE_PAL_BLE_API_V1_6 CHRE_PAL_CREATE_API_VERSION(1, 6) 42 43 /** 44 * Introduced alongside CHRE API v1.8, adds readRssi() API. 45 */ 46 #define CHRE_PAL_BLE_API_V1_8 CHRE_PAL_CREATE_API_VERSION(1, 8) 47 48 /** 49 * Introduced alongside CHRE API v1.8, adds flush() API. 50 */ 51 #define CHRE_PAL_BLE_API_V1_9 CHRE_PAL_CREATE_API_VERSION(1, 9) 52 53 /** 54 * Introduced alongside CHRE API v1.9, add broadcaster address filter. 55 */ 56 #define CHRE_PAL_BLE_API_V1_10 CHRE_PAL_CREATE_API_VERSION(1, 10) 57 58 /** 59 * The version of the CHRE BLE PAL defined in this header file. 60 */ 61 #define CHRE_PAL_BLE_API_CURRENT_VERSION CHRE_PAL_BLE_API_V1_10 62 63 /** 64 * The maximum amount of time allowed to elapse between the call to 65 * readRssi() and when the readRssiCallback() is invoked. 66 */ 67 #define CHRE_PAL_BLE_READ_RSSI_COMPLETE_TIMEOUT_NS (2 * CHRE_NSEC_PER_SEC) 68 69 struct chrePalBleCallbacks { 70 /** 71 * This function can be used by the BLE PAL subsystem to request that CHRE 72 * re-send requests for any ongoing scans. This can be useful, for example, if 73 * the BLE subsystem has recovered from a crash. 74 */ 75 void (*requestStateResync)(void); 76 77 /** 78 * Callback invoked to inform the CHRE of the result of startScan() or 79 * stopScan(). 80 * 81 * Unsolicited calls to this function must not be made. In other words, 82 * this callback should only be invoked as the direct result of an earlier 83 * call to startScan() or stopScan(). 84 * 85 * @param enabled true if the BLE scan is currently active and 86 * scanResultEventCallback() will receive scan results. False 87 * otherwise. 88 * @param errorCode An error code from enum chreError 89 * 90 * @see chrePalBleApi.startScan 91 * @see chrePalBleApi.stopScan 92 * @see #chreError 93 */ 94 void (*scanStatusChangeCallback)(bool enabled, uint8_t errorCode); 95 96 /** 97 * Callback used to pass BLE scan results from the to CHRE, which distributes 98 * it to clients (nanoapps). 99 * 100 * This function call passes ownership of the event memory to the core CHRE 101 * system, i.e. the PAL module must not modify the referenced data until 102 * releaseAdvertisingEvent() is called to release the memory. 103 * 104 * If the results of a BLE scan are be split across multiple events, multiple 105 * calls may be made to this callback. 106 * 107 * The PAL module must not deliver the same advertising event twice. 108 * 109 * @param event Event data to distribute to clients. The BLE module 110 * must ensure that this memory remains accessible until it is passed 111 * to the releaseAdvertisingEvent() function in struct chrePalBleApi. 112 * 113 * @see chrePalBleApi.startScan 114 * @see chreBleAdvertisementEvent 115 * @see releaseAdvertisingEvent 116 */ 117 void (*advertisingEventCallback)(struct chreBleAdvertisementEvent *event); 118 119 /** 120 * Callback used to pass completed BLE readRssi events up to CHRE, which hands 121 * it back to the (single) requesting client. 122 * 123 * @param errorCode An error code from enum chreError, with CHRE_ERROR_NONE 124 * indicating a successful response. 125 * @param handle Connection handle upon which the RSSI was read. 126 * @param rssi The RSSI of the latest packet read upon this connection 127 * (-128 to 20). 128 * 129 * @see chrePalBleApi.readRssi 130 * 131 * @since v1.8 132 */ 133 void (*readRssiCallback)(uint8_t errorCode, uint16_t handle, int8_t rssi); 134 135 /** 136 * Callback used to inform CHRE of a completed flush event. 137 * 138 * @param errorCode An error code from enum chreError, with CHRE_ERROR_NONE 139 * indicating a successful response. 140 * 141 * @see chrePalBleApi.flush 142 * 143 * @since v1.9 144 */ 145 void (*flushCallback)(uint8_t errorCode); 146 147 /** 148 * Sends a BT snoop log to the CHRE daemon. 149 * 150 * @param isTxToBtController True if the direction of the BT snoop log is Tx 151 * to BT controller. False then RX from BT controller is assumed. 152 * @param buffer a byte buffer containing the encoded log message. 153 * @param size size of the bt log message buffer. 154 */ 155 void (*handleBtSnoopLog)(bool isTxToBtController, const uint8_t *buffer, 156 size_t size); 157 }; 158 159 struct chrePalBleApi { 160 /** 161 * Version of the module providing this API. This value should be 162 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 163 * API version constant (CHRE_PAL_BLE_API_*) and the module-specific patch 164 * version. 165 */ 166 uint32_t moduleVersion; 167 168 /** 169 * Initializes the BLE module. Initialization must complete synchronously. 170 * 171 * @param systemApi Structure containing CHRE system function pointers which 172 * the PAL implementation should prefer to use over equivalent 173 * functionality exposed by the underlying platform. The module does 174 * not need to deep-copy this structure; its memory remains 175 * accessible at least until after close() is called. 176 * @param callbacks Structure containing entry points to the core CHRE 177 * system. The module does not need to deep-copy this structure; its 178 * memory remains accessible at least until after close() is called. 179 * 180 * @return true if initialization was successful, false otherwise 181 */ 182 bool (*open)(const struct chrePalSystemApi *systemApi, 183 const struct chrePalBleCallbacks *callbacks); 184 185 /** 186 * Performs clean shutdown of the BLE module, usually done in preparation 187 * for stopping the CHRE. The BLE module must ensure that it will not 188 * invoke any callbacks past this point, and complete any relevant teardown 189 * activities before returning from this function. 190 */ 191 void (*close)(void); 192 193 //! @see chreBleGetCapabilities() 194 uint32_t (*getCapabilities)(void); 195 196 //! @see chreBleGetFilterCapabilities() 197 uint32_t (*getFilterCapabilities)(void); 198 199 /** 200 * Starts Bluetooth LE (BLE) scanning. The resulting BLE scan results will 201 * be provided via subsequent calls to advertisingEventCallback(). 202 * 203 * If startScan() is called while a previous scan has been started, the 204 * previous scan will be stopped and replaced with the new scan. 205 * 206 * CHRE will combine Nanoapp BLE scan requests such that the PAL receives a 207 * single scan mode, report delay, RSSI filtering threshold, and a list of all 208 * requested filters. It is up to the BLE subsystem to optimize these filter 209 * requests as best it can based on the hardware it has available. 210 * 211 * @param mode Scanning mode selected among enum chreBleScanMode 212 * @param reportDelayMs Maximum requested batching delay in ms. 0 indicates no 213 * batching. Note that the system may deliver results 214 * before the maximum specified delay is reached. 215 * @param filter List of filters that, if possible, should be used as hardware 216 * filters by the BT peripheral. Note that if any of these 217 * filters are invalid, they can be discarded by the PAL rather 218 * than causing a synchronous failure. 219 * 220 * @return true if the request was accepted for processing, in which case a 221 * subsequent call to scanStatusChangeCallback() will be used to 222 * communicate the result of the operation. 223 * 224 * @see chreBleStartScanAsync() 225 */ 226 bool (*startScan)(enum chreBleScanMode mode, uint32_t reportDelayMs, 227 const struct chreBleScanFilterV1_9 *filter); 228 /** 229 * Stops Bluetooth LE (BLE) scanning. 230 * 231 * If stopScan() is called without a previous scan being started, stopScan() 232 * will be ignored. 233 * 234 * @return true if the request was accepted for processing, in which case a 235 * subsequent call to scanStatusChangeCallback() will be used to 236 * communicate the result of the operation. 237 * 238 * @see chreBleStopScanAsync() 239 */ 240 bool (*stopScan)(void); 241 242 /** 243 * Invoked when the core CHRE system no longer needs a BLE advertising event 244 * structure that was provided to it via advertisingEventCallback(). 245 * 246 * @param event Event data to release 247 */ 248 void (*releaseAdvertisingEvent)(struct chreBleAdvertisementEvent *event); 249 250 /** 251 * Reads the RSSI on a given LE-ACL connection handle. 252 * 253 * Only one call to this method may be outstanding until the 254 * readRssiCallback() is invoked. The readRssiCallback() is guaranteed to be 255 * invoked exactly one within CHRE_PAL_BLE_READ_RSSI_COMPLETE_TIMEOUT_NS of 256 * readRssi() being invoked. 257 * 258 * @param connectionHandle The LE-ACL handle upon which the RSSI is to be 259 * read. 260 * 261 * @return true if the request was accepted, in which case a subsequent call 262 * to readRssiCallback() will be used to indicate the result of the 263 * operation. 264 * 265 * @since v1.8 266 */ 267 bool (*readRssi)(uint16_t connectionHandle); 268 269 /** 270 * Initiates a flush operation where all batched advertisement events will be 271 * immediately processed. 272 * 273 * @return true if the request was accepted, in which case a subsequent call 274 * to flushCallback() will be used to indicate the result of the operation. 275 * 276 * @since v1.9 277 */ 278 bool (*flush)(); 279 }; 280 281 /** 282 * Retrieve a handle for the CHRE BLE PAL. 283 * 284 * @param requestedApiVersion The implementation of this function must return a 285 * pointer to a structure with the same major version as requested. 286 * 287 * @return Pointer to API handle, or NULL if a compatible API version is not 288 * supported by the module, or the API as a whole is not implemented. If 289 * non-NULL, the returned API handle must be valid as long as this 290 * module is loaded. 291 */ 292 const struct chrePalBleApi *chrePalBleGetApi(uint32_t requestedApiVersion); 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif // CHRE_PAL_BLE_H_ 299