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 * The version of the CHRE BLE PAL defined in this header file. 50 */ 51 #define CHRE_PAL_BLE_API_CURRENT_VERSION CHRE_PAL_BLE_API_V1_8 52 53 /** 54 * The maximum amount of time allowed to elapse between the call to 55 * readRssi() and when the readRssiCallback() is invoked. 56 */ 57 #define CHRE_PAL_BLE_READ_RSSI_COMPLETE_TIMEOUT_NS (2 * CHRE_NSEC_PER_SEC) 58 59 struct chrePalBleCallbacks { 60 /** 61 * This function can be used by the BLE PAL subsystem to request that CHRE 62 * re-send requests for any ongoing scans. This can be useful, for example, if 63 * the BLE subsystem has recovered from a crash. 64 */ 65 void (*requestStateResync)(void); 66 67 /** 68 * Callback invoked to inform the CHRE of the result of startScan() or 69 * stopScan(). 70 * 71 * Unsolicited calls to this function must not be made. In other words, 72 * this callback should only be invoked as the direct result of an earlier 73 * call to startScan() or stopScan(). 74 * 75 * @param enabled true if the BLE scan is currently active and 76 * scanResultEventCallback() will receive scan results. False 77 * otherwise. 78 * @param errorCode An error code from enum chreError 79 * 80 * @see chrePalBleApi.startScan 81 * @see chrePalBleApi.stopScan 82 * @see #chreError 83 */ 84 void (*scanStatusChangeCallback)(bool enabled, uint8_t errorCode); 85 86 /** 87 * Callback used to pass BLE scan results from the to CHRE, which distributes 88 * it to clients (nanoapps). 89 * 90 * This function call passes ownership of the event memory to the core CHRE 91 * system, i.e. the PAL module must not modify the referenced data until 92 * releaseAdvertisingEvent() is called to release the memory. 93 * 94 * If the results of a BLE scan are be split across multiple events, multiple 95 * calls may be made to this callback. 96 * 97 * The PAL module must not deliver the same advertising event twice. 98 * 99 * @param event Event data to distribute to clients. The BLE module 100 * must ensure that this memory remains accessible until it is passed 101 * to the releaseAdvertisingEvent() function in struct chrePalBleApi. 102 * 103 * @see chrePalBleApi.startScan 104 * @see chreBleAdvertisementEvent 105 * @see releaseAdvertisingEvent 106 */ 107 void (*advertisingEventCallback)(struct chreBleAdvertisementEvent *event); 108 109 /** 110 * Callback used to pass completed BLE readRssi events up to CHRE, which hands 111 * it back to the (single) requesting client. 112 * 113 * @param errorCode An error code from enum chreError, with CHRE_ERROR_NONE 114 * indicating a successful response. 115 * @param handle Connection handle upon which the RSSI was read. 116 * @param rssi The RSSI of the latest packet read upon this connection 117 * (-128 to 20). 118 * 119 * @see chrePalBleApi.readRssi 120 * 121 * @since v1.8 122 */ 123 void (*readRssiCallback)(uint8_t errorCode, uint16_t handle, int8_t rssi); 124 125 /** 126 * Sends a BT snoop log to the CHRE daemon. 127 * 128 * @param isTxToBtController True if the direction of the BT snoop log is Tx 129 * to BT controller. False then RX from BT controller is assumed. 130 * @param buffer a byte buffer containing the encoded log message. 131 * @param size size of the bt log message buffer. 132 */ 133 void (*handleBtSnoopLog)(bool isTxToBtController, const uint8_t *buffer, 134 size_t size); 135 }; 136 137 struct chrePalBleApi { 138 /** 139 * Version of the module providing this API. This value should be 140 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 141 * API version constant (CHRE_PAL_BLE_API_*) and the module-specific patch 142 * version. 143 */ 144 uint32_t moduleVersion; 145 146 /** 147 * Initializes the BLE module. Initialization must complete synchronously. 148 * 149 * @param systemApi Structure containing CHRE system function pointers which 150 * the PAL implementation should prefer to use over equivalent 151 * functionality exposed by the underlying platform. The module does 152 * not need to deep-copy this structure; its memory remains 153 * accessible at least until after close() is called. 154 * @param callbacks Structure containing entry points to the core CHRE 155 * system. The module does not need to deep-copy this structure; its 156 * memory remains accessible at least until after close() is called. 157 * 158 * @return true if initialization was successful, false otherwise 159 */ 160 bool (*open)(const struct chrePalSystemApi *systemApi, 161 const struct chrePalBleCallbacks *callbacks); 162 163 /** 164 * Performs clean shutdown of the BLE module, usually done in preparation 165 * for stopping the CHRE. The BLE module must ensure that it will not 166 * invoke any callbacks past this point, and complete any relevant teardown 167 * activities before returning from this function. 168 */ 169 void (*close)(void); 170 171 //! @see chreBleGetCapabilities() 172 uint32_t (*getCapabilities)(void); 173 174 //! @see chreBleGetFilterCapabilities() 175 uint32_t (*getFilterCapabilities)(void); 176 177 /** 178 * Starts Bluetooth LE (BLE) scanning. The resulting BLE scan results will 179 * be provided via subsequent calls to advertisingEventCallback(). 180 * 181 * If startScan() is called while a previous scan has been started, the 182 * previous scan will be stopped and replaced with the new scan. 183 * 184 * CHRE will combine Nanoapp BLE scan requests such that the PAL receives a 185 * single scan mode, report delay, RSSI filtering threshold, and a list of all 186 * requested filters. It is up to the BLE subsystem to optimize these filter 187 * requests as best it can based on the hardware it has available. 188 * 189 * @param mode Scanning mode selected among enum chreBleScanMode 190 * @param reportDelayMs Maximum requested batching delay in ms. 0 indicates no 191 * batching. Note that the system may deliver results 192 * before the maximum specified delay is reached. 193 * @param filter List of filters that, if possible, should be used as hardware 194 * filters by the BT peripheral. Note that if any of these 195 * filters are invalid, they can be discarded by the PAL rather 196 * than causing a synchronous failure. 197 * 198 * @return true if the request was accepted for processing, in which case a 199 * subsequent call to scanStatusChangeCallback() will be used to 200 * communicate the result of the operation. 201 * 202 * @see chreBleStartScanAsync() 203 */ 204 bool (*startScan)(enum chreBleScanMode mode, uint32_t reportDelayMs, 205 const struct chreBleScanFilter *filter); 206 /** 207 * Stops Bluetooth LE (BLE) scanning. 208 * 209 * If stopScan() is called without a previous scan being started, stopScan() 210 * will be ignored. 211 * 212 * @return true if the request was accepted for processing, in which case a 213 * subsequent call to scanStatusChangeCallback() will be used to 214 * communicate the result of the operation. 215 * 216 * @see chreBleStopScanAsync() 217 */ 218 bool (*stopScan)(void); 219 220 /** 221 * Invoked when the core CHRE system no longer needs a BLE advertising event 222 * structure that was provided to it via advertisingEventCallback(). 223 * 224 * @param event Event data to release 225 */ 226 void (*releaseAdvertisingEvent)(struct chreBleAdvertisementEvent *event); 227 228 /** 229 * Reads the RSSI on a given LE-ACL connection handle. 230 * 231 * Only one call to this method may be outstanding until the 232 * readRssiCallback() is invoked. The readRssiCallback() is guaranteed to be 233 * invoked exactly one within CHRE_PAL_BLE_READ_RSSI_COMPLETE_TIMEOUT_NS of 234 * readRssi() being invoked. 235 * 236 * @param connectionHandle The LE-ACL handle upon which the RSSI is to be 237 * read. 238 * 239 * @return true if the request was accepted, in which case a subsequent call 240 * to readRssiCallback() will be used to indicate the result of the 241 * operation. 242 * 243 * @since v1.8 244 */ 245 bool (*readRssi)(uint16_t connectionHandle); 246 }; 247 248 /** 249 * Retrieve a handle for the CHRE BLE PAL. 250 * 251 * @param requestedApiVersion The implementation of this function must return a 252 * pointer to a structure with the same major version as requested. 253 * 254 * @return Pointer to API handle, or NULL if a compatible API version is not 255 * supported by the module, or the API as a whole is not implemented. If 256 * non-NULL, the returned API handle must be valid as long as this 257 * module is loaded. 258 */ 259 const struct chrePalBleApi *chrePalBleGetApi(uint32_t requestedApiVersion); 260 261 #ifdef __cplusplus 262 } 263 #endif 264 265 #endif // CHRE_PAL_BLE_H_ 266