batman-adv: add missing kernel-doc comments
Sven Eckelmann
maintainerPATCH 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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]>