doc: Extend driver.h documentation
authorJouni Malinen <j@w1.fi>
Sat, 3 Jan 2015 14:59:14 +0000 (16:59 +0200)
committerJouni Malinen <j@w1.fi>
Sat, 3 Jan 2015 16:24:20 +0000 (18:24 +0200)
This documents some more parts of the driver wrapper interface.

Signed-off-by: Jouni Malinen <j@w1.fi>
src/ap/ap_drv_ops.c
src/ap/ap_drv_ops.h
src/drivers/driver.h

index 7486fda..8514cbe 100644 (file)
@@ -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)
index 7ad3ed7..c133be7 100644 (file)
@@ -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,
index b8ee825..8d1d1da 100644 (file)
@@ -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;
-       size_t sae_data_len;
 
+       /**
+        * 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;
+       /**
+        * mode - Mode/band (HOSTAPD_MODE_IEEE80211A, ..)
+        */
+       enum hostapd_hw_mode mode;
+
+       /**
+        * freq - Primary channel center frequency in MHz
+        */
        int freq;
+
+       /**
+        * channel - Channel number
+        */
        int channel;
-       /* for HT */
+
+       /**
+        * ht_enabled - Whether HT is enabled
+        */
        int ht_enabled;
-       int sec_channel_offset; /* 0 = HT40 disabled, -1 = HT40 enabled,
-                                * secondary channel below primary, 1 = HT40
-                                * enabled, secondary channel above primary */
 
-       /* for VHT */
+       /**
+        * 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;
+
+       /**
+        * htcaps_mask - HT Capabilities over-rides mask
+        *
+        * Pointer to struct ieee80211_ht_capabilities.
         */
-       const u8 *htcaps;       /* struct ieee80211_ht_capabilities * */
-       const u8 *htcaps_mask;  /* 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;