Document AP mode startup functions

This provides some more details on how interfaces and BSSes are
initialized during hostapd startup.

Signed-hostap: Jouni Malinen <j@w1.fi>

hostapd/main.c

@@ -147,6 +147,9 @@ static void hostapd_logger_cb(void *ctx, const u8 *addr, unsigned int module,
 #endif /* CONFIG_NO_HOSTAPD_LOGGER */
 
 
+/**
+ * hostapd_driver_init - Preparate driver interface
+ */
 static int hostapd_driver_init(struct hostapd_iface *iface)
 {
 	struct wpa_init_params params;
@@ -226,6 +229,13 @@ static int hostapd_driver_init(struct hostapd_iface *iface)
 }
 
 
+/**
+ * hostapd_interface_init - Read configuration file and init BSS data
+ *
+ * This function is used to parse configuration file for a full interface (one
+ * or more BSSes sharing the same radio) and allocate memory for the BSS
+ * interfaces. No actiual driver operations are started.
+ */
 static struct hostapd_iface *
 hostapd_interface_init(struct hapd_interfaces *interfaces,
 		       const char *config_fname, int debug)
@@ -628,7 +638,7 @@ int main(int argc, char *argv[])
 		return -1;
 	}
 
-	/* Initialize interfaces */
+	/* Allocate and parse configuration for full interface files */
 	for (i = 0; i < interfaces.count; i++) {
 		interfaces.iface[i] = hostapd_interface_init(&interfaces,
 							     argv[optind + i],
@@ -639,6 +649,7 @@ int main(int argc, char *argv[])
 		}
 	}
 
+	/* Allocate and parse configuration for per-BSS files */
 	for (i = 0; i < num_bss_configs; i++) {
 		struct hostapd_iface *iface;
 		char *fname;
@@ -674,6 +685,14 @@ int main(int argc, char *argv[])
 		}
 	}
 
+	/*
+	 * Enable configured interfaces. Depending on channel configuration,
+	 * this may complete full initialization before returning or use a
+	 * callback mechanism to complete setup in case of operations like HT
+	 * co-ex scans, ACS, or DFS are needed to determine channel parameters.
+	 * In such case, the interface will be enabled from eloop context within
+	 * hostapd_global_run().
+	 */
 	for (i = 0; i < interfaces.count; i++) {
 		if (hostapd_driver_init(interfaces.iface[i]) ||
 		    hostapd_setup_interface(interfaces.iface[i]))

src/ap/hostapd.c

@@ -1065,6 +1065,14 @@ static int setup_interface2(struct hostapd_iface *iface)
 }
 
 
+/**
+ * hostapd_setup_interface_complete - Complete interface setup
+ *
+ * This function is called when previous steps in the interface setup has been
+ * completed. This can also start operations, e.g., DFS, that will require
+ * additional processing before interface is ready to be enabled. Such
+ * operations will call this function from eloop callbacks when finished.
+ */
 int hostapd_setup_interface_complete(struct hostapd_iface *iface, int err)
 {
 	struct hostapd_data *hapd = iface->bss[0];
@@ -1193,6 +1201,12 @@ int hostapd_setup_interface_complete(struct hostapd_iface *iface, int err)
  * and sets driver parameters based on the configuration.
  * Flushes old stations, sets the channel, encryption,
  * beacons, and WDS links based on the configuration.
+ *
+ * If interface setup requires more time, e.g., to perform HT co-ex scans, ACS,
+ * or DFS operations, this function returns 0 before such operations have been
+ * completed. The pending operations are registered into eloop and will be
+ * completed from eloop callbacks. Those callbacks end up calling
+ * hostapd_setup_interface_complete() once setup has been completed.
  */
 int hostapd_setup_interface(struct hostapd_iface *iface)
 {
@@ -1350,6 +1364,17 @@ static int ifname_in_use(struct hapd_interfaces *interfaces, const char *ifname)
 }
 
 
+/**
+ * hostapd_interface_init_bss - Read configuration file and init BSS data
+ *
+ * This function is used to parse configuration file for a BSS. This BSS is
+ * added to an existing interface sharing the same radio (if any) or a new
+ * interface is created if this is the first interface on a radio. This
+ * allocate memory for the BSS. No actual driver operations are started.
+ *
+ * This is similar to hostapd_interface_init(), but for a case where the
+ * configuration is used to add a single BSS instead of all BSSes for a radio.
+ */
 struct hostapd_iface *
 hostapd_interface_init_bss(struct hapd_interfaces *interfaces, const char *phy,
 			   const char *config_fname, int debug)