From e8244f733036ffbfbb1d8e31496d481a19e9b03f Mon Sep 17 00:00:00 2001 From: Chaitanya Tata Date: Fri, 30 Jun 2023 01:08:34 +0530 Subject: [PATCH 1/3] net: wifi: Remove obsolete comment Support for legacy types has been added primarily to identify in scan results. Signed-off-by: Chaitanya Tata --- include/zephyr/net/wifi.h | 3 --- 1 file changed, 3 deletions(-) diff --git a/include/zephyr/net/wifi.h b/include/zephyr/net/wifi.h index 9c65f319790160..a21f7874239e48 100644 --- a/include/zephyr/net/wifi.h +++ b/include/zephyr/net/wifi.h @@ -19,9 +19,6 @@ #define WIFI_LISTEN_INTERVAL_MIN 0 #define WIFI_LISTEN_INTERVAL_MAX 65535 -/* Not having support for legacy types is deliberate to enforce - * higher security. - */ enum wifi_security_type { WIFI_SECURITY_TYPE_NONE = 0, WIFI_SECURITY_TYPE_PSK, From f4df04261f0a35f0409746c3c51523ebf4a900d5 Mon Sep 17 00:00:00 2001 From: Chaitanya Tata Date: Fri, 30 Jun 2023 01:32:34 +0530 Subject: [PATCH 2/3] net: wifi: Add doxygen style comments Fix doxygen formatting and add comments. Signed-off-by: Chaitanya Tata --- include/zephyr/net/wifi.h | 167 ++++++++++++++---- include/zephyr/net/wifi_mgmt.h | 306 +++++++++++++++++++++++++++++---- 2 files changed, 412 insertions(+), 61 deletions(-) diff --git a/include/zephyr/net/wifi.h b/include/zephyr/net/wifi.h index a21f7874239e48..0278680cd1db08 100644 --- a/include/zephyr/net/wifi.h +++ b/include/zephyr/net/wifi.h @@ -6,7 +6,12 @@ /** * @file - * @brief General WiFi Definitions + * @brief IEEE 802.11 protocol and general Wi-Fi definitions. + */ + +/** + * @addtogroup wifi_mgmt + * @{ */ #ifndef ZEPHYR_INCLUDE_NET_WIFI_H_ @@ -19,14 +24,23 @@ #define WIFI_LISTEN_INTERVAL_MIN 0 #define WIFI_LISTEN_INTERVAL_MAX 65535 +/** IEEE 802.11 security types. */ enum wifi_security_type { + /** No security. */ WIFI_SECURITY_TYPE_NONE = 0, + /** WPA2-PSK security. */ WIFI_SECURITY_TYPE_PSK, + /** WPA2-PSK-SHA256 security. */ WIFI_SECURITY_TYPE_PSK_SHA256, + /** WPA3-SAE security. */ WIFI_SECURITY_TYPE_SAE, + /** GB 15629.11-2003 WAPI security. */ WIFI_SECURITY_TYPE_WAPI, + /** EAP security - Enterprise. */ WIFI_SECURITY_TYPE_EAP, + /** WEP security. */ WIFI_SECURITY_TYPE_WEP, + /** WPA-PSK security. */ WIFI_SECURITY_TYPE_WPA_PSK, __WIFI_SECURITY_TYPE_AFTER_LAST, @@ -34,9 +48,7 @@ enum wifi_security_type { WIFI_SECURITY_TYPE_UNKNOWN }; -/** - * wifi_security_txt - Get the security type as a text string - */ +/** Helper function to get user-friendly security type name. */ static inline const char *wifi_security_txt(enum wifi_security_type security) { switch (security) { @@ -62,10 +74,13 @@ static inline const char *wifi_security_txt(enum wifi_security_type security) } } -/* Management frame protection (IEEE 802.11w) options */ +/** IEEE 802.11w - Management frame protection. */ enum wifi_mfp_options { + /** MFP disabled. */ WIFI_MFP_DISABLE = 0, + /** MFP optional. */ WIFI_MFP_OPTIONAL, + /** MFP required. */ WIFI_MFP_REQUIRED, __WIFI_MFP_AFTER_LAST, @@ -73,9 +88,7 @@ enum wifi_mfp_options { WIFI_MFP_UNKNOWN }; -/** - * wifi_mfp_txt - Get the MFP as a text string - */ +/** Helper function to get user-friendly MFP name.*/ static inline const char *wifi_mfp_txt(enum wifi_mfp_options mfp) { switch (mfp) { @@ -91,9 +104,13 @@ static inline const char *wifi_mfp_txt(enum wifi_mfp_options mfp) } } +/** IEEE 802.11 operational frequency bands (not exhaustive). */ enum wifi_frequency_bands { + /** 2.4GHz band. */ WIFI_FREQ_BAND_2_4_GHZ = 0, + /** 5GHz band. */ WIFI_FREQ_BAND_5_GHZ, + /** 6GHz band (Wi-Fi 6E, also extends to 7GHz). */ WIFI_FREQ_BAND_6_GHZ, __WIFI_FREQ_BAND_AFTER_LAST, @@ -101,9 +118,7 @@ enum wifi_frequency_bands { WIFI_FREQ_BAND_UNKNOWN }; -/** - * wifi_mode_txt - Get the interface mode type as a text string - */ +/** Helper function to get user-friendly frequency band name. */ static inline const char *wifi_band_txt(enum wifi_frequency_bands band) { switch (band) { @@ -126,17 +141,30 @@ static inline const char *wifi_band_txt(enum wifi_frequency_bands band) #define WIFI_CHANNEL_MAX 233 #define WIFI_CHANNEL_ANY 255 -/* Based on https://w1.fi/wpa_supplicant/devel/defs_8h.html#a4aeb27c1e4abd046df3064ea9756f0bc */ +/** Wi-Fi interface states. + * + * Based on https://w1.fi/wpa_supplicant/devel/defs_8h.html#a4aeb27c1e4abd046df3064ea9756f0bc + */ enum wifi_iface_state { + /** Interface is disconnected. */ WIFI_STATE_DISCONNECTED = 0, + /** Interface is disabled (administratively). */ WIFI_STATE_INTERFACE_DISABLED, + /** No enabled networks in the configuration. */ WIFI_STATE_INACTIVE, + /** Interface is scanning for networks. */ WIFI_STATE_SCANNING, + /** Authentication with a network is in progress. */ WIFI_STATE_AUTHENTICATING, + /** Association with a network is in progress. */ WIFI_STATE_ASSOCIATING, + /** Association with a network completed. */ WIFI_STATE_ASSOCIATED, + /** 4-way handshake with a network is in progress. */ WIFI_STATE_4WAY_HANDSHAKE, + /** Group Key exchange with a network is in progress. */ WIFI_STATE_GROUP_HANDSHAKE, + /** All authentication completed, ready to pass data. */ WIFI_STATE_COMPLETED, __WIFI_STATE_AFTER_LAST, @@ -144,9 +172,7 @@ enum wifi_iface_state { WIFI_STATE_UNKNOWN }; -/** - * wifi_state_txt - Get the connection state name as a text string - */ +/** Helper function to get user-friendly interface state name. */ static inline const char *wifi_state_txt(enum wifi_iface_state state) { switch (state) { @@ -176,13 +202,22 @@ static inline const char *wifi_state_txt(enum wifi_iface_state state) } } -/* Based on https://w1.fi/wpa_supplicant/devel/structwpa__ssid.html#a625821e2acfc9014f3b3de6e6593ffb7 */ +/** Wi-Fi interface modes. + * + * Based on https://w1.fi/wpa_supplicant/devel/defs_8h.html#a4aeb27c1e4abd046df3064ea9756f0bc + */ enum wifi_iface_mode { + /** Infrastructure station mode. */ WIFI_MODE_INFRA = 0, + /** IBSS (ad-hoc) station mode. */ WIFI_MODE_IBSS = 1, + /** AP mode. */ WIFI_MODE_AP = 2, + /** P2P group owner mode. */ WIFI_MODE_P2P_GO = 3, + /** P2P group formation mode. */ WIFI_MODE_P2P_GROUP_FORMATION = 4, + /** 802.11s Mesh mode. */ WIFI_MODE_MESH = 5, __WIFI_MODE_AFTER_LAST, @@ -190,9 +225,7 @@ enum wifi_iface_mode { WIFI_MODE_UNKNOWN }; -/** - * wifi_mode_txt - Get the interface mode type as a text string - */ +/** Helper function to get user-friendly interface mode name. */ static inline const char *wifi_mode_txt(enum wifi_iface_mode mode) { switch (mode) { @@ -214,16 +247,28 @@ static inline const char *wifi_mode_txt(enum wifi_iface_mode mode) } } -/* As per https://en.wikipedia.org/wiki/Wi-Fi#Versions_and_generations */ +/** Wi-Fi link operating modes + * + * As per https://en.wikipedia.org/wiki/Wi-Fi#Versions_and_generations. + */ enum wifi_link_mode { + /** 802.11 (legacy). */ WIFI_0 = 0, + /** 802.11b. */ WIFI_1, + /** 802.11a. */ WIFI_2, + /** 802.11g. */ WIFI_3, + /** 802.11n. */ WIFI_4, + /** 802.11ac. */ WIFI_5, + /** 802.11ax. */ WIFI_6, + /** 802.11ax 6GHz. */ WIFI_6E, + /** 802.11be. */ WIFI_7, __WIFI_LINK_MODE_AFTER_LAST, @@ -231,9 +276,7 @@ enum wifi_link_mode { WIFI_LINK_MODE_UNKNOWN }; -/** - * wifi_link_mode_txt - Get the link mode type as a text string - */ +/** Helper function to get user-friendly link mode name. */ static inline const char *wifi_link_mode_txt(enum wifi_link_mode link_mode) { switch (link_mode) { @@ -261,13 +304,19 @@ static inline const char *wifi_link_mode_txt(enum wifi_link_mode link_mode) } } +/** Wi-Fi scanning types. */ enum wifi_scan_type { + /** Active scanning (default). */ WIFI_SCAN_TYPE_ACTIVE = 0, + /** Passive scanning. */ WIFI_SCAN_TYPE_PASSIVE, }; +/** Wi-Fi power save states. */ enum wifi_ps { + /** Power save disabled. */ WIFI_PS_DISABLED = 0, + /** Power save enabled. */ WIFI_PS_ENABLED, }; @@ -276,11 +325,14 @@ static const char * const wifi_ps2str[] = { [WIFI_PS_ENABLED] = "Power save enabled", }; +/** Wi-Fi power save modes. */ enum wifi_ps_mode { + /** Legacy power save mode. */ WIFI_PS_MODE_LEGACY = 0, /* This has to be configured before connecting to the AP, * as support for ADDTS action frames is not available. */ + /** WMM power save mode. */ WIFI_PS_MODE_WMM, }; @@ -289,8 +341,11 @@ static const char * const wifi_ps_mode2str[] = { [WIFI_PS_MODE_WMM] = "WMM power save", }; +/** Wi-Fi Target Wake Time (TWT) operations. */ enum wifi_twt_operation { + /* TWT setup operation */ WIFI_TWT_SETUP = 0, + /* TWT teardown operation */ WIFI_TWT_TEARDOWN, }; @@ -299,9 +354,13 @@ static const char * const wifi_twt_operation2str[] = { [WIFI_TWT_TEARDOWN] = "TWT teardown", }; +/** Wi-Fi Target Wake Time (TWT) negotiation types. */ enum wifi_twt_negotiation_type { + /* TWT individual negotiation */ WIFI_TWT_INDIVIDUAL = 0, + /* TWT broadcast negotiation */ WIFI_TWT_BROADCAST, + /* TWT wake TBTT negotiation */ WIFI_TWT_WAKE_TBTT }; @@ -311,25 +370,32 @@ static const char * const wifi_twt_negotiation_type2str[] = { [WIFI_TWT_WAKE_TBTT] = "TWT wake TBTT negotiation", }; +/** Wi-Fi Target Wake Time (TWT) setup commands. */ enum wifi_twt_setup_cmd { - /* TWT Requests */ + /** TWT Requests */ + /* TWT setup request */ WIFI_TWT_SETUP_CMD_REQUEST = 0, + /* TWT setup suggest (parameters can be changed by AP) */ WIFI_TWT_SETUP_CMD_SUGGEST, + /* TWT setup demand (parameters can not be changed by AP) */ WIFI_TWT_SETUP_CMD_DEMAND, - /* TWT Responses */ + /** TWT Responses */ + /* TWT setup grouping (grouping of TWT flows) */ WIFI_TWT_SETUP_CMD_GROUPING, + /* TWT setup accept (parameters accepted by AP) */ WIFI_TWT_SETUP_CMD_ACCEPT, + /* TWT setup alternate (alternate parameters suggested by AP) */ WIFI_TWT_SETUP_CMD_ALTERNATE, + /* TWT setup dictate (parameters dictated by AP) */ WIFI_TWT_SETUP_CMD_DICTATE, + /* TWT setup reject (parameters rejected by AP) */ WIFI_TWT_SETUP_CMD_REJECT, }; static const char * const wifi_twt_setup_cmd2str[] = { - /* TWT Requests */ [WIFI_TWT_SETUP_CMD_REQUEST] = "TWT request", [WIFI_TWT_SETUP_CMD_SUGGEST] = "TWT suggest", [WIFI_TWT_SETUP_CMD_DEMAND] = "TWT demand", - /* TWT Responses */ [WIFI_TWT_SETUP_CMD_GROUPING] = "TWT grouping", [WIFI_TWT_SETUP_CMD_ACCEPT] = "TWT accept", [WIFI_TWT_SETUP_CMD_ALTERNATE] = "TWT alternate", @@ -337,23 +403,37 @@ static const char * const wifi_twt_setup_cmd2str[] = { [WIFI_TWT_SETUP_CMD_REJECT] = "TWT reject", }; +/** Wi-Fi Target Wake Time (TWT) negotiation status. */ enum wifi_twt_setup_resp_status { - /* TWT Setup response status */ + /** TWT response received for TWT request */ WIFI_TWT_RESP_RECEIVED = 0, + /** TWT response not received for TWT request */ WIFI_TWT_RESP_NOT_RECEIVED, }; +/** Target Wake Time (TWT) error codes. */ enum wifi_twt_fail_reason { + /** Unspecified error */ WIFI_TWT_FAIL_UNSPECIFIED, + /** Command execution failed */ WIFI_TWT_FAIL_CMD_EXEC_FAIL, + /** Operation not supported */ WIFI_TWT_FAIL_OPERATION_NOT_SUPPORTED, + /** Unable to get interface status */ WIFI_TWT_FAIL_UNABLE_TO_GET_IFACE_STATUS, + /** Device not connected to AP */ WIFI_TWT_FAIL_DEVICE_NOT_CONNECTED, + /** Peer not HE (802.11ax/Wi-Fi 6) capable */ WIFI_TWT_FAIL_PEER_NOT_HE_CAPAB, + /** Peer not TWT capable */ WIFI_TWT_FAIL_PEER_NOT_TWT_CAPAB, + /** A TWT flow is already in progress */ WIFI_TWT_FAIL_OPERATION_IN_PROGRESS, + /** Invalid negotiated flow id */ WIFI_TWT_FAIL_INVALID_FLOW_ID, + /** IP address not assigned or configured */ WIFI_TWT_FAIL_IP_NOT_ASSIGNED, + /** Flow already exists */ WIFI_TWT_FAIL_FLOW_ALREADY_EXISTS, }; @@ -378,6 +458,7 @@ static const char * const twt_err_code_tbl[] = { "Flow already exists", }; +/** Helper function to get user-friendly TWT error code name. */ static inline const char *get_twt_err_code_str(int16_t err_no) { if ((err_no) < (int16_t)ARRAY_SIZE(twt_err_code_tbl)) { @@ -387,16 +468,25 @@ static inline const char *get_twt_err_code_str(int16_t err_no) return ""; } +/** Wi-Fi power save parameters. */ enum ps_param_type { + /** Power save state. */ WIFI_PS_PARAM_STATE, + /** Power save listen interval. */ WIFI_PS_PARAM_LISTEN_INTERVAL, + /** Power save wakeup mode. */ WIFI_PS_PARAM_WAKEUP_MODE, + /** Power save mode. */ WIFI_PS_PARAM_MODE, + /** Power save timeout. */ WIFI_PS_PARAM_TIMEOUT, }; +/** Wi-Fi power save modes. */ enum wifi_ps_wakeup_mode { + /** DTIM based wakeup. */ WIFI_PS_WAKEUP_MODE_DTIM = 0, + /** Listen interval based wakeup. */ WIFI_PS_WAKEUP_MODE_LISTEN_INTERVAL, }; @@ -405,31 +495,40 @@ static const char * const wifi_ps_wakeup_mode2str[] = { [WIFI_PS_WAKEUP_MODE_LISTEN_INTERVAL] = "PS wakeup mode listen interval", }; +/** Wi-Fi power save error codes. */ enum wifi_config_ps_param_fail_reason { + /** Unspecified error */ WIFI_PS_PARAM_FAIL_UNSPECIFIED, + /** Command execution failed */ WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL, + /** Parameter not supported */ WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED, + /** Unable to get interface status */ WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS, + /** Device not connected to AP */ WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED, + /** Device already connected to AP */ WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED, + /** Listen interval out of range */ WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID, }; static const char * const ps_param_config_err_code_tbl[] = { - [WIFI_PS_PARAM_FAIL_UNSPECIFIED] = "Unspecfied", + [WIFI_PS_PARAM_FAIL_UNSPECIFIED] = "Unspecified", [WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL] = "Command Execution failed", [WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED] = "Operation not supported", [WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS] = "Unable to get iface status", [WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED] = - "Can not set while device not connected", + "Cannot set parameters while device not connected", [WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED] = - "Can not set while device already connected", + "Cannot set parameters while device connected", [WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID] = - "Can not set due to invalid range", + "Parameter out of range", }; +/** Helper function to get user-friendly power save error code name. */ static inline const char *get_ps_config_err_code_str(int16_t err_no) { if ((err_no) < (int16_t)ARRAY_SIZE(ps_param_config_err_code_tbl)) { @@ -438,4 +537,8 @@ static inline const char *get_ps_config_err_code_str(int16_t err_no) return ""; } + +/** + * @} + */ #endif /* ZEPHYR_INCLUDE_NET_WIFI_H_ */ diff --git a/include/zephyr/net/wifi_mgmt.h b/include/zephyr/net/wifi_mgmt.h index fdb2814408b13f..09d875f1394fa8 100644 --- a/include/zephyr/net/wifi_mgmt.h +++ b/include/zephyr/net/wifi_mgmt.h @@ -21,6 +21,11 @@ extern "C" { #endif +/** + * @addtogroup wifi_mgmt + * @{ + */ + /* Management part definitions */ #define _NET_WIFI_LAYER NET_MGMT_LAYER_L2 @@ -30,18 +35,31 @@ extern "C" { NET_MGMT_LAYER_CODE(_NET_WIFI_CODE)) #define _NET_WIFI_EVENT (_NET_WIFI_BASE | NET_MGMT_EVENT_BIT) +/** Wi-Fi management commands */ enum net_request_wifi_cmd { + /** Scan for Wi-Fi networks */ NET_REQUEST_WIFI_CMD_SCAN = 1, + /** Connect to a Wi-Fi network */ NET_REQUEST_WIFI_CMD_CONNECT, + /** Disconnect from a Wi-Fi network */ NET_REQUEST_WIFI_CMD_DISCONNECT, + /** Enable AP mode */ NET_REQUEST_WIFI_CMD_AP_ENABLE, + /** Disable AP mode */ NET_REQUEST_WIFI_CMD_AP_DISABLE, + /** Get interface status */ NET_REQUEST_WIFI_CMD_IFACE_STATUS, + /** Set power save status */ NET_REQUEST_WIFI_CMD_PS, + /** Set power save mode */ NET_REQUEST_WIFI_CMD_PS_MODE, + /** Setup or teardown TWT flow */ NET_REQUEST_WIFI_CMD_TWT, + /** Get power save config */ NET_REQUEST_WIFI_CMD_PS_CONFIG, + /** Set or get regulatory domain */ NET_REQUEST_WIFI_CMD_REG_DOMAIN, + /** Set power save timeout */ NET_REQUEST_WIFI_CMD_PS_TIMEOUT, NET_REQUEST_WIFI_CMD_MAX }; @@ -105,15 +123,27 @@ NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_WIFI_REG_DOMAIN); NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_WIFI_PS_TIMEOUT); +/** Wi-Fi management events */ enum net_event_wifi_cmd { + /** Scan results available */ NET_EVENT_WIFI_CMD_SCAN_RESULT = 1, + /** Scan done */ NET_EVENT_WIFI_CMD_SCAN_DONE, + /** Connect result */ NET_EVENT_WIFI_CMD_CONNECT_RESULT, + /** Disconnect result */ NET_EVENT_WIFI_CMD_DISCONNECT_RESULT, + /** Interface status */ NET_EVENT_WIFI_CMD_IFACE_STATUS, + /** TWT events */ NET_EVENT_WIFI_CMD_TWT, + /** TWT sleep status: awake or sleeping, can be used by application + * to determine if it can send data or not. + */ NET_EVENT_WIFI_CMD_TWT_SLEEP_STATE, + /** Raw scan results available */ NET_EVENT_WIFI_CMD_RAW_SCAN_RESULT, + /** Disconnect complete */ NET_EVENT_WIFI_CMD_DISCONNECT_COMPLETE, }; @@ -144,8 +174,11 @@ enum net_event_wifi_cmd { #define NET_EVENT_WIFI_DISCONNECT_COMPLETE \ (_NET_WIFI_EVENT | NET_EVENT_WIFI_CMD_DISCONNECT_COMPLETE) +/** Wi-Fi scan parameters */ struct wifi_scan_params { - /* The scan_type is only a hint to the underlying Wi-Fi chip for the + /** Scan type, see enum wifi_scan_type. + * + * The scan_type is only a hint to the underlying Wi-Fi chip for the * preferred mode of scan. The actual mode of scan can depend on factors * such as the Wi-Fi chip implementation support, regulatory domain * restrictions etc. @@ -153,102 +186,155 @@ struct wifi_scan_params { enum wifi_scan_type scan_type; }; -/* Each result is provided to the net_mgmt_event_callback +/** Wi-Fi scan result, each result is provided to the net_mgmt_event_callback * via its info attribute (see net_mgmt.h) */ struct wifi_scan_result { + /** SSID */ uint8_t ssid[WIFI_SSID_MAX_LEN]; + /** SSID length */ uint8_t ssid_length; - + /** Frequency band */ uint8_t band; + /** Channel */ uint8_t channel; + /** Security type */ enum wifi_security_type security; + /** MFP options */ enum wifi_mfp_options mfp; + /** RSSI */ int8_t rssi; - + /** BSSID */ uint8_t mac[WIFI_MAC_ADDR_LEN]; + /** BSSID length */ uint8_t mac_length; }; +/** Wi-Fi connect request parameters */ struct wifi_connect_req_params { + /** SSID */ const uint8_t *ssid; + /** SSID length */ uint8_t ssid_length; /* Max 32 */ - + /** Pre-shared key */ uint8_t *psk; + /** Pre-shared key length */ uint8_t psk_length; /* Min 8 - Max 64 */ - - uint8_t *sae_password; /* Optional with fallback to psk */ + /** SAE password (same as PSK but with no length restrictions), optional */ + uint8_t *sae_password; + /** SAE password length */ uint8_t sae_password_length; /* No length restrictions */ - + /** Frequency band */ uint8_t band; + /** Channel */ uint8_t channel; + /** Security type */ enum wifi_security_type security; + /** MFP options */ enum wifi_mfp_options mfp; - int timeout; /* SYS_FOREVER_MS for no timeout */ + /** Connect timeout in seconds, SYS_FOREVER_MS for no timeout */ + int timeout; }; +/** Generic Wi-Fi status for commands and events */ struct wifi_status { int status; }; +/** Wi-Fi interface status */ struct wifi_iface_status { - int state; /* enum wifi_iface_state */ + /** Interface state, see enum wifi_iface_state */ + int state; + /** SSID length */ unsigned int ssid_len; + /** SSID */ char ssid[WIFI_SSID_MAX_LEN]; + /** BSSID */ char bssid[WIFI_MAC_ADDR_LEN]; + /** Frequency band */ enum wifi_frequency_bands band; + /** Channel */ unsigned int channel; + /** Interface mode, see enum wifi_iface_mode */ enum wifi_iface_mode iface_mode; + /** Link mode, see enum wifi_link_mode */ enum wifi_link_mode link_mode; + /** Security type, see enum wifi_security_type */ enum wifi_security_type security; + /** MFP options, see enum wifi_mfp_options */ enum wifi_mfp_options mfp; + /** RSSI */ int rssi; + /** DTIM period */ unsigned char dtim_period; + /** Beacon interval */ unsigned short beacon_interval; + /** is TWT capable? */ bool twt_capable; }; +/** Wi-Fi power save parameters */ struct wifi_ps_params { + /* Power save state */ enum wifi_ps enabled; + /* Listen interval */ unsigned short listen_interval; + /** Wi-Fi power save wakeup mode */ enum wifi_ps_wakeup_mode wakeup_mode; + /** Wi-Fi power save mode */ enum wifi_ps_mode mode; - /* This is the time out to wait after sending a TX packet + /** Wi-Fi power save timeout + * + * This is the time out to wait after sending a TX packet * before going back to power save (in ms) to receive any replies * from the AP. Zero means this feature is disabled. * * It's a tradeoff between power consumption and latency. */ unsigned int timeout_ms; + /** Wi-Fi power save type */ enum ps_param_type type; + /** Wi-Fi power save fail reason */ enum wifi_config_ps_param_fail_reason fail_reason; }; +/** Wi-Fi TWT parameters */ struct wifi_twt_params { + /** TWT operation, see enum wifi_twt_operation */ enum wifi_twt_operation operation; + /** TWT negotiation type, see enum wifi_twt_negotiation_type */ enum wifi_twt_negotiation_type negotiation_type; + /** TWT setup command, see enum wifi_twt_setup_cmd */ enum wifi_twt_setup_cmd setup_cmd; + /** TWT setup response status, see enum wifi_twt_setup_resp_status */ enum wifi_twt_setup_resp_status resp_status; - /* Map requests to responses */ + /** Dialog token, used to map requests to responses */ uint8_t dialog_token; - /* Map setup with teardown */ + /** Flow ID, used to map setup with teardown */ uint8_t flow_id; union { + /** Setup specific parameters */ struct { - /* Interval = Wake up time + Sleeping time */ + /**Interval = Wake up time + Sleeping time */ uint64_t twt_interval; + /** Requestor or responder */ bool responder; + /** Trigger enabled or disabled */ bool trigger; + /** Implicit or explicit */ bool implicit; + /** Announced or unannounced */ bool announce; - /* Wake up time */ + /** Wake up time */ uint32_t twt_wake_interval; } setup; + /** Teardown specific parameters */ struct { - /* Only for Teardown */ + /** Teardown all flows */ bool teardown_all; } teardown; }; + /** TWT fail reason, see enum wifi_twt_fail_reason */ enum wifi_twt_fail_reason fail_reason; }; @@ -257,87 +343,201 @@ struct wifi_twt_params { #define WIFI_MAX_TWT_INTERVAL_US (LONG_MAX - 1) /* 256 (u8) * 1TU */ #define WIFI_MAX_TWT_WAKE_INTERVAL_US 262144 + +/** Wi-Fi TWT flow information */ struct wifi_twt_flow_info { - /* Interval = Wake up time + Sleeping time */ + /** Interval = Wake up time + Sleeping time */ uint64_t twt_interval; - /* Map requests to responses */ + /** Dialog token, used to map requests to responses */ uint8_t dialog_token; - /* Map setup with teardown */ + /** Flow ID, used to map setup with teardown */ uint8_t flow_id; + /** TWT negotiation type, see enum wifi_twt_negotiation_type */ enum wifi_twt_negotiation_type negotiation_type; + /** Requestor or responder */ bool responder; + /** Trigger enabled or disabled */ bool trigger; + /** Implicit or explicit */ bool implicit; + /** Announced or unannounced */ bool announce; - /* Wake up time */ + /** Wake up time */ uint32_t twt_wake_interval; }; +/** Wi-Fi power save configuration */ struct wifi_ps_config { + /** Number of TWT flows */ char num_twt_flows; + /** TWT flow details */ struct wifi_twt_flow_info twt_flows[WIFI_MAX_TWT_FLOWS]; + /** Power save configuration */ struct wifi_ps_params ps_params; }; -/* Generic get/set operation for any command*/ +/** Generic get/set operation for any command*/ enum wifi_mgmt_op { + /** Get operation */ WIFI_MGMT_GET = 0, + /** Set operation */ WIFI_MGMT_SET = 1, }; +/** Regulatory domain information or configuration */ struct wifi_reg_domain { + /* Regulatory domain operation */ enum wifi_mgmt_op oper; - /* Ignore all other regulatory hints */ + /** Ignore all other regulatory hints over this one */ bool force; + /** Country code: ISO/IEC 3166-1 alpha-2 */ uint8_t country_code[WIFI_COUNTRY_CODE_LEN]; }; +/** Wi-Fi TWT sleep states */ enum wifi_twt_sleep_state { + /** TWT sleep state: sleeping */ WIFI_TWT_STATE_SLEEP = 0, + /** TWT sleep state: awake */ WIFI_TWT_STATE_AWAKE = 1, }; -#ifdef CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS +#if defined(CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS) || defined(__DOXYGEN__) +/** Wi-Fi raw scan result */ struct wifi_raw_scan_result { + /** RSSI */ int8_t rssi; + /** Frame length */ int frame_length; + /** Frequency */ unsigned short frequency; + /** Raw scan data */ uint8_t data[CONFIG_WIFI_MGMT_RAW_SCAN_RESULT_LENGTH]; }; #endif /* CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS */ #include +/** Scan result callback + * + * @param iface Network interface + * @param status Scan result status + * @param entry Scan result entry + */ typedef void (*scan_result_cb_t)(struct net_if *iface, int status, struct wifi_scan_result *entry); #ifdef CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS +/** Raw scan result callback + * + * @param iface Network interface + * @param status Raw scan result status + * @param entry Raw scan result entry + */ typedef void (*raw_scan_result_cb_t)(struct net_if *iface, int status, struct wifi_raw_scan_result *entry); #endif /* CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS */ + +/** Wi-Fi management API */ struct wifi_mgmt_ops { - /* cb parameter is the cb that should be called for each - * result by the driver. The wifi mgmt part will take care of - * raising the necessary event etc... + /** Scan for Wi-Fi networks + * + * @param dev Pointer to the device structure for the driver instance. + * @param params Scan parameters + * @param cb Callback to be called for each result + * cb parameter is the cb that should be called for each + * result by the driver. The wifi mgmt part will take care of + * raising the necessary event etc. + * + * @return 0 if ok, < 0 if error */ int (*scan)(const struct device *dev, struct wifi_scan_params *params, scan_result_cb_t cb); + /** Connect to a Wi-Fi network + * + * @param dev Pointer to the device structure for the driver instance. + * @param params Connect parameters + * + * @return 0 if ok, < 0 if error + */ int (*connect)(const struct device *dev, struct wifi_connect_req_params *params); + /** Disconnect from a Wi-Fi network + * + * @param dev Pointer to the device structure for the driver instance. + * + * @return 0 if ok, < 0 if error + */ int (*disconnect)(const struct device *dev); + /** Enable AP mode + * + * @param dev Pointer to the device structure for the driver instance. + * @param params AP mode parameters + * + * @return 0 if ok, < 0 if error + */ int (*ap_enable)(const struct device *dev, struct wifi_connect_req_params *params); + /** Disable AP mode + * + * @param dev Pointer to the device structure for the driver instance. + * + * @return 0 if ok, < 0 if error + */ int (*ap_disable)(const struct device *dev); + /** Get interface status + * + * @param dev Pointer to the device structure for the driver instance. + * @param status Interface status + * + * @return 0 if ok, < 0 if error + */ int (*iface_status)(const struct device *dev, struct wifi_iface_status *status); -#ifdef CONFIG_NET_STATISTICS_WIFI +#if defined(CONFIG_NET_STATISTICS_WIFI) || defined(__DOXYGEN__) + /** Get Wi-Fi statistics + * + * @param dev Pointer to the device structure for the driver instance. + * @param stats Wi-Fi statistics + * + * @return 0 if ok, < 0 if error + */ int (*get_stats)(const struct device *dev, struct net_stats_wifi *stats); #endif /* CONFIG_NET_STATISTICS_WIFI */ + /** Set power save status + * + * @param dev Pointer to the device structure for the driver instance. + * @param params Power save parameters + * + * @return 0 if ok, < 0 if error + */ int (*set_power_save)(const struct device *dev, struct wifi_ps_params *params); + /** Setup or teardown TWT flow + * + * @param dev Pointer to the device structure for the driver instance. + * @param params TWT parameters + * + * @return 0 if ok, < 0 if error + */ int (*set_twt)(const struct device *dev, struct wifi_twt_params *params); + /** Get power save config + * + * @param dev Pointer to the device structure for the driver instance. + * @param config Power save config + * + * @return 0 if ok, < 0 if error + */ int (*get_power_save_config)(const struct device *dev, struct wifi_ps_config *config); + /** Set or get regulatory domain + * + * @param dev Pointer to the device structure for the driver instance. + * @param reg_domain Regulatory domain + * + * @return 0 if ok, < 0 if error + */ int (*reg_domain)(const struct device *dev, struct wifi_reg_domain *reg_domain); }; +/** Wi-Fi management offload API */ struct net_wifi_mgmt_offload { /** * Mandatory to get in first position. @@ -345,11 +545,14 @@ struct net_wifi_mgmt_offload { * net_if_api structure. So we make current structure pointer * that can be casted to a net_if_api structure pointer. */ -#ifdef CONFIG_WIFI_USE_NATIVE_NETWORKING +#if defined(CONFIG_WIFI_USE_NATIVE_NETWORKING) || defined(__DOXYGEN__) + /** Ethernet API */ struct ethernet_api wifi_iface; #else + /** Offloaded network device API */ struct offloaded_if_api wifi_iface; #endif + /** Wi-Fi management API */ const struct wifi_mgmt_ops *const wifi_mgmt_api; }; @@ -358,18 +561,63 @@ struct net_wifi_mgmt_offload { */ BUILD_ASSERT(offsetof(struct net_wifi_mgmt_offload, wifi_iface) == 0); +/** Wi-Fi management connect result event + * + * @param iface Network interface + * @param status Connect result status + */ void wifi_mgmt_raise_connect_result_event(struct net_if *iface, int status); + +/** Wi-Fi management disconnect result event + * + * @param iface Network interface + * @param status Disconnect result status + */ void wifi_mgmt_raise_disconnect_result_event(struct net_if *iface, int status); + +/** Wi-Fi management interface status event + * + * @param iface Network interface + * @param iface_status Interface status + */ void wifi_mgmt_raise_iface_status_event(struct net_if *iface, struct wifi_iface_status *iface_status); + +/** Wi-Fi management TWT event + * + * @param iface Network interface + * @param twt_params TWT parameters + */ void wifi_mgmt_raise_twt_event(struct net_if *iface, struct wifi_twt_params *twt_params); + +/** Wi-Fi management TWT sleep state event + * + * @param iface Network interface + * @param twt_sleep_state TWT sleep state + */ void wifi_mgmt_raise_twt_sleep_state(struct net_if *iface, int twt_sleep_state); -#ifdef CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS + +#if defined(CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS) || defined(__DOXYGEN__) +/** Wi-Fi management raw scan result event + * + * @param iface Network interface + * @param raw_scan_info Raw scan result + */ void wifi_mgmt_raise_raw_scan_result_event(struct net_if *iface, struct wifi_raw_scan_result *raw_scan_info); #endif /* CONFIG_WIFI_MGMT_RAW_SCAN_RESULTS */ + +/** Wi-Fi management disconnect complete event + * + * @param iface Network interface + * @param status Disconnect complete status + */ void wifi_mgmt_raise_disconnect_complete_event(struct net_if *iface, int status); + +/** + * @} + */ #ifdef __cplusplus } #endif From 5dbc8700d0a7bba7ec587bcf4bf9bd4e64656d81 Mon Sep 17 00:00:00 2001 From: Chaitanya Tata Date: Fri, 30 Jun 2023 02:20:49 +0530 Subject: [PATCH 3/3] doc: net: Add Wi-Fi management Add Wi-Fi management docs and APIs. Signed-off-by: Chaitanya Tata --- doc/connectivity/networking/api/net_tech.rst | 1 + doc/connectivity/networking/api/wifi.rst | 30 ++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 doc/connectivity/networking/api/wifi.rst diff --git a/doc/connectivity/networking/api/net_tech.rst b/doc/connectivity/networking/api/net_tech.rst index 3575db974b5439..910ec4e0cce526 100644 --- a/doc/connectivity/networking/api/net_tech.rst +++ b/doc/connectivity/networking/api/net_tech.rst @@ -10,3 +10,4 @@ Networking Technologies ieee802154.rst thread.rst ppp.rst + wifi.rst diff --git a/doc/connectivity/networking/api/wifi.rst b/doc/connectivity/networking/api/wifi.rst new file mode 100644 index 00000000000000..be29d9f8ddaafb --- /dev/null +++ b/doc/connectivity/networking/api/wifi.rst @@ -0,0 +1,30 @@ +.. _wifi_mgmt: + +Wi-Fi Management +################ + +Overview +======== + +The Wi-Fi management API is used to manage Wi-Fi networks. It supports below modes: + +* IEEE802.11 Station (STA) +* IEEE802.11 Access Point (AP) + +Only personal mode security is supported with below types: + +* Open +* WPA2-PSK +* WPA3-PSK-256 +* WPA3-SAE + +The Wi-Fi management API is implemented in the `wifi_mgmt` module as a part of the networking L2 stack. +Currently, two types of Wi-Fi drivers are supported: + +* Networking or socket offloaded drivers +* Native L2 Ethernet drivers + +API Reference +************* + +.. doxygengroup:: wifi_mgmt