Add more documentation for driver ops

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 is an optional function to configure the kernel driver to
-	 * This may be an empty function if 802.1X support is always enabled.
+	 * 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
+	 * set_privacy - Enable/disable privacy (AP only)
-	 * @priv: driver private data
+	 * @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
+	 * This is an optional function to configure privacy field in the
-	 *
+	 * kernel driver for Beacon frames. This can be left undefined (set to
-	 * Configure privacy.
+	 * %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);