diff --git a/wifi/1.0/README-NAN.md b/wifi/1.0/README-NAN.md
new file mode 100644
index 0000000000..f4b3320e33
--- /dev/null
+++ b/wifi/1.0/README-NAN.md
@@ -0,0 +1,221 @@
+Copyright 2017 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/\/):
+
+* IWifiNanIface.hal
+* IWifiNanIfaceEventCallback.hal
+* types.hal (structure definitions)
+
+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/wif/):
+
+* 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 value 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(IWifiNanIfaceEventCallback callback)
+* getCapabilitiesRequest
+* enableRequest
+ * 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
+* configRequest
+ * NanConfigRequest: same as for enableRequest
+* 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
+ * 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
+
+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
+* eventDataPathTerminated
+