From 4e8f31e2ef599fbe350f4cf39ecc8f2a2e818bd6 Mon Sep 17 00:00:00 2001 From: Jouni Malinen Date: Sat, 3 Jan 2015 16:59:14 +0200 Subject: [PATCH] doc: Extend driver.h documentation This documents some more parts of the driver wrapper interface. Signed-off-by: Jouni Malinen --- src/ap/ap_drv_ops.c | 10 +- src/ap/ap_drv_ops.h | 10 +- src/drivers/driver.h | 236 +++++++++++++++++++++++++++++-------------- 3 files changed, 174 insertions(+), 82 deletions(-) diff --git a/src/ap/ap_drv_ops.c b/src/ap/ap_drv_ops.c index 7486fdaa0..8514cbe70 100644 --- a/src/ap/ap_drv_ops.c +++ b/src/ap/ap_drv_ops.c @@ -477,7 +477,8 @@ int hostapd_flush(struct hostapd_data *hapd) } -int hostapd_set_freq_params(struct hostapd_freq_params *data, int mode, +int hostapd_set_freq_params(struct hostapd_freq_params *data, + enum hostapd_hw_mode mode, int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, @@ -562,8 +563,8 @@ int hostapd_set_freq_params(struct hostapd_freq_params *data, int mode, } -int hostapd_set_freq(struct hostapd_data *hapd, int mode, int freq, - int channel, int ht_enabled, int vht_enabled, +int hostapd_set_freq(struct hostapd_data *hapd, enum hostapd_hw_mode mode, + int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, int center_segment1) { @@ -748,7 +749,8 @@ int hostapd_drv_send_action(struct hostapd_data *hapd, unsigned int freq, } -int hostapd_start_dfs_cac(struct hostapd_iface *iface, int mode, int freq, +int hostapd_start_dfs_cac(struct hostapd_iface *iface, + enum hostapd_hw_mode mode, int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, int center_segment1) diff --git a/src/ap/ap_drv_ops.h b/src/ap/ap_drv_ops.h index 7ad3ed77c..c133be754 100644 --- a/src/ap/ap_drv_ops.h +++ b/src/ap/ap_drv_ops.h @@ -57,8 +57,8 @@ int hostapd_set_ieee8021x(struct hostapd_data *hapd, int hostapd_get_seqnum(const char *ifname, struct hostapd_data *hapd, const u8 *addr, int idx, u8 *seq); int hostapd_flush(struct hostapd_data *hapd); -int hostapd_set_freq(struct hostapd_data *hapd, int mode, int freq, - int channel, int ht_enabled, int vht_enabled, +int hostapd_set_freq(struct hostapd_data *hapd, enum hostapd_hw_mode mode, + int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, int center_segment1); int hostapd_set_rts(struct hostapd_data *hapd, int rts); @@ -102,11 +102,13 @@ int hostapd_sta_assoc(struct hostapd_data *hapd, const u8 *addr, int reassoc, u16 status, const u8 *ie, size_t len); int hostapd_add_tspec(struct hostapd_data *hapd, const u8 *addr, u8 *tspec_ie, size_t tspec_ielen); -int hostapd_start_dfs_cac(struct hostapd_iface *iface, int mode, int freq, +int hostapd_start_dfs_cac(struct hostapd_iface *iface, + enum hostapd_hw_mode mode, int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, int center_segment1); -int hostapd_set_freq_params(struct hostapd_freq_params *data, int mode, +int hostapd_set_freq_params(struct hostapd_freq_params *data, + enum hostapd_hw_mode mode, int freq, int channel, int ht_enabled, int vht_enabled, int sec_channel_offset, int vht_oper_chwidth, int center_segment0, diff --git a/src/drivers/driver.h b/src/drivers/driver.h index b8ee825d3..8d1d1da26 100644 --- a/src/drivers/driver.h +++ b/src/drivers/driver.h @@ -44,6 +44,9 @@ #define HOSTAPD_CHAN_INDOOR_ONLY 0x00010000 #define HOSTAPD_CHAN_GO_CONCURRENT 0x00020000 +/** + * enum reg_change_initiator - Regulatory change initiator + */ enum reg_change_initiator { REGDOM_SET_BY_CORE, REGDOM_SET_BY_USER, @@ -52,6 +55,9 @@ enum reg_change_initiator { REGDOM_BEACON_HINT, }; +/** + * enum reg_type - Regulatory change types + */ enum reg_type { REGDOM_TYPE_UNKNOWN, REGDOM_TYPE_COUNTRY, @@ -84,8 +90,8 @@ struct hostapd_channel_data { */ u8 max_tx_power; - /* - * survey_list - Linked list of surveys + /** + * survey_list - Linked list of surveys (struct freq_survey) */ struct dl_list survey_list; @@ -104,7 +110,9 @@ struct hostapd_channel_data { long double interference_factor; #endif /* CONFIG_ACS */ - /* DFS CAC time in milliseconds */ + /** + * dfs_cac_ms - DFS CAC time in milliseconds + */ unsigned int dfs_cac_ms; }; @@ -217,6 +225,11 @@ struct hostapd_hw_modes { * constructed of the IEs that are available. This field will also need to * include SSID in IE format. All drivers are encouraged to be extended to * report all IEs to make it easier to support future additions. + * + * This structure data is followed by ie_len octets of IEs from Probe Response + * frame (or if the driver does not indicate source of IEs, these may also be + * from Beacon frame). After the first set of IEs, another set of IEs may follow + * (with beacon_ie_len octets of data) if the driver provides both IE sets. */ struct wpa_scan_res { unsigned int flags; @@ -231,13 +244,7 @@ struct wpa_scan_res { unsigned int age; size_t ie_len; size_t beacon_ie_len; - /* - * Followed by ie_len octets of IEs from Probe Response frame (or if - * the driver does not indicate source of IEs, these may also be from - * Beacon frame). After the first set of IEs, another set of IEs may - * follow (with beacon_ie_len octets of data) if the driver provides - * both IE sets. - */ + /* Followed by ie_len + beacon_ie_len octets of IE data */ }; /** @@ -403,34 +410,95 @@ struct wpa_driver_auth_params { */ int p2p; + /** + * sae_data - SAE elements for Authentication frame + * + * This buffer starts with the Authentication transaction sequence + * number field. If SAE is not used, this pointer is %NULL. + */ const u8 *sae_data; + + /** + * sae_data_len - Length of sae_data buffer in octets + */ size_t sae_data_len; - }; +/** + * enum wps_mode - WPS mode + */ enum wps_mode { - WPS_MODE_NONE /* no WPS provisioning being used */, - WPS_MODE_OPEN /* WPS provisioning with AP that is in open mode */, - WPS_MODE_PRIVACY /* WPS provisioning with AP that is using protection - */ + /** + * WPS_MODE_NONE - No WPS provisioning being used + */ + WPS_MODE_NONE, + + /** + * WPS_MODE_OPEN - WPS provisioning with AP that is in open mode + */ + WPS_MODE_OPEN, + + /** + * WPS_MODE_PRIVACY - WPS provisioning with AP that is using protection + */ + WPS_MODE_PRIVACY }; +/** + * struct hostapd_freq_params - Channel parameters + */ struct hostapd_freq_params { - int mode; - int freq; - int channel; - /* for HT */ - int ht_enabled; - int sec_channel_offset; /* 0 = HT40 disabled, -1 = HT40 enabled, - * secondary channel below primary, 1 = HT40 - * enabled, secondary channel above primary */ + /** + * mode - Mode/band (HOSTAPD_MODE_IEEE80211A, ..) + */ + enum hostapd_hw_mode mode; - /* for VHT */ + /** + * freq - Primary channel center frequency in MHz + */ + int freq; + + /** + * channel - Channel number + */ + int channel; + + /** + * ht_enabled - Whether HT is enabled + */ + int ht_enabled; + + /** + * sec_channel_offset - Secondary channel offset for HT40 + * + * 0 = HT40 disabled, + * -1 = HT40 enabled, secondary channel below primary, + * 1 = HT40 enabled, secondary channel above primary + */ + int sec_channel_offset; + + /** + * vht_enabled - Whether VHT is enabled + */ int vht_enabled; - /* valid for both HT and VHT, center_freq2 is non-zero - * only for bandwidth 80 and an 80+80 channel */ - int center_freq1, center_freq2; + /** + * center_freq1 - Segment 0 center frequency in MHz + * + * Valid for both HT and VHT. + */ + int center_freq1; + + /** + * center_freq2 - Segment 1 center frequency in MHz + * + * Non-zero only for bandwidth 80 and an 80+80 channel + */ + int center_freq2; + + /** + * bandwidth - Channel bandwidth in MHz (20, 40, 80, 160) + */ int bandwidth; }; @@ -684,12 +752,21 @@ struct wpa_driver_associate_params { int disable_ht; /** - * HT Capabilities over-rides. Only bits set in the mask will be used, - * and not all values are used by the kernel anyway. Currently, MCS, - * MPDU and MSDU fields are used. + * htcaps - HT Capabilities over-rides + * + * Only bits set in the mask will be used, and not all values are used + * by the kernel anyway. Currently, MCS, MPDU and MSDU fields are used. + * + * Pointer to struct ieee80211_ht_capabilities. */ - const u8 *htcaps; /* struct ieee80211_ht_capabilities * */ - const u8 *htcaps_mask; /* struct ieee80211_ht_capabilities * */ + const u8 *htcaps; + + /** + * htcaps_mask - HT Capabilities over-rides mask + * + * Pointer to struct ieee80211_ht_capabilities. + */ + const u8 *htcaps_mask; #ifdef CONFIG_VHT_OVERRIDES /** @@ -975,6 +1052,7 @@ struct wpa_driver_capa { #define WPA_DRIVER_CAPA_KEY_MGMT_FT 0x00000020 #define WPA_DRIVER_CAPA_KEY_MGMT_FT_PSK 0x00000040 #define WPA_DRIVER_CAPA_KEY_MGMT_WAPI_PSK 0x00000080 + /** Bitfield of supported key management suites */ unsigned int key_mgmt; #define WPA_DRIVER_CAPA_ENC_WEP40 0x00000001 @@ -990,94 +1068,97 @@ struct wpa_driver_capa { #define WPA_DRIVER_CAPA_ENC_BIP_GMAC_256 0x00000400 #define WPA_DRIVER_CAPA_ENC_BIP_CMAC_256 0x00000800 #define WPA_DRIVER_CAPA_ENC_GTK_NOT_USED 0x00001000 + /** Bitfield of supported cipher suites */ unsigned int enc; #define WPA_DRIVER_AUTH_OPEN 0x00000001 #define WPA_DRIVER_AUTH_SHARED 0x00000002 #define WPA_DRIVER_AUTH_LEAP 0x00000004 + /** Bitfield of supported IEEE 802.11 authentication algorithms */ unsigned int auth; -/* Driver generated WPA/RSN IE */ +/** Driver generated WPA/RSN IE */ #define WPA_DRIVER_FLAGS_DRIVER_IE 0x00000001 -/* Driver needs static WEP key setup after association command */ +/** Driver needs static WEP key setup after association command */ #define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC 0x00000002 -/* Driver takes care of all DFS operations */ +/** Driver takes care of all DFS operations */ #define WPA_DRIVER_FLAGS_DFS_OFFLOAD 0x00000004 -/* Driver takes care of RSN 4-way handshake internally; PMK is configured with +/** Driver takes care of RSN 4-way handshake internally; PMK is configured with * struct wpa_driver_ops::set_key using alg = WPA_ALG_PMK */ #define WPA_DRIVER_FLAGS_4WAY_HANDSHAKE 0x00000008 +/** Driver is for a wired Ethernet interface */ #define WPA_DRIVER_FLAGS_WIRED 0x00000010 -/* Driver provides separate commands for authentication and association (SME in +/** Driver provides separate commands for authentication and association (SME in * wpa_supplicant). */ #define WPA_DRIVER_FLAGS_SME 0x00000020 -/* Driver supports AP mode */ +/** Driver supports AP mode */ #define WPA_DRIVER_FLAGS_AP 0x00000040 -/* Driver needs static WEP key setup after association has been completed */ +/** Driver needs static WEP key setup after association has been completed */ #define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC_DONE 0x00000080 -/* Driver supports dynamic HT 20/40 MHz channel changes during BSS lifetime */ +/** Driver supports dynamic HT 20/40 MHz channel changes during BSS lifetime */ #define WPA_DRIVER_FLAGS_HT_2040_COEX 0x00000100 -/* Driver supports concurrent P2P operations */ +/** Driver supports concurrent P2P operations */ #define WPA_DRIVER_FLAGS_P2P_CONCURRENT 0x00000200 -/* +/** * Driver uses the initial interface as a dedicated management interface, i.e., * it cannot be used for P2P group operations or non-P2P purposes. */ #define WPA_DRIVER_FLAGS_P2P_DEDICATED_INTERFACE 0x00000400 -/* This interface is P2P capable (P2P GO or P2P Client) */ +/** This interface is P2P capable (P2P GO or P2P Client) */ #define WPA_DRIVER_FLAGS_P2P_CAPABLE 0x00000800 -/* Driver supports station and key removal when stopping an AP */ +/** Driver supports station and key removal when stopping an AP */ #define WPA_DRIVER_FLAGS_AP_TEARDOWN_SUPPORT 0x00001000 -/* +/** * Driver uses the initial interface for P2P management interface and non-P2P * purposes (e.g., connect to infra AP), but this interface cannot be used for * P2P group operations. */ #define WPA_DRIVER_FLAGS_P2P_MGMT_AND_NON_P2P 0x00002000 -/* +/** * Driver is known to use sane error codes, i.e., when it indicates that * something (e.g., association) fails, there was indeed a failure and the * operation does not end up getting completed successfully later. */ #define WPA_DRIVER_FLAGS_SANE_ERROR_CODES 0x00004000 -/* Driver supports off-channel TX */ +/** Driver supports off-channel TX */ #define WPA_DRIVER_FLAGS_OFFCHANNEL_TX 0x00008000 -/* Driver indicates TX status events for EAPOL Data frames */ +/** Driver indicates TX status events for EAPOL Data frames */ #define WPA_DRIVER_FLAGS_EAPOL_TX_STATUS 0x00010000 -/* Driver indicates TX status events for Deauth/Disassoc frames */ +/** Driver indicates TX status events for Deauth/Disassoc frames */ #define WPA_DRIVER_FLAGS_DEAUTH_TX_STATUS 0x00020000 -/* Driver supports roaming (BSS selection) in firmware */ +/** Driver supports roaming (BSS selection) in firmware */ #define WPA_DRIVER_FLAGS_BSS_SELECTION 0x00040000 -/* Driver supports operating as a TDLS peer */ +/** Driver supports operating as a TDLS peer */ #define WPA_DRIVER_FLAGS_TDLS_SUPPORT 0x00080000 -/* Driver requires external TDLS setup/teardown/discovery */ +/** Driver requires external TDLS setup/teardown/discovery */ #define WPA_DRIVER_FLAGS_TDLS_EXTERNAL_SETUP 0x00100000 -/* Driver indicates support for Probe Response offloading in AP mode */ +/** Driver indicates support for Probe Response offloading in AP mode */ #define WPA_DRIVER_FLAGS_PROBE_RESP_OFFLOAD 0x00200000 -/* Driver supports U-APSD in AP mode */ +/** Driver supports U-APSD in AP mode */ #define WPA_DRIVER_FLAGS_AP_UAPSD 0x00400000 -/* Driver supports inactivity timer in AP mode */ +/** Driver supports inactivity timer in AP mode */ #define WPA_DRIVER_FLAGS_INACTIVITY_TIMER 0x00800000 -/* Driver expects user space implementation of MLME in AP mode */ +/** Driver expects user space implementation of MLME in AP mode */ #define WPA_DRIVER_FLAGS_AP_MLME 0x01000000 -/* Driver supports SAE with user space SME */ +/** Driver supports SAE with user space SME */ #define WPA_DRIVER_FLAGS_SAE 0x02000000 -/* Driver makes use of OBSS scan mechanism in wpa_supplicant */ +/** Driver makes use of OBSS scan mechanism in wpa_supplicant */ #define WPA_DRIVER_FLAGS_OBSS_SCAN 0x04000000 -/* Driver supports IBSS (Ad-hoc) mode */ +/** Driver supports IBSS (Ad-hoc) mode */ #define WPA_DRIVER_FLAGS_IBSS 0x08000000 -/* Driver supports radar detection */ +/** Driver supports radar detection */ #define WPA_DRIVER_FLAGS_RADAR 0x10000000 -/* Driver supports a dedicated interface for P2P Device */ +/** Driver supports a dedicated interface for P2P Device */ #define WPA_DRIVER_FLAGS_DEDICATED_P2P_DEVICE 0x20000000 -/* Driver supports QoS Mapping */ +/** Driver supports QoS Mapping */ #define WPA_DRIVER_FLAGS_QOS_MAPPING 0x40000000 -/* Driver supports CSA in AP mode */ +/** Driver supports CSA in AP mode */ #define WPA_DRIVER_FLAGS_AP_CSA 0x80000000 -/* Driver supports mesh */ +/** Driver supports mesh */ #define WPA_DRIVER_FLAGS_MESH 0x0000000100000000ULL -/* Driver support ACS offload */ +/** Driver support ACS offload */ #define WPA_DRIVER_FLAGS_ACS_OFFLOAD 0x0000000200000000ULL -/* Driver supports key management offload */ +/** Driver supports key management offload */ #define WPA_DRIVER_FLAGS_KEY_MGMT_OFFLOAD 0x0000000400000000ULL u64 flags; @@ -1087,9 +1168,16 @@ struct wpa_driver_capa { unsigned int wmm_ac_supported:1; + /** Maximum number of supported active probe SSIDs */ int max_scan_ssids; + + /** Maximum number of supported active probe SSIDs for sched_scan */ int max_sched_scan_ssids; + + /** Whether sched_scan (offloaded scanning) is supported */ int sched_scan_supported; + + /** Maximum number of supported match sets for sched_scan */ int max_match_sets; /** @@ -1107,13 +1195,13 @@ struct wpa_driver_capa { * probe_resp_offloads - Bitmap of supported protocols by the driver * for Probe Response offloading. */ -/* Driver Probe Response offloading support for WPS ver. 1 */ +/** Driver Probe Response offloading support for WPS ver. 1 */ #define WPA_DRIVER_PROBE_RESP_OFFLOAD_WPS 0x00000001 -/* Driver Probe Response offloading support for WPS ver. 2 */ +/** Driver Probe Response offloading support for WPS ver. 2 */ #define WPA_DRIVER_PROBE_RESP_OFFLOAD_WPS2 0x00000002 -/* Driver Probe Response offloading support for P2P */ +/** Driver Probe Response offloading support for P2P */ #define WPA_DRIVER_PROBE_RESP_OFFLOAD_P2P 0x00000004 -/* Driver Probe Response offloading support for IEEE 802.11u (Interworking) */ +/** Driver Probe Response offloading support for IEEE 802.11u (Interworking) */ #define WPA_DRIVER_PROBE_RESP_OFFLOAD_INTERWORKING 0x00000008 unsigned int probe_resp_offloads; @@ -1135,11 +1223,11 @@ struct wpa_driver_capa { struct wowlan_triggers wowlan_triggers; -/* Driver adds the DS Params Set IE in Probe Request frames */ +/** Driver adds the DS Params Set IE in Probe Request frames */ #define WPA_DRIVER_FLAGS_DS_PARAM_SET_IE_IN_PROBES 0x00000001 -/* Driver adds the WFA TPC IE in Probe Request frames */ +/** Driver adds the WFA TPC IE in Probe Request frames */ #define WPA_DRIVER_FLAGS_WFA_TPC_IE_IN_PROBES 0x00000002 -/* Driver handles quiet period requests */ +/** Driver handles quiet period requests */ #define WPA_DRIVER_FLAGS_QUIET 0x00000004 /** * Driver is capable of inserting the current TX power value into the body of @@ -4330,7 +4418,7 @@ union wpa_event_data { * survey_results - Survey result data for EVENT_SURVEY * @freq_filter: Requested frequency survey filter, 0 if request * was for all survey data - * @survey_list: Linked list of survey data + * @survey_list: Linked list of survey data (struct freq_survey) */ struct survey_results { unsigned int freq_filter;