// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

/// Acronyms \
/// Iface:  Interface \
/// Phy:    Physical \
/// Mac:    Medium Access Control \
/// Sta:    Station \
/// Addr:   Address
@available(added=15)
library fuchsia.wlan.phyimpl;

using fuchsia.wlan.common;
using fuchsia.wlan.ieee80211 as ieee80211;
using zx;

const WLANPHY_ALPHA2_LEN uint8 = 2;

/// Specific absorption rate scenarios that can be applied to WLAN PHY devices.
@available(added=HEAD)
type TxPowerScenario = flexible enum {
    DEFAULT = 0;
    VOICE_CALL = 1;
    HEAD_CELL_OFF = 2;
    HEAD_CELL_ON = 3;
    BODY_CELL_OFF = 4;
    BODY_CELL_ON = 5;
    BODY_BT_ACTIVE = 6;
};

type WlanPhyCountry = flexible union {
    /// ISO Alpha-2 takes two octet alphabet characters.
    /// This needs to be expanded if at least one WLAN device driver or firmware
    /// requires more than two octets.
    1: alpha2 array<uint8, WLANPHY_ALPHA2_LEN>;
};

@available(added=HEAD)
type BtCoexistenceMode = flexible enum {
    MODE_AUTO = 1;
    MODE_OFF = 2;
};

@available(added=HEAD)
type WlanPhyImplNotifyError = flexible enum {
    /// An unspecified internal error occurred.
    INTERNAL = 1;
    /// Receiver does not have support for handling the event.
    NOT_SUPPORTED = 2;
    /// Receiver not ready to handle event yet.
    SHOULD_WAIT = 3;
    /// Invalid arguments.
    INVALID_ARGS = 4;
};

@available(added=HEAD)
type CriticalErrorReason = flexible enum : uint8 {
    /// Notifies the receiver (wlanphy client) that the wlan firmware running on the wlan PHY
    /// has crashed.  Upon receiving this event, the client can decide to forward it to
    /// higher layers of the wlan stack, handle it itself (for example by requesting a
    /// reset of the PHY) or ignore it.
    FW_CRASH = 0;
};

/// This protocol is specifically meant for passing events/notifications from the WlanPhyImpl server
/// to its client.
@available(added=HEAD)
@discoverable
open protocol WlanPhyImplNotify {
    /// Indicate to the receiver (wlanphy client) that the wlan PHY has encountered a critical
    /// error specifying a reason code. The client can decide to forward it to higher layers of
    /// the wlan stack, handle it itself or ignore it. The sender can decide to handle the
    /// error if the receiver responds with an error code.
    /// Some possible error codes are:
    /// NOT_SUPPORTED: receiver does not have support for handling the event.
    /// INTERNAL: Error encountered during processing (including error returned by
    /// a higher layer module if it was forwarded).
    flexible OnCriticalError(table {
        1: reason_code CriticalErrorReason;
    }) -> () error WlanPhyImplNotifyError;
};

@discoverable
@transport("Driver")
open protocol WlanPhyImpl {
    /// This method can be used by the WlanPhyImpl client to send the client end of the
    /// WlanPhyImplNotify endpoint for the WlanPhyImpl server to use. If the WlanPhyImpl client
    /// never invokes this method that is an indirect implication that the WlanPhyImplNotify is not
    /// supported. Some possible error codes are:
    /// ZX_ERR_NOT_SUPPORTED: The WlanPhyImpl server does not support the WlanPhyImplNotify protocol.
    @available(added=HEAD)
    flexible Init(resource table {
        /// The WlanPhyImplNotify client end.
        /// Required.
        1: notify_client client_end:WlanPhyImplNotify;
    }) -> () error zx.Status;

    /// MAC roles supported for ifaces on the physical device.
    flexible GetSupportedMacRoles() -> (table {
        1: supported_mac_roles
                vector<fuchsia.wlan.common.WlanMacRole>:fuchsia.wlan.common.MAX_SUPPORTED_MAC_ROLES;
    }) error zx.Status;

    /// Create a new interface with the specified role, returning the interface id. \
    /// Some common error codes are: \
    /// ZX_ERR_NO_RESOURCES: maximum number of interfaces have already been created. \
    /// ZX_ERR_NOT_SUPPORTED: device does not support the specified role.
    flexible CreateIface(resource table {
        /// The station role for this interface. A device may support multiple roles,
        /// but an interface is instantiated with a single role. This field is required.
        1: role fuchsia.wlan.common.WlanMacRole;
        /// A handle to the direct MLME channel, if supported by the driver. This
        /// channel should be used by SME to communicate with MLME via the MLME
        /// protocol. This field is required.
        2: mlme_channel zx.Handle:CHANNEL;
        /// The initial station address set from configuration layer. This field is optional.
        3: init_sta_addr ieee80211.MacAddr;
    }) -> (table {
        /// This field is always present.
        1: iface_id uint16;
    }) error zx.Status;

    /// Destroy the interface with the matching id. \
    /// Some common error codes are: \
    /// ZX_ERR_NOT_FOUND: Specified iface does not exist or has already been removed. \
    /// ZX_ERR_SHOULD_WAIT: Device is busy and cannot be removed, try again later.
    flexible DestroyIface(table {
        /// This field is required.
        1: iface_id uint16;
    }) -> () error zx.Status;

    /// Set country with a WlanPhyCountry. \
    /// Some common error codes are: \
    /// ZX_ERR_NOT_FOUND: Specified country code not supported. PHY state is left unchanged.
    flexible SetCountry(WlanPhyCountry) -> () error zx.Status;

    /// Set device to a world-safe country, i.e. a mode that conforms to all
    /// regulatory constraints globally. \
    /// Generally expected to succeed if the device is in a functional state.
    flexible ClearCountry() -> () error zx.Status;

    /// Read currently configured country. Implementations are advised to read the
    /// country directly from the firmware, where possible. \
    /// Generally expected to succeed if the device is in a functional state.
    flexible GetCountry() -> (WlanPhyCountry) error zx.Status;

    /// Set Power Save mode on device. In most implementations this
    /// likely to be set in Firmware. \
    /// Some common error codes are: \
    /// ZX_ERR_NOT_SUPPORTED: Specified Power Save mode not supported.
    flexible SetPowerSaveMode(table {
        /// This field is required.
        1: ps_mode fuchsia.wlan.common.PowerSaveType;
    }) -> () error zx.Status;

    /// Get current Power Save mode from device. In most implementation this
    /// likely to be retrieved from Firmware.
    flexible GetPowerSaveMode() -> (table {
        /// This field is required.
        1: ps_mode fuchsia.wlan.common.PowerSaveType;
    }) error zx.Status;

    /// Power up/down/reset the wlan chip.
    /// If supported, PowerDown will power down the wlan chip if it is currently powered on.
    /// Any existing interfaces should have already been deleted before making this call or else the
    /// driver will fail the call with error code ZX_ERR_INTERNAL.
    /// Other possible error codes are: \
    /// ZX_ERR_NOT_SUPPORTED: the feature is not supported by the driver.
    /// ZX_ERR_BAD_STATE: the wlan chip is already powered down.
    @available(added=HEAD)
    flexible PowerDown() -> () error zx.Status;

    /// If supported, PowerUp will power up the wlan chip if it is currently powered down.
    /// Possible error codes are: \
    /// ZX_ERR_NOT_SUPPORTED: the feature is not supported by the driver.
    /// ZX_ERR_BAD_STATE: the wlan chip is already powered up.
    @available(added=HEAD)
    flexible PowerUp() -> () error zx.Status;

    /// If supported, Reset functionality implements PowerDown then PowerUp in an attempt to
    /// recover from an error state. For example, if an interface gets into a bad state or if
    /// firmware crashes, the firmware/chip may be unable to perform some actions and Reset
    /// may be able to clear the bad state.
    /// Possible error codes are: \
    /// ZX_ERR_NOT_SUPPORTED: the feature is not supported by the driver.
    @available(added=HEAD)
    flexible Reset() -> () error zx.Status;

    /// Returns the current power state of the wlan chip. After successful initialization
    /// of the wlan driver, the state is set to true (power on) by default. power_on set to
    /// true indicates that the wlan chip is powered on and false indicates the wlan chip
    /// is powered off.
    @available(added=HEAD)
    flexible GetPowerState() -> (table {
        1: power_on bool;
    }) error zx.Status;

    /// Set the Bluetooth coexistence mode.
    /// Possible error codes are: \
    /// ZX_ERR_NOT_SUPPORTED: device does not support the specified BT coexistence mode.
    @available(added=HEAD)
    flexible SetBtCoexistenceMode(table {
        1: mode BtCoexistenceMode;
    }) -> () error zx.Status;

    @available(added=HEAD)
    flexible SetTxPowerScenario(table {
        1: scenario TxPowerScenario;
    }) -> () error zx.Status;

    @available(added=HEAD)
    flexible ResetTxPowerScenario() -> () error zx.Status;

    @available(added=HEAD)
    flexible GetTxPowerScenario() -> (struct {
        scenario TxPowerScenario;
    }) error zx.Status;
};

service Service {
    wlan_phy_impl client_end:WlanPhyImpl;
};