batman-adv: kernel-doc fixes 2026.2
Sven Eckelmann
maintainercover batman-adv: kernel-doc fixes 2026.2
During the (recent) integration of various fixes and cleanups, some of the kernel-docs weren't correctly updated. This patchset should sync the kernel-doc again with the actual implementation. But at the same time, I've noticed other (older) kernel-doc problems and just added fixes for these in this patchset too.
The only common thing these patches have - they are kernel-doc changes :)
---
Sven Eckelmann (5):
batman-adv: tp_meter: update stale kernel-doc after refactoring
batman-adv: bla: update stale kernel-doc
batman-adv: uapi: keep kernel-doc in struct member order
batman-adv: fix batadv_v_ogm_packet_recv error handling kernel-doc
batman-adv: fix kernel-doc typos and grammar errors
include/uapi/linux/batadv_packet.h | 6 +++--- net/batman-adv/bat_v.c | 2 +- net/batman-adv/bat_v_ogm.c | 10 +++++----- net/batman-adv/bitarray.c | 2 +- net/batman-adv/bitarray.h | 2 +- net/batman-adv/bridge_loop_avoidance.c | 2 +- net/batman-adv/bridge_loop_avoidance.h | 2 +- net/batman-adv/fragmentation.c | 3 ++- net/batman-adv/hash.h | 4 ++-- net/batman-adv/mesh-interface.c | 6 +++--- net/batman-adv/netlink.c | 4 ++-- net/batman-adv/originator.c | 4 ++-- net/batman-adv/tp_meter.c | 16 ++++++++-------- net/batman-adv/tvlv.c | 4 ++-- net/batman-adv/types.h | 24 +++++++++++++++--------- 15 files changed, 49 insertions(+), 42 deletions(-)
---
base-commit: 7fb5fc7265f6ce4962357c5383873fd2ef9d50d4
change-id: 20260604-kernel-doc-cleanup-eeee2b3f73c1
Best regards,
Signature · 1 line
Sven Eckelmann <[email protected]>
Sven Eckelmann
maintainerPATCH 1/5 batman-adv: tp_meter: update stale kernel-doc after refactoring
The tp_meter codebase was recently refactored:
* throughput meter sender and receiver variables were split into two different structures
* the congestion control variables were extracted in a separate structure
But the kernel-doc was not updated everywhere to reflect these changes.
--- net/batman-adv/tp_meter.c | 16 ++++++++-------- net/batman-adv/types.h | 14 ++++++++------ 2 files changed, 16 insertions(+), 14 deletions(-)
net/batman-adv/tp_meter.c +8 -8
@@ -289,7 +289,7 @@ batadv_tp_list_find_sender(struct batadv_priv *bat_priv, const u8 *dst)* @bat_priv: the bat priv with all the mesh interface information * @dst: the other endpoint MAC address to look for * -* Return: if matching session with @dst was found +* Return: true if a matching session with @dst was found, false otherwise */ static bool batadv_tp_list_active(struct batadv_priv *bat_priv, const u8 *dst) __must_hold(&bat_priv->tp_list_lock)
@@ -355,7 +355,7 @@ batadv_tp_list_find_sender_session(struct batadv_priv *bat_priv, const u8 *dst,/** * batadv_tp_vars_common_release() - release batadv_tp_vars_common from lists * and queue for free after rcu grace period -* @ref: kref pointer of the batadv_tp_vars +* @ref: kref pointer of the batadv_tp_vars_common */ static void batadv_tp_vars_common_release (struct kref *ref) {
@@ -391,7 +391,7 @@ static void batadv_tp_sender_put(struct batadv_tp_sender *tp_vars) }/** -* batadv_tp_list_detach() - remove tp receiver session from mesh session list once +* batadv_tp_list_detach() - remove tp session from mesh session list once * @tp_vars: the private data of the current TP meter session * * Return: whether tp_vars was detached from list and reference must be freed
@@ -509,7 +509,7 @@ static void batadv_tp_sender_finish(struct work_struct *work)* batadv_tp_reset_sender_timer() - reschedule the sender timer * @tp_vars: the private TP meter data for this session * -* Reschedule the timer using tp_vars->rto as delay +* Reschedule the timer using tp_vars->cc.rto as delay */ static void batadv_tp_reset_sender_timer (struct batadv_tp_sender *tp_vars) {
@@ -621,9 +621,9 @@ static void batadv_tp_fill_prerandom(struct batadv_tp_sender *tp_vars,* * Create and send a single TP Meter message. * -* Return: 0 on success, BATADV_TP_REASON_DST_UNREACHABLE if the destination is -* not reachable, BATADV_TP_REASON_MEMORY_ERROR if the packet couldn't be -* allocated +* Return: 0 on success, BATADV_TP_REASON_MEMORY_ERROR if the packet couldn't +* be allocated, BATADV_TP_REASON_CANT_SEND if the packet could not be +* transmitted */ static int batadv_tp_send_msg(struct batadv_tp_sender *tp_vars, const u8 *src, struct batadv_orig_node *orig_node,
@@ -913,7 +913,7 @@ static int batadv_tp_wait_available(struct batadv_tp_sender *tp_vars, size_t ple* batadv_tp_send() - main sending thread of a tp meter session * @arg: address of the related tp_vars * -* Return: nothing, this function never returns +* Return: 0 */ static int batadv_tp_send (void *arg) {
net/batman-adv/types.h +8 -6
@@ -1331,7 +1331,7 @@ struct batadv_tp_unacked {/** @len: length of the packet */ u16 len; -/** @list: list node for &batadv_tp_vars.unacked_list */ +/** @list: list node for &batadv_tp_vars_common.unacked_list */ struct list_head list; };
@@ -1367,7 +1367,9 @@ struct batadv_tp_vars_common {struct rcu_head rcu; }; -/** struct batadv_tp_sender_cc - congestion control variables */ +/** +* struct batadv_tp_sender_cc - congestion control variables +*/ struct batadv_tp_sender_cc {/** @fast_recovery: true if in Fast Recovery mode */ bool fast_recovery:1 ;
@@ -1410,7 +1412,7 @@ struct batadv_tp_sender_cc {* struct batadv_tp_sender - sender tp meter private variables per session */ struct batadv_tp_sender { -/** @common: common batadv_tp_vars (best be first member) */ +/** @common: common batadv_tp_vars_common (must be first member) */ struct batadv_tp_vars_common common;/** @start_time: start time in jiffies */
@@ -1437,7 +1439,7 @@ struct batadv_tp_sender {/** @cc: congestion control variables */ struct batadv_tp_sender_cc cc; -/** @cc_lock: lock do protect @cc */ +/** @cc_lock: lock to protect @cc */ spinlock_t cc_lock;/** @tot_sent: amount of data sent/ACKed so far */
@@ -1460,7 +1462,7 @@ struct batadv_tp_sender {* struct batadv_tp_receiver - receiver tp meter private variables per session */ struct batadv_tp_receiver { -/** @common: common batadv_tp_vars (best be first member) */ +/** @common: common batadv_tp_vars_common (must be first member) */ struct batadv_tp_vars_common common;/** @receiving: receiving binary semaphore: 1 if receiving, 0 is not */
@@ -1662,7 +1664,7 @@ struct batadv_priv {/** @forw_bcast_list_lock: lock protecting forw_bcast_list */ spinlock_t forw_bcast_list_lock; -/** @tp_list_lock: spinlock protecting @tp_list */ +/** @tp_list_lock: spinlock protecting @tp_sender_list + @tp_receiver_list */ spinlock_t tp_list_lock;/** @tp_num: number of currently active tp sessions */
Signature · 1 line
2.47.3
Sven Eckelmann
maintainerPATCH 2/5 batman-adv: bla: update stale kernel-doc
In reply to Sven EckelmannThe bridge-loop-avoidance code was changed recently to avoid inconsistent state and race condition problems. The kernel-doc addded in these commits (and related code) has various minor deficits which are now resolved.
--- net/batman-adv/bridge_loop_avoidance.c | 2 +- net/batman-adv/bridge_loop_avoidance.h | 2 +- net/batman-adv/types.h | 10 +++++++--- 3 files changed, 9 insertions(+), 5 deletions(-)
net/batman-adv/bridge_loop_avoidance.c +1 -1
@@ -123,7 +123,7 @@ static bool batadv_compare_backbone_gw(const struct hlist_node *node,* @node: list node of the first entry to compare * @data2: pointer to the second claims * -* Return: true if the claim have the same data, 0 otherwise +* Return: true if the claims have the same data, false otherwise */ static bool batadv_compare_claim (const struct hlist_node *node,const void *data2)
net/batman-adv/bridge_loop_avoidance.h +1 -1
@@ -21,7 +21,7 @@* detect frame sent by bridge loop avoidance * @mac: mac address to check * -* Return: true if the it looks like a loop detect frame +* Return: true if it looks like a loop detect frame * (mac starts with BA:BE), false otherwise */ static inline bool batadv_bla_is_loopdetect_mac (const uint8_t *mac)
net/batman-adv/types.h +7 -3
@@ -1723,22 +1723,26 @@ struct batadv_priv {#ifdef CONFIG_BATMAN_ADV_BLA +/** +* enum batadv_bla_backbone_gw_state - state of a bridge loop avoidance +* backbone gateway +*/ enum batadv_bla_backbone_gw_state {/** * @BATADV_BLA_BACKBONE_GW_STOPPED: backbone gw is being removed -* and it must not longer work on requests +* and it must no longer work on requests */ BATADV_BLA_BACKBONE_GW_STOPPED ,/** * @BATADV_BLA_BACKBONE_GW_UNSYNCED: backbone was detected out -* of sync and a request was send. No traffic is forwarded until the +* of sync and a request was sent. No traffic is forwarded until the * situation is resolved */ BATADV_BLA_BACKBONE_GW_UNSYNCED ,/** -* @BATADV_BLA_BACKBONE_GW_SYNCED: backbone is consider to be in +* @BATADV_BLA_BACKBONE_GW_SYNCED: backbone is considered to be in * sync. traffic can be forwarded */ BATADV_BLA_BACKBONE_GW_SYNCED,
Signature · 1 line
2.47.3
Sven Eckelmann
maintainerPATCH 3/5 batman-adv: uapi: keep kernel-doc in struct member order
In reply to Sven EckelmannThe order of the members of struct batadv_coded_packet and struct batadv_unicast_tvlv_packet didn't match the kernel doc. This is the case for all other structures and should also be done the same way for these two.
--- include/uapi/linux/batadv_packet.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
include/uapi/linux/batadv_packet.h +3 -3
@@ -518,16 +518,16 @@ struct batadv_mcast_packet {* @packet_type: batman-adv packet type, part of the general header * @version: batman-adv protocol version, part of the general header * @ttl: time to live for this packet, part of the general header +* @first_ttvn: tt-version number of first included packet * @first_source: original source of first included packet * @first_orig_dest: original destination of first included packet * @first_crc: checksum of first included packet -* @first_ttvn: tt-version number of first included packet * @second_ttl: ttl of second packet +* @second_ttvn: tt version number of second included packet * @second_dest: second receiver of this coded packet * @second_source: original source of second included packet * @second_orig_dest: original destination of second included packet * @second_crc: checksum of second included packet -* @second_ttvn: tt version number of second included packet * @coded_len: length of network coded part of the payload */ struct batadv_coded_packet {
@@ -554,8 +554,8 @@ struct batadv_coded_packet {* @version: batman-adv protocol version, part of the general header * @ttl: time to live for this packet, part of the general header * @reserved: reserved field (for packet alignment) -* @src: address of the source * @dst: address of the destination +* @src: address of the source * @tvlv_len: length of tvlv data following the unicast tvlv header * @align: 2 bytes to align the header to a 4 byte boundary */
Signature · 1 line
2.47.3
Sven Eckelmann
maintainerPATCH 4/5 batman-adv: fix batadv_v_ogm_packet_recv error handling kernel-doc
In reply to Sven EckelmannAll receive handlers in batman-adv are consuming the skbuff independent of the result of the handler. The "(without freeing the skb) on failure" is therefore not corrrect anymore for the current implementation.
--- net/batman-adv/bat_v_ogm.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
net/batman-adv/bat_v_ogm.c +1 -1
@@ -982,7 +982,7 @@ static void batadv_v_ogm_process(const struct sk_buff *skb, int ogm_offset,* @if_incoming: the interface where this OGM has been received * * Return: NET_RX_SUCCESS and consume the skb on success or returns NET_RX_DROP -* (without freeing the skb) on failure +* (freeing the skb) on failure */ int batadv_v_ogm_packet_recv (struct sk_buff *skb,struct batadv_hard_iface *if_incoming)
Signature · 1 line
2.47.3
Sven Eckelmann
maintainerPATCH 5/5 batman-adv: fix kernel-doc typos and grammar errors
In reply to Sven EckelmannVarious minor errors were gathered over the time in batman-adv's kernel-doc comments. Get rid of many of them before they are copied (again) to new functions.
--- net/batman-adv/bat_v.c | 2 +- net/batman-adv/bat_v_ogm.c | 8 ++++---- net/batman-adv/bitarray.c | 2 +- net/batman-adv/bitarray.h | 2 +- net/batman-adv/fragmentation.c | 3 ++- net/batman-adv/hash.h | 4 ++-- net/batman-adv/mesh-interface.c | 6 +++--- net/batman-adv/netlink.c | 4 ++-- net/batman-adv/originator.c | 4 ++-- net/batman-adv/tvlv.c | 4 ++-- 10 files changed, 20 insertions(+), 19 deletions(-)
net/batman-adv/bat_v.c +1 -1
@@ -587,7 +587,7 @@ batadv_v_gw_get_best_gw_node(struct batadv_priv *bat_priv) }/** -* batadv_v_gw_is_eligible() - check if a originator would be selected as GW +* batadv_v_gw_is_eligible() - check if an originator would be selected as GW * @bat_priv: the bat priv with all the mesh interface information * @curr_gw_orig: originator representing the currently selected GW * @orig_node: the originator representing the new candidate
net/batman-adv/bat_v_ogm.c +4 -4
@@ -513,7 +513,7 @@ static u32 batadv_v_forward_penalty(struct batadv_priv *bat_priv,* @bat_priv: the bat priv with all the mesh interface information * @ogm_received: previously received OGM to be forwarded * @orig_node: the originator which has been updated -* @neigh_node: the neigh_node through with the OGM has been received +* @neigh_node: the neigh_node through which the OGM has been received * @if_incoming: the interface on which this OGM was received on * @if_outgoing: the interface to which the OGM has to be forwarded to *
@@ -600,7 +600,7 @@ static void batadv_v_ogm_forward(struct batadv_priv *bat_priv,* @bat_priv: the bat priv with all the mesh interface information * @ogm2: OGM2 structure * @orig_node: Originator structure for which the OGM has been received -* @neigh_node: the neigh_node through with the OGM has been received +* @neigh_node: the neigh_node through which the OGM has been received * @if_incoming: the interface where this packet was received * @if_outgoing: the interface for which the packet should be considered *
@@ -684,7 +684,7 @@ static int batadv_v_ogm_metric_update(struct batadv_priv *bat_priv,* @ethhdr: the Ethernet header of the OGM2 * @ogm2: OGM2 structure * @orig_node: Originator structure for which the OGM has been received -* @neigh_node: the neigh_node through with the OGM has been received +* @neigh_node: the neigh_node through which the OGM has been received * @if_incoming: the interface where this packet was received * @if_outgoing: the interface for which the packet should be considered *
@@ -779,7 +779,7 @@ static bool batadv_v_ogm_route_update(struct batadv_priv *bat_priv,* @ethhdr: the Ethernet header of the OGM2 * @ogm2: OGM2 structure * @orig_node: Originator structure for which the OGM has been received -* @neigh_node: the neigh_node through with the OGM has been received +* @neigh_node: the neigh_node through which the OGM has been received * @if_incoming: the interface where this packet was received * @if_outgoing: the interface for which the packet should be considered */
net/batman-adv/bitarray.c +1 -1
@@ -24,7 +24,7 @@ static void batadv_bitmap_shift_left(unsigned long *seq_bits, s32 n)* batadv_bit_get_packet() - receive and process one packet within the sequence * number window * @priv: the bat priv with all the mesh interface information -* @seq_bits: pointer to the sequence number receive packet +* @seq_bits: pointer to the sequence number bitmap of received packets * @seq_num_diff: difference between the current/received sequence number and * the last sequence number * @set_mark: whether this packet should be marked in seq_bits
net/batman-adv/bitarray.h +1 -1
@@ -17,7 +17,7 @@/** * batadv_test_bit() - check if bit is set in the current window * -* @seq_bits: pointer to the sequence number receive packet +* @seq_bits: pointer to the sequence number bitmap of received packets * @last_seqno: latest sequence number in seq_bits * @curr_seqno: sequence number to test for *
net/batman-adv/fragmentation.c +2 -1
@@ -309,7 +309,8 @@ batadv_frag_merge_packets(struct hlist_head *chain)* batadv_skb_is_frag() - check if newly merged skb contains unicast fragment * @skb: newly merged skb * -* Return: if newly merged skb is of type BATADV_UNICAST_FRAG +* Return: true if the newly merged skb is of type BATADV_UNICAST_FRAG, false +* otherwise */ static bool batadv_skb_is_frag (struct sk_buff *skb) {
net/batman-adv/hash.h +2 -2
@@ -120,10 +120,10 @@ static inline int batadv_hash_add(struct batadv_hashtable *hash,* @choose: callback calculating the hash index * @data: data passed to the aforementioned callbacks as argument * -* ata could be the structure you use with just the key filled, we just need +* data could be the structure you use with just the key filled, we just need * the key for comparing. * -* Return: returns pointer do data on success, so you can remove the used +* Return: returns pointer to data on success, so you can remove the used * structure yourself, or NULL on error */ static inline void *batadv_hash_remove(struct batadv_hashtable *hash,
net/batman-adv/mesh-interface.c +3 -3
@@ -392,13 +392,13 @@ static netdev_tx_t batadv_interface_tx(struct sk_buff *skb,* @orig_node: originator from which the batman-adv packet was sent * * Sends an ethernet frame to the receive path of the local @mesh_iface. -* skb->data has still point to the batman-adv header with the size @hdr_size. +* skb->data must still point to the batman-adv header with the size @hdr_size. * The caller has to have parsed this header already and made sure that at least * @hdr_size bytes are still available for pull in @skb. * * The packet may still get dropped. This can happen when the encapsulated -* ethernet frame is invalid or contains again an batman-adv packet. Also -* unicast packets will be dropped directly when it was sent between two +* ethernet frame is invalid or contains again a batman-adv packet. Also +* unicast packets will be dropped directly when they were sent between two * isolated clients. */ void batadv_interface_rx(struct net_device *mesh_iface,
net/batman-adv/netlink.c +2 -2
@@ -944,7 +944,7 @@ static int batadv_netlink_set_hardif(struct sk_buff *skb, }/** -* batadv_netlink_dump_hardif() - Dump all hard interface into a messages +* batadv_netlink_dump_hardif() - Dump all hard interfaces into a message * @msg: Netlink message to dump into * @cb: Parameters from query *
@@ -1101,7 +1101,7 @@ static int batadv_netlink_get_vlan(struct sk_buff *skb, struct genl_info *info) }/** -* batadv_netlink_set_vlan() - Get vlan attributes +* batadv_netlink_set_vlan() - Set vlan attributes * @skb: Netlink message with request data * @info: receiver information *
net/batman-adv/originator.c +2 -2
@@ -439,7 +439,7 @@ batadv_orig_ifinfo_new(struct batadv_orig_node *orig_node, }/** -* batadv_neigh_ifinfo_get() - find the ifinfo from an neigh_node +* batadv_neigh_ifinfo_get() - find the ifinfo from a neigh_node * @neigh: the neigh node to be queried * @if_outgoing: the interface for which the ifinfo should be acquired *
@@ -472,7 +472,7 @@ batadv_neigh_ifinfo_get(struct batadv_neigh_node *neigh, }/** -* batadv_neigh_ifinfo_new() - search and possibly create an neigh_ifinfo object +* batadv_neigh_ifinfo_new() - search and possibly create a neigh_ifinfo object * @neigh: the neigh node to be queried * @if_outgoing: the interface for which the ifinfo should be acquired *
net/batman-adv/tvlv.c +2 -2
@@ -48,7 +48,7 @@ static void batadv_tvlv_handler_release(struct kref *ref) }/** -* batadv_tvlv_handler_put() - decrement the tvlv container refcounter and +* batadv_tvlv_handler_put() - decrement the tvlv handler refcounter and * possibly release it * @tvlv_handler: the tvlv handler to free */
@@ -272,7 +272,7 @@ void batadv_tvlv_container_register(struct batadv_priv *bat_priv,* @additional_packet_len: requested additional packet size on top of minimum * size * -* Return: true of the packet buffer could be changed to the requested size, +* Return: true if the packet buffer could be changed to the requested size, * false otherwise. */ static bool batadv_tvlv_realloc_packet_buff(struct batadv_ogm_buf *ogm_buff,
Signature · 1 line
2.47.3