wifi(interface): Add gscan/apf related API's
Changes in the CL:
1. Add gscan/APF related API's to |IWifiStaIface|.
2. Add a new callback HIDL interface (|IWifiStaIfaceEventCallback)
for all callbacks received from |IWifiStaIface|.
Bug: 31991459
Test: Compiles
Change-Id: Id9f2ded9e20bee393ab53d84efa814d52704cd2c
diff --git a/wifi/1.0/IWifiStaIface.hal b/wifi/1.0/IWifiStaIface.hal
index 5234c71..a738ebe 100644
--- a/wifi/1.0/IWifiStaIface.hal
+++ b/wifi/1.0/IWifiStaIface.hal
@@ -17,10 +17,275 @@
package android.hardware.wifi@1.0;
import IWifiIface;
+import IWifiStaIfaceEventCallback;
/**
* Interface used to represent a single STA iface.
*/
interface IWifiStaIface extends IWifiIface {
- /** TODO(rpius): Add methods to the interface. */
+ /**
+ * Mask of capabilities suported by this Iface.
+ */
+ enum StaIfaceCapabilityMask : uint32_t {
+ /**
+ * If set indicates that the APF APIs are supported.
+ * APF (Android Packet Filter) is a BPF like packet filtering
+ * bytecode executed by the firmware.
+ */
+ APF = 1 << 0,
+ /**
+ * If set indicates that the Background Scan APIs are supported.
+ * Background scan allow the host to send a number of buckets down to the
+ * firmware. Each bucket contains a set of channels, a period, and some
+ * parameters about how and when to report results.
+ */
+ BACKGROUND_SCAN = 1 << 1,
+ };
+
+ /**
+ * Parameters to specify the APF capability of this iface.
+ */
+ struct ApfPacketFilterCapabilities {
+ /**
+ * Version of the packet filter interpreter supported
+ */
+ uint32_t version;
+ /**
+ * Maximum size of the filter bytecodes in bytes for an iface.
+ */
+ uint32_t maxLength;
+ };
+
+ /**
+ * Parameters to specify the Background Scan capability of this iface.
+ */
+ struct BackgroundScanCapabilities {
+ /**
+ * Maximum number of bytes available for cached scan results
+ */
+ uint32_t maxCacheSize;
+ /**
+ * Maximum number of buckets that can be supplied for a scan
+ */
+ uint32_t maxBuckets;
+ /**
+ * Maximum number of APs that must be stored for each scan.
+ */
+ uint32_t maxApCachePerScan;
+ /**
+ * Max reporting number of scans threshold that can be specified in the scan
+ * parameters.
+ */
+ int32_t maxReportingThreshold;
+ };
+
+ /**
+ * Bands that can be specified in Background scan requests.
+ */
+ enum BackgroundScanBand : uint32_t {
+ BAND_UNSPECIFIED,
+ /**
+ * 2.4 GHz.
+ */
+ BAND_24GHZ = 1,
+ /**
+ * 5 GHz without DFS.
+ */
+ BAND_5GHZ = 2,
+ /**
+ * 5 GHz DFS only.
+ */
+ BAND_5GHZ_DFS = 4,
+ /**
+ * 5 GHz with DFS.
+ */
+ BAND_5GHZ_WITH_DFS = 6,
+ /**
+ * 2.4 GHz + 5 GHz; no DFS.
+ */
+ BAND_24GHZ_5GHZ = 3,
+ /**
+ * 2.4 GHz + 5 GHz with DFS
+ */
+ BAND_24GHZ_5GHZ_WITH_DFS = 7
+ };
+
+ /**
+ * Mask of event reporting schemes that can be specified in background scan
+ * requests.
+ */
+ enum BackgroundScanBucketEventReportSchemeMask : uint32_t {
+ /**
+ * Report a scan completion event after scan. If this is not set then scan
+ * completion events must be reported if report_threshold_percent or
+ * report_threshold_num_scans is reached.
+ */
+ EACH_SCAN = 1 << 0,
+ /**
+ * Forward scan results (beacons/probe responses + IEs) in real time to HAL,
+ * in addition to completion events.
+ * Note: To keep backward compatibility, fire completion events regardless
+ * of REPORT_EVENTS_EACH_SCAN.
+ */
+ FULL_RESULTS = 1 << 1,
+ /**
+ * Controls if scans for this bucket must be placed in the results buffer.
+ */
+ NO_BATCH = 1 << 2,
+ };
+
+ /**
+ * Background Scan parameters per bucket that can be specified in background
+ * scan requests.
+ */
+ struct BackgroundScanBucketParameters {
+ /**
+ * Bands to scan or 0 if frequencies list must be used instead.
+ */
+ BackgroundScanBand band;
+ /**
+ * Channel frequencies (in Mhz) to scan if |band| is set to
+ * |UNSPECIFIED|.
+ */
+ vec<uint32_t> frequenciesInMhz;
+ /**
+ * Period at which this bucket must be scanned (in milliseconds). Must be an integer
+ * multiple of the |basePeriodInMs| specified in the BackgroundScanParameters.
+ */
+ uint32_t periodInMs;
+ /**
+ * Bitset of |BackgroundScanBucketEventReportSchemeMask| values controlling
+ * when events for this bucket must be reported.
+ */
+ uint32_t eventReportScheme;
+ /**
+ * For exponential back off. If |exponentialMaxPeriodInMs| is non zero or
+ * different than period, then this bucket is an exponential backoff bucket
+ * and the scan period must grow exponentially as per formula:
+ * actual_period(N) = period * (base ^ (N/step_count))
+ * to this maximum period (in milliseconds).
+ */
+ uint32_t exponentialMaxPeriodInMs;
+ /**
+ * For exponential back off. multiplier: new_period=old_period * base
+ */
+ uint32_t exponentialBase;
+ /**
+ * For exponential back off. Number of scans to perform for a given
+ * period.
+ */
+ uint32_t exponentialStepCount;
+ };
+
+ /**
+ * Background Scan parameters that can be specified in background scan
+ * requests.
+ */
+ struct BackgroundScanParameters {
+ /**
+ * GCD of all bucket periods (in milliseconds).
+ */
+ uint32_t basePeriodInMs;
+ /**
+ * Maximum number of APs that must be stored for each scan. If the maximum
+ * is reached the highest RSSI results must be returned.
+ */
+ uint32_t maxApPerScan;
+ /**
+ * % cache buffer filled threshold at which the host must be notified of
+ * batched scan results.
+ */
+ uint32_t reportThresholdPercent;
+ /**
+ * Threshold at which the AP must be woken up, in number of scans.
+ */
+ uint32_t reportThresholdNumScans;
+ /**
+ * List of buckets to be scheduled.
+ */
+ vec<BackgroundScanBucketParameters> buckets;
+ };
+
+ /**
+ * Requests notifications of significant events on this iface. Multiple calls
+ * to this must register multiple callbacks each of which must receive all
+ * events.
+ *
+ * @param callback An instance of the |IWifiStaIfaceEventCallback| HIDL interface
+ * object.
+ */
+ oneway registerEventCallback(IWifiStaIfaceEventCallback callback);
+
+ /**
+ * Get the capabilities supported by this STA iface.
+ *
+ * @return capabilities Bitset of |StaIfaceCapabilityMask| values.
+ */
+ getCapabilities() generates (uint64_t capabilities);
+
+ /**
+ * Used to query additional information about the chip's APF capabilities.
+ * Will fail if |StaIfaceCapabilityMask.APF| is not set.
+ *
+ * @return capabilities Instance of |ApfPacketFilterCapabilities|.
+ */
+ getApfPacketFilterCapabilities()
+ generates (ApfPacketFilterCapabilities capabilities);
+
+ /**
+ * Installs an APF program on this iface, replacing an existing
+ * program if present.
+ * Will fail if |StaIfaceCapabilityMask.APF| is not set.
+ *
+ * @param cmdId command Id to use for this invocation.
+ * @param program APF Program to be set.
+ */
+ oneway installApfPacketFilter(CommandId cmdId, vec<uint8_t> program);
+
+ /**
+ * Used to query additional information about the chip's APF capabilities.
+ * Will fail if |StaIfaceCapabilityMask.BACKGROUND_SCAN| is not set.
+ *
+ * @return capabilities Instance of |BackgroundScanCapabilities|.
+ */
+ getBackgroundScanCapabilities()
+ generates (BackgroundScanCapabilities capabilities);
+
+ /**
+ * Start a background scan using the given cmdId as an identifier. Only one
+ * active background scan need be supported.
+ *
+ * When this is called all requested buckets must be scanned, starting the
+ * beginning of the cycle.
+ *
+ * For example:
+ * If there are two buckets specified
+ * - Bucket 1: period=10s
+ * - Bucket 2: period=20s
+ * - Bucket 3: period=30s
+ * Then the following scans must occur
+ * - t=0 buckets 1, 2, and 3 are scanned
+ * - t=10 bucket 1 is scanned
+ * - t=20 bucket 1 and 2 are scanned
+ * - t=30 bucket 1 and 3 are scanned
+ * - t=40 bucket 1 and 2 are scanned
+ * - t=50 bucket 1 is scanned
+ * - t=60 buckets 1, 2, and 3 are scanned
+ * - and the patter repeats
+ *
+ * If any scan does not occur or is incomplete (error, interrupted, etc) then
+ * a cached scan result must still be recorded with the
+ * WIFI_SCAN_FLAG_INTERRUPTED flag set.
+ *
+ * @param cmdId command Id to use for this invocation.
+ * @param params Background scan parameters.
+ */
+ oneway startBackgroundScan(CommandId cmdId, BackgroundScanParameters params);
+
+ /**
+ * Stop the background scan started.
+ *
+ * @param cmdId command Id corresponding to the request.
+ */
+ oneway stopBackgroundScan(CommandId cmdId);
};