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>

diff --git a/hostapd/main.c b/hostapd/main.c
index 05d6273c3fd393095e85838c792e66873ebb60dc..bc61db180b8fea9e981b661d3f344a7fdeb136fd 100644 (file)
--- a/hostapd/main.c
+++ b/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]))

diff --git a/src/ap/hostapd.c b/src/ap/hostapd.c
index 80452a8c732db2687ece2ca9c6bbd609b7d587b0..5d51c7771250597c85a717d2163dab7580cb2a6c 100644 (file)
--- a/src/ap/hostapd.c
+++ b/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)