[PATCH] wireless: add comments to functions
Alexander Couzens
lynxis at fe80.eu
Fri Jan 8 11:44:41 EST 2021
Signed-off-by: Alexander Couzens <lynxis at fe80.eu>
---
wireless.c | 42 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
diff --git a/wireless.c b/wireless.c
index 818f7c994da8..4422656065b0 100644
--- a/wireless.c
+++ b/wireless.c
@@ -11,6 +11,21 @@
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*/
+
+/* The wireless configuration is projected on the following objects
+ *
+ * 1. wireless device
+ * 2. wireless interface
+ * 3. wireless vlan
+ * 4. wireless station
+ *
+ * A wireless device is a phy or simplified a wireless card.
+ * A wireless interface is a SSID on a phy.
+ * A wireless vlan can be assigned to a wireless interface. A wireless interface can
+ * have multiple vlans.
+ * A wireless station is a client connected to an wireless interface.
+ */
+
#include <signal.h>
#include "netifd.h"
#include "wireless.h"
@@ -508,6 +523,7 @@ wireless_device_mark_down(struct wireless_device *wdev)
wdev_handle_config_change(wdev);
}
+/* timeout callback to protect the tear down */
static void
wireless_device_setup_timeout(struct uloop_timeout *timeout)
{
@@ -553,6 +569,7 @@ __wireless_device_set_down(struct wireless_device *wdev)
wireless_device_run_handler(wdev, false);
}
+/* ubus callback network.wireless.notify, command = up */
static void
wireless_device_mark_up(struct wireless_device *wdev)
{
@@ -665,6 +682,7 @@ wdev_create(struct wireless_device *wdev)
wdev->config = blob_memdup(wdev->config);
}
+/* vlist update call for wireless device list */
static void
wdev_update(struct vlist_tree *tree, struct vlist_node *node_new,
struct vlist_node *node_old)
@@ -684,6 +702,7 @@ wdev_update(struct vlist_tree *tree, struct vlist_node *node_new,
}
}
+/* wireless netifd script handler */
static void
wireless_add_handler(const char *script, const char *name, json_object *obj)
{
@@ -751,6 +770,7 @@ void wireless_init(void)
netifd_init_script_handlers(drv_fd, wireless_add_handler);
}
+/* parse blob config into the wireless interface object */
static void
wireless_interface_init_config(struct wireless_interface *vif)
{
@@ -772,6 +792,7 @@ wireless_interface_init_config(struct wireless_interface *vif)
vif->ap_mode = !strcmp(blobmsg_get_string(cur), "ap");
}
+/* vlist update call for wireless interface list */
static void
vif_update(struct vlist_tree *tree, struct vlist_node *node_new,
struct vlist_node *node_old)
@@ -817,6 +838,7 @@ vif_update(struct vlist_tree *tree, struct vlist_node *node_new,
wdev_set_config_state(wdev, IFC_RELOAD);
}
+/* parse blob config into the vlan object */
static void
wireless_vlan_init_config(struct wireless_vlan *vlan)
{
@@ -834,6 +856,7 @@ wireless_vlan_init_config(struct wireless_vlan *vlan)
vlan->isolate = blobmsg_get_bool(cur);
}
+/* vlist update call for vlan list */
static void
vlan_update(struct vlist_tree *tree, struct vlist_node *node_new,
struct vlist_node *node_old)
@@ -878,6 +901,7 @@ vlan_update(struct vlist_tree *tree, struct vlist_node *node_new,
wdev_set_config_state(wdev, IFC_RELOAD);
}
+/* vlist update call for station list */
static void
station_update(struct vlist_tree *tree, struct vlist_node *node_new,
struct vlist_node *node_old)
@@ -944,6 +968,8 @@ done:
wireless_close_script_proc_fd(wdev);
}
+/* watchdog and garbage collector for wireless processes.
+ * It cleans up terminated processes. If a process is a requirement for the wireless device, it retries the setup */
static void
wireless_device_check_script_tasks(struct uloop_timeout *timeout)
{
@@ -968,6 +994,7 @@ wireless_device_check_script_tasks(struct uloop_timeout *timeout)
uloop_timeout_set(&wdev->script_check, 1000);
}
+/* creates a wireless device object. Called by config */
void
wireless_device_create(struct wireless_driver *drv, const char *name, struct blob_attr *data)
{
@@ -1019,6 +1046,7 @@ wireless_device_create(struct wireless_driver *drv, const char *name, struct blo
vlist_add(&wireless_devices, &wdev->node, wdev->name);
}
+/* creates a wireless station object. Called by config */
void
wireless_station_create(struct wireless_device *wdev, char *vif, struct blob_attr *data, const char *section)
{
@@ -1048,6 +1076,7 @@ wireless_station_create(struct wireless_device *wdev, char *vif, struct blob_att
vlist_add(&wdev->stations, &sta->node, sta->name);
}
+/* ubus callback network.wireless.status, runs for every interface, encode the station */
static void
wireless_station_status(struct wireless_station *sta, struct blob_buf *b)
{
@@ -1060,6 +1089,7 @@ wireless_station_status(struct wireless_station *sta, struct blob_buf *b)
blobmsg_close_table(b, i);
}
+/* create a vlan object. Called by config */
void
wireless_vlan_create(struct wireless_device *wdev, char *vif, struct blob_attr *data, const char *section)
{
@@ -1090,6 +1120,7 @@ wireless_vlan_create(struct wireless_device *wdev, char *vif, struct blob_attr *
vlist_add(&wdev->vlans, &vlan->node, vlan->name);
}
+/* ubus callback network.wireless.status, runs for every interface, encode the vlan informations */
static void
wireless_vlan_status(struct wireless_vlan *vlan, struct blob_buf *b)
{
@@ -1104,6 +1135,7 @@ wireless_vlan_status(struct wireless_vlan *vlan, struct blob_buf *b)
blobmsg_close_table(b, i);
}
+/* create a wireless interface object. Called by config */
struct wireless_interface* wireless_interface_create(struct wireless_device *wdev, struct blob_attr *data, const char *section)
{
struct wireless_interface *vif;
@@ -1132,6 +1164,7 @@ struct wireless_interface* wireless_interface_create(struct wireless_device *wde
return vif;
}
+/* ubus callback network.wireless.status, runs for every interface */
static void
wireless_interface_status(struct wireless_interface *iface, struct blob_buf *b)
{
@@ -1158,6 +1191,7 @@ wireless_interface_status(struct wireless_interface *iface, struct blob_buf *b)
blobmsg_close_table(b, i);
}
+/* ubus callback network.wireless.status */
void
wireless_device_status(struct wireless_device *wdev, struct blob_buf *b)
{
@@ -1179,6 +1213,7 @@ wireless_device_status(struct wireless_device *wdev, struct blob_buf *b)
blobmsg_close_table(b, c);
}
+/* ubus callback network.wireless.get_validate */
void
wireless_device_get_validate(struct wireless_device *wdev, struct blob_buf *b)
{
@@ -1203,6 +1238,7 @@ wireless_device_get_validate(struct wireless_device *wdev, struct blob_buf *b)
blobmsg_close_table(b, c);
}
+/* ubus callback network.wireless.notify, command = set data, for vif */
static void
wireless_interface_set_data(struct wireless_interface *vif)
{
@@ -1223,6 +1259,7 @@ wireless_interface_set_data(struct wireless_interface *vif)
vif->ifname = blobmsg_data(cur);
}
+/* ubus callback network.wireless.notify, command = set data, for vlan */
static void
wireless_vlan_set_data(struct wireless_vlan *vlan)
{
@@ -1243,6 +1280,7 @@ wireless_vlan_set_data(struct wireless_vlan *vlan)
vlan->ifname = blobmsg_data(cur);
}
+/* ubus callback network.wireless.notify, command = process add */
static int
wireless_device_add_process(struct wireless_device *wdev, struct blob_attr *data)
{
@@ -1294,6 +1332,7 @@ wireless_device_add_process(struct wireless_device *wdev, struct blob_attr *data
return 0;
}
+/* ubus callback network.wireless.notify, command = process kill all */
static int
wireless_device_process_kill_all(struct wireless_device *wdev, struct blob_attr *data,
struct ubus_request_data *req)
@@ -1334,6 +1373,7 @@ wireless_device_process_kill_all(struct wireless_device *wdev, struct blob_attr
return 0;
}
+/* ubus callback network.wireless.notify, command = set_retry */
static int
wireless_device_set_retry(struct wireless_device *wdev, struct blob_attr *data)
{
@@ -1358,6 +1398,7 @@ enum {
NOTIFY_CMD_SET_RETRY = 4,
};
+/* ubus callback network.wireless.notify */
int
wireless_device_notify(struct wireless_device *wdev, struct blob_attr *data,
struct ubus_request_data *req)
@@ -1441,6 +1482,7 @@ wireless_device_notify(struct wireless_device *wdev, struct blob_attr *data,
return 0;
}
+/* called on startup and by netifd reload() */
void
wireless_start_pending(void)
{
--
2.29.2
More information about the openwrt-devel
mailing list