From 7b77747bb565f50ced457ad931e8d0206385d3a1 Mon Sep 17 00:00:00 2001 From: Roshan Pius Date: Fri, 7 Oct 2016 13:15:59 -0700 Subject: [PATCH] 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 --- wifi/1.0/Android.bp | 8 + wifi/1.0/Android.mk | 46 ++++ wifi/1.0/IWifiChip.hal | 8 +- wifi/1.0/IWifiStaIface.hal | 267 +++++++++++++++++++++++- wifi/1.0/IWifiStaIfaceEventCallback.hal | 126 +++++++++++ wifi/1.0/types.hal | 9 +- 6 files changed, 458 insertions(+), 6 deletions(-) create mode 100644 wifi/1.0/IWifiStaIfaceEventCallback.hal diff --git a/wifi/1.0/Android.bp b/wifi/1.0/Android.bp index b7309310b8..a3daa89ffa 100644 --- a/wifi/1.0/Android.bp +++ b/wifi/1.0/Android.bp @@ -16,6 +16,7 @@ genrule { "IWifiP2pIface.hal", "IWifiRttController.hal", "IWifiStaIface.hal", + "IWifiStaIfaceEventCallback.hal", ], out: [ "android/hardware/wifi/1.0/types.cpp", @@ -29,6 +30,7 @@ genrule { "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 @@ genrule { "IWifiP2pIface.hal", "IWifiRttController.hal", "IWifiStaIface.hal", + "IWifiStaIfaceEventCallback.hal", ], out: [ "android/hardware/wifi/1.0/types.h", @@ -101,6 +104,11 @@ genrule { "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 58c487b76c..a1a716d23c 100644 --- a/wifi/1.0/Android.mk +++ b/wifi/1.0/Android.mk @@ -261,6 +261,10 @@ $(GEN): PRIVATE_HIDL := $(HIDL) $(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): PRIVATE_CUSTOM_TOOL = \ $(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_HIDL := $(HIDL) $(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): PRIVATE_CUSTOM_TOOL = \ $(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 cd4b21981a..55f6d61a92 100644 --- a/wifi/1.0/IWifiChip.hal +++ b/wifi/1.0/IWifiChip.hal @@ -36,7 +36,7 @@ interface IWifiChip { * ChipIfaceCombination for examples. */ struct ChipIfaceCombinationLimit { - vec types; // Each IfaceType may occur at most once + vec types; // Each IfaceType must occur at most once. uint32_t maxIfaces; }; @@ -89,7 +89,7 @@ interface IWifiChip { * 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 @@ interface IWifiChip { * 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 5234c71301..a738ebe4da 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 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 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 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 0000000000..1ee2d4e1d2 --- /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 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 ssid; + Bssid bssid; + uint32_t frequencyInMhz; + int8_t rssi; + uint16_t beaconPeriodInMs; + uint16_t capability; + vec 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 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 scanDatas); +}; diff --git a/wifi/1.0/types.hal b/wifi/1.0/types.hal index d9abaefe5d..cabb97dcc3 100644 --- a/wifi/1.0/types.hal +++ b/wifi/1.0/types.hal @@ -51,7 +51,7 @@ enum IfaceType : uint32_t { 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 @@ typedef uint32_t ChipId; * 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;