wifi/1.0/IWifiChip.hal

   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 IWifiChipEventCallback;
  20 import IWifiIface;
  21 import IWifiApIface;
  22 import IWifiNanIface;
  23 import IWifiP2pIface;
  24 import IWifiStaIface;
  25 import IWifiRttController;
  26
  27 /**
  28  * Interface that represents a chip that must be configured as a single unit.
  29  * The HAL/driver/firmware will be responsible for determining which phy is used
  30  * to perform operations like NAN, RTT, etc.
  31  */
  32 interface IWifiChip {
  33   /**
  34    * Set of interface types with the maximum number of interfaces that can have
  35    * one of the specified type for a given ChipIfaceCombination. See
  36    * ChipIfaceCombination for examples.
  37    */
  38   struct ChipIfaceCombinationLimit {
  39     vec<IfaceType> types; // Each IfaceType may occur at most once
  40     uint32_t maxIfaces;
  41   };
  42
  43   /**
  44    * Set of interfaces that can operate concurrently when in a given mode. See
  45    * ChipMode below.
  46    *
  47    * For example:
  48    *   [{STA} <= 2]
  49    *       At most two STA interfaces are supported
  50    *       [], [STA], [STA+STA]
  51    *
  52    *   [{STA} <= 1, {NAN} <= 1, {AP} <= 1]
  53    *       Any combination of STA, NAN, AP
  54    *       [], [STA], [NAN], [AP], [STA+NAN], [STA+AP], [NAN+AP], [STA+NAN+AP]
  55    *
  56    *   [{STA} <= 1, {NAN,P2P} <= 1]
  57    *       Optionally a STA and either NAN or P2P
  58    *       [], [STA], [STA+NAN], [STA+P2P], [NAN], [P2P]
  59    *       Not included [NAN+P2P], [STA+NAN+P2P]
  60    *
  61    *   [{STA} <= 1, {STA,NAN} <= 1]
  62    *       Optionally a STA and either a second STA or a NAN
  63    *       [], [STA], [STA+NAN], [STA+STA], [NAN]
  64    *       Not included [STA+STA+NAN]
  65    */
  66   struct ChipIfaceCombination {
  67     vec<ChipIfaceCombinationLimit> limits;
  68   };
  69
  70   /**
  71    * A mode that the chip can be put in. A mode defines a set of constraints on
  72    * the interfaces that can exist while in that mode. Modes define a unit of
  73    * configuration where all interfaces must be torn down to switch to a
  74    * different mode. Some HALs may only have a single mode, but an example where
  75    * multiple modes would be required is if a chip has different firmwares with
  76    * different capabilities.
  77    *
  78    * When in a mode, it must be possible to perform any combination of creating
  79    * and removing interfaces as long as at least one of the
  80    * ChipIfaceCombinations is satisfied. This means that if a chip has two
  81    * available combinations, [{STA} <= 1] and [{AP} <= 1] then it is expected
  82    * that exactly one STA interface or one AP interface can be created, but it
  83    * is not expected that both a STA and AP interface could be created. If it
  84    * was then there would be a single available combination
  85    * [{STA} <=1, {AP} <= 1].
  86    *
  87    * When switching between two available combinations it is expected that
  88    * interfaces only supported by the initial combination will be removed until
  89    * the target combination is also satisfied. At that point new interfaces
  90    * satisfying only the target combination can be added (meaning the initial
  91    * combination limits will no longer satisfied). The addition of these new
  92    * interfaces should not impact the existence of interfaces that satisfy both
  93    * combinations.
  94    *
  95    * For example, a chip with available combinations:
  96    *     [{STA} <= 2, {NAN} <=1] and [{STA} <=1, {NAN} <= 1, {AP} <= 1}]
  97    * If the chip currently has 3 interfaces STA, STA and NAN and wants to add an
  98    * AP interface in place of one of the STAs then first one of the STA
  99    * interfaces must be removed and then the AP interface can be created after
 100    * the STA had been torn down. During this process the remaining STA and NAN
 101    * interfaces should not be removed/recreated.
 102    *
 103    * If a chip does not support this kind of reconfiguration in this mode then
 104    * the combinations should be separated into two separate modes. Before
 105    * switching modes all interfaces will be torn down, the mode switch will be
 106    * enacted and when it completes the new interfaces will be brought up.
 107    */
 108   struct ChipMode {
 109     /**
 110      * Id that can be used to put the chip in this mode.
 111      */
 112     ChipModeId id;
 113
 114     /**
 115      * A list of the possible interface combinations that the chip can have
 116      * while in this mode.
 117      */
 118     vec<ChipIfaceCombination> availableCombinations;
 119   };
 120
 121   /**
 122    * Get the id assigned to this chip.
 123    *
 124    * @return id Assigned chip Id.
 125    */
 126   getId() generates (ChipId id);
 127
 128   /**
 129    * Requests notifications of significant events on this chip. Multiple calls
 130    * to this will register multiple callbacks each of which will receive all
 131    * events.
 132    *
 133    * @param callback An instance of the |IWifiChipEventCallback| HIDL interface
 134    *        object.
 135    */
 136   oneway registerEventCallback(IWifiChipEventCallback callback);
 137
 138   /**
 139    * Get the set of operation modes that the chip supports.
 140    *
 141    * @return modes List of modes supported by the device.
 142    */
 143   getAvailableModes() generates (vec<ChipMode> modes);
 144
 145   /**
 146    * Reconfigure the Chip.
 147    * Must trigger |IWifiChipEventCallback.onChipReconfigured| on sucess,
 148    * or |IWifiChipEventCallback.onChipReconfigureFailure| on failure.
 149    *
 150    * @param modeId The mode that the chip should switch to, corresponding to the
 151    *        id property of the target ChipMode.
 152    */
 153   oneway configureChip(ChipModeId modeId);
 154
 155   /**
 156    * Get the current mode that the chip is in.
 157    *
 158    * @return modeId The mode that the chip is currently configured to,
 159    *         corresponding to the id property of the target ChipMode.
 160    */
 161   getMode() generates (ChipModeId modeId);
 162
 163   /**
 164    * Request information about the chip.
 165    * Must trigger |IWifiChipEventCallback.onChipDebugInfoAvailable| on sucess,
 166    * or |IWifiChipEventCallback.onChipDebugInfoFailure| on failure.
 167    */
 168   oneway requestChipDebugInfo();
 169
 170   /**
 171    * Request vendor debug info from the driver.
 172    * Must trigger |IWifiChipEventCallback.onDriverDebugDumpAvailable| on success,
 173    * or |IWifiChipEventCallback.onDriverDebugDumpFailure| on failure.
 174    */
 175   oneway requestDriverDebugDump();
 176
 177   /**
 178    * Request vendor debug info from the firmware.
 179    * Must trigger |IWifiChipEventCallback.onFirmwareDebugDumpAvailable| on
 180    * success, or |IWifiChipEventCallback.onFirmwareDebugDumpFailure| on failure.
 181    */
 182   oneway requestFirmwareDebugDump();
 183
 184   /**
 185    * Create an AP iface on the chip.
 186    *
 187    * Depending on the mode the chip is configured in, the interface creation
 188    * may fail if we've already reached the maximum allowed
 189    * (specified in |ChipIfaceCombination|) number of ifaces of the AP type.
 190    *
 191    * @return iface HIDL interface object representing the iface if
 192    *         successful, null otherwise.
 193    */
 194   createApIface() generates (IWifiApIface iface);
 195
 196   /**
 197    * List all the AP iface names configured on the chip.
 198    * The corresponding |IWifiApIface| object for any iface are
 199    * retrieved using |getApIface| method.
 200    *
 201    * @return ifnames List of all AP iface names on the chip.
 202    */
 203   getApIfaceNames() generates (vec<string> ifnames);
 204
 205   /**
 206    * Gets a HIDL interface object for the AP Iface corresponding
 207    * to the provided ifname.
 208    *
 209    * @param ifname Name of the iface.
 210    * @return iface HIDL interface object representing the iface if
 211    *         it exists, null otherwise.
 212    */
 213   getApIface(string ifname) generates (IWifiApIface iface);
 214
 215   /**
 216    * Create a NAN iface on the chip.
 217    *
 218    * Depending on the mode the chip is configured in, the interface creation
 219    * may fail if we've already reached the maximum allowed
 220    * (specified in |ChipIfaceCombination|) number of ifaces of the NAN type.
 221    *
 222    * @return iface HIDL interface object representing the iface if
 223    *         successful, null otherwise.
 224    */
 225   createNanIface() generates (IWifiNanIface iface);
 226
 227   /**
 228    * List all the NAN iface names configured on the chip.
 229    * The corresponding |IWifiNanIface| object for any iface are
 230    * retrieved using |getNanIface| method.
 231    *
 232    * @return ifnames List of all NAN iface names on the chip.
 233    */
 234   getNanIfaceNames() generates (vec<string> ifnames);
 235
 236   /**
 237    * Gets a HIDL interface object for the NAN Iface corresponding
 238    * to the provided ifname.
 239    *
 240    * @param ifname Name of the iface.
 241    * @return iface HIDL interface object representing the iface if
 242    *         it exists, null otherwise.
 243    */
 244   getNanIface(string ifname) generates (IWifiNanIface iface);
 245
 246   /**
 247    * Create a P2P iface on the chip.
 248    *
 249    * Depending on the mode the chip is configured in, the interface creation
 250    * may fail if we've already reached the maximum allowed
 251    * (specified in |ChipIfaceCombination|) number of ifaces of the P2P type.
 252    *
 253    * @return iface HIDL interface object representing the iface if
 254    *         successful, null otherwise.
 255    */
 256   createP2pIface() generates (IWifiP2pIface iface);
 257
 258   /**
 259    * List all the P2P iface names configured on the chip.
 260    * The corresponding |IWifiP2pIface| object for any iface are
 261    * retrieved using |getP2pIface| method.
 262    *
 263    * @return ifnames List of all P2P iface names on the chip.
 264    */
 265   getP2pIfaceNames() generates (vec<string> ifnames);
 266
 267   /**
 268    * Gets a HIDL interface object for the P2P Iface corresponding
 269    * to the provided ifname.
 270    *
 271    * @param ifname Name of the iface.
 272    * @return iface HIDL interface object representing the iface if
 273    *         it exists, null otherwise.
 274    */
 275   getP2pIface(string ifname) generates (IWifiP2pIface iface);
 276
 277   /**
 278    * Create an STA iface on the chip.
 279    *
 280    * Depending on the mode the chip is configured in, the interface creation
 281    * may fail if we've already reached the maximum allowed
 282    * (specified in |ChipIfaceCombination|) number of ifaces of the STA type.
 283    *
 284    * @return iface HIDL interface object representing the iface if
 285    *         successful, null otherwise.
 286    */
 287   createStaIface() generates (IWifiStaIface iface);
 288
 289   /**
 290    * List all the STA iface names configured on the chip.
 291    * The corresponding |IWifiStaIface| object for any iface are
 292    * retrieved using |getStaIface| method.
 293    *
 294    * @return ifnames List of all STA iface names on the chip.
 295    */
 296   getStaIfaceNames() generates (vec<string> ifnames);
 297
 298   /**
 299    * Gets a HIDL interface object for the STA Iface corresponding
 300    * to the provided ifname.
 301    *
 302    * @param ifname Name of the iface.
 303    * @return iface HIDL interface object representing the iface if
 304    *         it exists, null otherwise.
 305    */
 306   getStaIface(string ifname) generates (IWifiStaIface iface);
 307
 308   /**
 309    * Create a RTTController instance.
 310    *
 311    * RTT controller can be either:
 312    * a) Bound to a specific iface by passing in the corresponding |IWifiIface|
 313    * object in |iface| param, OR
 314    * b) Let the implementation decide the iface to use for RTT operations by
 315    * passing null in |iface| param.
 316    *
 317    * @param boundIface HIDL interface object representing the iface if
 318    *        the responder must be bound to a specific iface, null otherwise.
 319    */
 320   createRttController(IWifiIface boundIface) generates (IWifiRttController rtt);
 321 };