1e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/* 2e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Copyright (C) 2016 The Android Open Source Project 3e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 4e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Licensed under the Apache License, Version 2.0 (the "License"); 5e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * you may not use this file except in compliance with the License. 6e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * You may obtain a copy of the License at 7e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 8e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * http://www.apache.org/licenses/LICENSE-2.0 9e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 10e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Unless required by applicable law or agreed to in writing, software 11e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * distributed under the License is distributed on an "AS IS" BASIS, 12e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * See the License for the specific language governing permissions and 14e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * limitations under the License. 15e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 16e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 173b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#ifndef CHRE_PAL_WIFI_H_ 183b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#define CHRE_PAL_WIFI_H_ 19e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 20e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 21e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @file 22e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Defines the interface between the common CHRE core system and the 23e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * platform-specific WiFi module. 24e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 25e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 263b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#include <stdbool.h> 273b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#include <stdint.h> 283b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie 29e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include "chre_api/chre/common.h" 30e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include "chre_api/chre/wifi.h" 313b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#include "chre/pal/system.h" 32e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#include "chre/pal/version.h" 33e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 34e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#ifdef __cplusplus 35e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieextern "C" { 36e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#endif 37e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 38e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 39e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Initial version of the CHRE WiFi PAL, tied to CHRE API v1.1. 40e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 41e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#define CHRE_PAL_WIFI_API_V1_0 CHRE_PAL_CREATE_API_VERSION(1, 0) 42e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 433aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie// v1.1 skipped to avoid confusion with CHRE API v1.1 443aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie 453aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie/** 463aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Introduced alongside CHRE API v1.2, adding support for RTT ranging and radio 473aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * chain preference 483aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie */ 493aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie#define CHRE_PAL_WIFI_API_V1_2 CHRE_PAL_CREATE_API_VERSION(1, 2) 503aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie 51e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 52e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * The version of the WiFi GNSS PAL defined in this header file. 53e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 543aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie#define CHRE_PAL_WIFI_API_CURRENT_VERSION CHRE_PAL_WIFI_API_V1_2 55e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 56e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddiestruct chrePalWifiCallbacks { 57e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 58e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Callback invoked to inform the CHRE of the result of changes to the scan 592d27551311a0ecd0c0c1ee6a7ac097adbe617dd8Brian Duddie * monitor registration status requested via configureScanMonitor in struct 60e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * chrePalWifiApi. 61e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 62e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Unsolicited calls to this function must not be made. In other words, 63e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * this callback should only be invoked as the direct result of an earlier 64e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * call to configureScanMonitor. If the scan monitor registration is lost, 65e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * for example due to a reset of the WiFi subsystem, then the PAL 66e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * implementation is required to silently re-register the scan monitor when 67e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * it recovers, as needed. 68e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 69e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param enabled true if the scan monitor is currently active and 70e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * scanEventCallback will receive unsolicited scan results, false 71e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * otherwise 72e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param errorCode An error code from enum chreError 73e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 74bfa47c43c9cd1f85f518febd6b0c7cc4358564f2Brian Duddie * @see chrePalWifiApi.configureScanMonitor 75e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see #chreError 76e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 77e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie void (*scanMonitorStatusChangeCallback)(bool enabled, uint8_t errorCode); 78e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 79e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 80e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Callback invoked to inform the CHRE of the result of a request for a 81e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * scan requested via requestScan in struct chrePalWifiApi. 82e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 83e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Unsolicited calls to this function must not be made. See 84e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * scanMonitorStatusChangeCallback() for more information. 85e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 86b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * This function must only be called after the final status of the scan 87b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * request is known. For example, it must not be called at the point when 88b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * the scan is initially scheduled if it can still fail prior to delivering 89b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * a result. 90b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 91b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * @param pending true if the request was successful and the results of the 92b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * scan are pending delivery (via scanEventCallback), false otherwise 93e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param errorCode An error code from enum chreError 94e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 95e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie void (*scanResponseCallback)(bool pending, uint8_t errorCode); 96e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 97e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 98e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Callback used to pass scan results from the WiFi module to the core CHRE 99e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * system, which distributes it to clients (nanoapps). 100e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 101e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * This function call passes ownership of the event memory to the core CHRE 102e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * system, i.e. the PAL module must not modify the referenced data until the 103e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * associated API function is called to release the memory. 104e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 10509d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * If the results of a given scan are be split across multiple events, and 10609d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * therefore multiple calls to this callback, then the events must be 10709d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * delivered in order, and in one contiguous series of callbacks with no 10809d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * interleaving of events that correspond to any other scan. 10909d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * 11009d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * The PAL module must not deliver the same scan event twice. As a specific 11109d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * example: if an explicit scan request is made via requestScan(), the PAL 11209d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * implementation must not redeliver the result a second time because scan 11309d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * monitoring is enabled. 11409d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * 115e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param event Event data to distribute to clients. The WiFi module 116e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * must ensure that this memory remains accessible until it is passed 117e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * to the releaseScanEvent() function in struct chrePalWifiApi. 11809d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * 119bfa47c43c9cd1f85f518febd6b0c7cc4358564f2Brian Duddie * @see chrePalWifiApi.configureScanMonitor 120bfa47c43c9cd1f85f518febd6b0c7cc4358564f2Brian Duddie * @see chrePalWifiApi.requestScan 121e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 122e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie void (*scanEventCallback)(struct chreWifiScanEvent *event); 1233aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie 1243aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie /** 1253aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Callback used to pass RTT ranging results from the WiFi module to the 1263aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * core CHRE system, which distributes it to clients (nanoapps). 1273aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 1283aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Like scanEventCallback, this function call passes ownership of the event 1293aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * memory to the core CHRE system. 1303aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 1313aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Only valid if requestedApiVersion given to chrePalWifiGetApi() is greater 1323aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * than or equal to CHRE_PAL_WIFI_API_V1_2. 1333aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 1343aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @param errorCode An error code from enum chreError, with CHRE_ERROR_NONE 1353aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * indicating successful completion of the ranging operation 1363aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @param event Event data to distribute to clients. Unlike with scan 1373aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * events, RTT ranging results must be provided for all requested MAC 1383aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * addresses in a single event. Ignored and may be NULL if errorCode 1393aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * is not CHRE_ERROR_NONE. 1403aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 1413aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @since v1.2 1423aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie */ 1433aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie void (*rangingEventCallback)(uint8_t errorCode, 1443aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie struct chreWifiRangingEvent *event); 145e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie}; 146e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 147e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddiestruct chrePalWifiApi { 148e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 149e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Version of the module providing this API. This value should be 150e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 151e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * API version constant (CHRE_PAL_WIFI_API_*) and the module-specific patch 152e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * version. 153e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 154e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie uint32_t moduleVersion; 155e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 156e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 157e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Initializes the WiFi module. Initialization must complete synchronously. 158e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 1593b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie * @param systemApi Structure containing CHRE system function pointers which 1603b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie * the PAL implementation should prefer to use over equivalent 1613b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie * functionality exposed by the underlying platform. The module does 1623b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie * not need to deep-copy this structure; its memory remains 1633b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie * accessible at least until after close() is called. 164e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param callbacks Structure containing entry points to the core CHRE 165e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * system. The module does not need to deep-copy this structure; its 166e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * memory remains accessible at least until after close() is called. 167e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 168e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @return true if initialization was successful, false otherwise 169e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 1703b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie bool (*open)(const struct chrePalSystemApi *systemApi, 1713b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie const struct chrePalWifiCallbacks *callbacks); 172e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 173e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 174e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Performs clean shutdown of the WiFi module, usually done in preparation 175e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * for stopping the CHRE. The WiFi module must ensure that it will not 176e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * invoke any callbacks past this point, and complete any relevant teardown 177e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * activities before returning from this function. 178e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 179e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie void (*close)(void); 180e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 181e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie //! @see chreWifiGetCapabilities() 182e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie uint32_t (*getCapabilities)(void); 183e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 184e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 185e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Configures whether the scanEventCallback receives unsolicited scan 186e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * results, i.e. the results of scans not performed at the request of CHRE. 187e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 188f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * While not expected, a duplicate request, e.g. one that requests to enable 189f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * scan monitoring when it is already enabled, must follow the successful 190f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * callback flow. 191f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * 192e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param enable true to enable listening for all available scan results 193e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 194e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @return true if the request was accepted for processing, in which case a 195e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * subsequent call to scanMonitorStatusChangeCallback will be used 196e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * to communicate the result of the operation 197e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 198e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see chreWifiConfigureScanMonitorAsync() 199e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 200e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie bool (*configureScanMonitor)(bool enable); 201e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 202e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 203e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Request that the WiFi chipset perform a scan, or deliver results from its 204e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * cache if the parameters allow for it. If this function returns true, then 205b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * the scanResponseCallback will be invoked to provide the result of the 206b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * scan. If that indicates a successful result (the scan data is pending), 207b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * then scanEventCallback() will be invoked one more more times to deliver 208b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * the results of the scan. The results for the requested scan are delivered 209b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * in scanEventCallback() regardless of the most recent setting passed to 210b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * configureScanMonitor(). 211b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 212b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * The asynchronous flow of a scan request made through this API is 213b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * as follows: 214b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 215b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 1. requestScan() called, returns true if request accepted, otherwise 216b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * false (in which case the request fails at this stage and further 217b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * steps do not occur) 218b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 2. Scan is performed, or an error is encountered preventing the 219b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * successful delivery of the scan result 220b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 3. scanResponseCallback() is invoked to indicate whether the scan 221b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * succeeded, or the reason for failure (in which case the request fails 222b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * at this stage and further steps do not occur) 223b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * 4. scanEventCallback() is invoked 1 or more times (even if the scan 224b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * resulted in no visible APs) 225e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 22609d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * Note that the callbacks in steps 3 and 4 must complete in the sequence 22709d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * given, and the call(s) to scanEventCallback() occurring immediately after 22809d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * scanResponseCallback() must be associated with this scan request, and not 22909d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * results delivered pursuant to an active scan monitor registration. 23009d74684491ed4341e86775706fba51aed5781d0Andrew Rossignol * 231f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * This function must follow the CHRE API-defined behavior regarding 232f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * timeouts. In other words, if a successful scan result is not produced by 233f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * the lower layers within CHRE_WIFI_SCAN_RESULT_TIMEOUT_NS, 234f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * scanResponseCallback() must be invoked to indicate the failure, and any 235f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * late arriving scan result from the lower layers must be dropped. 236f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * 237f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * At most 1 scan can be in progress from this API at any given time. 238f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * In other words, the implementation should return false if another scan 239f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * initiated via this function has not completed, i.e. it has not failed 240f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * yet, or the final scan event has not yet been delivered via 241f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * scanEventCallback(). However, this function must accept and queue a scan 242f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * request made from this API while a scan requested by another client, such 243f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * as the applications processor, is in progress. 244f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * 2453aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @param params See chreWifiRequestScanAsync(). If requestedApiVersion 2463aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * supplied to chrePalWifiGetApi is at least CHRE_PAL_WIFI_API_V1_2, 2473aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * then the new "radioChainPref" parameter will be included. 248e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 249e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @return true if the request was accepted for further processing, in which 250b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * case a subsequent call to scanResponseCallback will be used to 251b1243b7e37bca234ebdb17e79141a3d127ec47a8Brian Duddie * communicate the result of the operation 252e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 253e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see #chreWifiScanParams 254e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @see chreWifiRequestScanAsync() 255e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 256e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie bool (*requestScan)(const struct chreWifiScanParams *params); 257e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 258e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie /** 259e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Invoked when the core CHRE system no longer needs a WiFi scan event 260e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * structure that was provided to it via scanEventCallback() 261e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 262e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param event Event data to release 263e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 264e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie void (*releaseScanEvent)(struct chreWifiScanEvent *event); 2653aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie 2663aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie /** 2673aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Request that the WiFi chipset perform RTT ranging against a set of access 2683aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * points specified in params. If this function returns true, then 2693aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * rangingEventCallback must be invoked once to deliver the final result of 2703aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * the operation, with the accompanying result structure if ranging was 2713aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * performed. 2723aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 2733aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * RTT functionality in CHRE is based off the Android HAL definitions 2743aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * (hardware/interfaces/wifi/1.0/), but with less parameters. For 2753aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * example, CHRE only supports ranging against access points, and two-sided 2763aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * RTT. When mapping struct chreWifiRangingTarget into the equivalent fields 2773aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * defined in the HAL in struct RttConfig, the following default values 2783aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * should be used to fill the fields not specified in the CHRE structure: 2793aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 280bfa47c43c9cd1f85f518febd6b0c7cc4358564f2Brian Duddie * <pre> 2813aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * type = TWO_SIDED 2823aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * peer = AP 2833aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * burstPeriod = 0 2843aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * numBurst = 0 2853aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * numFramesPerBurst = 8 2863aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * numRetriesPerRttFrame = 0 2873aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * numRetriesPerFtmr = 0 2889d84d89f0b731ec66bdcf192f12a03f34bd88397Brian Duddie * mustRequestLci = true 2899d84d89f0b731ec66bdcf192f12a03f34bd88397Brian Duddie * mustRequestLcr = false (can be true, but not exposed by CHRE) 2903aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * burstDuration = 15 291e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * preamble = implementation-dependent** 292e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * bw = implementation-dependent** 293bfa47c43c9cd1f85f518febd6b0c7cc4358564f2Brian Duddie * </pre> 294e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * 295e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * **These are used to populate the Format And Bandwidth field in the Fine 296e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * Timing Measurement Parameters element. Per the specification, proposed 297e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * values must fall within the capabilities of the requesting device, and 298e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * the configuration used is ultimately negotiated with the responding 299e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * STA. Therefore, it is up to the underlying WiFi implementation to pick 300e8ccc4f8bf5d6251e1675e61601632ecd97a336eBrian Duddie * suitable values. 3013aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 302f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * Like {@link #requestScan}, this function must follow the CHRE API-defined 303f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * behavior regarding timeouts, indicating failure via rangingEventCallback 304f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * if the lower layers do not produce a result within 305f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * CHRE_WIFI_RANGING_RESULT_TIMEOUT_NS. 306f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * 307f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * Also like {@link #requestScan}, at most 1 RTT ranging request can be in 308f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * progress from this API at any given time. Implementations should return 309f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * false if this condition is not met, but must queue a request made from 310f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * this API while a request from another client, such as the applications 311f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * processor, is in progress. 312f1505fb97e761843a24176d6ce0db576f635ced9Brian Duddie * 3133aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @return true if the request was accepted for further processing, in which 3143aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * case a subsequent call to rangingEventCallback will be used to 3153aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * communicate the result of the operation 3163aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 3173aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @see #chreWifiRangingParams 3183aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @see chreWifiRequestRangingAsync() 3193aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 3203aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @since v1.2 3213aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie */ 3223aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie bool (*requestRanging)(const struct chreWifiRangingParams *params); 3233aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie 3243aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie /** 3253aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * Invoked when the core CHRE system no longer needs a WiFi ranging result 3263aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * event structure that was provided to it via rangingEventCallback() 3273aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 3283aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @param event Event data to release 3293aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * 3303aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie * @since v1.2 3313aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie */ 3323aa68d6f96ec229da78b57dff477cfd13b1c0885Brian Duddie void (*releaseRangingEvent)(struct chreWifiRangingEvent *event); 333e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie}; 334e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 335e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie/** 336e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * Retrieve a handle for the CHRE WiFi PAL. 337e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 338e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @param requestedApiVersion The implementation of this function must return a 339e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * pointer to a structure with the same major version as requested. 340e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * 341e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * @return Pointer to API handle, or NULL if a compatible API version is not 342e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * supported by the module, or the API as a whole is not implemented. If 343e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * non-NULL, the returned API handle must be valid as long as this 344e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie * module is loaded. 345e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie */ 346e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddieconst struct chrePalWifiApi *chrePalWifiGetApi(uint32_t requestedApiVersion); 347e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 348e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#ifdef __cplusplus 349e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie} 350e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie#endif 351e64f180233e64c40b56993cfea3696c5b4b16395Brian Duddie 3523b19f44cd6a77d1bb95397e4ec730bd362b0f37dBrian Duddie#endif // CHRE_PAL_WIFI_H_ 353