// 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.softmac;

using fuchsia.hardware.wlan.associnfo;
using fuchsia.wlan.common;
using fuchsia.wlan.internal;
using fuchsia.wlan.ieee80211 as ieee80211;
using zx;

type WlanSoftmacBandCapability = struct {
    /// The values of this struct apply to the band indicated in this field.
    band fuchsia.wlan.common.WlanBand;

    /// Basic rates supported in units of 500 kbit/s (as defined in
    /// IEEE Std 802.11-2016, 9.4.2.3), e.g., 0x02 represents 1 Mbps.
    /// The value returned by this type indicates all the non-HT rates
    /// the device supports transmitting and receiving.
    basic_rate_count uint8;
    basic_rate_list array<uint8, fuchsia.wlan.internal.MAX_SUPPORTED_BASIC_RATES>;

    /// If the device supports the HT PHY mode in this band, then ht_supported is
    /// set to true, and the value in ht_caps indicates the capabilities. Otherwise,
    /// ht_supported is set to false.
    ht_supported bool;
    ht_caps ieee80211.HtCapabilities;

    /// If the device supports the VHT PHY mode in this band, then vht_supported is
    /// set to true, and the value in vht_caps indicates the capabilities. Otherwise,
    /// vht_supported is set to false.
    vht_supported bool;
    vht_caps ieee80211.VhtCapabilities;

    /// A list of operating channels considered valid by hardware, in the context of
    /// regulatory information known to the device driver, at the time of its
    /// construction during iface creation. In this context, an operating channel
    /// means a channel which APs may transmit Beacon frames on in the current
    /// regulatory domain.
    ///
    /// This list should be used to determine efficacy of subsequent requests to
    /// scan a subset of channels using the iface, or to determine which operating
    /// channel to use when starting an AP.
    operating_channel_count uint16;
    operating_channel_list array<uint8, ieee80211.MAX_UNIQUE_CHANNEL_NUMBERS>;
};

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

    /// MAC role
    mac_role fuchsia.wlan.common.WlanMacRole;

    /// Bitmask indicating WlanInfoPhyType values supported by the hardware.
    supported_phys_list
            array<fuchsia.wlan.common.WlanPhyType, fuchsia.wlan.common.MAX_SUPPORTED_PHY_TYPES>;
    supported_phys_count uint8;

    /// Bitmask indicating enabled WlanInfoHardwareCapability values.
    hardware_capability fuchsia.wlan.common.WlanSoftmacHardwareCapability;

    /// Supported bands.
    band_cap_list array<WlanSoftmacBandCapability, fuchsia.wlan.common.MAX_BANDS>;
    band_cap_count uint8;
};

/// These flags are used as a bitfield.
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;
};

type WlanRxInfo = struct {
    /// Boolean receive flags. Enums and value-based info are represented below.
    rx_flags WlanRxInfoFlags;

    /// 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 fuchsia.wlan.common.WlanPhyType;
    /// 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;
    CHANNEL_BANDWIDTH = 0x8;
    MCS = 0x10;
};

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 WlanTxInfoFlags;

    /// 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 softmac 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 fuchsia.wlan.common.WlanPhyType;
    // 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;
};

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.associnfo.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;
};

/// 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 WlanSoftmacIfc {
    /// Report the status of the softmac 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 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 fuchsia.wlan.common.WlanTxStatus;
    });

    /// Reports completion of a scan associated with the unique `scan_id`. The status
    /// `ZX_ERR_OUT_OF_RANGE` implies the scan request included a prohibited channel.
    /// The channel may be prohibited because of the current country setting.
    ScanComplete(struct {
        status zx.status;
        scan_id uint64;
    });
};

/// Argument struct to be passed as the single argument to WlanSoftmac.StartPassiveScan.
type WlanSoftmacPassiveScanArgs = struct {
    /// List of channels to scan on. An empty list of channels will cause a
    /// scan request to immediately return ZX_ERR_INVALID_ARGS.
    ///
    /// Invalid channel numbers will be silently ignored. The validity of a channel
    /// number depends on the current regulatory region, and a SoftMAC driver cannot
    /// always determine the region setting. This is especially the case when
    /// firmware changes the region setting dynamically.
    channels vector<uint8>:ieee80211.MAX_UNIQUE_CHANNEL_NUMBERS;

    /// Minimum duration to spend on each channel during the scan.
    min_channel_time zx.duration;

    /// Maximum duration to spend on each channel during the scan.
    max_channel_time zx.duration;

    /// Minimum duration to spend on the home channel(s) between the dwell time on each channel
    /// where a home channel corresponds to channels the device should otherwise be present
    /// on while not scanning.
    min_home_time zx.duration;
};

/// Argument struct to be passed as the single argument to WlanSoftmac.StartActiveScan
type WlanSoftmacActiveScanArgs = struct {
    /// List of channels to scan on. An empty list of channels will cause a
    /// scan request to immediately return ZX_ERR_INVALID_ARGS.
    ///
    /// Invalid channel numbers will be silently ignored. The validity of a channel
    /// number depends on the current regulatory region, and a SoftMAC driver cannot
    /// always determine the region setting. This is especially the case when
    /// firmware changes the region setting dynamically.
    channels vector<uint8>:ieee80211.MAX_UNIQUE_CHANNEL_NUMBERS;

    /// List of SSIDs to scan for. For a list with a single SSID, the SSID will be placed in
    /// the SSID element in the Probe Request frame. For a list with more than one SSID,
    /// all SSIDs will be placed in an SSID List element in the Probe Request frame with the
    /// first SSID in the list in the required SSID element. An empty list is the same as
    /// specifying a list containing only the wildcard SSID.
    ssids vector<ieee80211.CSsid>:ieee80211.SSID_LIST_MAX;

    /// Buffer containing a MAC header (as defined in IEEE Std 802.11-2016, 9.3.3.2) to
    /// include in each Probe Request frame.
    @buffer
    mac_header vector<uint8>:ieee80211.MAX_MGMT_FRAME_MAC_HEADER_BYTE_LEN;

    /// Buffer containing IE bytes to include in each Probe Request frame.
    @buffer
    ies vector<uint8>:ieee80211.MAX_VHT_MPDU_BYTE_LEN_2;

    /// Minimum duration to spend on each channel during the scan.
    min_channel_time zx.duration;

    /// Maximum duration to spend on each channel during the scan.
    max_channel_time zx.duration;

    /// Minimum duration to spend on the home channel(s) between the dwell time on each channel
    /// where a home channel corresponds to channels the device should otherwise be present
    /// on while not scanning.
    min_home_time zx.duration;

    /// Minimum number of Probe Request frames to transmit per channel visit during a scan.
    /// The definition of a channel visit may differ between device drivers, but it is roughly
    /// the interval of time spent on a specific channel during a scan.
    ///
    /// Sending more than one Probe Request frame on a channel may increase the probability that
    /// it is received in a noisy environment.
    min_probes_per_channel uint8;

    /// Maximum number of Probe Request frames to transmit per channel visit during a scan.
    /// The definition of a channel visit may differ between device drivers, but it is roughly
    /// the interval of time spent on a specific channel during a scan. Specifying 0 is invalid
    /// since at least one Probe Request frame must be transmitted for an active scan.
    ///
    /// Limiting the number of Probe Request frames sent on a channel reduces the time spent
    /// transmitting frames, and thus increase the time spent receiving frames, while scanning.
    max_probes_per_channel uint8;
};

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

    QueryDiscoverySupport() -> (struct {
        resp fuchsia.wlan.common.DiscoverySupport;
    });
    QueryMacSublayerSupport() -> (struct {
        resp fuchsia.wlan.common.MacSublayerSupport;
    });
    QuerySecuritySupport() -> (struct {
        resp fuchsia.wlan.common.SecuritySupport;
    });
    QuerySpectrumManagementSupport() -> (struct {
        resp fuchsia.wlan.common.SpectrumManagementSupport;
    });

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

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

    /// Queue a packet for transmission. May return before a packet has actually been transmitted.
    /// The driver may choose to take ownership of the given WlanTxPacket by setting enqueue_pending
    /// to true, in which case the packet must be returned later via CompleteTx.
    ///
    /// Note: CompleteTx may be used to return the WlanTxPacket before transmission completes, but
    /// MUST NOT be called from within the QueueTx implementation.
    QueueTx(struct {
        packet WlanTxPacket;
    }) -> (struct {
        /// status only indicates that the packet was successfully queued, not successfully
        /// transmitted. enqueue_pending should only be true if status is ZX_OK.
        status zx.status;
        enqueue_pending bool;
    });

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

    // Configures a BSS which the STA is either joining or managing.
    ConfigureBss(struct {
        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 {
        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 {
        packet WlanTxPacket;
    }) -> (struct {
        st zx.status;
    });

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

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

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

    /// Start a passive scan in the device driver. Scan results will be delivered as Beacon
    /// frames via WlanSoftmacIfc.Recv(). When complete, WlanSoftmacIfc.ScanComplete() will
    /// be called with the corresponding unique `scan_id`.
    StartPassiveScan(struct {
        args WlanSoftmacPassiveScanArgs;
    }) -> (struct {
        status zx.status;
        scan_id uint64;
    });

    /// Start an active scan in the device driver. Scan results will be delivered as Beacon or
    /// Probe Response frames via WlanSoftmacIfc.Recv(). When complete,
    /// WlanSoftmacIfc.ScanComplete() will be called with the corresponding unique `scan_id`.
    ///
    /// The IEs specified must not result in a Probe Request MMPDU that exceed the limits
    /// defined by IEEE Std 802.11-2016, 9.2.4.7. MMPDU limit constants can be found in
    /// fuchsia.wlan.ieee80211. These limits are very large and will likely not be exceeded
    /// by specifying the most common IEs found in Probe Request frames.
    StartActiveScan(struct {
        args WlanSoftmacActiveScanArgs;
    }) -> (struct {
        status zx.status;
        scan_id uint64;
    });

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