1 /* 2 * Copyright 2016 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 17 package android.hardware.wifi@1.0; 18 19 import IWifiIface; 20 import IWifiStaIfaceEventCallback; 21 22 /** 23 * Interface used to represent a single STA iface. 24 */ 25 interface IWifiStaIface extends IWifiIface { 26 /** 27 * Mask of capabilities suported by this Iface. 28 */ 29 enum StaIfaceCapabilityMask : uint32_t { 30 /** 31 * If set indicates that the APF APIs are supported. 32 * APF (Android Packet Filter) is a BPF like packet filtering 33 * bytecode executed by the firmware. 34 */ 35 APF = 1 << 0, 36 /** 37 * If set indicates that the Background Scan APIs are supported. 38 * Background scan allow the host to send a number of buckets down to the 39 * firmware. Each bucket contains a set of channels, a period, and some 40 * parameters about how and when to report results. 41 */ 42 BACKGROUND_SCAN = 1 << 1, 43 /** 44 * If set indicates that the link layer stats APIs are supported. 45 */ 46 LINK_LAYER_STATS = 1 << 2, 47 /** 48 * If set indicates that the RSSI monitor APIs are supported. 49 */ 50 RSSI_MONITOR = 1 << 3, 51 /** 52 * If set indicates that the roaming API's are supported. 53 */ 54 CONTROL_ROAMING = 1 << 4, 55 /** 56 * If set indicates support for Probe IE white listing. 57 */ 58 PROBE_IE_WHITELIST = 1 << 5, 59 /** 60 * If set indicates support for MAC & Probe Sequence Number randomization. 61 */ 62 SCAN_RAND = 1 << 6, 63 /** 64 * Support for 5 GHz Band. 65 */ 66 STA_5G = 1 << 7, 67 /** 68 * Support for GAS/ANQP queries. 69 */ 70 HOTSPOT = 1 << 8, 71 /** 72 * Support for Preferred Network Offload. 73 */ 74 PNO = 1 << 9, 75 /** 76 * Support for Tunneled Direct Link Setup. 77 */ 78 TDLS = 1 << 10, 79 /** 80 * Support for Tunneled Direct Link Setup off channel. 81 */ 82 TDLS_OFFCHANNEL = 1 << 11, 83 /** 84 * Support for neighbour discovery offload. 85 */ 86 ND_OFFLOAD = 1 << 12, 87 /** 88 * Support for keep alive packet offload. 89 */ 90 KEEP_ALIVE = 1 << 13, 91 /** 92 * Support for tracking connection packets' fate. 93 */ 94 DEBUG_PACKET_FATE = 1 << 14 95 }; 96 97 /** 98 * Requests notifications of significant events on this iface. Multiple calls 99 * to this must register multiple callbacks each of which must receive all 100 * events. 101 * 102 * @param callback An instance of the |IWifiStaIfaceEventCallback| HIDL interface 103 * object. 104 * @return status WifiStatus of the operation. 105 * Possible status codes: 106 * |WifiStatusCode.SUCCESS|, 107 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID| 108 */ 109 registerEventCallback(IWifiStaIfaceEventCallback callback) 110 generates (WifiStatus status); 111 112 /** 113 * Get the capabilities supported by this STA iface. 114 * 115 * @return status WifiStatus of the operation. 116 * Possible status codes: 117 * |WifiStatusCode.SUCCESS|, 118 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 119 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 120 * |WifiStatusCode.ERROR_UNKNOWN| 121 * @return capabilities Bitset of |StaIfaceCapabilityMask| values. 122 */ 123 getCapabilities() 124 generates (WifiStatus status, 125 bitfield<StaIfaceCapabilityMask> capabilities); 126 127 /** 128 * Used to query additional information about the chip's APF capabilities. 129 * Must fail if |StaIfaceCapabilityMask.APF| is not set. 130 * 131 * @return status WifiStatus of the operation. 132 * Possible status codes: 133 * |WifiStatusCode.SUCCESS|, 134 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 135 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 136 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 137 * |WifiStatusCode.ERROR_UNKNOWN| 138 * @return capabilities Instance of |StaApfPacketFilterCapabilities|. 139 */ 140 getApfPacketFilterCapabilities() 141 generates (WifiStatus status, StaApfPacketFilterCapabilities capabilities); 142 143 /** 144 * Installs an APF program on this iface, replacing an existing 145 * program if present. 146 * Must fail if |StaIfaceCapabilityMask.APF| is not set. 147 * 148 * APF docs 149 * ========================================================================== 150 * APF functionality, instructions and bytecode/binary format is described in: 151 * http://android.googlesource.com/platform/hardware/google/apf/ 152 * +/b75c9f3714cfae3dad3d976958e063150781437e/apf.h 153 * 154 * The interpreter API is described here: 155 * http://android.googlesource.com/platform/hardware/google/apf/+/ 156 * b75c9f3714cfae3dad3d976958e063150781437e/apf_interpreter.h#32 157 * 158 * The assembler/generator API is described in javadocs here: 159 * http://android.googlesource.com/platform/frameworks/base/+/ 160 * 4456f33a958a7f09e608399da83c4d12b2e7d191/services/net/java/android/net/ 161 * apf/ApfGenerator.java 162 * 163 * Disassembler usage is described here: 164 * http://android.googlesource.com/platform/hardware/google/apf/+/ 165 * b75c9f3714cfae3dad3d976958e063150781437e/apf_disassembler.c#65 166 * 167 * The BPF to APF translator usage is described here: 168 * http://android.googlesource.com/platform/frameworks/base/+/ 169 * 4456f33a958a7f09e608399da83c4d12b2e7d191/tests/net/java/android/net/ 170 * apf/Bpf2Apf.java 171 * ========================================================================== 172 * 173 * @param cmdId command Id to use for this invocation. 174 * @param APF Program to be set. 175 * @return status WifiStatus of the operation. 176 * Possible status codes: 177 * |WifiStatusCode.SUCCESS|, 178 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 179 * |WifiStatusCode.ERROR_INVALID_ARGS|, 180 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 181 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 182 * |WifiStatusCode.ERROR_UNKNOWN| 183 */ 184 installApfPacketFilter(CommandId cmdId, vec<uint8_t> program) 185 generates (WifiStatus status); 186 187 /** 188 * Used to query additional information about the chip's Background Scan capabilities. 189 * Must fail if |StaIfaceCapabilityMask.BACKGROUND_SCAN| is not set. 190 * 191 * @return status WifiStatus of the operation. 192 * Possible status codes: 193 * |WifiStatusCode.SUCCESS|, 194 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 195 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 196 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 197 * |WifiStatusCode.ERROR_UNKNOWN| 198 * @return capabilities Instance of |StaBackgroundScanCapabilities|. 199 */ 200 getBackgroundScanCapabilities() 201 generates (WifiStatus status, StaBackgroundScanCapabilities capabilities); 202 203 /** 204 * Used to query the list of valid frequencies (depending on country code set) 205 * for the provided band. These channels may be specifed in the 206 * |BackgroundScanBucketParameters.frequenciesInMhz| for a background scan 207 * request. 208 * 209 * @param band Band for which the frequency list is being generated. 210 * @return status WifiStatus of the operation. 211 * Possible status codes: 212 * |WifiStatusCode.SUCCESS|, 213 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 214 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 215 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 216 * |WifiStatusCode.ERROR_UNKNOWN| 217 * @return frequencies vector of valid frequencies for the provided band. 218 */ 219 getValidFrequenciesForBand(WifiBand band) 220 generates (WifiStatus status, vec<WifiChannelInMhz> frequencies); 221 222 /** 223 * Start a background scan using the given cmdId as an identifier. Only one 224 * active background scan need be supported. 225 * Must fail if |StaIfaceCapabilityMask.BACKGROUND_SCAN| is not set. 226 * 227 * When this is called all requested buckets must be scanned, starting the 228 * beginning of the cycle. 229 * 230 * For example: 231 * If there are two buckets specified 232 * - Bucket 1: period=10s 233 * - Bucket 2: period=20s 234 * - Bucket 3: period=30s 235 * Then the following scans must occur 236 * - t=0 buckets 1, 2, and 3 are scanned 237 * - t=10 bucket 1 is scanned 238 * - t=20 bucket 1 and 2 are scanned 239 * - t=30 bucket 1 and 3 are scanned 240 * - t=40 bucket 1 and 2 are scanned 241 * - t=50 bucket 1 is scanned 242 * - t=60 buckets 1, 2, and 3 are scanned 243 * - and the patter repeats 244 * 245 * If any scan does not occur or is incomplete (error, interrupted, etc) then 246 * a cached scan result must still be recorded with the 247 * WIFI_SCAN_FLAG_INTERRUPTED flag set. 248 * 249 * @param cmdId command Id to use for this invocation. 250 * @params Background scan parameters. 251 * @return status WifiStatus of the operation. 252 * Possible status codes: 253 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 254 * |WifiStatusCode.ERROR_INVALID_ARGS|, 255 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 256 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 257 * |WifiStatusCode.ERROR_UNKNOWN| 258 */ 259 startBackgroundScan(CommandId cmdId, StaBackgroundScanParameters params) 260 generates (WifiStatus status); 261 262 /** 263 * Stop the background scan started. 264 * Must fail if |StaIfaceCapabilityMask.BACKGROUND_SCAN| is not set. 265 * 266 * @param cmdId command Id corresponding to the request. 267 * @return status WifiStatus of the operation. 268 * Possible status codes: 269 * |WifiStatusCode.SUCCESS|, 270 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 271 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 272 * |WifiStatusCode.ERROR_NOT_STARTED|, 273 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 274 * |WifiStatusCode.ERROR_UNKNOWN| 275 */ 276 stopBackgroundScan(CommandId cmdId) generates (WifiStatus status); 277 278 /** 279 * Enable link layer stats collection. 280 * Must fail if |StaIfaceCapabilityMask.LINK_LAYER_STATS| is not set. 281 * 282 * Radio statistics (once started) must not stop until disabled. 283 * Iface statistics (once started) reset and start afresh after each 284 * connection until disabled. 285 * 286 * @param debug Set for field debug mode. Driver must collect all 287 * statistics regardless of performance impact. 288 * @return status WifiStatus of the operation. 289 * Possible status codes: 290 * |WifiStatusCode.SUCCESS|, 291 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 292 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 293 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 294 * |WifiStatusCode.ERROR_UNKNOWN| 295 */ 296 enableLinkLayerStatsCollection(bool debug) 297 generates (WifiStatus status); 298 299 /** 300 * Disable link layer stats collection. 301 * Must fail if |StaIfaceCapabilityMask.LINK_LAYER_STATS| is not set. 302 * 303 * @return status WifiStatus of the operation. 304 * Possible status codes: 305 * |WifiStatusCode.SUCCESS|, 306 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 307 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 308 * |WifiStatusCode.ERROR_NOT_STARTED|, 309 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 310 * |WifiStatusCode.ERROR_UNKNOWN| 311 */ 312 disableLinkLayerStatsCollection() generates (WifiStatus status); 313 314 /** 315 * Retrieve the latest link layer stats. 316 * Must fail if |StaIfaceCapabilityMask.LINK_LAYER_STATS| is not set or if 317 * link layer stats collection hasn't been explicitly enabled. 318 * 319 * @return status WifiStatus of the operation. 320 * Possible status codes: 321 * |WifiStatusCode.SUCCESS|, 322 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 323 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 324 * |WifiStatusCode.ERROR_NOT_STARTED|, 325 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 326 * |WifiStatusCode.ERROR_UNKNOWN| 327 * @return stats Instance of |LinkLayerStats|. 328 */ 329 getLinkLayerStats() generates (WifiStatus status, StaLinkLayerStats stats); 330 331 /** 332 * Start RSSI monitoring on the currently connected access point. 333 * Once the monitoring is enabled, 334 * |IWifiStaIfaceEventCallback.onRssiThresholdBreached| callback must be 335 * invoked to indicate if the RSSI goes above |maxRssi| or below |minRssi|. 336 * Must fail if |StaIfaceCapabilityMask.RSSI_MONITOR| is not set. 337 * 338 * @param cmdId command Id to use for this invocation. 339 * @param maxRssi Maximum RSSI threshold. 340 * @param minRssi Minimum RSSI threshold. 341 * @return status WifiStatus of the operation. 342 * Possible status codes: 343 * |WifiStatusCode.SUCCESS|, 344 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 345 * |WifiStatusCode.ERROR_ARGS_INVALID|, 346 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 347 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 348 * |WifiStatusCode.ERROR_UNKNOWN| 349 */ 350 startRssiMonitoring(CommandId cmdId, Rssi maxRssi, Rssi minRssi) 351 generates (WifiStatus status); 352 353 /** 354 * Stop RSSI monitoring. 355 * Must fail if |StaIfaceCapabilityMask.RSSI_MONITOR| is not set. 356 * 357 * @param cmdId command Id corresponding to the request. 358 * @return status WifiStatus of the operation. 359 * Possible status codes: 360 * |WifiStatusCode.SUCCESS|, 361 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 362 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 363 * |WifiStatusCode.ERROR_NOT_STARTED|, 364 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 365 * |WifiStatusCode.ERROR_UNKNOWN| 366 */ 367 stopRssiMonitoring(CommandId cmdId) generates (WifiStatus status); 368 369 /** 370 * Get roaming control capabilities. 371 * Must fail if |StaIfaceCapabilityMask.CONTROL_ROAMING| is not set. 372 * 373 * @return status WifiStatus of the operation. 374 * Possible status codes: 375 * |WifiStatusCode.SUCCESS|, 376 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 377 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 378 * |WifiStatusCode.ERROR_UNKNOWN| 379 * @return caps Instance of |StaRoamingCapabilities|. 380 */ 381 getRoamingCapabilities() 382 generates (WifiStatus status, StaRoamingCapabilities caps); 383 384 /** 385 * Configure roaming control parameters. 386 * Must fail if |StaIfaceCapabilityMask.CONTROL_ROAMING| is not set. 387 * 388 * @param config Instance of |StaRoamingConfig|. 389 * @return status WifiStatus of the operation. 390 * Possible status codes: 391 * |WifiStatusCode.SUCCESS|, 392 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 393 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 394 * |WifiStatusCode.ERROR_UNKNOWN| 395 */ 396 configureRoaming(StaRoamingConfig config) generates (WifiStatus status); 397 398 /** 399 * Set the roaming control state with the parameters configured 400 * using |configureRoaming|. Depending on the roaming state set, the 401 * driver/firmware would enable/disable control over roaming decisions. 402 * Must fail if |StaIfaceCapabilityMask.CONTROL_ROAMING| is not set. 403 * 404 * @param state State of the roaming control. 405 * @return status WifiStatus of the operation. 406 * Possible status codes: 407 * |WifiStatusCode.SUCCESS|, 408 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 409 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 410 * |WifiStatusCode.ERROR_BUSY|, 411 * |WifiStatusCode.ERROR_UNKNOWN| 412 */ 413 setRoamingState(StaRoamingState state) generates (WifiStatus status); 414 415 /** 416 * Enable/Disable Neighbour discovery offload functionality in the firmware. 417 * 418 * @param enable true to enable, false to disable. 419 * @return status WifiStatus of the operation. 420 * Possible status codes: 421 * |WifiStatusCode.SUCCESS|, 422 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 423 * |WifiStatusCode.ERROR_UNKNOWN| 424 */ 425 enableNdOffload(bool enable) generates (WifiStatus status); 426 427 /** 428 * Start sending the specified keep alive packets periodically. 429 * 430 * @param cmdId command Id to use for this invocation. 431 * @param ipPacketData IP packet contents to be transmitted. 432 * @param etherType 16 bit ether type to be set in the ethernet frame 433 * transmitted. 434 * @param srcAddress Source MAC address of the packet. 435 * @param dstAddress Destination MAC address of the packet. 436 * @param periodInMs Interval at which this packet must be transmitted. 437 * @return status WifiStatus of the operation. 438 * Possible status codes: 439 * |WifiStatusCode.SUCCESS|, 440 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 441 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 442 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 443 * |WifiStatusCode.ERROR_UNKNOWN| 444 */ 445 startSendingKeepAlivePackets( 446 CommandId cmdId, vec<uint8_t> ipPacketData, uint16_t etherType, 447 MacAddress srcAddress, MacAddress dstAddress, uint32_t periodInMs) 448 generates (WifiStatus status); 449 450 /** 451 * Stop sending the specified keep alive packets. 452 * 453 * @param cmdId command Id corresponding to the request. 454 * @return status WifiStatus of the operation. 455 * Possible status codes: 456 * |WifiStatusCode.SUCCESS|, 457 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 458 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 459 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 460 * |WifiStatusCode.ERROR_UNKNOWN| 461 */ 462 stopSendingKeepAlivePackets(CommandId cmdId) generates (WifiStatus status); 463 464 /** 465 * Set the MAC OUI during scanning. 466 * An OUI {Organizationally Unique Identifier} is a 24-bit number that 467 * uniquely identifies a vendor or manufacturer. 468 * 469 * @return status WifiStatus of the operation. 470 * Possible status codes: 471 * |WifiStatusCode.SUCCESS|, 472 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 473 * |WifiStatusCode.ERROR_UNKNOWN| 474 */ 475 setScanningMacOui(uint8_t[3] oui) generates (WifiStatus status); 476 477 /** 478 * API to start packet fate monitoring. 479 * - Once started, monitoring must remain active until HAL is stopped or the 480 * chip is reconfigured. 481 * - When HAL is unloaded, all packet fate buffers must be cleared. 482 * - The packet fates are used to monitor the state of packets transmitted/ 483 * received during association. 484 * 485 * @return status WifiStatus of the operation. 486 * Possible status codes: 487 * |WifiStatusCode.SUCCESS|, 488 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 489 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 490 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 491 * |WifiStatusCode.ERROR_UNKNOWN| 492 */ 493 startDebugPacketFateMonitoring() generates (WifiStatus status); 494 495 /** 496 * API to retrieve fates of outbound packets. 497 * - HAL implementation must return the fates of 498 * all the frames transmitted for the most recent association. 499 * The fate reports must follow the same order as their respective 500 * packets. 501 * - HAL implementation may choose (but is not required) to include 502 * reports for management frames. 503 * - Packets reported by firmware, but not recognized by driver, 504 * must be included. However, the ordering of the corresponding 505 * reports is at the discretion of HAL implementation. 506 * - Framework must be able to call this API multiple times for the same 507 * association. 508 * 509 * @return status WifiStatus of the operation. 510 * Possible status codes: 511 * |WifiStatusCode.SUCCESS|, 512 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 513 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 514 * |WifiStatusCode.ERROR_NOT_STARTED|, 515 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 516 * |WifiStatusCode.ERROR_UNKNOWN| 517 * @return fates Vector of |WifiDebugTxPacketFateReport| instances corresponding 518 * to the packet fates. 519 */ 520 getDebugTxPacketFates() 521 generates (WifiStatus status, vec<WifiDebugTxPacketFateReport> fates); 522 523 /** 524 * API to retrieve fates of inbound packets. 525 * - HAL implementation must return the fates of 526 * all the frames received for the most recent association. 527 * The fate reports must follow the same order as their respective 528 * packets. 529 * - HAL implementation may choose (but is not required) to include 530 * reports for management frames. 531 * - Packets reported by firmware, but not recognized by driver, 532 * must be included. However, the ordering of the corresponding 533 * reports is at the discretion of HAL implementation. 534 * - Framework must be able to call this API multiple times for the same 535 * association. 536 * 537 * @return status WifiStatus of the operation. 538 * Possible status codes: 539 * |WifiStatusCode.SUCCESS|, 540 * |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|, 541 * |WifiStatusCode.ERROR_NOT_SUPPORTED|, 542 * |WifiStatusCode.ERROR_NOT_STARTED|, 543 * |WifiStatusCode.ERROR_NOT_AVAILABLE|, 544 * |WifiStatusCode.ERROR_UNKNOWN| 545 * @return fates Vector of |WifiDebugRxPacketFateReport| instances corresponding 546 * to the packet fates. 547 */ 548 getDebugRxPacketFates() 549 generates (WifiStatus status, vec<WifiDebugRxPacketFateReport> fates); 550 }; 551
