1/* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.wifi@1.5; 18 19import @1.0::WifiStatus; 20import @1.5::IWifiApIface; 21import @1.0::IWifiIface; 22import @1.3::IWifiChip; 23import @1.4::IWifiChip; 24 25/** 26 * Interface that represents a chip that must be configured as a single unit. 27 */ 28interface IWifiChip extends @1.4::IWifiChip { 29 /** 30 * Capabilities exposed by this chip. 31 */ 32 enum ChipCapabilityMask : @1.3::IWifiChip.ChipCapabilityMask { 33 /** 34 * chip can operate in the 60GHz band(WiGig chip) 35 */ 36 WIGIG = 1 << 14, 37 }; 38 39 /** 40 * When there are 2 or more simultaneous STA connections, this use case hint indicates what 41 * use-case is being enabled by the framework. This use case hint can be used by the firmware 42 * to modify various firmware configurations like: 43 * - Allowed BSSIDs the firmware can choose for the initial connection/roaming attempts. 44 * - Duty cycle to choose for the 2 STA connections if the radio is in MCC mode. 45 * - Whether roaming, APF and other offloads needs to be enabled or not. 46 * Note: 47 * - This will be invoked before an active wifi connection is established on the second 48 * interface. 49 * - This use-case hint is implicitly void when the second STA interface is brought down. 50 * - When there is only 1 STA interface, the must should still retain the last use case 51 * set, which must become active the next time multi STA is enabled. 52 * 1. Initialize with single STA. 53 * 2. Framework creates second STA. 54 * 3. Framework sets use case to DUAL_STA_NON_TRANSIENT_UNBIASED. 55 * 4. Framework destroys second STA. Only 1 STA remains. 56 * 5. Framework recreates second STA. 57 * 6. The active use case remains DUAL_STA_NON_TRANSIENT_UNBIASED (i.e. firmware should not 58 * automatically change it during period of single STA unless requested by framework). 59 */ 60 enum MultiStaUseCase : uint8_t { 61 /** 62 * Usage: 63 * - This will be sent down for make before break use-case. 64 * - Platform is trying to speculatively connect to a second network and evaluate it without 65 * disrupting the primary connection. 66 * Requirements for Firmware: 67 * - Do not reduce the number of tx/rx chains of primary connection. 68 * - If using MCC, should set the MCC duty cycle of the primary connection to be higher than 69 * the secondary connection (maybe 70/30 split). 70 * - Should pick the best BSSID for the secondary STA (disregard the chip mode) independent 71 * of the primary STA: 72 * - Don’t optimize for DBS vs MCC/SCC 73 * - Should not impact the primary connection’s bssid selection: 74 * - Don’t downgrade chains of the existing primary connection. 75 * - Don’t optimize for DBS vs MCC/SCC. 76 */ 77 DUAL_STA_TRANSIENT_PREFER_PRIMARY = 0, 78 /** 79 * Usage: 80 * - This will be sent down for any app requested peer to peer connections. 81 * - In this case, both the connections needs to be allocated equal resources. 82 * - For the peer to peer use case, BSSID for the secondary connection will be chosen by the 83 * framework. 84 * 85 * Requirements for Firmware: 86 * - Can choose MCC or DBS mode depending on the MCC efficiency and HW capability. 87 * - If using MCC, set the MCC duty cycle of the primary connection to be equal to the 88 * secondary connection. 89 * - Prefer BSSID candidates which will help provide the best "overall" performance for both 90 * the connections. 91 */ 92 DUAL_STA_NON_TRANSIENT_UNBIASED = 1, 93 }; 94 95 /** 96 * Get the capabilities supported by this chip. 97 * 98 * @return status WifiStatus of the operation. 99 * Possible status codes: 100 * |WifiStatusCode.SUCCESS|, 101 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 102 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 103 * |WifiStatusCode.ERROR_UNKNOWN| 104 * @return capabilities Bitset of |ChipCapabilityMask| values. 105 */ 106 getCapabilities_1_5() 107 generates (WifiStatus status, bitfield<ChipCapabilityMask> capabilities); 108 109 /** 110 * Invoked to indicate that the provided iface is the primary STA iface when there are more 111 * than 1 STA iface concurrently active. 112 * Notes: 113 * - If the wifi firmware/chip cannot support multiple instances of any offload 114 * (like roaming, APF, rssi threshold, etc), the firmware should ensure that these 115 * offloads are at least enabled for the primary interface. If the new primary interface is 116 * already connected to a network, the firmware must switch all the offloads on 117 * this new interface without disconnecting. 118 * - When there is only 1 STA interface, the firmware must still retain the last primary 119 * connection, which must become active the next time multi STA is enabled. 120 * 121 * @param ifname Name of the STA iface. 122 * @return status WifiStatus of the operation. 123 * Possible status codes: 124 * |WifiStatusCode.SUCCESS|, 125 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 126 * |WifiStatusCode.ERROR_INVALID_ARGS| 127 */ 128 setMultiStaPrimaryConnection(string ifName) generates (WifiStatus status); 129 130 /** 131 * Invoked to indicate the STA + STA use-case that is active. 132 * 133 * Refer to documentation of |MultiStaUseCase| for details. 134 * 135 * @param useCase Use case that is active. 136 * @return status WifiStatus of the operation. 137 * Possible status codes: 138 * |WifiStatusCode.SUCCESS|, 139 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 140 * |WifiStatusCode.ERROR_INVALID_ARGS| 141 */ 142 setMultiStaUseCase(MultiStaUseCase useCase) generates (WifiStatus status); 143 144 /** 145 * Create bridged IWifiApIface. 146 * 147 * Depending on the mode the chip is configured in, the interface creation 148 * may fail (code: |ERROR_NOT_AVAILABLE|) if we've already reached the maximum 149 * allowed (specified in |ChipIfaceCombination|) number of ifaces of the AP 150 * type. 151 * 152 * @return status WifiStatus of the operation. 153 * Possible status codes: 154 * |WifiStatusCode.SUCCESS|, 155 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 156 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 157 * |WifiStatusCode.ERROR_NOT_AVAILABLE| 158 * @return iface HIDL interface object representing the iface if 159 * successful, null otherwise. 160 */ 161 createBridgedApIface() generates (WifiStatus status, IWifiApIface iface); 162 163 /** 164 * Removes one of the instance on the AP Iface with the provided ifaceName and 165 * ifaceInstanceName. 166 * 167 * Use the API: removeApIface with brIfaceName in the V1_0::WifiChip.hal to remove bridge Iface. 168 * 169 * @param brIfaceName Name of the bridged AP iface. 170 * @param ifaceInstanceName Name of the instance. The empty instance is 171 * invalid. 172 * @return status WifiStatus of the operation. 173 * Possible status codes: 174 * |WifiStatusCode.SUCCESS|, 175 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 176 * |WifiStatusCode.ERROR_INVALID_ARGS|, 177 * |WifiStatusCode.ERROR_NOT_AVAILABLE| 178 */ 179 removeIfaceInstanceFromBridgedApIface(string brIfaceName, string ifaceInstanceName) 180 generates (WifiStatus status); 181 182 /** 183 * Representation of a Wi-Fi channel for Wi-Fi coex channel avoidance. 184 */ 185 struct CoexUnsafeChannel { 186 /* The band of the channel */ 187 WifiBand band; 188 /* The channel number */ 189 uint32_t channel; 190 /** The power cap will be a maximum power value in dbm that is allowed to be transmitted by 191 the chip on this channel. A value of PowerCapConstant.NO_POWER_CAP means no limitation 192 on transmitted power is needed by the chip for this channel. 193 */ 194 int32_t powerCapDbm; 195 }; 196 197 enum PowerCapConstant : int32_t { 198 NO_POWER_CAP = 0x7FFFFFFF, 199 }; 200 201 enum CoexRestriction : uint32_t { 202 WIFI_DIRECT = 1 << 0, 203 SOFTAP = 1 << 1, 204 WIFI_AWARE = 1 << 2 205 }; 206 207 /** 208 * Invoked to indicate that the provided |CoexUnsafeChannels| should be avoided with the 209 * specified restrictions. 210 * 211 * Channel avoidance is a suggestion and should be done on a best-effort approach. If a provided 212 * channel is used, then the specified power cap should be applied. 213 * 214 * In addition, hard restrictions on the Wifi modes may be indicated by |CoexRestriction| bits 215 * (WIFI_DIRECT, SOFTAP, WIFI_AWARE) in the |restrictions| bitfield. If a hard restriction is 216 * provided, then the channels should be completely avoided for the provided Wifi modes instead 217 * of by best-effort. 218 * 219 * @param unsafeChannels List of |CoexUnsafeChannels| to avoid. 220 * @param restrictions Bitset of |CoexRestriction| values indicating Wifi interfaces to 221 * completely avoid. 222 * @return status WifiStatus of the operation. 223 * Possible status codes: 224 * |WifiStatusCode.SUCCESS|, 225 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 226 * |WifiStatusCode.ERROR_INVALID_ARGS|, 227 */ 228 setCoexUnsafeChannels( 229 vec<CoexUnsafeChannel> unsafeChannels, bitfield<CoexRestriction> restrictions) 230 generates (WifiStatus status); 231 232 /** 233 * Set country code for this Wifi chip. 234 * 235 * Country code is global setting across the Wifi chip and not Wifi 236 * interface (STA or AP) specific. Legacy HAL API's for country code in 237 * @1.0::ISupplicantStaIface::setCountryCode & 238 * @1.0::IWifiApIface:setCountryCode are deprecated in favor of this 239 * chip level API. 240 * 241 * @param code 2 byte country code (as defined in ISO 3166) to set. 242 * @return status Status of the operation. 243 * Possible status codes: 244 * |WifiStatusCode.SUCCESS|, 245 * |WifiStatusCode.FAILURE_UNKNOWN|, 246 * |WifiStatusCode.FAILURE_IFACE_INVALID| 247 */ 248 setCountryCode(int8_t[2] code) generates (WifiStatus status); 249 250 /** 251 * Usable Wifi channels filter masks. 252 */ 253 enum UsableChannelFilter : uint32_t { 254 /** 255 * Filter Wifi channels that should be avoided due to extreme 256 * cellular coexistence restrictions. Some Wifi channels can have 257 * extreme interference from/to cellular due to short frequency 258 * seperation with neighboring cellular channels or when there 259 * is harmonic and intermodulation interference. Channels which 260 * only have some performance degradation (e.g. power back off is 261 * sufficient to deal with coexistence issue) can be included and 262 * should not be filtered out. 263 */ 264 CELLULAR_COEXISTENCE = 1 << 0, 265 /** 266 * Filter based on concurrency state. 267 * Examples: 268 * - 5GHz SAP operation may be supported in standalone mode, but if 269 * there is STA connection on 5GHz DFS channel, none of the 5GHz 270 * channels are usable for SAP if device does not support DFS SAP mode. 271 * - P2P GO may not be supported on indoor channels in EU during 272 * standalone mode but if there is a STA connection on indoor channel, 273 * P2P GO may be supported by some vendors on the same STA channel. 274 */ 275 CONCURRENCY = 1 << 1, 276 }; 277 278 /** 279 * Retrieve list of usable Wifi channels for the specified band & 280 * operational modes. 281 * 282 * The list of usable Wifi channels in a given band depends on factors 283 * like current country code, operational mode (e.g. STA, SAP, WFD-CLI, 284 * WFD-GO, TDLS, NAN) and other restrictons due to DFS, cellular coexistence 285 * and conncurency state of the device. 286 * 287 * @param band |WifiBand| for which list of usable channels is requested. 288 * @param ifaceModeMask Bitmask of the modes represented by |WifiIfaceMode| 289 * Bitmask respresents all the modes that the caller is interested 290 * in (e.g. STA, SAP, CLI, GO, TDLS, NAN). E.g. If the caller is 291 * interested in knowing usable channels for P2P CLI, P2P GO & NAN, 292 * ifaceModeMask would be set to 293 * IFACE_MODE_P2P_CLIENT|IFACE_MODE_P2P_GO|IFACE_MODE_NAN. 294 * @param filterMask Bitmask of filters represented by 295 * |UsableChannelFilter|. Specifies whether driver should filter 296 * channels based on additional criteria. If no filter is specified 297 * driver should return usable channels purely based on regulatory 298 * constraints. 299 * @return status WifiStatus of the operation. 300 * Possible status codes: 301 * |WifiStatusCode.SUCCESS|, 302 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 303 * |WifiStatusCode.ERROR_INVALID_ARGS|, 304 * |WifiStatusCode.FAILURE_UNKNOWN| 305 * @return channels List of channels represented by |WifiUsableChannel| 306 * Each entry represents a channel frequency, bandwidth and 307 * bitmask of modes (e.g. STA, SAP, CLI, GO, TDLS, NAN) that are 308 * allowed on that channel. E.g. If only STA mode can be supported 309 * on an indoor channel, only the IFACE_MODE_STA bit would be set 310 * for that channel. If 5GHz SAP cannot be supported, then none of 311 * the 5GHz channels will have IFACE_MODE_SOFTAP bit set. 312 * Note: Bits do not represent concurrency state. Each bit only 313 * represents whether particular mode is allowed on that channel. 314 */ 315 getUsableChannels(WifiBand band, bitfield<WifiIfaceMode> ifaceModeMask, 316 bitfield<UsableChannelFilter> filterMask) 317 generates (WifiStatus status, vec<WifiUsableChannel> channels); 318 319 /** 320 * Trigger subsystem restart 321 * 322 * If the framework detects a problem (e.g. connection failure), 323 * it must call this function to attempt recovery. 324 * 325 * When the wifi HAL receiveds triggerSubsystemRestart(), it must restart 326 * the wlan subsystem, especially the wlan firmware. 327 * 328 * Regarding the callback function for subsystem restart, refer to documentation of 329 * |IWifiEventCallback.onSubsystemRestart| for details. 330 * 331 * @return status WifiStatus of the operation. 332 * Possible status codes: 333 * |WifiStatusCode.SUCCESS|, 334 * |WifiStatusCode.ERROR_WIFI_CHIP_INVALID|, 335 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 336 * |WifiStatusCode.ERROR_UNKNOWN| 337 */ 338 triggerSubsystemRestart() generates (WifiStatus status); 339}; 340