From a67fdff49b8964acf212cdbd342ccc0bb171e6d1 Mon Sep 17 00:00:00 2001 From: Etan Cohen Date: Fri, 18 May 2018 10:18:58 -0700 Subject: [PATCH] [AWARE] Developer documentation on HAL usage Add documentation specifying which HAL APIs are used by the framework. Bug: 79431608 Test: N/A Change-Id: Ie5b1da7b9a613d17df61351b067819a4d765a762 --- wifi/1.0/README-NAN.md | 6 +- wifi/1.2/README-NAN.md | 231 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 3 deletions(-) create mode 100644 wifi/1.2/README-NAN.md diff --git a/wifi/1.0/README-NAN.md b/wifi/1.0/README-NAN.md index f4b3320e33..645c9f942b 100644 --- a/wifi/1.0/README-NAN.md +++ b/wifi/1.0/README-NAN.md @@ -14,7 +14,7 @@ limitations under the License. # Wi-Fi Aware (NAN) HAL API Usage -The Wi-Fi Aware (NAN) HAL API is defined in (hardware/interfaces/wifi/\/): +The Wi-Fi Aware (NAN) HAL API is defined in (hardware/interfaces/wifi/1.0/): * IWifiNanIface.hal * IWifiNanIfaceEventCallback.hal @@ -23,7 +23,7 @@ The Wi-Fi Aware (NAN) HAL API is defined in (hardware/interfaces/wifi/\frameworks/opt/net/wif/): +by reviewing framework code, specifically (frameworks/opt/net/wifi/): * WifiAwareNativeApi.java * WifiAwareNativeCallback.java @@ -41,7 +41,7 @@ the new HAL API only. To understand the mapping between new and legacy HALs plea Format: * Hard-coded values are in bold, e.g. true or 5 -* Assigned but not fixed value are specified using the variable keyword, possibly with some +* Assigned but not fixed values are specified using the variable keyword, possibly with some details/constraints * Unassigned values are specified using the N/A keyword. Unassigned usually means initialized to 0. diff --git a/wifi/1.2/README-NAN.md b/wifi/1.2/README-NAN.md new file mode 100644 index 0000000000..00b916909b --- /dev/null +++ b/wifi/1.2/README-NAN.md @@ -0,0 +1,231 @@ +Copyright 2018 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. + +# Wi-Fi Aware (NAN) HAL API Usage + +The Wi-Fi Aware (NAN) HAL API is defined in (hardware/interfaces/wifi/1.0/ and +hardware/interfaces/wifi/1.2/): + +* IWifiNanIface.hal +* IWifiNanIfaceEventCallback.hal +* types.hal (structure definitions) + +Note that the 1.2 HAL is supplemental to the 1.0 HAL - not a replacement. + +The Wi-Fi Aware (NAN) HAL API surface is very large - only a subset is used from the framework. + +Understanding of the HAL API subset which is actively used by the Android framework can be deduced +by reviewing framework code, specifically (frameworks/opt/net/wifi/): + +* WifiAwareNativeApi.java +* WifiAwareNativeCallback.java + +The above framework files determine the API usage - and should be consulted as the authoritative +reference. Please consult the primary HAL file for documentation - they will not be replicated +in this document. APIs which are in the HAL but are not listed in this README file are not used by +the framework. + +Note: the HAL API is translated to the legacy HAL API (wifi_nan.h). This README file covers +the new HAL API only. To understand the mapping between new and legacy HALs please consult +hardware/interfaces/wifi/\/default/hidl_struct_util.cpp. + +## IWifiNanIface + +Format: +* Hard-coded values are in bold, e.g. true or 5 +* Assigned but not fixed values are specified using the variable keyword, possibly with some +details/constraints +* Unassigned values are specified using the N/A keyword. Unassigned usually means initialized +to 0. + +APIs: + +* registerEventCallback_1_2(IWifiNanIfaceEventCallback_1_2 callback) +* getCapabilitiesRequest +* enableRequest_1_2 + * NanEnableRequest + * bool[2] operateInBand + * Index [NanBandIndex.NAN_BAND_24GHZ] = true + * Index [NanBandIndex.NAN_BAND_5GHZ] = variable + * uint8_t hopCountMax = 2 + * NanConfigRequest configParams + * uint8_t masterPref = variable + * bool disableDiscoveryAddressChangeIndication = variable + * bool disableStartedClusterIndication = variable + * bool disableJoinedClusterIndication = variable + * bool includePublishServiceIdsInBeacon = true + * uint8_t numberOfPublishServiceIdsInBeacon = 0 + * bool includeSubscribeServiceIdsInBeacon = true + * uint8_t numberOfSubscribeServiceIdsInBeacon = 0 + * uint16_t rssiWindowSize = 8 + * uint32_t macAddressRandomizationIntervalSec = variable + * Normal run-time: set to 1800 (30 minutes) + * Tests: set to 120 (2 minutes) + * NanBandSpecificConfig[2] bandSpecificConfig + * Index [NanBandIndex.NAN_BAND_24GHZ] + * uint8_t rssiClose = 60 + * uint8_t rssiMiddle = 70 + * uint8_t rssiCloseProximity = 60 + * uint8_t dwellTimeMs = 200 + * uint16_t scanPeriodSec = 20 + * bool validDiscoveryWindowIntervalVal = variable + * uint8_t discoveryWindowIntervalVal = variable + * Index [NanBandIndex.NAN_BAND_5GHZ] + * uint8_t rssiClose = 60 + * uint8_t rssiMiddle = 75 + * uint8_t rssiCloseProximity = 60 + * uint8_t dwellTimeMs = 200 + * uint16_t scanPeriodSec = 20 + * bool validDiscoveryWindowIntervalVal = variable + * uint8_t discoveryWindowIntervalVal = variable + * NanDebugConfig debugConfigs + * bool validClusterIdVals = true + * uint16_t clusterIdBottomRangeVal = variable + * uint16_t clusterIdTopRangeVal = variable + * bool validIntfAddrVal = false + * MacAddress intfAddrVal = N/A + * bool validOuiVal = false + * uint32_t ouiVal = N/A + * bool validRandomFactorForceVal = false + * uint8_t randomFactorForceVal = N/A + * bool validHopCountForceVal = false + * uint8_t hopCountForceVal = N/A + * bool validDiscoveryChannelVal = false + * WifiChannelInMhz[2] discoveryChannelMhzVal = N/A + * bool validUseBeaconsInBandVal = false + * bool[2] useBeaconsInBandVal = N/A + * bool validUseSdfInBandVal = false + * bool[2] useSdfInBandVal = N/A + * NanConfigRequestSupplemental + * uint32_t discoveryBeaconIntervalMs = 0 + * uint32_t numberOfSpatialStreamsInDiscovery = 0 + * bool enableDiscoveryWindowEarlyTermination = false + * bool enableRanging = true +* configRequest_1_2 + * NanConfigRequest: same as for enableRequest_1_2 +* disableRequest +* startPublishRequest + * NanPublishRequest + * NanDiscoveryCommonConfig baseConfigs + * uint8_t sessionId = variable + * uint16_t ttlSec = variable + * uint16_t discoveryWindowPeriod = 1 + * uint8_t discoveryCount = 0 + * vec serviceName = variable + * NanMatchAlg discoveryMatchIndicator = NanMatchAlg.MATCH_NEVER + * vec serviceSpecificInfo = variable + * vec extendedServiceSpecificInfo = N/A + e vec rxMatchFilter = variable + * vec txMatchFilter = variable + * bool useRssiThreshold = false + * bool disableDiscoveryTerminationIndication = variable + * bool disableMatchExpirationIndication = true + * bool disableFollowupReceivedIndication = false + * NanDataPathSecurityConfig securityConfig = NanDataPathSecurityType.OPEN + * bool rangingRequired = false + * uint32_t rangingIntervalMsec = N/A + * bitfield configRangingIndications = N/A + * uint16_t distanceIngressCm = N/A + * uint16_t distanceEgressCm = N/A + * NanPublishType publishType = variable + * NanTxType txType = NanTxType.BROADCAST + * bool autoAcceptDataPathRequests = false +* stopPublishRequest +* startSubscribeRequest + * NanSubscribeRequest + * NanDiscoveryCommonConfig baseConfigs + * Mostly same as publish above except: + * NanMatchAlg discoveryMatchIndicator = NanMatchAlg.MATCH_ONCE + * NanSubscribeType subscribeType = variable + * NanSrfType srfType = N/A + * bool srfRespondIfInAddressSet = N/A + * bool shouldUseSrf = N/A + * bool isSsiRequiredForMatch = N/A + * vec intfAddr = N/A +* stopSubscribeRequest +* transmitFollowupRequest + * NanTransmitFollowupRequest + * uint8_t discoverySessionId = variable + * uint32_t peerId = variable + * MacAddress addr = variable + * bool isHighPriority = false + * bool shouldUseDiscoveryWindow = true + * vec serviceSpecificInfo = variable + * vec extendedServiceSpecificInfo = N/A + * bool disableFollowupResultIndication = false +* createDataInterfaceRequest +* deleteDataInterfaceRequest +* initiateDataPathRequest + * NanInitiateDataPathRequest + * uint32_t peerId = variable + * MacAddress peerDiscMacAddr = variable + * NanDataPathChannelCfg channelRequestType = + NanDataPathChannelCfg.CHANNEL_NOT_REQUESTED + * WifiChannelInMhz channel = 2437 (note that should be ignored though - + CHANNEL_NOT_REQUESTED!) + * string ifaceName = variable + * NanDataPathSecurityConfig securityConfig = variable + * vec appInfo = N/A + * vec serviceNameOutOfBand = variable +* respondToDataPathIndicationRequest + * NanRespondToDataPathIndicationRequest + * bool acceptRequest = variable + * uint32_t ndpInstanceId = variable + * string ifaceName = variable + * NanDataPathSecurityConfig securityConfig = variable + * vec appInfo = N/A + * vec serviceNameOutOfBand = variable +* terminateDataPathRequest + +## IWifiNanIfaceEventCallback_1_2 + +Format: +* Parameters whose values are ignored will be flagged, otherwise the parameter value is used +by the framework. + +API: + +* notifyXxxResponse: all callbacks are used by framework +* eventClusterEvent +* eventDisabled +* eventPublishTerminated +* eventSubscribeTerminated +* eventMatch + * NanMatchInd (all parameters are used except those listed below) + * vec extendedServiceSpecificInfo: ignored + * bool matchOccuredInBeaconFlag: ignored + * bool outOfResourceFlag: ignored + * uint8_t rssiValue: ignored + * NanCipherSuiteType peerCipherType: ignored + * bool peerRequiresSecurityEnabledInNdp: ignored + * bool peerRequiresRanging: ignored + * uint32_t rangingMeasurementInCm: ignored + * bitfield rangingIndicationType: ignored +* eventMatchExpired: ignored +* eventFollowupReceived + * NanFollowupReceivedInd (all parameters are used except those listed below) + * bool receivedInFaw: ignored + * vec extendedServiceSpecificInfo: ignored +* eventTransmitFollowup +* eventDataPathRequest + * NanDataPathRequestInd (all parameters are used except those listed below) + * bool securityRequired: ignored + * vec appInfo: ignored +* eventDataPathConfirm + * NanDataPathConfirmInd (all parameters are used except those listed below) + * vec appInfo: ignored +* eventDataPathScheduleUpdate + * NanDataPathScheduleUpdateInd +* eventDataPathTerminated +