sdk/banjo/fuchsia.hardware.wlan.mac/mac.fidl

// Copyright 2021 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.wlan.mac;

using ddk.hw.wlan.wlaninfo;
using fuchsia.hardware.wlan.info;
using fuchsia.wlan.common;
using fuchsia.wlan.internal;
using fuchsia.wlan.ieee80211 as ieee80211;
using zx;

type WlanmacInfo = struct {
    /// Station address.
    sta_addr ieee80211.MacAddr;

    /// MAC role
    mac_role ddk.hw.wlan.wlaninfo.WlanInfoMacRole;

    /// Bitmask indicating WlanInfoPhyType values supported by the hardware.
    supported_phys ddk.hw.wlan.wlaninfo.WlanInfoPhyType;

    /// Bitmask indicating enabled WlanInfoDriverFeature values.
    driver_features ddk.hw.wlan.wlaninfo.WlanInfoDriverFeature;

    /// Bitmask indicating enabled WlanInfoHardwareCapability values.
    caps ddk.hw.wlan.wlaninfo.WlanInfoHardwareCapability;

    /// Supported bands.
    bands array<ddk.hw.wlan.wlaninfo.WlanInfoBandInfo, ddk.hw.wlan.wlaninfo.WLAN_INFO_MAX_BANDS>;
    bands_count uint32;
};

type WlanRxInfoFlags = strict enum : uint32 {
    /// The FCS for the received frame was invalid.
    FCS_INVALID = 0x1;
    /// Padding was added after the MAC header to align the frame body to 4 bytes.
    FRAME_BODY_PADDING_4 = 0x2;
    // Bits 2-31 reserved
};

const WLAN_RSSI_DBM_MIN int8 = -97;
const WLAN_RSSI_DBM_MAX int8 = -10;
const WLAN_RSSI_DBM_INVALID int8 = 0;

const WLAN_SNR_DBH_MIN int16 = 1;
const WLAN_SNR_DBH_MAX int16 = 120; // 60 * 2
const WLAN_SNR_DBH_INVALID int16 = 0;

type WlanRxInfo = struct {
    /// Receive flags. These represent boolean flags as opposed to enums or value-based info which
    /// are represented below. Values should be taken from the WLAN_RX_INFO_FLAGS_* enum.
    rx_flags uint32;

    /// Bitmask indicating which of the following fields are valid in this struct. Reserved flags
    /// must be zero.
    valid_fields uint32;
    /// The PHY format of the device at the time of the operation.
    phy uint16;
    /// The data rate of the device, measured in units of 0.5 Mb/s.
    data_rate uint32;
    /// The channel of the device at the time of the operation. This field must be included.
    channel fuchsia.wlan.common.WlanChannel;
    /// The modulation and coding scheme index of the device at the time of the operation. Depends
    /// on the PHY format and channel width.
    mcs uint8;

    /// Received Signal Strength Indicator.
    rssi_dbm int8;
    /// Signal-to-Noise Ratio, in 0.5 dB.
    snr_dbh int16;
};

type WlanTxInfoFlags = strict enum : uint8 {
    PROTECTED = 0x1;
    /// For rate control: indicate an important data frame, such as EAPOL, which should be sent
    /// _reliably_ rather than fast, and is exempt from rate probing
    FAVOR_RELIABILITY = 0x2;
    /// Indicate that this packet should be sent out with QoS header when possible (11n+).
    // TODO(fxbug.dev/29622): remove this when MLME supports QoS tag.
    QOS = 0x4;
};

type WlanTxInfoValid = strict enum : uint8 {
    DATA_RATE = 0x1;
    TX_VECTOR_IDX = 0x2;
    PHY = 0x4;
    //CHAN_WIDTH = 0x4;
    MCS = 0x8;
    // Bits 5-31 reserved
};

const WLAN_TX_INFO_VALID_CHAN_WIDTH uint8 = 0x4;

type WlanTxInfo = struct {
    /// Transmit flags. These represent boolean options as opposed to enums or other value-based
    /// info which are represented below. Values should be taken from the WLAN_TX_INFO_FLAGS_* enum.
    tx_flags uint32;

    /// Bitmask indicating which of the following fields are valid in this struct. Reserved flags
    /// must be zero. Values for fields not indicated by a flag may be chosen at the discretion of
    /// the wlanmac driver.
    valid_fields uint32;
    // Will be sent back in wlan_tx_status_t if Minstrel is enabled for the device, indicated by
    // WLAN_TX_INFO_VALID_TX_VECTOR_IDX.
    tx_vector_idx uint16;
    // The PHY format to be used to transmit this packet.
    phy uint16;
    // The channel width to be used to transmit this packet.
    channel_bandwidth fuchsia.wlan.common.ChannelBandwidth;
    /// The modulation and coding scheme index for this packet. Depends on the PHY format and
    /// channel width.
    mcs uint8;
};

const WLAN_TX_VECTOR_IDX_INVALID uint16 = 0;
const WLAN_TX_STATUS_MAX_ENTRY uint32 = 8;

type WlanTxStatusEntry = struct {
    tx_vector_idx uint16;
    /// Number of total attempts with this specific tx vector, including successful attempts.
    /// DDK assumes the number of attempts per packet will not exceed 255. (usually <= 8)
    attempts uint8;
};

type WlanTxStatus = struct {
    /// up to 8 different tx_vector for one PPDU frame.
    /// WLAN_TX_VECTOR_IDX_INVALID indicates no more entries.
    tx_status_entry array<WlanTxStatusEntry, WLAN_TX_STATUS_MAX_ENTRY>;
    /// Destination mac address, or addr1 in packet header.
    peer_addr ieee80211.MacAddr;
    /// Outcome of packet transmission. True iff ACK was received from peer.
    success bool;
};

type WlanProtection = strict enum : uint8 {
    NONE = 0;
    RX = 1;
    TX = 2;
    RX_TX = 3;
};

type WlanKeyConfig = struct {
    /// The BSSID for which this key is relevant.
    bssid uint8;
    /// Which path to protect: None, TX, RX, or TX and RX.
    protection WlanProtection;
    /// IEEE Cipher suite selector.
    /// See IEEE Std 802.11-2016, 9.4.2.25.2, Table 9-131
    cipher_oui array<uint8, 3>;
    cipher_type uint8;
    /// Whether this key is a pairwise, group or peer key.
    key_type fuchsia.hardware.wlan.info.WlanKeyType;
    /// The peer MAC address for pairwise and peer keys.
    /// For group keys this value is always the broadcast address.
    peer_addr ieee80211.MacAddr;
    /// Index for rotating keys, e.g. group keys.
    /// This value is always 0 for key types which aren't rotating, e.g. pairwise keys.
    key_idx uint8;
    // Length of the supplied key.
    key_len uint8;
    // They key's actual bytes.
    key array<uint8, 32>;
    /// Receive Sequence Counter for group keys only.
    /// In all other cases the RSC will be 0.
    rsc uint64;
};

type WlanRxPacket = struct {
    @buffer
    mac_frame vector<uint8>:MAX;
    info WlanRxInfo;
};

type WlanTxPacket = struct {
    @buffer
    mac_frame vector<uint8>:MAX;
    /// Additional data needed to transmit the packet.
    info WlanTxInfo;
};

type WlanIndication = strict enum : uint8 {
    PRE_TBTT = 1;
    BCN_TX_COMPLETE = 2;
    HW_SCAN_COMPLETE = 3;
    HW_SCAN_ABORTED = 4;
};

@derive_debug
type WlanHwScanType = strict enum : uint8 {
    ACTIVE = 1;
    PASSIVE = 2;
};

type WlanHwScanConfig = struct {
    scan_type WlanHwScanType;
    /// Number of channels in the |channels| array. Must be at least 1
    num_channels uint8;
    /// Channel numbers to scan
    channels array<uint8, ddk.hw.wlan.wlaninfo.WLAN_INFO_CHANNEL_LIST_MAX_CHANNELS>;
    /// SSID for directed probe requests
    ssid ieee80211.CSsid;
};

type WlanHwScan = strict enum : uint8 {
    SUCCESS = 0;
    ABORTED = 1;
};

type WlanHwScanResult = struct {
    code WlanHwScan;
};

/// Includes the information about beacon template.
type WlanBcnConfig = struct {
    /// Points to the beacon template. Since this is just the template, some packet content can
    /// contain only minimum valid info. They will be changed later by hardware/firmware or software.
    /// Note that the driver must copy the packet content into its own memory and cannot rely on
    /// the pointers in the struct.
    packet_template WlanTxPacket;

    /// TIM offset (in bytes) to the start of |bcn_tmpl|. This points to the first byte of TIM IE,
    /// which is the tag ID.
    tim_ele_offset uint64;

    /// in TU
    beacon_interval uint16;
};

@transport("Banjo")
@banjo_layout("ddk-interface")
protocol WlanmacIfc {
    /// Report the status of the wlanmac device.
    Status(struct {
        status uint32;
    }) -> ();

    /// Submit received data to the next driver.
    Recv(struct {
        packet WlanRxPacket;
    });

    /// complete_tx() is called to return ownership of a packet to the wlan driver.
    /// Return status indicates queue state:
    ///   ZX_OK: Packet has been enqueued.
    ///   Other: Packet could not be enqueued.
    ///
    /// Upon a return of ZX_OK, the packet has been enqueued, but no information is returned as to
    /// the completion state of the transmission itself.
    CompleteTx(struct {
        packet WlanTxPacket;
        status zx.status;
    }) -> ();

    /// Reports an indication of a status, state or action to the wlan driver.
    Indication(struct {
        ind uint32;
    });

    /// Reports the status of an attempted transmission.
    /// |tx_status|: contains status info of one transmitted packet to one peer at one specific rate.
    ReportTxStatus(struct {
        tx_status WlanTxStatus;
    });

    /// Reports completion of a hardware scan
    HwScanComplete(struct {
        result WlanHwScanResult;
    });
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol Wlanmac {
    /// Obtain information about the device and supported features
    /// Safe to call at any time.
    Query(struct {
        options uint32;
    }) -> (struct {
        status zx.status;
        info WlanmacInfo;
    });

    /// Start wlanmac running with ifc_virt
    /// Callbacks on ifc may be invoked from now until stop() is called
    Start(resource struct {
        ifc client_end:WlanmacIfc;
    }) -> (resource struct {
        status zx.status;
        sme_channel zx.handle:CHANNEL;
    });

    /// Shut down a running wlanmac
    /// Safe to call if the wlanmac is already stopped.
    Stop() -> ();

    /// Queue the data for transmit. Return status indicates queue state:
    ///   ZX_ERR_SHOULD_WAIT: Packet is being enqueued.
    ///   ZX_OK: Packet has been enqueued.
    ///   Other: Packet could not be enqueued.
    ///
    /// In the SHOULD_WAIT case the driver takes ownership of the wlan_tx_packet_t and must call
    /// complete_tx() to return it once the enqueue is complete. complete_tx() may be used to return
    /// the packet before transmission itself completes, and MUST NOT be called from within the
    /// queue_tx() implementation.
    ///
    /// queue_tx() may be called at any time after start() is called including from multiple threads
    /// simultaneously.
    QueueTx(struct {
        options uint32;
        packet WlanTxPacket;
    }) -> (struct {
        status zx.status;
    });

    // Set the radio channel
    SetChannel(struct {
        options uint32;
        chan fuchsia.wlan.common.WlanChannel;
    }) -> (struct {
        status zx.status;
    });

    // Configures a BSS which the STA is either joining or managing.
    ConfigureBss(struct {
        options uint32;
        config fuchsia.wlan.internal.BssConfig;
    }) -> (struct {
        st zx.status;
    });

    // Enables or disables hardware Beaconing.
    // * |bcn_cfg|: Pass `nullptr` to disable hardware Beacons. Used by hardware beacon offload.
    EnableBeaconing(struct {
        options uint32;
        bcn_cfg WlanBcnConfig;
    }) -> (struct {
        st zx.status;
    });

    /// Configures a Beacon frame in hardware to announce the BSS' existence.
    /// * |packet|: Pass `nullptr` to disable hardware Beacons. Used by software generated beacon.
    /// TODO(fxbug.dev/29298): Rename to update_beacon.
    ConfigureBeacon(struct {
        options uint32;
        packet WlanTxPacket;
    }) -> (struct {
        st zx.status;
    });

    /// Specify a key for frame protection.
    SetKey(struct {
        options uint32;
        key_config WlanKeyConfig;
    }) -> (struct {
        st zx.status;
    });

    /// Notifies MAC and PHY parameters negotiated through a successful association
    ConfigureAssoc(struct {
        options uint32;
        assoc_ctx fuchsia.hardware.wlan.info.WlanAssocCtx;
    }) -> (struct {
        st zx.status;
    });

    /// Notifies MAC and PHY that the peer has been de-associated.
    ClearAssoc(struct {
        options uint32;
        peer_addr ieee80211.MacAddr;
    }) -> (struct {
        st zx.status;
    });

    /// Initiate a hardware scan
    ///
    /// Once the scan starts, scan results will be delivered as beacon and probe response frames
    /// via the regular rx path.
    ///
    /// Unless an error is returned immediately, the driver will eventually
    /// call wlanmac_ifc->hw_scan_complete()
    StartHwScan(struct {
        scan_config WlanHwScanConfig;
    }) -> (struct {
        st zx.status;
    });

    /// Notifies change of WMM parameters for specified AC
    UpdateWmmParams(struct {
        ac fuchsia.hardware.wlan.info.WlanAc;
        params fuchsia.hardware.wlan.info.WlanWmmParams;
    }) -> (struct {
        st zx.status;
    });
};