Add more documentation for driver ops

diff --git a/src/drivers/driver.h b/src/drivers/driver.h
index 1bb55956a4614f85117cd56f2bcac3649e66c831..c5a158a598869cd78dd298d87140f6b3f17472d7 100644 (file)
--- a/src/drivers/driver.h
+++ b/src/drivers/driver.h
@@ -1042,52 +1042,153 @@ struct wpa_driver_ops {
        int (*authenticate)(void *priv,
                            struct wpa_driver_auth_params *params);
 
+       /**
+        * set_beacon - Set Beacon frame template
+        * @iface: Interface name (main interface or virtual BSS)
+        * @priv: Private driver interface data
+        * @head: Beacon head from IEEE 802.11 header to IEs before TIM IE
+        * @head_len: Length of the head buffer in octets
+        * @tail: Beacon tail following TIM IE
+        * @tail_len: Length of the tail buffer in octets
+        * @dtim_period: DTIM period
+        * @beacon_int: Beacon interval
+        * Returns: 0 on success, -1 on failure
+        *
+        * This function is used to configure Beacon template for the driver in
+        * AP mode. The driver is responsible for building the full Beacon
+        * frame by concatenating the head part with TIM IE generated by the
+        * driver/firmware and finishing with the tail part.
+        */
        int (*set_beacon)(const char *ifname, void *priv,
                          const u8 *head, size_t head_len,
                          const u8 *tail, size_t tail_len, int dtim_period,
                          int beacon_int);
 
+       /**
+        * hapd_init - Initialize driver interface (hostapd only)
+        * @hapd: Pointer to hostapd context
+        * @params: Configuration for the driver wrapper
+        * Returns: Pointer to private data, %NULL on failure
+        *
+        * This function is used instead of init() or init2() when the driver
+        * wrapper is used withh hostapd.
+        */
        void * (*hapd_init)(struct hostapd_data *hapd,
                            struct wpa_init_params *params);
+
+       /**
+        * hapd_deinit - Deinitialize driver interface (hostapd only)
+        * @priv: Private driver interface data from hapd_init()
+        */
        void (*hapd_deinit)(void *priv);
 
        /**
-        * set_8021x - enable/disable IEEE 802.1X support
+        * set_ieee8021x - Enable/disable IEEE 802.1X support (AP only)
         * @ifname: Interface name (for multi-SSID/VLAN support)
-        * @priv: driver private data
+        * @priv: Private driver interface data
         * @enabled: 1 = enable, 0 = disable
-        *
         * Returns: 0 on success, -1 on failure
         *
-        * Configure the kernel driver to enable/disable 802.1X support.
-        * This may be an empty function if 802.1X support is always enabled.
+        * This is an optional function to configure the kernel driver to
+        * enable/disable 802.1X support. This can be left undefined (set to
+        * %NULL) if IEEE 802.1X support is always enabled.
         */
        int (*set_ieee8021x)(const char *ifname, void *priv, int enabled);
 
        /**
-        * set_privacy - enable/disable privacy
-        * @priv: driver private data
+        * set_privacy - Enable/disable privacy (AP only)
+        * @priv: Private driver interface data
         * @enabled: 1 = privacy enabled, 0 = disabled
+        * Returns: 0 on success, -1 on failure
         *
-        * Return: 0 on success, -1 on failure
-        *
-        * Configure privacy.
+        * This is an optional function to configure privacy field in the
+        * kernel driver for Beacon frames. This can be left undefined (set to
+        * %NULL) if the driver uses the Beacon template from set_beacon().
         */
        int (*set_privacy)(const char *ifname, void *priv, int enabled);
 
+       /**
+        * get_seqnum - Fetch the current TSC/packet number (AP only)
+        * @ifname: The interface name (main or virtual)
+        * @priv: Private driver interface data
+        * @addr: MAC address of the station or %NULL for group keys
+        * @idx: Key index
+        * @seq: Buffer for returning the latest used TSC/packet number
+        * Returns: 0 on success, -1 on failure
+        *
+        * This function is used to fetch the last used TSC/packet number for
+        * a TKIP or CCMP key.
+        */
        int (*get_seqnum)(const char *ifname, void *priv, const u8 *addr,
                          int idx, u8 *seq);
+
+       /**
+        * get_seqnum_igtk - Fetch the IGTK packet number (AP only)
+        * @ifname: The interface name (main or virtual)
+        * @priv: Private driver interface data
+        * @addr: %NULL for group keys
+        * @idx: Key index
+        * @seq: Buffer for returning the last used packet number
+        * Returns: 0 on success, -1 on failure
+        *
+        * This function is used to fetch the last used packet number for an
+        * IGTK key.
+        */
        int (*get_seqnum_igtk)(const char *ifname, void *priv, const u8 *addr,
                               int idx, u8 *seq);
+
+       /**
+        * flush - Flush all association stations (AP only)
+        * @priv: Private driver interface data
+        * Returns: 0 on success, -1 on failure
+        *
+        * This function requests the driver to disassociate all associated
+        * stations. This function does not need to be implemented if the
+        * driver does not process association frames internally.
+        */
        int (*flush)(void *priv);
+
+       /**
+        * set_generic_elem - Add IEs into Beacon/Probe Response frames (AP)
+        * @ifname: The interface name (main or virtual BSS)
+        * @priv: Private driver interface data
+        * @elem: Information elements
+        * @elem_len: Length of the elem buffer in octets
+        * Returns: 0 on success, -1 on failure
+        *
+        * This is an optional function to add information elements in the
+        * kernel driver for Beacon and Probe Response frames. This can be left
+        * undefined (set to %NULL) if the driver uses the Beacon template from
+        * set_beacon().
+        */
        int (*set_generic_elem)(const char *ifname, void *priv, const u8 *elem,
                                size_t elem_len);
 
+       /**
+        * read_sta_data - Fetch station data (AP only)
+        * @priv: Private driver interface data
+        * @data: Buffer for returning station information
+        * @addr: MAC address of the station
+        * Returns: 0 on success, -1 on failure
+        */
        int (*read_sta_data)(void *priv, struct hostap_sta_driver_data *data,
                             const u8 *addr);
+
+       /**
+        * hapd_send_eapol - Send an EAPOL packet (AP only)
+        * @priv: private driver interface data
+        * @addr: Destination MAC address
+        * @data: EAPOL packet starting with IEEE 802.1X header
+        * @data_len: Length of the EAPOL packet in octets
+        * @encrypt: Whether the frame should be encrypted
+        * @own_addr: Source MAC address
+        *
+        * Returns: 0 on success, -1 on failure
+        */
        int (*hapd_send_eapol)(void *priv, const u8 *addr, const u8 *data,
                               size_t data_len, int encrypt,
                               const u8 *own_addr);
+
        int (*sta_deauth)(void *priv, const u8 *own_addr, const u8 *addr,
                          int reason);
        int (*sta_disassoc)(void *priv, const u8 *own_addr, const u8 *addr,
@@ -1120,8 +1221,8 @@ struct wpa_driver_ops {
 
        /**
         * if_add - Add a virtual interface
-        * @priv: Private driver interface data
         * @iface: Parent interface name
+        * @priv: Private driver interface data
         * @type: Interface type
         * @ifname: Interface name for the new virtual interface
         * @addr: Local address to use for the interface or %NULL to use the
@@ -1141,10 +1242,25 @@ struct wpa_driver_ops {
         */
        int (*if_remove)(void *priv, enum wpa_driver_if_type type,
                         const char *ifname);
+       /**
+        * set_sta_vlan - Bind a station into a specific interface (AP only)
+        * @priv: Private driver interface data
+        * @ifname: Interface (main or virtual BSS or VLAN)
+        * @addr: MAC address of the associated station
+        * @vlan_id: VLAN ID
+        * Returns: 0 on success, -1 on failure
+        *
+        * This function is used to bind a station to a specific virtual
+        * interface. It is only used if when virtual interfaces are supported,
+        * e.g., to assign stations to different VLAN interfaces based on
+        * information from a RADIUS server. This allows separate broadcast
+        * domains to be used with a single BSS.
+        */
        int (*set_sta_vlan)(void *priv, const u8 *addr, const char *ifname,
                            int vlan_id);
+
        /**
-        * commit - Optional commit changes handler
+        * commit - Optional commit changes handler (AP only)
         * @priv: driver private data
         * Returns: 0 on success, -1 on failure
         *
@@ -1166,8 +1282,33 @@ struct wpa_driver_ops {
                             const u8 *ht_capab, size_t ht_capab_len,
                             const u8 *ht_oper, size_t ht_oper_len);
 
+       /**
+        * set_wps_beacon_ie - Add WPS IE into Beacon frames (AP only)
+        * @ifname: The interface name (main or virtual BSS)
+        * @priv: Private driver interface data
+        * @ie: WPS IE
+        * @len: Length of the ie buffer in octets
+        * Returns: 0 on success, -1 on failure
+        *
+        * This is an optional function to add WPS IE in the kernel driver for
+        * Beacon frames. This can be left undefined (set to %NULL) if the
+        * driver uses the Beacon template from set_beacon().
+        */
        int (*set_wps_beacon_ie)(const char *ifname, void *priv,
                                 const u8 *ie, size_t len);
+
+       /**
+        * set_wps_probe_resp_ie - Add WPS IE into Probe Response frames (AP)
+        * @ifname: The interface name (main or virtual BSS)
+        * @priv: Private driver interface data
+        * @ie: WPS IE
+        * @len: Length of the ie buffer in octets
+        * Returns: 0 on success, -1 on failure
+        *
+        * This is an optional function to add WPS IE in the kernel driver for
+        * Beacon frames. This can be left undefined (set to %NULL) if the
+        * driver does process Probe Request frames.
+        */
        int (*set_wps_probe_resp_ie)(const char *ifname, void *priv,
                                     const u8 *ie, size_t len);