[PATCH net-next 09/15] batman-adv: add missing kernel-doc comments

@@ -192,13 +192,19 @@ enum batadv_tvlv_type {
 };
 
 #pragma pack(2)
-/* the destination hardware field in the ARP frame is used to
- * transport the claim type and the group id
+/**
+ * struct batadv_bla_claim_dst - layout of the destination MAC of a BLA claim
+ *  frame
+ * @magic: fixed magic prefix (FF:43:05) identifying claim frames
+ * @type: claim frame type, see &enum batadv_bla_claimframe
+ * @group: group identifier of the announcing backbone gateway
+ *
+ * used in the destination hardware field of the ARP frame
  */
 struct batadv_bla_claim_dst {
-	__u8   magic[3];	/* FF:43:05 */
-	__u8   type;		/* bla_claimframe */
-	__be16 group;		/* group id */
+	__u8   magic[3];
+	__u8   type;
+	__be16 group;
 };
 
 /**

@@ -116,6 +116,16 @@ int batadv_algo_select(struct batadv_priv *bat_priv, const char *name)
 	return 0;
 }
 
+/**
+ * batadv_param_set_ra() - Validate and store routing_algo module parameter
+ * @val: new value for the routing_algo module parameter
+ * @kp: kernel parameter description used to store the value
+ *
+ * Check that the requested algorithm is known to batman-adv and then store
+ * the name as the new default routing algorithm.
+ *
+ * Return: 0 on success or negative error number in case of failure
+ */
 static int batadv_param_set_ra(const char *val, const struct kernel_param *kp)
 {
 	struct batadv_algo_ops *bat_algo_ops;

@@ -171,6 +171,14 @@ batadv_iv_ogm_orig_get(struct batadv_priv *bat_priv, const u8 *addr)
 	return NULL;
 }
 
+/**
+ * batadv_iv_ogm_neigh_new() - retrieve or create a B.A.T.M.A.N. IV neighbour
+ * @hard_iface: the interface where the neighbour is connected to
+ * @neigh_addr: the mac address of the neighbour
+ * @orig_node: originator object representing the neighbour
+ *
+ * Return: pointer to the neigh_node or NULL in case of failure
+ */
 static struct batadv_neigh_node *
 batadv_iv_ogm_neigh_new(struct batadv_hard_iface *hard_iface,
 			const u8 *neigh_addr,

@@ -183,6 +191,14 @@ batadv_iv_ogm_neigh_new(struct batadv_hard_iface *hard_iface,
 	return neigh_node;
 }
 
+/**
+ * batadv_iv_ogm_iface_enable() - prepare an interface for B.A.T.M.A.N. IV
+ * @hard_iface: the interface to prepare
+ *
+ * Allocate and prepare the per-interface OGM buffer
+ *
+ * Return: 0 on success or negative error number in case of failure
+ */
 static int batadv_iv_ogm_iface_enable(struct batadv_hard_iface *hard_iface)
 {
 	struct batadv_ogm_packet *batadv_ogm_packet;

@@ -220,6 +236,14 @@ static int batadv_iv_ogm_iface_enable(struct batadv_hard_iface *hard_iface)
 	return 0;
 }
 
+/**
+ * batadv_iv_ogm_iface_disable() - release B.A.T.M.A.N. IV resources of an
+ *  interface
+ * @hard_iface: the interface which is shutting down
+ *
+ * Free the per-interface OGM buffer and cancel a possibly pending OGM
+ * rescheduling work.
+ */
 static void batadv_iv_ogm_iface_disable(struct batadv_hard_iface *hard_iface)
 {
 	mutex_lock(&hard_iface->bat_iv.ogm_buff_mutex);

@@ -233,6 +257,11 @@ static void batadv_iv_ogm_iface_disable(struct batadv_hard_iface *hard_iface)
 	disable_delayed_work_sync(&hard_iface->bat_iv.reschedule_work);
 }
 
+/**
+ * batadv_iv_ogm_iface_update_mac() - update the originator MAC stored in the
+ *  per-interface OGM buffer
+ * @hard_iface: the interface for which the OGM buffer should be updated
+ */
 static void batadv_iv_ogm_iface_update_mac(struct batadv_hard_iface *hard_iface)
 {
 	struct batadv_ogm_packet *batadv_ogm_packet;

@@ -254,6 +283,14 @@ static void batadv_iv_ogm_iface_update_mac(struct batadv_hard_iface *hard_iface)
 	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
 }
 
+/**
+ * batadv_iv_ogm_primary_iface_set() - apply primary interface state to
+ *  a batadv_hard_iface
+ * @hard_iface: interface which just became the primary
+ *
+ * The primary interface uses the full TTL for its own OGMs, so adjust the TTL
+ * stored in the OGM template buffer accordingly.
+ */
 static void
 batadv_iv_ogm_primary_iface_set(struct batadv_hard_iface *hard_iface)
 {

@@ -273,7 +310,17 @@ batadv_iv_ogm_primary_iface_set(struct batadv_hard_iface *hard_iface)
 	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
 }
 
-/* when do we schedule our own ogm to be sent */
+/**
+ * batadv_iv_ogm_emit_send_time() - calculate the jiffies when an own OGM
+ *  should be sent next
+ * @bat_priv: the bat priv with all the mesh interface information
+ *
+ * The next emission point is the configured orig_interval randomised by
+ * +/- BATADV_JITTER milliseconds to reduce chance of potential collisions
+ * between neighbours.
+ *
+ * Return: jiffies value when the next OGM should be transmitted
+ */
 static unsigned long
 batadv_iv_ogm_emit_send_time(const struct batadv_priv *bat_priv)
 {

@@ -285,13 +332,24 @@ batadv_iv_ogm_emit_send_time(const struct batadv_priv *bat_priv)
 	return jiffies + msecs_to_jiffies(msecs);
 }
 
-/* when do we schedule a ogm packet to be sent */
+/**
+ * batadv_iv_ogm_fwd_send_time() - calculate the jiffies when a forwarded OGM
+ *  should be sent next
+ *
+ * Return: jiffies value at which a forwarded OGM should be transmitted
+ */
 static unsigned long batadv_iv_ogm_fwd_send_time(void)
 {
 	return jiffies + msecs_to_jiffies(get_random_u32_below(BATADV_JITTER / 2));
 }
 
-/* apply hop penalty for a normal link */
+/**
+ * batadv_hop_penalty() - apply the configured hop penalty to a TQ value
+ * @tq: input TQ value to be reduced
+ * @bat_priv: the bat priv with all the mesh interface information
+ *
+ * Return: the TQ value after the hop penalty has been applied
+ */
 static u8 batadv_hop_penalty(u8 tq, const struct batadv_priv *bat_priv)
 {
 	int hop_penalty = READ_ONCE(bat_priv->hop_penalty);

@@ -337,7 +395,15 @@ batadv_iv_ogm_aggr_packet(int buff_pos, int packet_len,
 	return next_buff_pos <= packet_len;
 }
 
-/* send a batman ogm to a given interface */
+/**
+ * batadv_iv_ogm_send_to_if() - send a batman OGM to a given interface
+ * @forw_packet: forward packet containing the OGM(s) to be transmitted
+ * @hard_iface: interface to send the OGM out on
+ *
+ * Update the direct link flags of each aggregated OGM for the outgoing
+ * interface, log the transmission and finally hand a clone of the skb to the
+ * lower layer for broadcast.
+ */
 static void batadv_iv_ogm_send_to_if(struct batadv_forw_packet *forw_packet,
 				     struct batadv_hard_iface *hard_iface)
 {

@@ -401,7 +467,13 @@ static void batadv_iv_ogm_send_to_if(struct batadv_forw_packet *forw_packet,
 	}
 }
 
-/* send a batman ogm packet */
+/**
+ * batadv_iv_ogm_emit() - emit an (aggregated) OGM packet
+ * @forw_packet: forward packet which should be emitted
+ *
+ * The @forw_packet will be emitted but not consumed. When the interface is
+ * no longer active, the transmission will be skipped.
+ */
 static void batadv_iv_ogm_emit(struct batadv_forw_packet *forw_packet)
 {
 	if (!forw_packet->if_incoming) {

@@ -603,7 +675,14 @@ static bool batadv_iv_ogm_aggregate_new(const unsigned char *packet_buff,
 	return true;
 }
 
-/* aggregate a new packet into the existing ogm packet */
+/**
+ * batadv_iv_ogm_aggregate() - append an OGM to an existing aggregated forward
+ *  packet
+ * @forw_packet_aggr: aggregated forward packet to extend
+ * @packet_buff: pointer to the OGM to append
+ * @packet_len: length of the OGM to append
+ * @direct_link: true if @packet_buff was received as a direct link OGM
+ */
 static void batadv_iv_ogm_aggregate(struct batadv_forw_packet *forw_packet_aggr,
 				    const unsigned char *packet_buff,
 				    int packet_len, bool direct_link)

@@ -699,6 +778,21 @@ static bool batadv_iv_ogm_queue_add(struct batadv_priv *bat_priv,
 	}
 }
 
+/**
+ * batadv_iv_ogm_forward() - rebroadcast a received OGM
+ * @orig_node: originator that sent the OGM
+ * @ethhdr: ethernet header of the OGM packet
+ * @batadv_ogm_packet: OGM packet to be forwarded
+ * @is_single_hop_neigh: true if the OGM was received via a one-hop neighbour
+ * @is_from_best_next_hop: true if the sender is the currently selected best
+ *  next hop towards @orig_node
+ * @if_incoming: interface where the packet was received
+ * @if_outgoing: interface for which the retransmission should be considered
+ *
+ * Decrement the TTL, apply the hop penalty and queue the OGM for
+ * retransmission. OGMs that do not arrive over the best next hop are only
+ * forwarded for link-quality measurement reasons (and marked accordingly).
+ */
 static void batadv_iv_ogm_forward(struct batadv_orig_node *orig_node,
 				  const struct ethhdr *ethhdr,
 				  struct batadv_ogm_packet *batadv_ogm_packet,

@@ -899,6 +993,13 @@ static void batadv_iv_ogm_schedule_buff(struct batadv_hard_iface *hard_iface)
 	batadv_hardif_put(primary_if);
 }
 
+/**
+ * batadv_iv_ogm_schedule() - schedule the next OGM transmission on an
+ *  interface
+ * @hard_iface: interface for which the next OGM should be scheduled
+ *
+ * Take the OGM buffer mutex and prepare the next OGM for transmission.
+ */
 static void batadv_iv_ogm_schedule(struct batadv_hard_iface *hard_iface)
 {
 	if (hard_iface->if_status == BATADV_IF_TO_BE_REMOVED)

@@ -909,6 +1010,13 @@ static void batadv_iv_ogm_schedule(struct batadv_hard_iface *hard_iface)
 	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
 }
 
+/**
+ * batadv_iv_ogm_reschedule() - work-queue helper to rerun batadv_iv_ogm_schedule()
+ * @work: work item embedded in the hard interface
+ *
+ * Invoked from the per-interface reschedule_work delayed work when the
+ * previous attempt to enqueue the own OGM failed.
+ */
 static void batadv_iv_ogm_reschedule(struct work_struct *work)
 {
 	struct delayed_work *delayed_work = to_delayed_work(work);

@@ -1765,6 +1873,14 @@ static void batadv_iv_ogm_process(const struct sk_buff *skb, int ogm_offset,
 	batadv_orig_node_put(orig_node);
 }
 
+/**
+ * batadv_iv_send_outstanding_bat_ogm_packet() - work-queue helper to emit a
+ *  queued forward packet
+ * @work: work item embedded in the forward packet
+ *
+ * Emit the queued OGM forward packet and, for own primary-interface packets,
+ * schedule the next periodic OGM. The forward packet is freed afterwards.
+ */
 static void batadv_iv_send_outstanding_bat_ogm_packet(struct work_struct *work)
 {
 	struct delayed_work *delayed_work;

@@ -1803,6 +1919,17 @@ static void batadv_iv_send_outstanding_bat_ogm_packet(struct work_struct *work)
 		batadv_forw_packet_free(forw_packet, dropped);
 }
 
+/**
+ * batadv_iv_ogm_receive() - receive a B.A.T.M.A.N. IV OGM packet
+ * @skb: skb containing the OGM packet
+ * @if_incoming: interface where the packet was received
+ *
+ * Validate the packet, then split the aggregated OGM packet into individual
+ * OGMs and hand each of them to batadv_iv_ogm_process(). Ownership of @skb is
+ * always taken over by this function.
+ *
+ * Return: NET_RX_SUCCESS or NET_RX_DROP
+ */
 static int batadv_iv_ogm_receive(struct sk_buff *skb,
 				 struct batadv_hard_iface *if_incoming)
 {

@@ -2310,6 +2437,12 @@ batadv_iv_ogm_neigh_is_sob(struct batadv_neigh_node *neigh1,
 	return ret;
 }
 
+/**
+ * batadv_iv_iface_enabled() - notification handler for activated interfaces
+ * @hard_iface: interface that was just activated
+ *
+ * Set up the per-interface reschedule work and start sending periodic OGMs.
+ */
 static void batadv_iv_iface_enabled(struct batadv_hard_iface *hard_iface)
 {
 	INIT_DELAYED_WORK(&hard_iface->bat_iv.reschedule_work, batadv_iv_ogm_reschedule);

@@ -2328,6 +2461,14 @@ static void batadv_iv_init_sel_class(struct batadv_priv *bat_priv)
 	WRITE_ONCE(bat_priv->gw.sel_class, 20);
 }
 
+/**
+ * batadv_iv_gw_get_best_gw_node() - retrieve the best gateway node based on
+ *  the B.A.T.M.A.N. IV metric and the configured GW selection class
+ * @bat_priv: the bat priv with all the mesh interface information
+ *
+ * Return: gateway node with the highest score for the current selection class,
+ *  or NULL if no eligible gateway exists.
+ */
 static struct batadv_gw_node *
 batadv_iv_gw_get_best_gw_node(struct batadv_priv *bat_priv)
 {

@@ -2405,6 +2546,19 @@ batadv_iv_gw_get_best_gw_node(struct batadv_priv *bat_priv)
 	return curr_gw;
 }
 
+/**
+ * batadv_iv_gw_is_eligible() - check whether a new gateway should replace the
+ *  currently selected one
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @curr_gw_orig: originator of the currently selected gateway
+ * @orig_node: originator of the gateway candidate
+ *
+ * Compare the TQ values of @curr_gw_orig and @orig_node, taking the configured
+ * gateway selection class into account.
+ *
+ * Return: true if @orig_node should take over as the active gateway, false
+ *  otherwise
+ */
 static bool batadv_iv_gw_is_eligible(struct batadv_priv *bat_priv,
 				     struct batadv_orig_node *curr_gw_orig,
 				     struct batadv_orig_node *orig_node)

@@ -41,6 +41,13 @@
 #include "netlink.h"
 #include "originator.h"
 
+/**
+ * batadv_v_iface_activate() - finalise the activation of a hard interface
+ * @hard_iface: interface to activate
+ *
+ * Reuse the currently selected primary interface to seed the ELP packet.
+ * Immediately activate the interface.
+ */
 static void batadv_v_iface_activate(struct batadv_hard_iface *hard_iface)
 {
 	struct batadv_priv *bat_priv = netdev_priv(hard_iface->mesh_iface);

@@ -61,6 +68,16 @@ static void batadv_v_iface_activate(struct batadv_hard_iface *hard_iface)
 		hard_iface->if_status = BATADV_IF_ACTIVE;
 }
 
+/**
+ * batadv_v_iface_enable() - enable the B.A.T.M.A.N. V protocol on an
+ *  interface
+ * @hard_iface: interface to enable
+ *
+ * Enable the ELP and OGM components for @hard_iface. On error, the partially
+ * enabled state is rolled back before returning.
+ *
+ * Return: 0 on success or negative error number in case of failure
+ */
 static int batadv_v_iface_enable(struct batadv_hard_iface *hard_iface)
 {
 	int ret;

@@ -76,12 +93,21 @@ static int batadv_v_iface_enable(struct batadv_hard_iface *hard_iface)
 	return ret;
 }
 
+/**
+ * batadv_v_iface_disable() - disable the B.A.T.M.A.N. V protocol on an
+ *  interface
+ * @hard_iface: interface to disable
+ */
 static void batadv_v_iface_disable(struct batadv_hard_iface *hard_iface)
 {
 	batadv_v_ogm_iface_disable(hard_iface);
 	batadv_v_elp_iface_disable(hard_iface);
 }
 
+/**
+ * batadv_v_primary_iface_set() - apply primary interface state
+ * @hard_iface: interface which just became the primary
+ */
 static void batadv_v_primary_iface_set(struct batadv_hard_iface *hard_iface)
 {
 	batadv_v_elp_primary_iface_set(hard_iface);

@@ -109,6 +135,11 @@ static void batadv_v_iface_update_mac(struct batadv_hard_iface *hard_iface)
 	batadv_hardif_put(primary_if);
 }
 
+/**
+ * batadv_v_hardif_neigh_init() - initialise the B.A.T.M.A.N. V state of a
+ *  hard interface neighbour
+ * @hardif_neigh: hard interface neighbour to initialise
+ */
 static void
 batadv_v_hardif_neigh_init(struct batadv_hardif_neigh_node *hardif_neigh)
 {

@@ -444,6 +475,16 @@ batadv_v_orig_dump(struct sk_buff *msg, struct netlink_callback *cb,
 	cb->args[2] = sub;
 }
 
+/**
+ * batadv_v_neigh_cmp() - compare two B.A.T.M.A.N. V neighbours by throughput
+ * @neigh1: first neighbour to compare
+ * @if_outgoing1: outgoing interface to use for @neigh1
+ * @neigh2: second neighbour to compare
+ * @if_outgoing2: outgoing interface to use for @neigh2
+ *
+ * Return: a positive value if @neigh1 is better, a negative value if @neigh2
+ *  is better and 0 if both have equal throughput
+ */
 static int batadv_v_neigh_cmp(struct batadv_neigh_node *neigh1,
 			      struct batadv_hard_iface *if_outgoing1,
 			      struct batadv_neigh_node *neigh2,

@@ -469,6 +510,17 @@ static int batadv_v_neigh_cmp(struct batadv_neigh_node *neigh1,
 	return ret;
 }
 
+/**
+ * batadv_v_neigh_is_sob() - check whether two B.A.T.M.A.N. V neighbours have
+ *  a similar or better throughput
+ * @neigh1: first neighbour to compare
+ * @if_outgoing1: outgoing interface to use for @neigh1
+ * @neigh2: second neighbour to compare
+ * @if_outgoing2: outgoing interface to use for @neigh2
+ *
+ * Return: true if the throughput of @neigh2 is at least 3/4 of the
+ *  @neigh1 throughput
+ */
 static bool batadv_v_neigh_is_sob(struct batadv_neigh_node *neigh1,
 				  struct batadv_hard_iface *if_outgoing1,
 				  struct batadv_neigh_node *neigh2,

@@ -11,7 +11,14 @@
 
 #include "log.h"
 
-/* shift the packet array by n places. */
+/**
+ * batadv_bitmap_shift_left() - shift the sequence number bitmap left
+ * @seq_bits: the sequence number bitmap to shift
+ * @n: number of positions to shift left
+ *
+ * Shift @seq_bits by @n positions. No-op if @n is not within the bounds of
+ * the bitmap.
+ */
 static void batadv_bitmap_shift_left(unsigned long *seq_bits, s32 n)
 {
 	if (n <= 0 || n >= BATADV_TQ_LOCAL_WINDOW_SIZE)

@@ -50,27 +50,65 @@
 #include "translation-table.h"
 #include "tvlv.h"
 
+/**
+ * enum batadv_bootpop - BOOTP/DHCP message op codes
+ */
 enum batadv_bootpop {
+	/** @BATADV_BOOTREPLY: server-to-client reply */
 	BATADV_BOOTREPLY	= 2,
 };
 
+/**
+ * enum batadv_boothtype - BOOTP/DHCP hardware address types
+ */
 enum batadv_boothtype {
+	/** @BATADV_HTYPE_ETHERNET: Ethernet (10Mb) */
 	BATADV_HTYPE_ETHERNET	= 1,
 };
 
+/**
+ * enum batadv_dhcpoptioncode - DHCP option codes relevant for batman-adv DAT
+ */
 enum batadv_dhcpoptioncode {
+	/** @BATADV_DHCP_OPT_PAD: pad option */
 	BATADV_DHCP_OPT_PAD		= 0,
+
+	/** @BATADV_DHCP_OPT_MSG_TYPE: DHCP message type option */
 	BATADV_DHCP_OPT_MSG_TYPE	= 53,
+
+	/** @BATADV_DHCP_OPT_END: end of options marker */
 	BATADV_DHCP_OPT_END		= 255,
 };
 
+/**
+ * enum batadv_dhcptype - DHCP message types relevant for batman-adv DAT
+ */
 enum batadv_dhcptype {
+	/** @BATADV_DHCPACK: DHCPACK message */
 	BATADV_DHCPACK		= 5,
 };
 
 /* { 99, 130, 83, 99 } */
 #define BATADV_DHCP_MAGIC 1669485411
 
+/**
+ * struct batadv_dhcp_packet - BOOTP/DHCP packet header
+ * @op: message op code / message type
+ * @htype: hardware address type
+ * @hlen: hardware address length
+ * @hops: number of relay hops
+ * @xid: transaction identifier
+ * @secs: seconds elapsed since client started trying to boot
+ * @flags: BOOTP/DHCP flags
+ * @ciaddr: client IP address
+ * @yiaddr: "your" (client) IP address as assigned by the server
+ * @siaddr: IP address of next server to use in bootstrap
+ * @giaddr: relay agent IP address
+ * @chaddr: client hardware address
+ * @sname: optional server host name
+ * @file: boot file name
+ * @magic: BOOTP/DHCP magic cookie identifying the start of options
+ */
 struct batadv_dhcp_packet {
 	__u8 op;
 	__u8 htype;

@@ -125,6 +125,14 @@ batadv_gw_get_selected_orig(struct batadv_priv *bat_priv)
 	return orig_node;
 }
 
+/**
+ * batadv_gw_select() - select a new currently active gateway
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @new_gw_node: gateway node to be set as the current gateway, may be NULL
+ *
+ * Atomically replace the currently active gateway with @new_gw_node and drop
+ * the reference to the previous one.
+ */
 static void batadv_gw_select(struct batadv_priv *bat_priv,
 			     struct batadv_gw_node *new_gw_node)
 {

@@ -197,6 +197,17 @@ static bool batadv_is_on_batman_iface(const struct net_device *net_dev)
 	return ret;
 }
 
+/**
+ * batadv_is_valid_iface() - check whether a net_device can be used as a hard
+ *  interface
+ * @net_dev: the net_device to check
+ *
+ * Refuse loopback devices, non-Ethernet devices, devices with a non-Ethernet
+ * address length and any device that is already part of a batman-adv mesh
+ * interface stack.
+ *
+ * Return: true if @net_dev can be used as a hard interface, false otherwise
+ */
 static bool batadv_is_valid_iface(const struct net_device *net_dev)
 {
 	if (net_dev->flags & IFF_LOOPBACK)

@@ -467,6 +478,14 @@ int batadv_hardif_no_broadcast(struct batadv_hard_iface *if_outgoing,
 	return ret;
 }
 
+/**
+ * batadv_hardif_get_active() - retrieve an active hard interface for a mesh
+ *  interface
+ * @mesh_iface: mesh interface to search
+ *
+ * Return: first hard interface in BATADV_IF_ACTIVE state attached to
+ *  @mesh_iface, or NULL if none is active.
+ */
 static struct batadv_hard_iface *
 batadv_hardif_get_active(struct net_device *mesh_iface)
 {

@@ -487,6 +506,15 @@ batadv_hardif_get_active(struct net_device *mesh_iface)
 	return hard_iface;
 }
 
+/**
+ * batadv_primary_if_update_addr() - propagate the new primary interface MAC
+ *  address to all dependent components
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @oldif: previously used primary interface, or NULL if none
+ *
+ * Inform DAT and BLA that the originator address has changed so they can
+ * adjust their state accordingly.
+ */
 static void batadv_primary_if_update_addr(struct batadv_priv *bat_priv,
 					  struct batadv_hard_iface *oldif)
 {

@@ -502,6 +530,15 @@ static void batadv_primary_if_update_addr(struct batadv_priv *bat_priv,
 	batadv_hardif_put(primary_if);
 }
 
+/**
+ * batadv_primary_if_select() - select the new primary interface
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @new_hard_iface: new primary interface, may be NULL
+ *
+ * Replace the currently selected primary interface with @new_hard_iface,
+ * invoke the algorithm-specific primary_set hook and update the originator
+ * MAC address.
+ */
 static void batadv_primary_if_select(struct batadv_priv *bat_priv,
 				     struct batadv_hard_iface *new_hard_iface)
 {

@@ -525,6 +562,13 @@ static void batadv_primary_if_select(struct batadv_priv *bat_priv,
 	batadv_hardif_put(curr_hard_iface);
 }
 
+/**
+ * batadv_hardif_is_iface_up() - check whether the underlying net_device of a
+ *  hard interface is up
+ * @hard_iface: the hard interface to check
+ *
+ * Return: true if the underlying net_device has the IFF_UP flag set
+ */
 static bool
 batadv_hardif_is_iface_up(const struct batadv_hard_iface *hard_iface)
 {

@@ -534,6 +578,15 @@ batadv_hardif_is_iface_up(const struct batadv_hard_iface *hard_iface)
 	return false;
 }
 
+/**
+ * batadv_check_known_mac_addr() - warn about duplicate hard interface MAC
+ *  addresses
+ * @hard_iface: hard interface that was just added or had its MAC changed
+ *
+ * Iterate over all hard interfaces of the same mesh interface and emit a
+ * warning if another in-use interface shares the same MAC address as
+ * @hard_iface.
+ */
 static void batadv_check_known_mac_addr(const struct batadv_hard_iface *hard_iface)
 {
 	struct net_device *mesh_iface = hard_iface->mesh_iface;

@@ -666,6 +719,15 @@ void batadv_update_min_mtu(struct net_device *mesh_iface)
 	batadv_tt_local_resize_to_mtu(mesh_iface);
 }
 
+/**
+ * batadv_hardif_activate_interface() - move a hard interface to the active
+ *  state
+ * @hard_iface: the interface that has come up
+ *
+ * Activate an interface, select it as the primary interface if no
+ * primary is currently active and invoke the algorithm-specific
+ * activate hook.
+ */
 static void
 batadv_hardif_activate_interface(struct batadv_hard_iface *hard_iface)
 {

@@ -699,6 +761,14 @@ batadv_hardif_activate_interface(struct batadv_hard_iface *hard_iface)
 	batadv_hardif_put(primary_if);
 }
 
+/**
+ * batadv_hardif_deactivate_interface() - move a hard interface to the
+ *  inactive state
+ * @hard_iface: the interface that went down
+ *
+ * Demote @hard_iface to BATADV_IF_INACTIVE and recalculate the mesh minimum
+ * MTU based on the remaining active interfaces.
+ */
 static void
 batadv_hardif_deactivate_interface(struct batadv_hard_iface *hard_iface)
 {

@@ -1020,6 +1090,18 @@ static void batadv_wifi_net_device_event(unsigned long event,
 	}
 }
 
+/**
+ * batadv_hard_if_event() - netdevice notifier callback for hard interfaces
+ * @this: notifier block (unused)
+ * @event: the NETDEV_* event to handle
+ * @ptr: notifier info pointing to the affected net_device
+ *
+ * Dispatch netdevice events that affect potential or existing hard
+ * interfaces. Mesh interfaces are handled separately by
+ * batadv_hard_if_event_meshif().
+ *
+ * Return: NOTIFY_DONE
+ */
 static int batadv_hard_if_event(struct notifier_block *this,
 				unsigned long event, void *ptr)
 {

@@ -11,7 +11,10 @@
 #include <linux/lockdep.h>
 #include <linux/slab.h>
 
-/* clears the hash */
+/**
+ * batadv_hash_init() - clear all buckets of a hashtable
+ * @hash: hashtable to clear
+ */
 static void batadv_hash_init(struct batadv_hashtable *hash)
 {
 	u32 i;

@@ -18,21 +18,35 @@
 #include <linux/stddef.h>
 #include <linux/types.h>
 
-/* callback to a compare function.  should compare 2 element data for their
- * keys
+/**
+ * typedef batadv_hashdata_compare_cb - hash element comparison callback
+ * @node: hlist node of the element currently stored in the bucket
+ * @key: opaque payload to compare @node's key against
+ *
+ * Compare hash element by its keys.
  *
- * Return: true if same and false if not same
+ * Return: true if both elements are considered equal, false otherwise.
  */
-typedef bool (*batadv_hashdata_compare_cb)(const struct hlist_node *,
-					   const void *);
+typedef bool (*batadv_hashdata_compare_cb)(const struct hlist_node *node,
+					   const void *key);
 
-/* the hashfunction
+/**
+ * typedef batadv_hashdata_choose_cb - hash bucket selection callback
+ * @key: opaque payload whose key selects the bucket
+ * @size: number of buckets in the hash table
+ *
+ * Return: bucket index derived from the key in @data and the table @size.
+ */
+typedef u32 (*batadv_hashdata_choose_cb)(const void *key, u32 size);
+
+/**
+ * typedef batadv_hashdata_free_cb - hash element free callback
+ * @node: hlist node of the element being removed
+ * @arg: opaque caller-supplied argument forwarded from the caller
  *
- * Return: an index based on the key in the data of the first argument and the
- * size the second
+ * Release a previously inserted hash element.
  */
-typedef u32 (*batadv_hashdata_choose_cb)(const void *, u32);
-typedef void (*batadv_hashdata_free_cb)(struct hlist_node *, void *);
+typedef void (*batadv_hashdata_free_cb)(struct hlist_node *node, void *arg);
 
 /**
  * struct batadv_hashtable - Wrapper of simple hlist based hashtable

@@ -82,6 +82,14 @@ static char *batadv_uev_type_str[] = {
 	"bla",
 };
 
+/**
+ * batadv_init() - batman-adv module init function
+ *
+ * Initialise the global state used by all mesh interfaces, register the
+ * netdevice notifier and the netlink/rtnl family.
+ *
+ * Return: 0 on success or negative error number in case of failure
+ */
 static int __init batadv_init(void)
 {
 	int ret;