Moved documentation from developer.txt into source code files

Use Doxygen comments for functions to replace the old text file that was
not up-to-date anymore.

hostapd/accounting.c

@@ -225,6 +225,11 @@ static void accounting_interim_update(void *eloop_ctx, void *timeout_ctx)
 }
 
 
+/**
+ * accounting_sta_start - Start STA accounting
+ * @hapd: hostapd BSS data
+ * @sta: The station
+ */
 void accounting_sta_start(struct hostapd_data *hapd, struct sta_info *sta)
 {
 	struct radius_msg *msg;
@@ -363,6 +368,11 @@ static void accounting_sta_report(struct hostapd_data *hapd,
 }
 
 
+/**
+ * accounting_sta_interim - Send a interim STA accounting report
+ * @hapd: hostapd BSS data
+ * @sta: The station
+ */
 void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta)
 {
 	if (sta->acct_session_started)
@@ -370,6 +380,11 @@ void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta)
 }
 
 
+/**
+ * accounting_sta_stop - Stop STA accounting
+ * @hapd: hostapd BSS data
+ * @sta: The station
+ */
 void accounting_sta_stop(struct hostapd_data *hapd, struct sta_info *sta)
 {
 	if (sta->acct_session_started) {
@@ -396,7 +411,15 @@ static void accounting_sta_get_id(struct hostapd_data *hapd,
 }
 
 
-/* Process the RADIUS frames from Accounting Server */
+/**
+ * accounting_receive - Process the RADIUS frames from Accounting Server
+ * @msg: RADIUS response message
+ * @req: RADIUS request message
+ * @shared_secret: RADIUS shared secret
+ * @shared_secret_len: Length of shared_secret in octets
+ * @data: Context data (struct hostapd_data *)
+ * Returns: Processing status
+ */
 static RadiusRxResult
 accounting_receive(struct radius_msg *msg, struct radius_msg *req,
 		   u8 *shared_secret, size_t shared_secret_len, void *data)
@@ -444,6 +467,11 @@ static void accounting_report_state(struct hostapd_data *hapd, int on)
 }
 
 
+/**
+ * accounting_init: Initialize accounting
+ * @hapd: hostapd BSS data
+ * Returns: 0 on success, -1 on failure
+ */
 int accounting_init(struct hostapd_data *hapd)
 {
 	/* Acct-Session-Id should be unique over reboots. If reliable clock is
@@ -460,6 +488,10 @@ int accounting_init(struct hostapd_data *hapd)
 }
 
 
+/**
+ * accounting_deinit: Deinitilize accounting
+ * @hapd: hostapd BSS data
+ */
 void accounting_deinit(struct hostapd_data *hapd)
 {
 	accounting_report_state(hapd, 0);

hostapd/config.c

@@ -1377,6 +1377,11 @@ static int hostapd_config_ht_capab(struct hostapd_config *conf,
 #endif /* CONFIG_IEEE80211N */
 
 
+/**
+ * hostapd_config_read - Read and parse a configuration file
+ * @fname: Configuration file name (including path, if needed)
+ * Returns: Allocated configuration data structure
+ */
 struct hostapd_config * hostapd_config_read(const char *fname)
 {
 	struct hostapd_config *conf;
@@ -2366,6 +2371,10 @@ static void hostapd_config_free_bss(struct hostapd_bss_config *conf)
 }
 
 
+/**
+ * hostapd_config_free - Free hostapd configuration
+ * @conf: Configuration data from hostapd_config_read().
+ */
 void hostapd_config_free(struct hostapd_config *conf)
 {
 	size_t i;
@@ -2381,8 +2390,16 @@ void hostapd_config_free(struct hostapd_config *conf)
 }
 
 
-/* Perform a binary search for given MAC address from a pre-sorted list.
- * Returns 1 if address is in the list or 0 if not. */
+/**
+ * hostapd_maclist_found - Find a MAC address from a list
+ * @list: MAC address list
+ * @num_entries: Number of addresses in the list
+ * @addr: Address to search for
+ * @vlan_id: Buffer for returning VLAN ID or %NULL if not needed
+ * Returns: 1 if address is in the list or 0 if not.
+ *
+ * Perform a binary search for given MAC address from a pre-sorted list.
+ */
 int hostapd_maclist_found(struct mac_acl_entry *list, int num_entries,
 			  const u8 *addr, int *vlan_id)
 {

hostapd/developer.txt

@@ -1,219 +0,0 @@
-Developer notes for hostapd
-===========================
-
-hostapd daemon setup, operations, and shutdown
-----------------------------------------------
-
-Files: hostapd.[ch]
-
-Externally called functions:
-  hostapd_new_assoc_sta() is called when a station associates with the AP
-
-Event loop functions:
-  handle_term() is called on SIGINT and SIGTERM to terminate hostapd process
-  handle_reload() is called on SIGHUP to reload configuration
-  handle_dump_state() is called on SIGUSR1 to dump station state data to a
-	text file
-  hostapd_rotate_wep() is called to periodically change WEP keys
-
-
-Configuration parsing
----------------------
-
-Configuration file parsing and data structure definition.
-
-Files: config.[ch]
-
-Externally called functions:
-  hostapd_config_read() is called to read and parse a configuration file;
-	allocates and returns configuration data structure
-  hostapd_config_free() is called to free configuration data structure
-  hostapd_maclist_found() is called to check whether a given address is found
-	in a list of MAC addresses
-
-
-Kernel driver access
---------------------
-
-Helper functions for configuring the Host AP kernel driver and
-accessing data from it.
-
-Files: driver.[ch]
-
-
-IEEE 802.11 frame handling (netdevice wlan#ap)
-----------------------------------------------
-
-Receive all incoming IEEE 802.11 frames from the kernel driver via
-wlan#ap interface.
-
-Files: receive.c
-
-Externally called functions:
-  hostapd_init_sockets() is called to initialize sockets for receiving and
-	sending IEEE 802.11 frames via wlan#ap interface
-
-Event loop functions:
-  handle_read() is called for each incoming packet from wlan#ap net device
-
-
-Station table
--------------
-
-Files: sta_info.[ch], ap.h
-
-Event loop functions:
-  ap_handle_timer() is called to check station activity and to remove
-	inactive stations
-
-
-IEEE 802.11 management
-----------------------
-
-IEEE 802.11 management frame sending and processing (mainly,
-authentication and association). IEEE 802.11 station functionality
-(authenticate and associate with another AP as an station).
-
-Files: ieee802_11.[ch]
-
-Externally called functions:
-  ieee802_11_mgmt() is called for each received IEEE 802.11 management frame
-	(from handle_frame() in hostapd.c)
-  ieee802_11_mgmt_cb() is called for each received TX callback of IEEE 802.11
-	management frame (from handle_tx_callback() in hostapd.c)
-  ieee802_11_send_deauth() is called to send deauthentication frame
-  ieee802_11_send_disassoc() is called to send disassociation frame
-  ieee802_11_parse_elems() is used to parse information elements in
-	IEEE 802.11 management frames
-
-Event loop functions:
-  ieee802_11_sta_authenticate() called to retry authentication (with another
-	AP)
-  ieee802_11_sta_associate() called to retry association (with another AP)
-
-
-IEEE 802.11 authentication
---------------------------
-
-Access control list for IEEE 802.11 authentication. Uses staticly
-configured ACL from configuration files or an external RADIUS
-server. Results from external RADIUS queries are cached to allow
-faster authentication frame processing.
-
-Files: ieee802_11_auth.[ch]
-
-Externally called functions:
-  hostapd_acl_init() called once during hostapd startup
-  hostapd_acl_deinit() called once during hostapd shutdown
-  hostapd_acl_recv_radius() called by IEEE 802.1X code for incoming RADIUS
-	Authentication messages (returns 0 if message was processed)
-  hostapd_allowed_address() called to check whether a specified station can be
-	authenticated
-
-Event loop functions:
-  hostapd_acl_expire() is called to expire ACL cache entries
-
-
-IEEE 802.1X Authenticator
--------------------------
-
-Files: ieee802_1x.[ch]
-
-
-Externally called functions:
-  ieee802_1x_receive() is called for each incoming EAPOL frame from the
-	wireless interface
-  ieee802_1x_new_station() is called to start IEEE 802.1X authentication when
-	a new station completes IEEE 802.11 association
-
-Event loop functions:
-  ieee802_1x_receive_auth() called for each incoming RADIUS Authentication
-	message
-
-
-EAPOL state machine
--------------------
-
-IEEE 802.1X state machine for EAPOL.
-
-Files: eapol_sm.[ch]
-
-Externally called functions:
-  eapol_sm_step() is called to advance EAPOL state machines after any change
-	that could affect their state
-
-Event loop functions:
-  eapol_port_timers_tick() called once per second to advance Port Timers state
-	machine
-
-
-IEEE 802.11f (IAPP)
--------------------
-
-Files: iapp.[ch]
-
-Externally called functions:
-  iapp_new_station() is called to start accounting session when a new station
-	completes IEEE 802.11 association or IEEE 802.1X authentication
-
-Event loop functions:
-  iapp_receive_udp() is called for incoming IAPP frames over UDP
-
-
-Per station accounting
-----------------------
-
-Send RADIUS Accounting start and stop messages to a RADIUS Accounting
-server. Process incoming RADIUS Accounting messages.
-
-Files: accounting.[ch]
-
-Externally called functions:
-  accounting_init() called once during hostapd startup
-  accounting_deinit() called once during hostapd shutdown
-  accounting_sta_start() called when a station starts new session
-  accounting_sta_stop() called when a station session is terminated
-
-Event loop functions:
-  accounting_receive() called for each incoming RADIUS Accounting message
-  accounting_list_timer() called to retransmit accounting messages and to
-	remove expired entries
-
-
-RADIUS messages
----------------
-
-RADIUS message generation and parsing functions.
-
-Files: radius.[ch]
-
-
-Event loop
-----------
-
-Event loop for registering timeout calls, signal handlers, and socket
-read events.
-
-Files: eloop.[ch]
-
-
-RC4
----
-
-RC4 encryption
-
-Files: rc4.[ch]
-
-
-MD5
----
-
-MD5 hash and HMAC-MD5.
-
-Files: md5.[ch]
-
-
-Miscellaneous helper functions
-------------------------------
-
-Files: common.[ch]

hostapd/eapol_sm.c

@@ -140,9 +140,14 @@ static void eapol_auth_tx_req(struct eapol_state_machine *sm)
 }
 
 
-/* Port Timers state machine - implemented as a function that will be called
- * once a second as a registered event loop timeout */
-
+/**
+ * eapol_port_timers_tick - Port Timers state machine
+ * @eloop_ctx: struct eapol_state_machine *
+ * @timeout_ctx: Not used
+ *
+ * This statemachine is implemented as a function that will be called
+ * once a second as a registered event loop timeout.
+ */
 static void eapol_port_timers_tick(void *eloop_ctx, void *timeout_ctx)
 {
 	struct eapol_state_machine *state = timeout_ctx;
@@ -941,6 +946,13 @@ static void eapol_sm_step_cb(void *eloop_ctx, void *timeout_ctx)
 }
 
 
+/**
+ * eapol_auth_step - Advance EAPOL state machines
+ * @sm: EAPOL state machine
+ *
+ * This function is called to advance EAPOL state machines after any change
+ * that could affect their state.
+ */
 void eapol_auth_step(struct eapol_state_machine *sm)
 {
 	/*

hostapd/hostapd.c

@@ -281,6 +281,9 @@ static void hostapd_sim_db_cb(void *ctx, void *session_ctx)
 #endif /* EAP_SERVER */
 
 
+/**
+ * handle_term - SIGINT and SIGTERM handler to terminate hostapd process
+ */
 static void handle_term(int sig, void *eloop_ctx, void *signal_ctx)
 {
 	printf("Signal %d received - terminating\n", sig);
@@ -384,6 +387,9 @@ int hostapd_reload_config(struct hostapd_iface *iface)
 
 
 #ifndef CONFIG_NATIVE_WINDOWS
+/**
+ * handle_reload - SIGHUP handler to reload configuration
+ */
 static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx)
 {
 	struct hapd_interfaces *hapds = (struct hapd_interfaces *) eloop_ctx;
@@ -402,6 +408,9 @@ static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx)
 
 
 #ifdef HOSTAPD_DUMP_STATE
+/**
+ * hostapd_dump_state - SIGUSR1 handler to dump hostapd state to a text file
+ */
 static void hostapd_dump_state(struct hostapd_data *hapd)
 {
 	FILE *f;

hostapd/iapp.c

@@ -13,7 +13,7 @@
  *
  * Note: IEEE 802.11F-2003 was a experimental use specification. It has expired
  * and IEEE has withdrawn it. In other words, it is likely better to look at
- * using some other mechanism for AP-to-AP communication than extenting the
+ * using some other mechanism for AP-to-AP communication than extending the
  * implementation here.
  */
 
@@ -238,6 +238,11 @@ static void iapp_send_layer2_update(struct iapp_data *iapp, u8 *addr)
 }
 
 
+/**
+ * iapp_new_station - IAPP processing for a new STA
+ * @iapp: IAPP data
+ * @sta: The associated station
+ */
 void iapp_new_station(struct iapp_data *iapp, struct sta_info *sta)
 {
 	struct ieee80211_mgmt *assoc;
@@ -306,6 +311,12 @@ static void iapp_process_add_notify(struct iapp_data *iapp,
 }
 
 
+/**
+ * iapp_receive_udp - Process IAPP UDP frames
+ * @sock: File descriptor for the socket
+ * @eloop_ctx: IAPP data (struct iapp_data *)
+ * @sock_ctx: Not used
+ */
 static void iapp_receive_udp(int sock, void *eloop_ctx, void *sock_ctx)
 {
 	struct iapp_data *iapp = eloop_ctx;

hostapd/ieee802_11.c

@@ -335,6 +335,12 @@ void ieee802_11_print_ssid(char *buf, const u8 *ssid, u8 len)
 }
 
 
+/**
+ * ieee802_11_send_deauth - Send Deauthentication frame
+ * @hapd: hostapd BSS data
+ * @addr: Address of the destination STA
+ * @reason: Reason code for Deauthentication
+ */
 void ieee802_11_send_deauth(struct hostapd_data *hapd, u8 *addr, u16 reason)
 {
 	struct ieee80211_mgmt mgmt;
@@ -1631,6 +1637,15 @@ static void handle_assoc_cb(struct hostapd_data *hapd,
 }
 
 
+/**
+ * ieee802_11_mgmt_cb - Process management frame TX status callback
+ * @hapd: hostapd BSS data structure (the BSS from which the management frame
+ * was sent from)
+ * @buf: management frame data (starting from IEEE 802.11 header)
+ * @len: length of frame data in octets
+ * @stype: management frame subtype from frame control field
+ * @ok: Whether the frame was ACK'ed
+ */
 void ieee802_11_mgmt_cb(struct hostapd_data *hapd, u8 *buf, size_t len,
 			u16 stype, int ok)
 {

hostapd/ieee802_11_auth.c

@@ -10,6 +10,11 @@
  * license.
  *
  * See README and COPYING for more details.
+ *
+ * Access control list for IEEE 802.11 authentication can uses statically
+ * configured ACL from configuration files or an external RADIUS server.
+ * Results from external RADIUS queries are cached to allow faster
+ * authentication frame processing.
  */
 
 #include "includes.h"
@@ -193,6 +198,17 @@ static int hostapd_radius_acl_query(struct hostapd_data *hapd, const u8 *addr,
 }
 
 
+/**
+ * hostapd_allowed_address - Check whether a specified STA can be authenticated
+ * @hapd: hostapd BSS data
+ * @addr: MAC address of the STA
+ * @msg: Authentication message
+ * @len: Length of msg in octets
+ * @session_timeout: Buffer for returning session timeout (from RADIUS)
+ * @acct_interim_interval: Buffer for returning account interval (from RADIUS)
+ * @vlan_id: Buffer for returning VLAN ID
+ * Returns: HOSTAPD_ACL_ACCEPT, HOSTAPD_ACL_REJECT, or HOSTAPD_ACL_PENDING
+ */
 int hostapd_allowed_address(struct hostapd_data *hapd, const u8 *addr,
 			    const u8 *msg, size_t len, u32 *session_timeout,
 			    u32 *acct_interim_interval, int *vlan_id)
@@ -337,6 +353,11 @@ static void hostapd_acl_expire_queries(struct hostapd_data *hapd, time_t now)
 }
 
 
+/**
+ * hostapd_acl_expire - ACL cache expiration callback
+ * @eloop_ctx: struct hostapd_data *
+ * @timeout_ctx: Not used
+ */
 static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx)
 {
 	struct hostapd_data *hapd = eloop_ctx;
@@ -350,8 +371,16 @@ static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx)
 }
 
 
-/* Return 0 if RADIUS message was a reply to ACL query (and was processed here)
- * or -1 if not. */
+/**
+ * hostapd_acl_recv_radius - Process incoming RADIUS Authentication messages
+ * @msg: RADIUS response message
+ * @req: RADIUS request message
+ * @shared_secret: RADIUS shared secret
+ * @shared_secret_len: Length of shared_secret in octets
+ * @data: Context data (struct hostapd_data *)
+ * Returns: RADIUS_RX_PROCESSED if RADIUS message was a reply to ACL query (and
+ * was processed here) or RADIUS_RX_UNKNOWN if not.
+ */
 static RadiusRxResult
 hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req,
 			u8 *shared_secret, size_t shared_secret_len,
@@ -443,6 +472,11 @@ hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req,
 }
 
 
+/**
+ * hostapd_acl_init: Initialize IEEE 802.11 ACL
+ * @hapd: hostapd BSS data
+ * Returns: 0 on success, -1 on failure
+ */
 int hostapd_acl_init(struct hostapd_data *hapd)
 {
 	if (radius_client_register(hapd->radius, RADIUS_AUTH,
@@ -455,6 +489,10 @@ int hostapd_acl_init(struct hostapd_data *hapd)
 }
 
 
+/**
+ * hostapd_acl_deinit - Deinitialize IEEE 802.11 ACL
+ * @hapd: hostapd BSS data
+ */
 void hostapd_acl_deinit(struct hostapd_data *hapd)
 {
 	struct hostapd_acl_query_data *query, *prev;

hostapd/ieee802_1x.c

@@ -647,7 +647,15 @@ static void handle_eap(struct hostapd_data *hapd, struct sta_info *sta,
 }
 
 
-/* Process the EAPOL frames from the Supplicant */
+/**
+ * ieee802_1x_receive - Process the EAPOL frames from the Supplicant
+ * @hapd: hostapd BSS data
+ * @sa: Source address (sender of the EAPOL frame)
+ * @buf: EAPOL frame
+ * @len: Length of buf in octets
+ *
+ * This function is called for each incoming EAPOL frame from the interface
+ */
 void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf,
 			size_t len)
 {
@@ -796,6 +804,14 @@ void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf,
 }
 
 
+/**
+ * ieee802_1x_new_station - Start IEEE 802.1X authentication
+ * @hapd: hostapd BSS data
+ * @sta: The station
+ *
+ * This function is called to start IEEE 802.1X authentication when a new
+ * station completes IEEE 802.11 association.
+ */
 void ieee802_1x_new_station(struct hostapd_data *hapd, struct sta_info *sta)
 {
 	struct rsn_pmksa_cache_entry *pmksa;
@@ -1186,7 +1202,15 @@ ieee802_1x_search_radius_identifier(struct hostapd_data *hapd, u8 identifier)
 }
 
 
-/* Process the RADIUS frames from Authentication Server */
+/**
+ * ieee802_1x_receive_auth - Process RADIUS frames from Authentication Server
+ * @msg: RADIUS response message
+ * @req: RADIUS request message
+ * @shared_secret: RADIUS shared secret
+ * @shared_secret_len: Length of shared_secret in octets
+ * @data: Context data (struct hostapd_data *)
+ * Returns: Processing status
+ */
 static RadiusRxResult
 ieee802_1x_receive_auth(struct radius_msg *msg, struct radius_msg *req,
 			u8 *shared_secret, size_t shared_secret_len,

hostapd/sta_info.c

@@ -219,6 +219,14 @@ void hostapd_free_stas(struct hostapd_data *hapd)
 }
 
 
+/**
+ * ap_handle_timer - Per STA timer handler
+ * @eloop_ctx: struct hostapd_data *
+ * @timeout_ctx: struct sta_info *
+ *
+ * This function is called to check station activity and to remove inactive
+ * stations.
+ */
 void ap_handle_timer(void *eloop_ctx, void *timeout_ctx)
 {
 	struct hostapd_data *hapd = eloop_ctx;

src/common/ieee802_11_common.c

@@ -116,6 +116,14 @@ static int ieee802_11_parse_vendor_specific(u8 *pos, size_t elen,
 }
 
 
+/**
+ * ieee802_11_parse_elems - Parse information elements in management frames
+ * @start: Pointer to the start of IEs
+ * @len: Length of IE buffer in octets
+ * @elems: Data structure for parsed elements
+ * @show_errors: Whether to show parsing errors in debug log
+ * Returns: Parsing result
+ */
 ParseRes ieee802_11_parse_elems(u8 *start, size_t len,
 				struct ieee802_11_elems *elems,
 				int show_errors)