ElixirForge/firmware
1
0
Fork 0
mirror of https://github.com/alexhopeoconnor/firmware.git synced 2026-10-04 03:18:10 +10:00
Code Releases Activity
Files
a1acad6dc44d57eb7d89317293b187c8ac08d7e0
firmware/lib/MorseWlan/include/mmwlan.h
T

2179 lines
83 KiB
C
Raw Blame History

/*
* Copyright 2021-2024 Morse Micro
*
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @defgroup MMWLAN Morse Micro Wireless LAN (mmwlan) API
*
* Wireless LAN control and datapath.
*
* @warning Aside from specific exceptions, the functions in this API must not be called
* concurrently (e.g., from different thread contexts). The exception to this
* is the TX API (@ref mmwlan_tx() and @ref mmwlan_tx_tid()).
*
* @section MMWLAN_THREADS Thread priorities
*
* The following table documents the threads created by the Morse WLAN driver and Upper MAC
* included in morselib.
*
* | Thread | Thread Name | Priority |
* | ----------------- | ----------------------- | ------------------------- |
* | SPI driver | @c spi_irq | @ref MMOSAL_TASK_PRI_HIGH |
* | Morse driver | @c drv | @ref MMOSAL_TASK_PRI_HIGH |
* | WLAN event loop | @c evtloop | @ref MMOSAL_TASK_PRI_HIGH |
* | Morse health check| @c health | @ref MMOSAL_TASK_PRI_LOW |
*
* Note that to get the best performance, the WLAN driver/UMAC threads run at a high priority
* while it is expected that application threads run at a lower priority.
*
* @{
*/
#pragma once
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "mmpkt.h"
#ifdef __cplusplus
extern "C" {
#endif
/** Enumeration of status return codes. */
enum mmwlan_status {
/** The operation was successful. */
MMWLAN_SUCCESS,
/** The operation failed with an unspecified error. */
MMWLAN_ERROR,
/** The operation failed due to an invalid argument. */
MMWLAN_INVALID_ARGUMENT,
/** Functionality is temporarily unavailable. */
MMWLAN_UNAVAILABLE,
/** Unable to proceed because channel list has not been set.
* @see mmwlan_set_channel_list(). */
MMWLAN_CHANNEL_LIST_NOT_SET,
/** Failed due to memory allocation failure. */
MMWLAN_NO_MEM,
/** Failed due to timeout */
MMWLAN_TIMED_OUT,
/** Used to indicate that a call to @ref mmwlan_sta_disable() did not shutdown
* the transceiver. */
MMWLAN_SHUTDOWN_BLOCKED,
/** Attempted to tune to a channel that was not in the regulatory database or not supported. */
MMWLAN_CHANNEL_INVALID,
/** The request could not be completed because the given resource was not found. */
MMWLAN_NOT_FOUND,
/** Indicates that the operation failed because the UMAC was not running (e.g., the
* device was not booted). */
MMWLAN_NOT_RUNNING,
};
/** Maximum allowable length of an SSID. */
#define MMWLAN_SSID_MAXLEN (32)
/** Maximum allowable length of a passphrase when connecting to an AP. */
#define MMWLAN_PASSPHRASE_MAXLEN (100)
/** Maximum allowable Restricted Access Window (RAW) priority for STA. */
#define MMWLAN_RAW_MAX_PRIORITY (7)
/** Length of a WLAN MAC address. */
#define MMWLAN_MAC_ADDR_LEN (6)
/** Maximum allowable number of EC Groups. */
#define MMWLAN_MAX_EC_GROUPS (4)
/** Size of an 802.11 OUI element in octets. */
#define MMWLAN_OUI_SIZE (3)
/** Default Background scan short interval in seconds.
* Setting to 0 will disable background scanning. */
#define DEFAULT_BGSCAN_SHORT_INTERVAL_S (0)
/** Default Background scan signal threshold in dBm. */
#define DEFAULT_BGSCAN_THRESHOLD_DBM (0)
/** Default Background scan long interval in seconds.
* Setting to 0 will disable background scanning. */
#define DEFAULT_BGSCAN_LONG_INTERVAL_S (0)
/** Default Target Wake Time (TWT) interval in micro seconds. */
#define DEFAULT_TWT_WAKE_INTERVAL_US (300000000)
/** Default min Target Wake Time (TWT) duration in micro seconds. */
#define DEFAULT_TWT_MIN_WAKE_DURATION_US (65280)
/**
* The maximum length of a user-specified payload (bytes) for Standby status
* frames.
*/
#define MMWLAN_STANDBY_STATUS_FRAME_USER_PAYLOAD_MAXLEN (64)
/** The maximum allowed length of a user filter to apply to wake frames */
#define MMWLAN_STANDBY_WAKE_FRAME_USER_FILTER_MAXLEN (64)
/** Enumeration of supported security types. */
enum mmwlan_security_type {
/** Open (no security) */
MMWLAN_OPEN,
/** Opportunistic Wireless Encryption (OWE) */
MMWLAN_OWE,
/** Simultaneous Authentication of Equals (SAE) */
MMWLAN_SAE,
};
/** Enumeration of supported 802.11 power save modes. */
enum mmwlan_ps_mode {
/** Power save disabled */
MMWLAN_PS_DISABLED,
/** Power save enabled */
MMWLAN_PS_ENABLED
};
/** Enumeration of Protected Management Frame (PMF) modes (802.11w). */
enum mmwlan_pmf_mode {
/** Protected management frames must be used */
MMWLAN_PMF_REQUIRED,
/** No protected management frames */
MMWLAN_PMF_DISABLED
};
/** Enumeration of Centralized Authentication Control (CAC) modes. */
enum mmwlan_cac_mode {
/** CAC disabled */
MMWLAN_CAC_DISABLED,
/** CAC enabled */
MMWLAN_CAC_ENABLED
};
/**
* Enumeration of Target Wake Time (TWT) modes.
*
* @note TWT is only supported as a requester.
*/
enum mmwlan_twt_mode {
/** TWT disabled */
MMWLAN_TWT_DISABLED,
/** TWT enabled as a requester */
MMWLAN_TWT_REQUESTER,
/** TWT enabled as a responder */
MMWLAN_TWT_RESPONDER
};
/** Enumeration of Target Wake Time (TWT) setup commands. */
enum mmwlan_twt_setup_command {
/** TWT setup request command */
MMWLAN_TWT_SETUP_REQUEST,
/** TWT setup suggest command */
MMWLAN_TWT_SETUP_SUGGEST,
/** TWT setup demand command */
MMWLAN_TWT_SETUP_DEMAND
};
/**
* @defgroup MMWLAN_REGDB WLAN Regulatory Database API
*
* @{
*/
/**
* If either the global or s1g operating class is set to this, the operating class will
* not be checked when associating to an AP.
*/
#define MMWLAN_SKIP_OP_CLASS_CHECK -1
/** Regulatory domain information about an S1G channel. */
struct mmwlan_s1g_channel {
/** Center frequency of the channel (in Hz). */
uint32_t centre_freq_hz;
/** STA Duty Cycle (in 100th of %). */
uint16_t duty_cycle_sta;
/** Boolean indicating whether to omit control response frames from duty cycle. */
bool duty_cycle_omit_ctrl_resp;
/** Global operating class. If @ref MMWLAN_SKIP_OP_CLASS_CHECK, check is skipped */
int16_t global_operating_class;
/** S1G operating class. If @ref MMWLAN_SKIP_OP_CLASS_CHECK, check is skipped */
int16_t s1g_operating_class;
/** S1G channel number. */
uint8_t s1g_chan_num;
/** Channel operating bandwidth (in MHz). */
uint8_t bw_mhz;
/** Maximum transmit power (EIRP in dBm). */
int8_t max_tx_eirp_dbm;
/** The length of time to close the tx window between packets (in microseconds). */
uint32_t pkt_spacing_us;
/** The minimum packet airtime duration to trigger spacing (in microseconds). */
uint32_t airtime_min_us;
/** The maximum allowable packet airtime duration (in microseconds). */
uint32_t airtime_max_us;
};
/** A list of S1G channels supported by a given regulatory domain. */
struct mmwlan_s1g_channel_list {
/** Two character country code (null-terminated) used to identify the regulatory domain. */
uint8_t country_code[3];
/** The number of channels in the list. */
unsigned num_channels;
/** The channel data. */
const struct mmwlan_s1g_channel *channels;
};
/**
* Regulatory database data structure. This is a list of @c mmwlan_s1g_channel_list structs, where
* each channel list corresponds to a regulatory domain.
*/
struct mmwlan_regulatory_db {
/** Number of regulatory domains in the database. */
unsigned num_domains;
/** The regulatory domain data */
const struct mmwlan_s1g_channel_list **domains;
};
/**
* Look up the given country code in the regulatory database and return the matching channel
* list if found.
*
* @param db The regulatory database.
* @param country_code Country code to look up.
*
* @returns the matching channel list if found, else NULL.
*/
static inline const struct mmwlan_s1g_channel_list *mmwlan_lookup_regulatory_domain(const struct mmwlan_regulatory_db *db,
const char *country_code)
{
unsigned ii;
if (db == NULL) {
return NULL;
}
for (ii = 0; ii < db->num_domains; ii++) {
const struct mmwlan_s1g_channel_list *channel_list = db->domains[ii];
if (channel_list->country_code[0] == country_code[0] && channel_list->country_code[1] == country_code[1]) {
return channel_list;
}
}
return NULL;
}
/**
* Set the list of channels that are supported by the regulatory domain in which the device
* resides.
*
* @note Must be invoked after WLAN initialization (see @ref mmwlan_init()) but only when inactive
* (i.e., STA not enabled).
*
* @warning This function takes a reference to the given channel list. It expects the channel
* list to remain valid in memory as long as WLAN is in use, or until a new channel
* list is configured.
*
* @param channel_list The channel list to set. The list must remain valid in memory.
*
* @return @ref MMWLAN_SUCCESS if the channel list was valid and updated successfully,
* @ref MMWLAN_UNAVAILABLE if the WLAN subsystem was currently active.
*/
enum mmwlan_status mmwlan_set_channel_list(const struct mmwlan_s1g_channel_list *channel_list);
/** @} */
/**
* @defgroup MMWLAN_CTRL WLAN Control API
*
* @{
*/
/** Maximum length of the Morselib version string. */
#define MMWLAN_MORSELIB_VERSION_MAXLEN (32)
/** Maximum length of the firmware version string. */
#define MMWLAN_FW_VERSION_MAXLEN (32)
/** Structure for retrieving version information from the mmwlan subsystem. */
struct mmwlan_version {
/** Morselib version string. Null terminated. */
char morselib_version[MMWLAN_MORSELIB_VERSION_MAXLEN];
/** Morse transceiver firmware version string. Null terminated. */
char morse_fw_version[MMWLAN_FW_VERSION_MAXLEN];
/** Morse transceiver chip ID. */
uint32_t morse_chip_id;
};
/**
* Retrieve version information from morselib and the connected Morse transceiver.
*
* @param version The data structure to fill out with version information.
*
* @note If the Morse transceiver has not previously been powered on then the @c fw_version
* field of @p version will be set to a zero length string.
*
* @returns @c MMWLAN_SUCCESS on success else an error code.
*/
enum mmwlan_status mmwlan_get_version(struct mmwlan_version *version);
/** Maximum length of a BCF board description string (excluding null terminator). */
#define MMWLAN_BCF_BOARD_DESC_MAXLEN (31)
/** Maximum length of a BCF build version string (excluding null terminator). */
#define MMWLAN_BCF_BUILD_VERSION_MAXLEN (31)
/** Board configuration file (BCF) metadata. */
struct mmwlan_bcf_metadata {
/** BCF semantic version. */
struct {
/** Major version field. */
uint16_t major;
/** Minor version field. */
uint8_t minor;
/** Patch version field. */
uint8_t patch;
} version;
/**
* Board description string. This is a free form text field included in the BCF.
*
* This string will be null-terminated and if it exceeds @ref MMWLAN_BCF_BOARD_DESC_MAXLEN
* characters in length it will be truncated.
*/
char board_desc[MMWLAN_BCF_BOARD_DESC_MAXLEN + 1];
/**
* Build version string.
*
* This string will be null-terminated and if it exceeds @ref MMWLAN_BCF_BOARD_DESC_MAXLEN
* characters in length it will be truncated.
*/
char build_version[MMWLAN_BCF_BUILD_VERSION_MAXLEN + 1];
};
/**
* Read the metadata from the board configuration file (BCF)r.
*
* @param metadata Pointer to a metadata data structure to be filled out on success.
*
* @returns @c MMWLAN_SUCCESS on success else an error code.
*/
enum mmwlan_status mmwlan_get_bcf_metadata(struct mmwlan_bcf_metadata *metadata);
/**
* Override the maximum TX power. If no override is specified then the maximum TX power used
* will be the maximum TX power allowed for the channel in the current regulatory domain.
*
* @note Must be invoked after WLAN initialization (see @ref mmwlan_init()). Only takes
* effect when switching channel (e.g., during scan or AP connection procedure).
*
* @note This will not increase the TX power over the maximum allowed for the current channel
* in the configured regulatory domain. Therefore, this override in effect will only
* reduce the maximum TX power and cannot increase it.
*
* @param tx_power_dbm The maximum TX power override to set (in dBm). Set to zero to disable
* the override.
*
* @return @ref MMWLAN_SUCCESS if the country code was valid and updated successfully,
* @ref MMWLAN_UNAVAILABLE if the WLAN subsystem was currently active.
*/
enum mmwlan_status mmwlan_override_max_tx_power(uint16_t tx_power_dbm);
/**
* Set the RTS threshold.
*
* When packets larger than the RTS threshold are transmitted they are protected by an RTS/CTS
* exchange.
*
* @param rts_threshold The RTS threshold (in octets) to set, or 0 to disable.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_rts_threshold(unsigned rts_threshold);
/**
* Sets whether or not Short Guard Interval (SGI) support is enabled. Defaults to enabled
* if not set otherwise.
*
* @note This will not force use of SGI, only enable support for it. The rate control algorithm
* will make the decision as to which guard interval to use unless explicitly overridden
* by @ref mmwlan_ate_override_rate_control().
*
* @note This must only be invoked when MMWLAN is inactive (i.e., STA mode not enabled).
*
* @param sgi_enabled Boolean value indicating whether SGI support should be enabled.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_sgi_enabled(bool sgi_enabled);
/**
* Sets whether or not sub-band support is enabled for transmit. Defaults to enabled
* if not set otherwise.
*
* @note This will not force use of sub-bands, only enable support for it. The rate control
* algorithm will make the decision as to which bandwidth to use unless explicitly overridden
* by @ref mmwlan_ate_override_rate_control().
*
* @note This must only be invoked when MMWLAN is inactive (i.e., STA mode not enabled).
*
* @param subbands_enabled Boolean value indicating whether sub-band support should be enabled.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_subbands_enabled(bool subbands_enabled);
/**
* Sets whether or not the 802.11 power save is enabled. Defaults to @ref MMWLAN_PS_ENABLED
*
* @param mode enum indicating which 802.11 power save mode to use.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_power_save_mode(enum mmwlan_ps_mode mode);
/**
* Sets whether or not Aggregated MAC Protocol Data Unit (A-MPDU) support is enabled.
* This defaults to enabled, if not set otherwise.
*
* @note This must only be invoked when MMWLAN is inactive (i.e., STA mode not enabled).
*
* @param ampdu_enabled Boolean value indicating whether AMPDU support should be enabled.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_ampdu_enabled(bool ampdu_enabled);
/**
* Minimum value of fragmentation threshold that can be set with
* @ref mmwlan_set_fragment_threshold().
*/
#define MMWLAN_MINIMUM_FRAGMENT_THRESHOLD (256)
/**
* Set the Fragmentation threshold.
*
* Maximum length of the frame, beyond which packets must be fragmented into two or more frames.
*
* @note Even if the fragmentation threshold is set to 0 (disabled), fragmentation may still occur
* if a given packet is too large to be transmitted at the selected rate.
*
* @warning Setting a fragmentation threshold may have unintended side effects due to restrictions
* at lower bandwidths and MCS rates. In normal operation the fragmentation threshold
* should be disabled, in which case packets will be fragmented automatically as necessary
* based on the selected rate.
*
* @param fragment_threshold The fragmentation threshold (in octets) to set,
* or zero to disable the fragmentation threshold. Minimum value
* (if not zero) is given by @ref MMWLAN_MINIMUM_FRAGMENT_THRESHOLD.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_fragment_threshold(unsigned fragment_threshold);
/**
* Scan configuration data structure.
*
* Use @ref MMWLAN_SCAN_CONFIG_INIT for initialization. For example:
*
* @code{.c}
* struct mmwlan_scan_config scan_config = MMWLAN_SCAN_CONFIG_INIT;
* @endcode
*
* @see mmwlan_set_scan_config()
*/
struct mmwlan_scan_config {
/**
* Set the per-channel dwell time to use for scans that are requested internally within the
* mmwlan driver (e.g., when connecting or background scanning).
*
* @note This does not affect scans requested with the @ref mmwlan_scan_request().
*/
uint32_t dwell_time_ms;
};
/** Initializer for @ref mmwlan_scan_config. */
#define MMWLAN_SCAN_CONFIG_INIT \
{ \
MMWLAN_SCAN_DEFAULT_DWELL_TIME_MS \
}
/**
* Update the scan configuration with the given settings.
*
* @param config The new configuration to set.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_scan_config(const struct mmwlan_scan_config *config);
/** Structure for storing Target Wake Time (TWT) configuration arguments. */
struct mmwlan_twt_config_args {
/** Target Wake Time (TWT) modes, @ref mmwlan_twt_mode. */
enum mmwlan_twt_mode twt_mode;
/**
* TWT service period interval in micro seconds.
* This parameter will be ignored if @c twt_wake_interval_mantissa or
* @c twt_wake_interval_exponent is non-zero.
*/
uint64_t twt_wake_interval_us;
/**
* TWT Wake interval mantissa
* If non-zero, this parameter will be used to calculate @c twt_wake_interval_us.
*/
uint16_t twt_wake_interval_mantissa;
/**
* TWT Wake interval exponent
* If non-zero, this parameter will be used to calculate @c twt_wake_interval_us.
*/
uint8_t twt_wake_interval_exponent;
/** Minimum TWT wake duration in micro seconds. */
uint32_t twt_min_wake_duration_us;
/** TWT setup command, @ref mmwlan_twt_setup_command. */
enum mmwlan_twt_setup_command twt_setup_command;
};
/**
* Initializer for @ref mmwlan_twt_config_args.
*
* For example:
*
* @code{c}
* struct mmwlan_twt_config_args twt_config_args = MMWLAN_TWT_CONFIG_ARGS_INIT;
* @endcode
*/
#define MMWLAN_TWT_CONFIG_ARGS_INIT \
{ \
MMWLAN_TWT_DISABLED, DEFAULT_TWT_WAKE_INTERVAL_US, 0, 0, DEFAULT_TWT_MIN_WAKE_DURATION_US, MMWLAN_TWT_SETUP_REQUEST \
}
/**
* Add configurations for Target Wake Time (TWT).
*
* @note This is used to add TWT configuration for a new TWT agreement.
* This function should be invoked before @ref mmwlan_sta_enable.
*
* @param twt_config_args TWT configuration arguments @ref mmwlan_twt_config_args.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_twt_add_configuration(const struct mmwlan_twt_config_args *twt_config_args);
/**
* Arguments data structure for @ref mmwlan_boot().
*
* This structure should be initialized using @ref MMWLAN_BOOT_ARGS_INIT for sensible
* default values, particularly for forward compatibility with new releases that may add
* new fields to the struct. For example:
*
* @note This struct currently does not include any sensible arguments yet, and is provided
* for forwards compatibility with potential future API extensions.
*
* @code{.c}
* enum mmwlan_status status;
* struct mmwlan_boot_args boot_args = MMWLAN_BOOT_ARGS_INIT;
* // HERE: initialize arguments
* status = mmwlan_boot(&boot_args);
* @endcode
*/
struct mmwlan_boot_args {
/** Note this field should not be used and will be removed in future. */
uint8_t reserved;
};
/**
* Initializer for @ref mmwlan_boot_args.
*
* @see mmwlan_boot_args
*/
#define MMWLAN_BOOT_ARGS_INIT \
{ \
0 \
}
/**
* Boot the Morse Micro transceiver and leave it in an idle state.
*
* @note In general, it is not necessary to use this function as @ref mmwlan_sta_enable()
* will automatically boot the chip if required. It may be used, for example, to power
* on the chip for production test, etc.
*
* @warning Channel list must be set before booting the transceiver. @ref mmwlan_set_channel_list().
*
* @param args Boot arguments. May be @c NULL, in which case default values will be used.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_boot(const struct mmwlan_boot_args *args);
/**
* Perform a clean shutdown of the Morse Micro transceiver, including cleanly disconnecting
* from a connected AP, if necessary.
*
* Has no effect if the transceiver is already shutdown.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_shutdown(void);
/**
* Enumeration of states in STA mode.
*/
enum mmwlan_sta_state {
MMWLAN_STA_DISABLED,
MMWLAN_STA_CONNECTING,
MMWLAN_STA_CONNECTED,
};
/**
* Enumeration of S1G non-AP STA types.
*/
enum mmwlan_station_type {
MMWLAN_STA_TYPE_SENSOR = 0x01,
MMWLAN_STA_TYPE_NON_SENSOR = 0x02,
};
/** Result of the scan request. */
struct mmwlan_scan_result {
/** RSSI of the received frame. */
int16_t rssi;
/** Pointer to the BSSID field within the Probe Response frame. */
const uint8_t *bssid;
/** Pointer to the SSID within the SSID IE of the Probe Response frame. */
const uint8_t *ssid;
/** Pointer to the start of the Information Elements within the Probe Response frame. */
const uint8_t *ies;
/** Value of the Beacon Interval field. */
uint16_t beacon_interval;
/** Value of the Capability Information field. */
uint16_t capability_info;
/** Length of the Information Elements (@c ies). */
uint16_t ies_len;
/** Length of the SSID (@c ssid). */
uint8_t ssid_len;
/** Center frequency in Hz of the channel where the frame was received. */
uint32_t channel_freq_hz;
/** Bandwidth, in MHz, where the frame was received. */
uint8_t bw_mhz;
/** Operating bandwidth, in MHz, of the access point. */
uint8_t op_bw_mhz;
/** TSF timestamp in the Probe Response frame. */
uint64_t tsf;
};
/** mmwlan scan rx callback function prototype. */
typedef void (*mmwlan_scan_rx_cb_t)(const struct mmwlan_scan_result *result, void *arg);
/** STA status callback function prototype. */
typedef void (*mmwlan_sta_status_cb_t)(enum mmwlan_sta_state sta_state);
/**
* Arguments data structure for @ref mmwlan_sta_enable().
*
* This structure should be initialized using @ref MMWLAN_STA_ARGS_INIT for sensible
* default values, particularly for forward compatibility with new releases that may add
* new fields to the struct. For example:
*
* @code{.c}
* enum mmwlan_status status;
* struct mmwlan_sta_args sta_args = MMWLAN_STA_ARGS_INIT;
* // HERE: initialize arguments
* status = mmwlan_sta_enable(&sta_args);
* @endcode
*/
struct mmwlan_sta_args {
/** SSID of the AP to connect to. */
uint8_t ssid[MMWLAN_SSID_MAXLEN];
/** Length of the SSID. */
uint16_t ssid_len;
/**
* BSSID of the AP to connect to.
* If non-zero, the STA will only connect to an AP that matches this value.
*/
uint8_t bssid[MMWLAN_MAC_ADDR_LEN];
/** Type of security to use. If @c MMWLAN_SAE then a @c passphrase must be specified. */
enum mmwlan_security_type security_type;
/** Passphrase (only used if @c security_type is @c MMWLAN_SAE, otherwise ignored. */
char passphrase[MMWLAN_PASSPHRASE_MAXLEN + 1];
/** Length of @c passphrase. May be zero if @c passphrase is null-terminated. */
uint16_t passphrase_len;
/** Protected Management Frame mode to use (802.11w) */
enum mmwlan_pmf_mode pmf_mode;
/**
* Priority used by the AP to assign a STA to a Restricted Access Window (RAW) group.
* Valid range is 0 - @ref MMWLAN_RAW_MAX_PRIORITY, or -1 to disable RAW.
*/
int16_t raw_sta_priority;
/** S1G non-AP STA type. For valid STA types, @ref mmwlan_station_type */
enum mmwlan_station_type sta_type;
/**
* Preference list of enabled elliptic curve groups for SAE and OWE.
* By default (if this parameter is not set), the mandatory group 19 is preferred.
*/
int sae_owe_ec_groups[MMWLAN_MAX_EC_GROUPS];
/** Whether Centralized Authentication Controlled is enabled on the STA. */
enum mmwlan_cac_mode cac_mode;
/**
* Background scan short interval, measured in seconds.
*
* When the signal strength falls below @c bgscan_signal_threshold_dbm, this interval
* will be used between iterations of background scan. After several iterations, or
* if the signal threshold increases above @c bgscan_signal_threshold_dbm background
* scan will return to using the long interval.
*
* @note Setting this to zero will disable background scanning.
*/
uint16_t bgscan_short_interval_s;
/**
* Background scan signal strength threshold that switches between short and long intervals.
*/
int bgscan_signal_threshold_dbm;
/**
* Background scan long interval, measured in seconds.
*
* When the signal strength is above @c bgscan_signal_threshold_dbm, this interval
* will be used between iterations of background scan. If the signal threshold
* falls below @c bgscan_signal_threshold_dbm, background scan will use the short
* interval.
*
* @note Setting this to zero will disable background scanning.
*/
uint16_t bgscan_long_interval_s;
/** Optional callback for scan results which are received during the connection process. */
mmwlan_scan_rx_cb_t scan_rx_cb;
/** Opaque argument to be passed to @ref scan_rx_cb. */
void *scan_rx_cb_arg;
};
/**
* Initializer for @ref mmwlan_sta_args.
*
* @see mmwlan_sta_args
*/
#define MMWLAN_STA_ARGS_INIT \
{ \
{0}, 0, {0}, MMWLAN_OPEN, {0}, 0, MMWLAN_PMF_REQUIRED, -1, MMWLAN_STA_TYPE_NON_SENSOR, {0}, MMWLAN_CAC_DISABLED, \
DEFAULT_BGSCAN_SHORT_INTERVAL_S, DEFAULT_BGSCAN_THRESHOLD_DBM, DEFAULT_BGSCAN_LONG_INTERVAL_S, NULL, NULL \
}
/**
* Enable station mode.
*
* This will power on the transceiver then initiate connection to the given Access Point. If
* station mode is already enabled when this function is invoked then it will disconnect from
* (if already connected) and initiate connection to the given AP.
*
* @note The STA status callback (@p sta_status_cb) must not block and MMWLAN API functions
* may not be invoked from the callback.
*
* @warning Channel list must be set before enabling station mode. @ref mmwlan_set_channel_list().
*
* @param args STA arguments (e.g., SSID, etc.). See @ref mmwlan_sta_args.
* @param sta_status_cb Optional callback to be invoked on STA state changes. May be @c NULL.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_sta_enable(const struct mmwlan_sta_args *args, mmwlan_sta_status_cb_t sta_status_cb);
/**
* Disable station mode.
*
* This will disconnect from the AP. It will also shut down the transceiver if nothing else
* is holding it open. Note that if the transceiver was booted by @c mmwlan_boot() then
* this function will shut down the transceiver.
*
* @return @ref MMWLAN_SUCCESS if successful and the transceiver was also shut down,
* @ref MMWLAN_SHUTDOWN_BLOCKED if successful and the transceiver was not shut down,
* else an appropriate error code.
*/
enum mmwlan_status mmwlan_sta_disable(void);
/**
* Gets the current WLAN STA state.
*
* @return the current WLAN STA state.
*/
enum mmwlan_sta_state mmwlan_get_sta_state(void);
/** Default value for @c mmwlan_scan_args.dwell_time_ms. Note that reducing the dwell time
* below this value may impact scan reliability. */
#define MMWLAN_SCAN_DEFAULT_DWELL_TIME_MS (105)
/** Minimum value for @c mmwlan_scan_args.dwell_time_ms. */
#define MMWLAN_SCAN_MIN_DWELL_TIME_MS (15)
/**
* Enumeration of states in Scan mode.
*/
enum mmwlan_scan_state {
/** Scan was successful and all channels were scanned. */
MMWLAN_SCAN_SUCCESSFUL,
/** Scan was incomplete. One or more channels may have been scanned and therefore an
* incomplete set of scan results may still have been received. */
MMWLAN_SCAN_TERMINATED,
/** Scanning in progress. */
MMWLAN_SCAN_RUNNING,
};
/** mmwlan scan complete callback function prototype. */
typedef void (*mmwlan_scan_complete_cb_t)(enum mmwlan_scan_state scan_state, void *arg);
/**
* Structure to hold scan arguments. This structure should be initialized using
* @ref MMWLAN_SCAN_ARGS_INIT for forward compatibility.
*/
struct mmwlan_scan_args {
/**
* Time to dwell on a channel waiting for probe responses/beacons.
*
* @note This includes the time it takes to actually tune to the channel.
*/
uint32_t dwell_time_ms;
/**
* Extra Information Elements to include in Probe Request frames.
* May be @c NULL if @c extra_ies_len is zero.
*/
uint8_t *extra_ies;
/** Length of @c extra_ies. */
size_t extra_ies_len;
/**
* SSID used for scan.
* May be @c NULL, with @c ssid_len set to zero for an undirected scan.
*/
uint8_t ssid[MMWLAN_SSID_MAXLEN];
/** Length of the SSID. */
uint16_t ssid_len;
};
/**
* Initializer for @ref mmwlan_scan_args.
*
* For example:
*
* @code{c}
* struct mmwlan_scan_args scan_args = MMWLAN_SCAN_ARGS_INIT;
* @endcode
*/
#define MMWLAN_SCAN_ARGS_INIT \
{ \
MMWLAN_SCAN_DEFAULT_DWELL_TIME_MS, NULL, 0, {0}, 0 \
}
/**
* Structure to hold arguments specific to a given instance of a scan.
*/
struct mmwlan_scan_req {
/** Scan response receive callback. Must not be @c NULL. */
mmwlan_scan_rx_cb_t scan_rx_cb;
/** Scan complete callback. Must not be @c NULL. */
mmwlan_scan_complete_cb_t scan_complete_cb;
/** Opaque argument to be passed to the callbacks. */
void *scan_cb_arg;
/** Scan arguments to be used @ref mmwlan_scan_args. */
struct mmwlan_scan_args args;
};
/**
* Initializer for @ref mmwlan_scan_req.
*
* For example:
*
* @code{c}
* struct mmwlan_scan_req scan_req = MMWLAN_SCAN_REQ_INIT;
* @endcode
*/
#define MMWLAN_SCAN_REQ_INIT \
{ \
NULL, NULL, NULL, MMWLAN_SCAN_ARGS_INIT \
}
/**
* Request a scan.
*
* If the transceiver is not already powered on, it will be powered on before the scan is
* initiated. The power on procedure will block this function. The transceiver will remain
* powered on after scan completion and must be shutdown by invoking @ref mmwlan_shutdown().
*
* @note Just because a scan is requested does not mean it will happen immediately.
* It may take some time for the request to be serviced.
*
* @note The scan request may be rejected, in which case the complete callback will be
* invoked immediately with an error status.
*
* @param scan_req Scan request instance. See @ref mmwlan_scan_req.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_scan_request(const struct mmwlan_scan_req *scan_req);
/**
* Abort in progress or pending scans.
*
* The scan callback will be called back with result code @ref MMWLAN_SCAN_TERMINATED for
* all aborted scans.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_scan_abort(void);
/**
* Gets the MAC address of this device.
*
* The MAC address address comes from one of the following sources, in descending priority order:
* 1. @c mmhal_read_mac_addr()
* 2. Morse Micro transceiver
* 3. Randomly generated in the form `02:01:XX:XX:XX:XX`
*
* @note If a MAC address override is not provided (via @c mmhal_read_mac_addr()) then the
* transceiver must have been booted at least once before this function is invoked.
*
* @param mac_addr Buffer to receive the MAC address. Length must be @ref MMWLAN_MAC_ADDR_LEN.
*
* @return @ref MMWLAN_SUCCESS on success, @ref MMWLAN_UNAVAILABLE if the MAC address was not
* able to be read from the transceiver because it was not booted, else an appropriate
* error code.
*/
enum mmwlan_status mmwlan_get_mac_addr(uint8_t *mac_addr);
/**
* Gets the station's AID
*
* @return AID of station, or 0 if not associated
*/
uint16_t mmwlan_get_aid(void);
/**
* Gets the BSSID of the AP to which the STA is associated.
*
* @param bssid Buffer to receive the BSSID. Length must be @ref MMWLAN_MAC_ADDR_LEN.
* Will be set to 00:00:00:00:00:00 if the station is not currently associated.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_get_bssid(uint8_t *bssid);
/**
* Gets the RSSI measured from the AP.
*
* When power save is enabled, this will only be updated when traffic is received from the AP.
*
* @returns last known RSSI of the AP or INT32_MIN on error.
*/
int32_t mmwlan_get_rssi(void);
/** @} */
/**
* @defgroup MMWLAN_OFFLOAD WLAN offload features
*
* @{
*
* WLAN offload features enable offloading some high level networking features to the WLAN chip.
* Features like ARP response, ARP refresh and DHCP lease updates can be offloaded to the chip
* allowing the host processor to sleep for longer resulting in better power savings.
*
*/
/**
* Enables ARP response offload.
*
* When enabled the chip will automatically respond to ARP requests with the specified
* IPv4 address.
*
* @note ARP offload is not supported for IPv6 addresses.
*
* @param arp_addr The IPv4 address to respond with for ARP requests for this interface.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_enable_arp_response_offload(uint32_t arp_addr);
/**
* Enables ARP refresh offload.
*
* When enabled the Morse chip will periodically send ARP requests to the AP to refresh
* its ARP table. This keeps this stations ARP entry from expiring. ARP response offload
* needs to be enabled first for this feature to work.
*
* @note ARP refresh offload is not supported for IPv6 addresses.
*
* @param interval_s The interval in seconds to refresh the ARP entries on the AP.
* @param dest_ip The IP to send the ARP packets to.
* @param send_as_garp If true, send as gratuitous ARP.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_enable_arp_refresh_offload(uint32_t interval_s, uint32_t dest_ip, bool send_as_garp);
/**
* DHCP lease info structure.
*/
struct mmwlan_dhcp_lease_info {
/** local IP address */
uint32_t ip4_addr;
/** Netmask address */
uint32_t mask4_addr;
/** Gateway address */
uint32_t gw4_addr;
/** DNS address */
uint32_t dns4_addr;
};
/** DHCP Lease update callback function prototype - this is called whenever a lease is updated. */
typedef void (*mmwlan_dhcp_lease_update_cb_t)(const struct mmwlan_dhcp_lease_info *lease_info, void *arg);
/**
* Enables DHCP offload.
*
* When enabled the Morse chip will handle DHCP discovery and lease updates automatically.
*
* @note DHCP offload is not supported for IPv6 addresses.
*
* @note The DHCP lease update callback (@p dhcp_lease_update_cb) must not block and MMWLAN API
* functions may not be invoked from the callback.
*
* @note Once enabled this feature can only be disabled by a complete system reset or by calling
* @c mmwlan_shutdown().
*
* @param dhcp_lease_update_cb The callback to call whenever the DHCP lease is updated.
* @param arg An opaque argument to pass to @c dhcp_lease_update_cb.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_enable_dhcp_offload(mmwlan_dhcp_lease_update_cb_t dhcp_lease_update_cb, void *arg);
/**
* Keep-alive offload configuration options for @ref mmwlan_tcp_keepalive_offload_args.set_cfgs
* bitmap.
*/
enum mmwlan_tcp_keepalive_offload_cfg {
/** Bitmap for TCP keep alive period parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_PERIOD = (0x01),
/** Bitmap for TCP keep alive retry count parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_RETRY_COUNT = (0x02),
/** Bitmap for TCP keep alive retry interval parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_RETRY_INTERVAL = (0x04),
/** Bitmap for TCP keep alive source IP parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_SRC_IP_ADDR = (0x08),
/** Bitmap for TCP keep alive destination IP parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_DEST_IP_ADDR = (0x10),
/** Bitmap for TCP keep alive source port parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_SRC_PORT = (0x20),
/** Bitmap for TCP keep alive destination port parameter */
MMWLAN_TCP_KEEPALIVE_SET_CFG_DEST_PORT = (0x40),
/** Bitmap for TCP keep alive timing parameters only */
MMWLAN_TCP_KEEPALIVE_SET_CFG_TIMING_ONLY = (0x07),
/** Bitmap for all TCP keep alive parameters */
MMWLAN_TCP_KEEPALIVE_SET_CFG_ALL = (0x7F),
};
/**
* Arguments data structure for TCP keep-alive arguments.
*
* This structure should be initialized using @ref MMWLAN_TCP_KEEPALIVE_OFFLOAD_ARGS_INIT
* for sensible default values, particularly for forward compatibility with new releases
* that may add new fields to the struct. For example:
*
* @code{.c}
* struct mmwlan_tcp_keepalive_offload_args args = MMWLAN_TCP_KEEPALIVE_OFFLOAD_ARGS_INIT;
* @endcode
*/
struct mmwlan_tcp_keepalive_offload_args {
/**
* A bitmap specifying which configs to set.
* See @ref mmwlan_tcp_keepalive_offload_cfg for values.
*/
uint8_t set_cfgs;
/**
* The interval in seconds to send the keep alive in. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_PERIOD
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint16_t period_s;
/** Number of times to retry before giving up. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_RETRY_COUNT
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint8_t retry_count;
/** The time to wait between retries in seconds. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_RETRY_INTERVAL
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint8_t retry_interval_s;
/** The source IP for the keep alive packet. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_SRC_IP_ADDR
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint32_t src_ip;
/** The source port for the keep alive packet. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_SRC_PORT
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint16_t src_port;
/** The destination IP for the keep alive packet. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_DEST_IP_ADDR
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint32_t dest_ip;
/** The destination port for the keep alive packet. @c MMWLAN_TCP_KEEPALIVE_SET_CFG_SRC_PORT
* bit in @ref set_cfgs must be set if specifying this parameter
*/
uint16_t dest_port;
};
/**
* Initializer for @ref mmwlan_tcp_keepalive_offload_args.
*
* @see mmwlan_tcp_keepalive_offload_args
*/
#define MMWLAN_TCP_KEEPALIVE_OFFLOAD_ARGS_INIT \
{ \
0 \
}
/**
* Enables TCP keep-alive offload.
*
* When enabled the Morse chip will periodically send TCP keep-alive packets to the destination
* even when the host processor is in standby mode. This function needs to be called before
* opening a TCP connection.
*
* @note TCP keep-alive offload will only be applied to the first TCP connection matching the
* given configuration that is opened after this function is called.
*
* @note TCP keep-alive offload is not supported for IPv6 addresses.
*
* @param args A pointer to arguments of @c struct @c mmwlan_tcp_keepalive_offload_args.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_enable_tcp_keepalive_offload(const struct mmwlan_tcp_keepalive_offload_args *args);
/**
* Disables the TCP keep-alive offload feature.
*
* Has no effect if TCP keep-alive offload is not enabled.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_disable_tcp_keepalive_offload(void);
/**
* If this bit is set in the flags parameter of @ref mmwlan_config_whitelist then any active
* whitelist filters are cleared,
*/
#define MMWLAN_WHITELIST_FLAGS_CLEAR 0x01
/**
* Whitelist filter configuration
*/
struct mmwlan_config_whitelist {
/** Flags - clear any active whitelist filters if bit 0 is set */
uint8_t flags;
/** The IP protocol to match - 6 for TCP, 17 for UDP, 0 for any */
uint8_t ip_protocol;
/** The @c LLC protocol to match - 0x0800 for IPv4 and 0x86DD for IPv6, 0 for any */
uint16_t llc_protocol;
/** The IPv4 source address to match, 0.0.0.0 for any. */
uint32_t src_ip;
/** The IPv4 destination address to match, 0.0.0.0 for any - this is usually our IP address */
uint32_t dest_ip;
/** The netmask to apply to the source or destination IP, 0.0.0.0 for any */
uint32_t netmask;
/** The source TCP or UDP port to match, 0 for any */
uint16_t src_port;
/** The destination TCP or UDP port to match, 0 for any */
uint16_t dest_port;
};
/**
* Sets and enables the IP whitelist filter.
*
* The IP whitelist filter specifies which incoming IP packets can wake the host from standby.
* The filter can be used to specify parameters such as source or destination IP addresses to
* match on, source or destination ports and even IP layer (Such as TCP, ICMP or UDP) or @c LLC
* layer (Such as IPv4 or IPv6) protocols. If any filter parameter is set to 0, then it is
* excluded from the filtering process.
*
* If the @c flags parameter is set to @c MMWLAN_WHITELIST_FLAGS_CLEAR, then all active whitelist
* filters are cleared.
*
* @note Address/port level filtering is not supported for IPv6 packets.
*
* @param whitelist The whitelist filter to set.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_set_whitelist_filter(const struct mmwlan_config_whitelist *whitelist);
/** @} */
/**
* @defgroup MMWLAN_STANDBY WLAN Standby features
*
* @ingroup MMWLAN_OFFLOAD
*
* @{
*
* The standby mode allows the system to power off or put the host processor in a deep sleep mode
* while the Morse chip takes over certain functionality to keep the connection alive with the
* provision to wake up the host processor when certain conditions are met.
*
* When in Standby mode, the chip will:
* - Not try to communicate with the host in any way.
* - Use normal Power Save mechanisms to wake for DTIM beacons and to receive data frames when a
* DTIM beacon indicates pending data.
* - Directly respond to ARP requests if ARP offload is enabled, handle DHCP lease expiry/renewal
* if DHCP offload is enabled, and drop all other traffic other than a wake request packet from
* the access point.
* - Monitor access point reach-ability and provide status by periodically transmitting encrypted
* keep-alive frames to the access point.
* - If access point is no longer reachable, then the chip will enter a snooze mode where
* it stops listening for beacons, waking up only occasionally to see if the access point is
* reachable again. This allows the chip to conserve power when the access point is not reachable.
*
* The chip will wake the host only if one of the following occurs.
* - An encrypted Standby wake packet is received.
* - Association has been lost (indicated via a @c deauth response to a keep-alive frame from the
* access point).
* - The access point was not reachable and beacons are now detected indicating the access point
* is available again.
* - The input trigger GPIO pin on the chip was toggled indicating some on board hardware requires
* attention.
* - A TCP connection maintained by the TCP keep-alive offload feature was lost.
*
* The host will be powered on by toggling a GPIO pin, the BUSY pin is also toggled to interrupt
* the host. By offloading features like ARP response, ARP refresh, TCP keep-alive, and DHCP lease
* updates while in standby mode allows the host processor to sleep for longer resulting in better
* power savings.
*/
/**
* Reasons we can exit standby mode.
*/
enum mmwlan_standby_exit_reason {
/** No specific reason for exiting standby mode */
MMWLAN_STANDBY_EXIT_REASON_NONE,
/** The STA has received the wake-up frame */
MMWLAN_STANDBY_EXIT_REASON_WAKEUP_FRAME,
/** The STA needs to (re)associate */
MMWLAN_STANDBY_EXIT_REASON_ASSOCIATE,
/** The external input pin has fired */
MMWLAN_STANDBY_EXIT_REASON_EXT_INPUT,
/** Whitelisted packet received */
MMWLAN_STANDBY_EXIT_REASON_WHITELIST_PKT,
/** TCP connection lost */
MMWLAN_STANDBY_EXIT_REASON_TCP_CONNECTION_LOST,
};
/**
* Standby mode callback whenever an event requiring an exit from standby mode occurs.
*
* @param reason The reason we exited standby mode. See enum @ref mmwlan_standby_exit_reason.
* @param arg An opaque pointer passed from @ref mmwlan_standby_enter()
*/
typedef void (*mmwlan_standby_exit_cb_t)(uint8_t reason, void *arg);
/** Arguments for @ref mmwlan_standby_enter */
struct mmwlan_standby_enter_args {
/** Callback function to call when we exit standby mode */
mmwlan_standby_exit_cb_t standby_exit_cb;
/** Arguments to pass to callback function */
void *standby_exit_arg;
};
/**
* This function puts the Morse chip into standby mode allowing the host processor to go to sleep.
*
* When in standby mode the Morse chip takes over certain functionality to keep the connection
* alive with the provision to wake up the host processor when certain conditions are met.
* Exit from standby mode can be triggered by the Morse chip under certain conditions or by the host by
* invoking @ref mmwlan_standby_exit(). Before invoking this function, standby mode parameters can be
* configured by calling @ref mmwlan_standby_set_config(), @ref mmwlan_standby_set_status_payload() and/or
* @ref mmwlan_standby_set_wake_filter()
*
* @param args A pointer to the arguments for this function.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_standby_enter(const struct mmwlan_standby_enter_args *args);
/**
* Forces the Morse chip to exit standby mode.
*
* here may be certain instances such as a timer expiry, which cause the host chip to wake up
* independent of the Morse chip. In such situations, the host calls this function to instruct
* the Morse chip to exit standby mode and return to normal operating mode.
*
* Triggers @ref mmwlan_standby_exit_cb_t with reason @c MMWLAN_STANDBY_EXIT_REASON_NONE.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_standby_exit(void);
/** Arguments for @ref mmwlan_standby_set_status_payload */
struct mmwlan_standby_set_status_payload_args {
/** User data to append to the standby status packets */
uint8_t payload[MMWLAN_STANDBY_STATUS_FRAME_USER_PAYLOAD_MAXLEN];
/**
* The length of the payload in bytes.
* See @ref MMWLAN_STANDBY_STATUS_FRAME_USER_PAYLOAD_MAXLEN for maximum payload length.
*/
uint32_t payload_len;
};
/**
* Sets the user payload in the standby status packet.
*
* Once standby mode is enabled, the Morse chip will periodically emit a UDP packet of the
* following format regardless of whether it is in standby or not. The UDP packet
* will also be sent immediately upon entering or exiting Standby mode.
*
* @code
* +----------------------+----------------------+--------------------------------+---------+
* | Morse OUI (0c:bf:74) | Type: Standby (0x01) | Awake (0x00) or Standby (0x01) | Payload |
* +----------------------+----------------------+--------------------------------+---------+
* @endcode
*
* @note The payload is optional and is not present if this function is not called.
*
* @param args A pointer to the arguments for this function.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_standby_set_status_payload(const struct mmwlan_standby_set_status_payload_args *args);
/** Arguments for @ref mmwlan_standby_set_wake_filter */
struct mmwlan_standby_set_wake_filter_args {
/** Data to match with for filtering */
uint8_t filter[MMWLAN_STANDBY_WAKE_FRAME_USER_FILTER_MAXLEN];
/**
* The length of the filter data in bytes.
* See @ref MMWLAN_STANDBY_WAKE_FRAME_USER_FILTER_MAXLEN for maximum filter length.
*/
uint32_t filter_len;
/** The offset within the packet to search for the filter match */
uint32_t offset;
};
/**
* Configures the standby mode UDP wake packet filter.
*
* The system can be woken up from standby mode by sending it a UDP wake packet of the following
* format. If a wake filter is set using this function then the wake packet will only wake up
* the system if the specified filter pattern matches the payload at the specified offset within
* the payload.
*
* The wake packet has the following format:
* @code
* +----------------------+----------------------+----------------+--------------------+
* | Morse OUI (0c:bf:74) | Type: Standby (0x01) | Wake up (0x02) | Payload (optional) |
* +----------------------+----------------------+----------------+--------------------+
* @endcode
*
* @note If a wake filter is not configured then the system will wake on any wake packet and
* the payload (if any) is ignored.
*
* @param args A pointer to the arguments for this function.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_standby_set_wake_filter(const struct mmwlan_standby_set_wake_filter_args *args);
/**
* Standby mode configuration parameters. If the @ref mmwlan_standby_set_config()
* function is not called, then the defaults are as specified.
*/
struct mmwlan_standby_config {
/** Interval in seconds for transmitting Standby status packets. (Default 15s) */
uint32_t notify_period_s;
/** Source IP address to use for the standby status packets. (Default 0.0.0.0) */
uint32_t src_ip;
/** Destination IP address for the standby status packets. (Default 0.0.0.0) */
uint32_t dst_ip;
/**
* Destination UDP Port for the standby status packets, also used the source port for
* outgoing UDP port for outgoing UDP packets. (Default 22000)
*/
uint16_t dst_port;
/**
* The interval in seconds to wait after beacon loss before entering snooze. In
* snooze mode the chip stops listening for beacons to save power. (Default 120s)
*/
uint32_t bss_inactivity_before_snooze_s;
/**
* The interval in seconds to wake periodically from snooze and check for beacons.
* If no beacons are found then the chip will re-enter snooze. If beacons are found
* then the chip will exit standby mode so the host can re-associate. (Default 60s)
*/
uint32_t snooze_period_s;
/**
* The amount in seconds to increase successive snooze intervals. This saves power
* by sleeping for longer before checking for beacons again if no beacons are found.
* (Default 0s)
*/
uint32_t snooze_increment_s;
/** The maximum time in seconds to snooze for after increments. (Default @c UINT32_MAX) */
uint32_t snooze_max_s;
};
/**
* Sets the configuration for standby mode.
*
* @param config A pointer to the configuration structure. See @ref mmwlan_standby_config.
*
* @returns @ref MMWLAN_SUCCESS on success or @ref MMWLAN_ERROR on failure.
*/
enum mmwlan_status mmwlan_standby_set_config(const struct mmwlan_standby_config *config);
/** @} */
/**
* @defgroup MMWLAN_WNM WNM Sleep management
*
* @{
*
* @note It is highly recommended to refer to Morse Micro App Note 04 on WNM sleep for a more
* detailed explanation on how this feature works.
*
* WNM sleep is an extended power save mode in which the STA need not listen for every DTIM beacon
* and need not perform rekey, allowing the STA to remain associated and reduce power consumption
* when it has no traffic to send or receive from the AP. While a STA is in WNM sleep it will be
* unable to communicate with the AP, and thus any traffic for the STA may be buffered or dropped
* at the discretion of the AP while the STA is in WNM sleep.
*
* @note WNM sleep can only be entered after the STA is associated to the AP. The AP must also
* support WNM sleep.
*
* When entry to WNM sleep is enabled via this API, the STA sends a request to the AP and after
* successful negotiation, the chip is either put into a lower power mode or powered down
* completely, depending on arguments given when WNM sleep mode was enabled. The datapath is paused
* during this time. If the STA does not successfully negotiate with the AP to enter WNM Sleep, it
* will return an error code and the chip will not enter a low power mode.
*
* When WNM sleep is disabled, the chip returns to normal operation and sends a request to the AP
* to exit WNM sleep. Note that the chip will exit low power mode regardless of whether or not the
* exit request was successful. WNM sleep will be exited if @ref mmwlan_shutdown or
* @ref mmwlan_sta_disable is invoked.
*
* If the AP takes down the link, then the station will be unaware until it sends the WNM Sleep
* exit request. At that point the AP will send a de-authentication frame with reason code
* "non-associated station". After validating this is actually the AP the station was connected
* to, the station will bring down the connection and return @ref MMWLAN_ERROR. The station will
* attempt to re-associate but will not re-enter WNM sleep. The application needs to enable WNM
* sleep again via this API if required.
*
* A high level overview of enabling and disabling WNM sleep is shown below.
*
* @include{doc} wnm_sleep_overview.puml
*/
/** Structure for storing WNM sleep extended arguments. */
struct mmwlan_set_wnm_sleep_enabled_args {
/** Boolean indicating whether WNM sleep is enabled. */
bool wnm_sleep_enabled;
/** Boolean indicating whether chip should be powered down during WNM sleep. */
bool chip_powerdown_enabled;
};
/**
* Initializer for @ref mmwlan_set_wnm_sleep_enabled_args.
*
* For example:
*
* @code{c}
* struct mmwlan_set_wnm_sleep_enabled_args wnm_sleep_args = MMWLAN_SET_WNM_SLEEP_ENABLED_ARGS_INIT;
* @endcode
*/
#define MMWLAN_SET_WNM_SLEEP_ENABLED_ARGS_INIT \
{ \
false, false \
}
/**
* Sets extended WNM sleep mode.
*
* Provides an extended interface for setting WNM sleep. See @ref mmwlan_set_wnm_sleep_enabled_args
* for parameter details. If WNM sleep mode is enabled then the transceiver will sleep across
* multiple DTIM periods until WNM sleep mode is disabled. This allows the transceiver to use less
* power with the caveat that it will not wake up for group- or individually-addressed traffic. If
* a group rekey occurs while the device is in WNM sleep it will be applied when the device exits
* WNM sleep.
*
* @note Data should not be queued for transmission (using, e.g., @ref mmwlan_tx()) during
* WNM sleep.
* @note 802.11 power save must be enabled for any benefit to be obtained
* (see @ref mmwlan_set_power_save_mode()).
* @note Negotiation with the AP is required to enter WNM sleep. As such the transceiver will only
* be placed into low power mode when a connection has been establish and the AP has accepted
* the request to enter WNM sleep. This will automatically be handled within mmwlan once WNM
* sleep mode is enabled.
*
* @param args WNM sleep arguments - see @ref mmwlan_set_wnm_sleep_enabled_args.
*
* @return @ref MMWLAN_SUCCESS on success, MMWLAN_UNAVAILABLE if already requested,
* else an appropriate error code.
* @ref MMWLAN_TIMED_OUT if the maximum retry request reached. For WNM sleep exit request,
* this means that the device exited WNM sleep but failed to inform the AP.
*/
enum mmwlan_status mmwlan_set_wnm_sleep_enabled_ext(const struct mmwlan_set_wnm_sleep_enabled_args *args);
/**
* Sets whether WNM sleep mode is enabled.
*
* If WNM sleep mode is enabled then the transceiver will sleep across multiple DTIM periods
* until WNM sleep mode is disabled. This allows the transceiver to use less power with the
* caveat that it will not wake up for group- or individually-addressed traffic. If a group
* rekey occurs while the device is in WNM sleep it will be applied when the device exits
* WNM sleep.
*
* @note Data should not be queued for transmission (using, e.g., @ref mmwlan_tx()) during
* WNM sleep.
* @note 802.11 power save must be enabled for any benefit to be obtained
* (see @ref mmwlan_set_power_save_mode()).
* @note Negotiation with the AP is required to enter WNM sleep. As such the transceiver will only
* be placed into low power mode when a connection has been establish and the AP has accepted
* the request to enter WNM sleep. This will automatically be handled within mmwlan once WNM
* sleep mode is enabled.
*
* @param wnm_sleep_enabled Boolean indicating whether WNM sleep is enabled.
*
* @return @ref MMWLAN_SUCCESS on success, MMWLAN_UNAVAILABLE if already requested,
* else an appropriate error code.
* @ref MMWLAN_TIMED_OUT if the maximum retry request reached. For WNM sleep exit request,
* this means that the device exited WNM sleep but failed to inform the AP.
*/
static inline enum mmwlan_status mmwlan_set_wnm_sleep_enabled(bool wnm_sleep_enabled)
{
struct mmwlan_set_wnm_sleep_enabled_args wnm_sleep_args = MMWLAN_SET_WNM_SLEEP_ENABLED_ARGS_INIT;
wnm_sleep_args.wnm_sleep_enabled = wnm_sleep_enabled;
return mmwlan_set_wnm_sleep_enabled_ext(&wnm_sleep_args);
}
/**
* @}
*/
/**
* @defgroup MMWLAN_BEACON_VENDOR_IE_FILTER_API Beacon Vendor Specific IE Filter API
*
* @{
*
* This API enables access to Vendor Specific information elements (IEs) in beacons. The application
* can register a callback to be executed if Vendor Specific IEs containing one of the specified
* Organizational Unique Identifiers (OUIs). Up to @ref MMWLAN_BEACON_VENDOR_IE_MAX_OUI_FILTERS can
* be specified.
*/
/** Max number of OUIs supported in vendor IE OUI filter, @ref mmwlan_beacon_vendor_ie_filter. */
#define MMWLAN_BEACON_VENDOR_IE_MAX_OUI_FILTERS (5)
/**
* Beacon vendor ie filter callback function prototype.
*
* @param ies Reference to the list of information elements (little endian order) present in
* the beacon that matched the filter.
* @param ies_len Length of the IE list in octets.
* @param arg Reference to the opaque argument provided with the filter.
*/
typedef void (*mmwlan_beacon_vendor_ie_filter_cb_t)(const uint8_t *ies, uint32_t ies_len, void *arg);
/** 24-bit OUI type. */
typedef uint8_t mmwlan_oui_t[MMWLAN_OUI_SIZE];
/** Structure for storing beacon vendor ie filter parameter. */
struct mmwlan_beacon_vendor_ie_filter {
/**
* Callback that will be executed upon reception of a beacon containing a Vendor Specific
* information element that has an OUI that matches this filter. Must not be @c NULL.
*
* @note This is executed in the MMWLAN main processing loop. As such, processing within the
* callback itself should be kept as short as possible. If extensive processing is done within
* the callback this could have an impact on throughput and/or connection stability.
*/
mmwlan_beacon_vendor_ie_filter_cb_t cb;
/** Opaque argument to be passed to the callbacks. */
void *cb_arg;
/** Number of OUIs contained within @ref ouis. This can be @ref
* MMWLAN_BEACON_VENDOR_IE_MAX_OUI_FILTERS max. */
uint8_t n_ouis;
/** List of OUIs to filter on. */
mmwlan_oui_t ouis[MMWLAN_BEACON_VENDOR_IE_MAX_OUI_FILTERS];
};
/**
* Function to update the filter used to pass beacon back.
*
* @note This will block until the filter has been installed or some error has occurred.
*
* @param filter Reference to the filter to use. This must reside in memory and not be modified
* until after the filter is **successfully** cleared. To clear the filter pass @c
* NULL here.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_update_beacon_vendor_ie_filter(const struct mmwlan_beacon_vendor_ie_filter *filter);
/** @} */
/*
* ---------------------------------------------------------------------------------------------
*/
/**
* @defgroup MMWLAN_INIT WLAN Initialization/Deinitialization API
*
* @note If using LWIP, this API is invoked by the LWIP @c netif for MMWLAN, and thus does not
* need to be used directly by the application.
*
* @{
*/
/**
* Initialize the MMWLAN subsystem.
*
* @warning @ref mmhal_init() must be called before this function is executed.
*/
void mmwlan_init(void);
/**
* Deinitialize the MMWLAN subsystem, freeing any allocated memory.
*
* Must not be called while there is any activity in progress (e.g., while connected).
*
* @warning @ref mmwlan_shutdown must be called before executing this function.
*/
void mmwlan_deinit(void);
/** @} */
/**
* @defgroup MMWLAN_HEALTH WLAN Health check API
*
* @{
*/
/**
* The default minimum interval to wait after the last health check before triggering another.
* If this is 0 then health checks will always happen at the
* @ref MMWLAN_DEFAULT_MAX_HEALTH_CHECK_INTERVAL_MS value.
* @ref MMWLAN_DEFAULT_MIN_HEALTH_CHECK_INTERVAL_MS must always be less than or equal to
* @ref MMWLAN_DEFAULT_MAX_HEALTH_CHECK_INTERVAL_MS.
*/
#define MMWLAN_DEFAULT_MIN_HEALTH_CHECK_INTERVAL_MS 60000
/**
* The default maximum interval to wait after the last health check before triggering another.
* If this parameter is 0 then periodic health checks will be disabled.
* @ref MMWLAN_DEFAULT_MIN_HEALTH_CHECK_INTERVAL_MS must always be less than or equal to
* @ref MMWLAN_DEFAULT_MAX_HEALTH_CHECK_INTERVAL_MS. Set this to @c UINT32_MAX to have the
* maximum unbounded.
*/
#define MMWLAN_DEFAULT_MAX_HEALTH_CHECK_INTERVAL_MS 120000
/**
* Specify the periodic health check intervals.
*
* The system will always schedule the periodic health check for the @c max_interval_ms
* interval. It will however monitor system activity and opportunistically perform health
* checks after @c min_interval_ms time has passed and some activity was detected. If no
* activity was detected then the health check will be performed after @c max_interval_ms
* as originally scheduled. Every time the health check is performed, the next one will be
* rescheduled to occur after @c max_interval_ms. If both @c min_interval_ms and
* @c max_interval_ms are set to 0, then periodic health checks will be disabled.
*
* @param min_interval_ms The minimum interval to wait after the last health check before
* triggering another. If this parameter is 0 then health checks will
* always happen at the @c max_interval_ms value. @c min_interval_ms
* must always be less than or equal to @c max_interval_ms.
*
* @param max_interval_ms The maximum interval to wait after the last health check before
* triggering another. If this parameter is 0 then periodic health checks
* will be disabled. @c min_interval_ms must always be less than or
* equal to @c max_interval_ms. Set this to @c UINT32_MAX to have the
* maximum unbounded.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_set_health_check_interval(uint32_t min_interval_ms, uint32_t max_interval_ms);
/** @} */
/*
* ---------------------------------------------------------------------------------------------
*/
/**
* @defgroup MMWLAN_DATA WLAN Datapath API
*
* @{
*/
/** Enumeration of link states. */
enum mmwlan_link_state {
MMWLAN_LINK_DOWN, /**< The link is down. */
MMWLAN_LINK_UP, /**< The link is up. */
};
/**
* Prototype for link state change callbacks.
*
* @param link_state The new link state.
* @param arg Opaque argument that was given when the callback was registered.
*/
typedef void (*mmwlan_link_state_cb_t)(enum mmwlan_link_state link_state, void *arg);
/**
* Register a link status callback.
*
* @note Only one link status callback may be registered. Further registration will overwrite the
* previously registered callback.
*
* @note The link status callback must not block and MMWLAN API functions may not be invoked
* from the callback.
*
* @param callback The callback to register.
* @param arg Opaque argument to be passed to the callback.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_register_link_state_cb(mmwlan_link_state_cb_t callback, void *arg);
/**
* Receive data packet callback function.
*
* @param header Buffer containing the 802.3 header for this packet.
* @param header_len Length of the @p header.
* @param payload Packet payload (excluding header).
* @param payload_len Length of @p payload.
* @param arg Opaque argument that was given when the callback was registered.
*/
typedef void (*mmwlan_rx_cb_t)(uint8_t *header, unsigned header_len, uint8_t *payload, unsigned payload_len, void *arg);
/**
* Register a receive callback.
*
* @note Only one receive callback may be registered. Further registration will overwrite the
* previously registered callback.
*
* @note Only a single receive callback may be registered at a time.
*
* @param callback The callback to register (@c NULL to unregister).
* @param arg Opaque argument to be passed to the callback.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_register_rx_cb(mmwlan_rx_cb_t callback, void *arg);
/**
* Receive data packet callback function, consuming an mmpkt.
*
* @param mmpkt The mmpkt containing the received packet, including an 802.3 header.
* Ownership of the mmpkt is passed to this callback.
* @param arg Opaque argument that was given when the callback was registered.
*/
typedef void (*mmwlan_rx_pkt_cb_t)(struct mmpkt *mmpkt, void *arg);
/**
* Register a receive callback which consumes an mmpkt.
*
* @note Only one receive callback of any type may be registered. Further registration will
* overwrite the previously registered callback.
*
* @param callback The callback to register (@c NULL to unregister).
* @param arg Opaque argument to be passed to the callback.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_register_rx_pkt_cb(mmwlan_rx_pkt_cb_t callback, void *arg);
/**
* Blocks until the transmit path is ready for transmit.
*
* @param timeout_ms The maximum time to wait, in milliseconds. If zero then this function
* does not block.
*
* @return @ref MMWLAN_SUCCESS on success, @ref MMWLAN_TIMED_OUT if the transmit datapath
* was not ready within the given timeout, or another error code as appropriate.
*/
enum mmwlan_status mmwlan_tx_wait_until_ready(uint32_t timeout_ms);
/**
* Allocate an @c mmpkt data structure for transmission with at least enough space for the given
* payload length.
*
* The return mmpkt can be passed to @ref mmwlan_tx_pkt().
*
* @param payload_len Minimum space required for payload.
* @param tid The TID that this packet will be transmitted at. This may be used
* by the allocation function to, for example, prioritize allocation of
* certain classes of traffic.
*
* @returns the allocated mmpkt on success or @c NULL on failure.
*/
struct mmpkt *mmwlan_alloc_mmpkt_for_tx(uint32_t payload_len, uint8_t tid);
/** Default transmit timeout. Used by @ref mmwlan_tx() and @ref mmwlan_tx_tid(). */
#define MMWLAN_TX_DEFAULT_TIMEOUT_MS (1000)
/** Default QoS Traffic ID (TID) to use for transmit (@c mmwlan_tx()). */
#define MMWLAN_TX_DEFAULT_QOS_TID (0)
/** Maximum Traffic ID (TID) supported for QoS traffic. */
#define MMWLAN_MAX_QOS_TID (7)
/**
* Metadata for TX packets.
*
* This structure should be initialized using @ref MMWLAN_TX_METADATA_INIT for sensible
* default values, particularly for forward compatibility with new releases that may add
* new fields to the struct. For example:
*
* @code{.c}
* enum mmwlan_status status;
* struct mmwlan_tx_metadata metadata = MMWLAN_TX_METADATA_INIT;
* // HERE: initialize metadata
* status = mmwlan_tx_pkt(pkt, &metadata);
* @endcode
*/
struct mmwlan_tx_metadata {
/**
* Traffic ID (TID) to use. Must be less than or equal to @ref MMWLAN_MAX_QOS_TID.
* @see MMWLAN_TX_DEFAULT_QOS_TID
*/
uint8_t tid;
};
/**
* Initializer for @ref mmwlan_tx_metadata.
*/
#define MMWLAN_TX_METADATA_INIT \
{ \
MMWLAN_TX_DEFAULT_QOS_TID \
}
/**
* Transmit the given packet. The packet must start with an 802.3 header, which will be
* translated into an 802.11 header by this function.
*
* @code
*
* +----------+----------+-----------+------------------+
* | DST ADDR | SRC ADDR | ETHERTYPE | Payload |
* +----------+----------+-----------+------------------+
* ^ ^ ^
* |--------802.3 MAC Header---------| |
* | |
* | |
* | |
* |<----------------------len------------------------->|
* data
*
* @endcode
*
* @note The TID should be set in the tx metadata of @p txbuf before invoking this function.
*
* @note This function is non-blocking. It will return immediately if the tx path is blocked.
* Use the tx flow control callback.
*
* @warning The given @p txbuf must be allocated by @ref mmwlan_alloc_mmpkt_for_tx().
*
* @param pkt mmpkt containing the packet to transmit. This will be consumed by this
* function.
* @param metadata Extra information relating to the packet transmission. May be @c NULL,
* in which case default values will be used.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_tx_pkt(struct mmpkt *pkt, const struct mmwlan_tx_metadata *metadata);
/**
* Transmit the given packet using the given QoS Traffic ID (TID). The packet must start with
* an 802.3 header that will be translated into an 802.11 header.
*
* @code
*
* +----------+----------+-----------+------------------+
* | DST ADDR | SRC ADDR | ETHERTYPE | Payload |
* +----------+----------+-----------+------------------+
* ^ ^ ^
* |--------802.3 MAC Header---------| |
* | |
* | |
* | |
* |<----------------------len------------------------->|
* data
*
* @endcode
*
* @param data Packet data.
* @param len Length of packet.
* @param tid TID to use (0 - @ref MMWLAN_MAX_QOS_TID).
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
static inline enum mmwlan_status mmwlan_tx_tid(const uint8_t *data, unsigned len, uint8_t tid)
{
enum mmwlan_status status;
struct mmpkt *pkt;
struct mmpktview *pktview;
struct mmwlan_tx_metadata metadata = MMWLAN_TX_METADATA_INIT;
status = mmwlan_tx_wait_until_ready(MMWLAN_TX_DEFAULT_TIMEOUT_MS);
if (status != MMWLAN_SUCCESS) {
return status;
}
pkt = mmwlan_alloc_mmpkt_for_tx(len, tid);
if (pkt == NULL) {
return MMWLAN_NO_MEM;
}
pktview = mmpkt_open(pkt);
mmpkt_append_data(pktview, data, len);
mmpkt_close(&pktview);
metadata.tid = tid;
return mmwlan_tx_pkt(pkt, &metadata);
}
/**
* Transmit the given packet using @ref MMWLAN_TX_DEFAULT_QOS_TID. The packet must start with an
* 802.3 header that will be translated into an 802.11 header.
*
* @code
*
* +----------+----------+-----------+------------------+
* | DST ADDR | SRC ADDR | ETHERTYPE | Payload |
* +----------+----------+-----------+------------------+
* ^ ^ ^
* |--------802.3 MAC Header---------| |
* | |
* | |
* | |
* |<----------------------len------------------------->|
* data
*
* @endcode
*
* @param data Packet data.
* @param len Length of packet.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
static inline enum mmwlan_status mmwlan_tx(const uint8_t *data, unsigned len)
{
return mmwlan_tx_tid(data, len, MMWLAN_TX_DEFAULT_QOS_TID);
}
/**
* Enumeration of states that can be returned by the transmit flow control callback (as
* registered by @ref mmwlan_register_tx_flow_control_cb().
*/
enum mmwlan_tx_flow_control_state {
MMWLAN_TX_READY, /**< Transmit data path ready for packets (not paused). */
MMWLAN_TX_PAUSED, /**< Transmit data path paused (blocked). */
};
/**
* Transmit flow control callback function type. When registered, this callback will be
* invoked when the transmit data path is paused and when unpaused.
*
* @note This function will always be invoked from the Upper MAC thread context. Therefore its
* invocation may not be synchronous with changes in flow control state.
*
* @param state Current transmit flow control state.
* @param arg Opaque argument that was given when the function was registered.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
typedef void (*mmwlan_tx_flow_control_cb_t)(enum mmwlan_tx_flow_control_state state, void *arg);
/**
* Register a transmit flow control callback. This callback will be invoked when the tx data path
* is paused and when unpaused.
*
* @note This function will always be invoked from the Upper MAC thread context. Therefore its
* invocation may not be synchronous with changes in flow control state.
*
* @param cb The callback to register.
* @param arg Opaque argument to pass to the callback.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_register_tx_flow_control_cb(mmwlan_tx_flow_control_cb_t cb, void *arg);
/** @} */
/*
* ---------------------------------------------------------------------------------------------
*/
/**
* @defgroup MMWLAN_STATS Statistics API
*
* API for retrieving statistics information from the WLAN subsystem.
*
* @{
*/
/** Rate control statistics data structure. */
struct mmwlan_rc_stats {
/** The number of rate table entries. */
uint32_t n_entries;
/** Rate info for each rate table entry. */
uint32_t *rate_info;
/** Total number of packets sent for each rate table entry. */
uint32_t *total_sent;
/** Total successes for each rate table entry. */
uint32_t *total_success;
};
/**
* Enumeration defined offsets into the bit field of rate information (@c rate_info in
* @ref mmwlan_rc_stats).
*
* ```
* 31 9 8 4 0
* +----------+-------+------+----+
* | Reserved | Guard | Rate | BW |
* | 23 | 1 | 4 | 4 |
* +----------+-------+------+----+
* ```
* * BW: 0 = 1 MHz, 1 = 2 MHz, 2 = 4 MHz
* * Rate: MCS Rate
* * Guard: 0 = LGI, 1 = SGI
*/
enum mmwlan_rc_stats_rate_info_offsets {
MMWLAN_RC_STATS_RATE_INFO_BW_OFFSET = 0,
MMWLAN_RC_STATS_RATE_INFO_RATE_OFFSET = 4,
MMWLAN_RC_STATS_RATE_INFO_GUARD_OFFSET = 8,
};
/**
* Retrieves WLAN rate control statistics.
*
* @note The returned data structure must be freed using @ref mmwlan_free_rc_stats().
*
* @returns the statistics data structure on success or @c NULL on failure.
*/
struct mmwlan_rc_stats *mmwlan_get_rc_stats(void);
/**
* Free a mmwlan_rc_stats structure that was allocated with @ref mmwlan_get_rc_stats().
*
* @param stats The structure to be freed (may be @c NULL).
*/
void mmwlan_free_rc_stats(struct mmwlan_rc_stats *stats);
/**
* Data structure used to represent an opaque buffer containing Morse statistics. This is
* returned by @c mmwlan_get_morse_stats() and must be freed by @c mmwlan_free_morse_stats().
*/
struct mmwlan_morse_stats {
/** Buffer containing the stats. */
uint8_t *buf;
/** Length of stats in @c buf. */
uint32_t len;
};
/**
* Retrieves statistics from the Morse transceiver. The stats are returned as a binary blob
* that can be parsed by host tools.
*
* @param core_num The core to retrieve stats for.
* @param reset Boolean indicating whether to reset the stats after retrieving.
*
* @note The returned @c mmwlan_morse_stats instance must be freed using
* @ref mmwlan_free_morse_stats.
*
* @returns a @c mmwlan_morse_stats instance on success or @c NULL on failure.
*/
struct mmwlan_morse_stats *mmwlan_get_morse_stats(uint32_t core_num, bool reset);
/**
* Frees a @c mmwlan_morse_stats instance that was returned by @c mmwlan_get_morse_stats().
*
* @param stats The instance to free. May be @ NULL.
*/
void mmwlan_free_morse_stats(struct mmwlan_morse_stats *stats);
/** @} */
/*
* ---------------------------------------------------------------------------------------------
*/
/**
* @defgroup MMWLAN_TEST Test (ATE) API
*
* Extended API particularly intended for test use cases.
*
* @{
*/
/** Enumeration of MCS rates. */
enum mmwlan_mcs {
MMWLAN_MCS_NONE = -1, /**< Use-case specific special value */
MMWLAN_MCS_0 = 0, /**< MCS0 */
MMWLAN_MCS_1, /**< MCS1 */
MMWLAN_MCS_2, /**< MCS2 */
MMWLAN_MCS_3, /**< MCS3*/
MMWLAN_MCS_4, /**< MCS4 */
MMWLAN_MCS_5, /**< MCS5 */
MMWLAN_MCS_6, /**< MCS6 */
MMWLAN_MCS_7, /**< MCS7 */
MMWLAN_MCS_MAX = MMWLAN_MCS_7 /**< Maximum supported MCS rate */
};
/** Enumeration of bandwidths. */
enum mmwlan_bw {
MMWLAN_BW_NONE = -1, /**< Use-case specific special value */
MMWLAN_BW_1MHZ = 1, /**< 1 MHz bandwidth */
MMWLAN_BW_2MHZ = 2, /**< 2 MHz bandwidth */
MMWLAN_BW_4MHZ = 4, /**< 4 MHz bandwidth */
MMWLAN_BW_8MHZ = 8, /**< 8 MHz bandwidth */
MMWLAN_BW_MAX = MMWLAN_BW_8MHZ, /**< Maximum supported bandwidth */
};
/** Enumeration of guard intervals. */
enum mmwlan_gi {
MMWLAN_GI_NONE = -1, /**< Use-case specific special value */
MMWLAN_GI_SHORT = 0, /**< Short guard interval */
MMWLAN_GI_LONG, /**< Long guard interval */
MMWLAN_GI_MAX = MMWLAN_GI_LONG, /**< Maximum valid value of this @c enum. */
};
/**
* Enable/disable override of rate control parameters.
*
* @param tx_rate_override Overrides the transmit MCS rate. Set to @ref MMWLAN_MCS_NONE for no
* override.
* @param bandwidth_override Overrides the TX bandwidth. Set to @ref MMWLAN_BW_NONE for no
* override.
* @param gi_override Overrides the guard interval. Set to @ref MMWLAN_GI_NONE for no
* override.
*
* @return @ref MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_ate_override_rate_control(enum mmwlan_mcs tx_rate_override, enum mmwlan_bw bandwidth_override,
enum mmwlan_gi gi_override);
/**
* Execute a test/debug command. The format of command and response is opaque to this API.
*
* @param[in] command Buffer containing the command to be executed. Note that buffer
* contents may be modified by this function.
* @param[in] command_len Length of the command to be executed.
* @param[out] response Buffer to received the response to the command.
* May be NULL, in which case @p response_len should also be NULL.
* @param[in,out] response_len Pointer to a @c uint32_t that is initialized to the length of the
* response buffer. On success, the value will be updated to the
* length of data that was put into the response buffer.
* May be NULL, in which case @p response must also be NULL.
*
* @returns @c MMWLAN_SUCCESS on success, else an appropriate error code.
*/
enum mmwlan_status mmwlan_ate_execute_command(uint8_t *command, uint32_t command_len, uint8_t *response, uint32_t *response_len);
/** @} */
#ifdef __cplusplus
}
#endif
/** @} */
View Git Blame Copy Permalink