xref: /hardware/interfaces/wifi/1.0/IWifiChip.hal

/*
 * Copyright 2016 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.
 */

package android.hardware.wifi@1.0;

import IWifiChipEventCallback;

/**
 * Interface that represents a chip that must be configured as a single unit.
 * The HAL/driver/firmware will be responsible for determining which phy is used
 * to perform operations like NAN, RTT, etc.
 */
interface IWifiChip {
  enum IfaceType : uint32_t {
    STA, AP, P2P,
    /**
     * NAN control interface. Datapath support may be queried and created
     * through this interface.
     */
    NAN,
  };

  /**
   * Set of interface types with the maximum number of interfaces that can have
   * one of the specified type for a given ChipIfaceCombination. See
   * ChipIfaceCombination for examples.
   */
  struct ChipIfaceCombinationLimit {
    vec<IfaceType> types; // Each IfaceType may occur at most once
    uint32_t maxIfaces;
  };

  /**
   * Set of interfaces that can operate concurrently when in a given mode. See
   * ChipMode below.
   *
   * For example:
   *   [{STA} <= 2]
   *       At most two STA interfaces are supported
   *       [], [STA], [STA+STA]
   *
   *   [{STA} <= 1, {NAN} <= 1, {AP} <= 1]
   *       Any combination of STA, NAN, AP
   *       [], [STA], [NAN], [AP], [STA+NAN], [STA+AP], [NAN+AP], [STA+NAN+AP]
   *
   *   [{STA} <= 1, {NAN,P2P} <= 1]
   *       Optionally a STA and either NAN or P2P
   *       [], [STA], [STA+NAN], [STA+P2P], [NAN], [P2P]
   *       Not included [NAN+P2P], [STA+NAN+P2P]
   *
   *   [{STA} <= 1, {STA,NAN} <= 1]
   *       Optionally a STA and either a second STA or a NAN
   *       [], [STA], [STA+NAN], [STA+STA], [NAN]
   *       Not included [STA+STA+NAN]
   */
  struct ChipIfaceCombination {
    vec<ChipIfaceCombinationLimit> limits;
  };

  /**
   * A mode that the chip can be put in. A mode defines a set of constraints on
   * the interfaces that can exist while in that mode. Modes define a unit of
   * configuration where all interfaces must be torn down to switch to a
   * different mode. Some HALs may only have a single mode, but an example where
   * multiple modes would be required is if a chip has different firmwares with
   * different capabilities.
   *
   * When in a mode, it must be possible to perform any combination of creating
   * and removing interfaces as long as at least one of the
   * ChipIfaceCombinations is satisfied. This means that if a chip has two
   * available combinations, [{STA} <= 1] and [{AP} <= 1] then it is expected
   * that exactly one STA interface or one AP interface can be created, but it
   * is not expected that both a STA and AP interface could be created. If it
   * was then there would be a single available combination
   * [{STA} <=1, {AP} <= 1].
   *
   * When switching between two available combinations it is expected that
   * interfaces only supported by the initial combination will be removed until
   * the target combination is also satisfied. At that point new interfaces
   * satisfying only the target combination can be added (meaning the initial
   * combination limits will no longer satisfied). The addition of these new
   * interfaces should not impact the existence of interfaces that satisfy both
   * combinations.
   *
   * For example, a chip with available combinations:
   *     [{STA} <= 2, {NAN} <=1] and [{STA} <=1, {NAN} <= 1, {AP} <= 1}]
   * If the chip currently has 3 interfaces STA, STA and NAN and wants to add an
   * AP interface in place of one of the STAs then first one of the STA
   * interfaces must be removed and then the AP interface can be created after
   * the STA had been torn down. During this process the remaining STA and NAN
   * interfaces should not be removed/recreated.
   *
   * If a chip does not support this kind of reconfiguration in this mode then
   * the combinations should be separated into two separate modes. Before
   * switching modes all interfaces will be torn down, the mode switch will be
   * enacted and when it completes the new interfaces will be brought up.
   */
  struct ChipMode {
    /**
     * Id that can be used to put the chip in this mode.
     */
    ChipModeId id;

    /**
     * A list of the possible interface combinations that the chip can have
     * while in this mode.
     */
    vec<ChipIfaceCombination> availableCombinations;
  };

  /**
   * Requests notifications of significant events on this chip. Multiple calls
   * to this will register multiple callbacks each of which will receive all
   * events.
   *
   * @param callback An instance of the |IWifiChipEventCallback| HIDL interface
   *        object.
   */
  oneway registerEventCallback(IWifiChipEventCallback callback);

  /**
   * Get the set of operation modes that the chip supports.
   *
   * @return modes List of modes supported by the device.
   */
  getAvailableModes() generates (vec<ChipMode> modes);

  /**
   * Reconfigure the Chip.
   * Must trigger |IWifiChipEventCallback.onChipReconfigured| on sucess,
   * or |IWifiChipEventCallback.onChipReconfigureFailure| on failure.
   *
   * @param modeId The mode that the chip should switch to, corresponding to the
   *        id property of the target ChipMode.
   */
  oneway configureChip(ChipModeId modeId);

  /**
   * Get the current mode that the chip is in.
   *
   * @return modeId The mode that the chip is currently configured to,
   *         corresponding to the id property of the target ChipMode.
   */
  getMode() generates (ChipModeId modeId);

  /**
   * Request information about the chip.
   * Must trigger |IWifiChipEventCallback.onChipDebugInfoAvailable| on sucess,
   * or |IWifiChipEventCallback.onChipDebugInfoFailure| on failure.
   */
  oneway requestChipDebugInfo();

  /**
   * Request vendor debug info from the driver.
   * Must trigger |IWifiChipEventCallback.onDriverDebugDumpAvailable| on success,
   * or |IWifiChipEventCallback.onDriverDebugDumpFailure| on failure.
   */
  oneway requestDriverDebugDump();

  /**
   * Request vendor debug info from the firmware.
   * Must trigger |IWifiChipEventCallback.onFirmwareDebugDumpAvailable| on
   * success, or |IWifiChipEventCallback.onFirmwareDebugDumpFailure| on failure.
   */
  oneway requestFirmwareDebugDump();
};