Skip to contentSkip to conversation

batman-adv: add missing kernel-doc comments

PATCH New Sven Eckelmann 1 participant 1 message Jun 9 Batman advanced

lore
Share & tools
lore

Sven Eckelmann

author maintainer
#0 lore raw

PATCH 1/1 batman-adv: add missing kernel-doc comments

batman-adv requires kernel-doc for all functions and data types visible outside their own translation unit. Promoting a function from static to module-wide visibility currently requires adding documentation from scratch. However, this burden falls on whoever promotes a function from static to module-wide visibility, rather than its original implementer.

Add the missing kernel-doc comments for the remaining undocumented functions and data types to reduce the complexity for new contributions.

---
 include/uapi/linux/batadv_packet.h     |  16 ++-
 net/batman-adv/bat_algo.c              |  10 ++
 net/batman-adv/bat_iv_ogm.c            | 166 ++++++++++++++++++++++++++++--
 net/batman-adv/bat_v.c                 |  52 ++++++++++
 net/batman-adv/bitarray.c              |   9 +-
 net/batman-adv/distributed-arp-table.c |  38 +++++++
 net/batman-adv/gateway_client.c        |   8 ++
 net/batman-adv/hard-interface.c        |  98 ++++++++++++++++++
 net/batman-adv/hash.c                  |   5 +-
 net/batman-adv/hash.h                  |  34 +++++--
 net/batman-adv/main.c                  |  36 ++++++-
 net/batman-adv/mesh-interface.c        |  63 ++++++++++++
 net/batman-adv/netlink.c               |   8 +-
 net/batman-adv/originator.c            |   7 ++
 net/batman-adv/routing.c               |  31 ++++++
 net/batman-adv/translation-table.c     | 179 ++++++++++++++++++++++++++++++++-
 16 files changed, 727 insertions(+), 33 deletions(-)
include/uapi/linux/batadv_packet.h +11 -5
index 1241285b..32436560 100644
@@ -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;
 };
 
 /**
net/batman-adv/bat_algo.c +10 -0
index 49e5861b..a040141c 100644
@@ -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;
net/batman-adv/bat_iv_ogm.c +160 -6

279 lines not on this page · raw message

net/batman-adv/bat_v.c +52 -0

94 lines not on this page · raw message

net/batman-adv/bitarray.c +8 -1
index 67cb3563..f814756d 100644
@@ -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)
net/batman-adv/distributed-arp-table.c +38 -0
index aaea155b..28eccfbb 100644
@@ -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;
net/batman-adv/gateway_client.c +8 -0
index 305488a7..2c82c36e 100644
@@ -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)
 {
net/batman-adv/hard-interface.c +98 -0

164 lines not on this page · raw message

net/batman-adv/hash.c +4 -1
index 759fa291..b9a652bd 100644
@@ -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;
net/batman-adv/hash.h +24 -10
index 86a2c200..debbbc93 100644
@@ -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
  *
- * Return: true if same and false if not same
+ * Compare hash element by its keys.
+ *
+ * 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: an index based on the key in the data of the first argument and the
- * size the second
+ * Return: bucket index derived from the key in @data and the table @size.
  */
-typedef u32 (*batadv_hashdata_choose_cb)(const void *, u32);
-typedef void (*batadv_hashdata_free_cb)(struct hlist_node *, void *);
+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
+ *
+ * Release a previously inserted hash element.
+ */
+typedef void (*batadv_hashdata_free_cb)(struct hlist_node *node, void *arg);
 
 /**
  * struct batadv_hashtable - Wrapper of simple hlist based hashtable
net/batman-adv/main.c +32 -4
index 3c457228..50b61352 100644
@@ -87,6 +87,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;
@@ -134,6 +142,12 @@ static int __init batadv_init(void)
 	return ret;
 }
 
+/**
+ * batadv_exit() - batman-adv module exit function
+ *
+ * Unregister the netdevice notifier and tear down all global state allocated
+ * by batadv_init().
+ */
 static void __exit batadv_exit(void)
 {
 	batadv_netlink_unregister();
@@ -396,6 +410,17 @@ void batadv_skb_set_priority(struct sk_buff *skb, int offset)
 	skb->priority = prio + 256;
 }
 
+/**
+ * batadv_recv_unhandled_packet() - default RX handler for unsupported packet
+ *  types
+ * @skb: incoming packet
+ * @recv_if: interface on which the packet was received (unused)
+ *
+ * Drop incoming packets whose packet_type has no dedicated RX handler
+ * registered.
+ *
+ * Return: NET_RX_DROP
+ */
 static int batadv_recv_unhandled_packet(struct sk_buff *skb,
 					struct batadv_hard_iface *recv_if)
 {
@@ -404,10 +429,6 @@ static int batadv_recv_unhandled_packet(struct sk_buff *skb,
 	return NET_RX_DROP;
 }
 
-/* incoming packets with the batman ethertype received on any active hard
- * interface
- */
-
 /**
  * batadv_batman_skb_recv() - Handle incoming message from an hard interface
  * @skb: the received packet
@@ -493,6 +514,13 @@ int batadv_batman_skb_recv(struct sk_buff *skb, struct net_device *dev,
 	return NET_RX_DROP;
 }
 
+/**
+ * batadv_recv_handler_init() - initialise the RX handler dispatch table
+ *
+ * Initialise all entries of the RX handler table (+ unused to the
+ * default drop handler) and perform compile-time size sanity checks on
+ * all on-wire packet structs.
+ */
 static void batadv_recv_handler_init(void)
 {
 	int i;
net/batman-adv/mesh-interface.c +63 -0

111 lines not on this page · raw message

net/batman-adv/netlink.c +7 -1
index e3d47f3e..794ed825 100644
@@ -52,9 +52,15 @@
 
 struct genl_family batadv_netlink_family;
 
-/* multicast groups */
+/**
+ * enum batadv_netlink_multicast_groups - batman-adv generic netlink multicast
+ *  groups
+ */
 enum batadv_netlink_multicast_groups {
+	/** @BATADV_NL_MCGRP_CONFIG: configuration change notifications */
 	BATADV_NL_MCGRP_CONFIG,
+
+	/** @BATADV_NL_MCGRP_TPMETER: throughput meter result notifications */
 	BATADV_NL_MCGRP_TPMETER,
 };
 
net/batman-adv/originator.c +7 -0
index 9b38bd9e..a5d00864 100644
@@ -1299,6 +1299,13 @@ void batadv_purge_orig_ref(struct batadv_priv *bat_priv)
 	batadv_gw_election(bat_priv);
 }
 
+/**
+ * batadv_purge_orig() - periodic worker to purge stale originator entries
+ * @work: delayed work embedded in the bat_priv
+ *
+ * Invoke batadv_purge_orig_ref() to drop stale originators and reschedule the
+ * next run after BATADV_ORIG_WORK_PERIOD milliseconds.
+ */
 static void batadv_purge_orig(struct work_struct *work)
 {
 	struct delayed_work *delayed_work;
net/batman-adv/routing.c +31 -0
index cd4368b8..e0cd05e5 100644
@@ -274,6 +274,16 @@ static int batadv_recv_my_icmp_packet(struct batadv_priv *bat_priv,
 	return ret;
 }
 
+/**
+ * batadv_recv_icmp_ttl_exceeded() - handle an ICMP packet that hit TTL 0
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @skb: ICMP packet whose TTL has expired
+ *
+ * For traceroute-style ICMP echo requests, send a TTL exceeded reply back to
+ * the source. Other ICMP types are simply dropped.
+ *
+ * Return: NET_XMIT_SUCCESS if the reply was queued, NET_RX_DROP otherwise
+ */
 static int batadv_recv_icmp_ttl_exceeded(struct batadv_priv *bat_priv,
 					 struct sk_buff *skb)
 {
@@ -652,6 +662,18 @@ batadv_find_router(struct batadv_priv *bat_priv,
 	return router;
 }
 
+/**
+ * batadv_route_unicast_packet() - forward a unicast packet towards its
+ *  destination originator
+ * @skb: the received unicast packet
+ * @recv_if: interface on which the packet was received
+ *
+ * Decrement the TTL, look up the originator for the destination address and
+ * hand the packet over to batadv_send_skb_to_orig() for transmission. Drop
+ * the packet when the TTL is exhausted or no route exists.
+ *
+ * Return: NET_RX_SUCCESS if the packet was forwarded, NET_RX_DROP otherwise
+ */
 static int batadv_route_unicast_packet(struct sk_buff *skb,
 				       struct batadv_hard_iface *recv_if)
 {
@@ -782,6 +804,15 @@ batadv_reroute_unicast_packet(struct batadv_priv *bat_priv, struct sk_buff *skb,
 	return ret;
 }
 
+/**
+ * batadv_check_unicast_ttvn() - check and adjust the TTVN of a unicast packet
+ * @bat_priv: the bat priv with all the mesh interface information
+ * @skb: the unicast packet to check
+ * @hdr_len: length of the unicast header preceding the payload
+ *
+ * Return: true if the packet may be processed further, false if it has been
+ *  consumed or has to be dropped by the caller
+ */
 static bool batadv_check_unicast_ttvn(struct batadv_priv *bat_priv,
 				      struct sk_buff *skb, int hdr_len)
 {
net/batman-adv/translation-table.c +174 -5

311 lines not on this page · raw message

---
base-commit: 385b248dd4e46c4ce022adeb1b13e547d1954901
change-id: 20260608-kernel-doc-272b4d5e2830

Best regards,

Signature · 1 line
Sven Eckelmann <[email protected]>