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/Android.bp b/wifi/1.0/Android.bp
index b730931..a3daa89 100644
--- a/wifi/1.0/Android.bp
+++ b/wifi/1.0/Android.bp
@@ -16,6 +16,7 @@
"IWifiP2pIface.hal",
"IWifiRttController.hal",
"IWifiStaIface.hal",
+ "IWifiStaIfaceEventCallback.hal",
],
out: [
"android/hardware/wifi/1.0/types.cpp",
@@ -29,6 +30,7 @@
"android/hardware/wifi/1.0/WifiP2pIfaceAll.cpp",
"android/hardware/wifi/1.0/WifiRttControllerAll.cpp",
"android/hardware/wifi/1.0/WifiStaIfaceAll.cpp",
+ "android/hardware/wifi/1.0/WifiStaIfaceEventCallbackAll.cpp",
],
}
@@ -48,6 +50,7 @@
"IWifiP2pIface.hal",
"IWifiRttController.hal",
"IWifiStaIface.hal",
+ "IWifiStaIfaceEventCallback.hal",
],
out: [
"android/hardware/wifi/1.0/types.h",
@@ -101,6 +104,11 @@
"android/hardware/wifi/1.0/BnWifiStaIface.h",
"android/hardware/wifi/1.0/BpWifiStaIface.h",
"android/hardware/wifi/1.0/BsWifiStaIface.h",
+ "android/hardware/wifi/1.0/IWifiStaIfaceEventCallback.h",
+ "android/hardware/wifi/1.0/IHwWifiStaIfaceEventCallback.h",
+ "android/hardware/wifi/1.0/BnWifiStaIfaceEventCallback.h",
+ "android/hardware/wifi/1.0/BpWifiStaIfaceEventCallback.h",
+ "android/hardware/wifi/1.0/BsWifiStaIfaceEventCallback.h",
],
}
diff --git a/wifi/1.0/Android.mk b/wifi/1.0/Android.mk
index 58c487b..a1a716d 100644
--- a/wifi/1.0/Android.mk
+++ b/wifi/1.0/Android.mk
@@ -261,6 +261,10 @@
$(GEN): PRIVATE_DEPS := $(LOCAL_PATH)/IWifiStaIface.hal
$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/IWifiIface.hal
$(GEN): $(LOCAL_PATH)/IWifiIface.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/types.hal
+$(GEN): $(LOCAL_PATH)/types.hal
$(GEN): PRIVATE_OUTPUT_DIR := $(intermediates)
$(GEN): PRIVATE_CUSTOM_TOOL = \
$(PRIVATE_HIDL) -o $(PRIVATE_OUTPUT_DIR) \
@@ -270,6 +274,25 @@
$(GEN): $(LOCAL_PATH)/IWifiStaIface.hal
$(transform-generated-source)
LOCAL_GENERATED_SOURCES += $(GEN)
+
+#
+# Build IWifiStaIfaceEventCallback.hal
+#
+GEN := $(intermediates)/android/hardware/wifi/1.0/IWifiStaIfaceEventCallback.java
+$(GEN): $(HIDL)
+$(GEN): PRIVATE_HIDL := $(HIDL)
+$(GEN): PRIVATE_DEPS := $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/types.hal
+$(GEN): $(LOCAL_PATH)/types.hal
+$(GEN): PRIVATE_OUTPUT_DIR := $(intermediates)
+$(GEN): PRIVATE_CUSTOM_TOOL = \
+ $(PRIVATE_HIDL) -o $(PRIVATE_OUTPUT_DIR) \
+ -Ljava -randroid.hardware:hardware/interfaces \
+ android.hardware.wifi@1.0::IWifiStaIfaceEventCallback
+
+$(GEN): $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+ $(transform-generated-source)
+LOCAL_GENERATED_SOURCES += $(GEN)
include $(BUILD_JAVA_LIBRARY)
@@ -532,6 +555,10 @@
$(GEN): PRIVATE_DEPS := $(LOCAL_PATH)/IWifiStaIface.hal
$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/IWifiIface.hal
$(GEN): $(LOCAL_PATH)/IWifiIface.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/types.hal
+$(GEN): $(LOCAL_PATH)/types.hal
$(GEN): PRIVATE_OUTPUT_DIR := $(intermediates)
$(GEN): PRIVATE_CUSTOM_TOOL = \
$(PRIVATE_HIDL) -o $(PRIVATE_OUTPUT_DIR) \
@@ -541,6 +568,25 @@
$(GEN): $(LOCAL_PATH)/IWifiStaIface.hal
$(transform-generated-source)
LOCAL_GENERATED_SOURCES += $(GEN)
+
+#
+# Build IWifiStaIfaceEventCallback.hal
+#
+GEN := $(intermediates)/android/hardware/wifi/1.0/IWifiStaIfaceEventCallback.java
+$(GEN): $(HIDL)
+$(GEN): PRIVATE_HIDL := $(HIDL)
+$(GEN): PRIVATE_DEPS := $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+$(GEN): PRIVATE_DEPS += $(LOCAL_PATH)/types.hal
+$(GEN): $(LOCAL_PATH)/types.hal
+$(GEN): PRIVATE_OUTPUT_DIR := $(intermediates)
+$(GEN): PRIVATE_CUSTOM_TOOL = \
+ $(PRIVATE_HIDL) -o $(PRIVATE_OUTPUT_DIR) \
+ -Ljava -randroid.hardware:hardware/interfaces \
+ android.hardware.wifi@1.0::IWifiStaIfaceEventCallback
+
+$(GEN): $(LOCAL_PATH)/IWifiStaIfaceEventCallback.hal
+ $(transform-generated-source)
+LOCAL_GENERATED_SOURCES += $(GEN)
include $(BUILD_STATIC_JAVA_LIBRARY)
diff --git a/wifi/1.0/IWifiChip.hal b/wifi/1.0/IWifiChip.hal
index cd4b219..55f6d61 100644
--- a/wifi/1.0/IWifiChip.hal
+++ b/wifi/1.0/IWifiChip.hal
@@ -36,7 +36,7 @@
* ChipIfaceCombination for examples.
*/
struct ChipIfaceCombinationLimit {
- vec<IfaceType> types; // Each IfaceType may occur at most once
+ vec<IfaceType> types; // Each IfaceType must occur at most once.
uint32_t maxIfaces;
};
@@ -89,7 +89,7 @@
* the target combination is also satisfied. At that point new interfaces
* satisfying only the target combination can be added (meaning the initial
* combination limits will no longer satisfied). The addition of these new
- * interfaces should not impact the existence of interfaces that satisfy both
+ * interfaces must not impact the existence of interfaces that satisfy both
* combinations.
*
* For example, a chip with available combinations:
@@ -98,10 +98,10 @@
* AP interface in place of one of the STAs then first one of the STA
* interfaces must be removed and then the AP interface can be created after
* the STA had been torn down. During this process the remaining STA and NAN
- * interfaces should not be removed/recreated.
+ * interfaces must not be removed/recreated.
*
* If a chip does not support this kind of reconfiguration in this mode then
- * the combinations should be separated into two separate modes. Before
+ * the combinations must be separated into two separate modes. Before
* switching modes all interfaces will be torn down, the mode switch will be
* enacted and when it completes the new interfaces will be brought up.
*/
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);
};
diff --git a/wifi/1.0/IWifiStaIfaceEventCallback.hal b/wifi/1.0/IWifiStaIfaceEventCallback.hal
new file mode 100644
index 0000000..1ee2d4e
--- /dev/null
+++ b/wifi/1.0/IWifiStaIfaceEventCallback.hal
@@ -0,0 +1,126 @@
+/*
+ * Copyright 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.wifi@1.0;
+
+interface IWifiStaIfaceEventCallback {
+ /**
+ * Callback indicating that the requested packet filter was successfully
+ * installed.
+ */
+ oneway onInstallPacketFilterSuccess();
+
+ /**
+ * Callback indicating that installing a packet filter failed.
+ */
+ oneway onInstallPacketFilterFailure(FailureReason reason);
+
+ /**
+ * Callback indicating that a requested background scan was started.
+ */
+ oneway onBackgroundScanStarted();
+
+ /**
+ * Callback indicating that a requested background scan failed to start.
+ */
+ oneway onBackgroundScanStartFailure(FailureReason reason);
+
+ /**
+ * Callback indicating that a scan was stopped
+ */
+ oneway onBackgroundScanStopped();
+
+ /**
+ * Information elements contained within the |ScanResult| structure.
+ * These elements correspond to the IEEE_802.11 standard.
+ */
+ struct InformationElement {
+ uint8_t id;
+ vec<uint8_t> data;
+ };
+
+ /**
+ * BSSID type. 6 octets representing the physical address of an AP.
+ */
+ typedef uint8_t[6] Bssid;
+
+ /**
+ * Structure describing all the information about a single access point seen
+ * during the scan.
+ */
+ struct ScanResult {
+ int64_t timeStampInUs;
+ vec<uint8_t> ssid;
+ Bssid bssid;
+ uint32_t frequencyInMhz;
+ int8_t rssi;
+ uint16_t beaconPeriodInMs;
+ uint16_t capability;
+ vec<InformationElement> informationElements;
+ };
+
+ /**
+ * Mask of flags set in the |ScanData| instance.
+ */
+ enum ScanDataFlagMask {
+ /**
+ * Indicates that a scan was interrupted/did not occur so results may be
+ * incomplete.
+ */
+ WIFI_SCAN_FLAG_INTERRUPTED = 1 << 0,
+ };
+
+ /**
+ * Structure describing all the information about all the access points seen during
+ * the scan.
+ */
+ struct ScanData {
+ /**
+ * Bitset containing |ScanDataFlagMask| values.
+ */
+ uint32_t flags;
+ /**
+ * Bitset where each bit indicates if the bucket with that index was
+ * scanned.
+ */
+ uint32_t bucketsScanned;
+ /**
+ * List of scan results.
+ */
+ vec<ScanResult> results;
+ };
+
+ /**
+ * Called for each received beacon/probe response for a scan with the
+ * |REPORT_EVENTS_FULL_RESULTS| flag set in
+ * |BackgroundScanBucketParameters.eventReportScheme|.
+ *
+ * @param cmdId command Id corresponding to the request.
+ * @parm result Full scan result for an AP.
+ */
+ oneway onBackgroundFullScanResult(CommandId cmdId, ScanResult result);
+
+ /**
+ * Called when the |BackgroundScanBucketParameters.eventReportScheme| flags
+ * for at least one bucket that was just scanned was
+ * |REPORT_EVENTS_EACH_SCAN| or one of the configured thresholds was
+ * breached.
+ *
+ * @param cmdId command Id corresponding to the request.
+ * @parm scanDatas List of scan result for all AP's seen since last callback.
+ */
+ oneway onBackgroundScanResults(CommandId cmdId, vec<ScanData> scanDatas);
+};
diff --git a/wifi/1.0/types.hal b/wifi/1.0/types.hal
index d9abaef..cabb97d 100644
--- a/wifi/1.0/types.hal
+++ b/wifi/1.0/types.hal
@@ -51,7 +51,7 @@
AP,
P2P,
/**
- * NAN control interface. Datapath support may be queried and created
+ * NAN control interface. Datapath support must be queried and created
* through this interface.
*/
NAN,
@@ -66,3 +66,10 @@
* An identifier for a mode that the chip can be put in.
*/
typedef uint32_t ChipModeId;
+
+/**
+ * A unique handle provided by the client to identify individual invocations of
+ * certain API's like |IWifiStaIface.startBackgroundScan|,
+ * |IWifiStaIface.installApfPacketFilter|, etc.
+ */
+typedef uint32_t CommandId;