// Copyright 2019 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.

library fuchsia.hardware.wlanphyimpl;

using ddk.hw.wlan.wlaninfo;
using fuchsia.hardware.ethernet.mac;
using zx;

/// Parameters to create an interface.
struct WlanphyImplCreateIfaceReq {
    /// The station role for this interface. A device may support multiple roles,
    /// but an interface is instantiated with a single role.
    ddk.hw.wlan.wlaninfo.WlanInfoMacRole role;

    /// A handle to the direct SME channel, if supported by the driver.
    handle<channel> sme_channel;

    /// Whether this iface creation request come with an initial MAC address.
    bool has_init_mac_addr;

    /// The initial mac address set from configuration layer.
    array<uint8>:MAC_ARRAY_LENGTH init_mac_addr;
};

/// Info about this WLAN PHY.
struct WlanphyImplInfo {
    /// Bitmask for MAC roles supported. For an interface, this will be a single
    /// value.
    ddk.hw.wlan.wlaninfo.WlanInfoMacRole supported_mac_roles;
};

const uint8 WLANPHY_ALPHA2_LEN = 2;

[Packed]
union WlanphyCountry {
    /// 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.
    array<uint8>:WLANPHY_ALPHA2_LEN alpha2;
    uint16 val;
};

[Layout = "ddk-protocol"]
protocol WlanphyImpl {
    /// Get information about the capabilities of the physical device.
    Query() -> (zx.status s, WlanphyImplInfo info);

    /// 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
    CreateIface(WlanphyImplCreateIfaceReq req) -> (zx.status s, uint16 iface_id);

    /// Destroy the interface with the matching id.
    DestroyIface(uint16 iface_id) -> (zx.status s);

    /// Set country with a WlanphyCountry
    SetCountry(WlanphyCountry country) -> (zx.status s);

    /// Set device to a world-safe country
    ClearCountry() -> (zx.status s);

    /// Read currently configured country. Implementations are advised to read the
    /// country directly from the firmware, where possible.
    GetCountry() -> (zx.status s, WlanphyCountry country);
};