Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e57acf8e authored by Sven Eckelmann's avatar Sven Eckelmann Committed by Simon Wunderlich
Browse files

batman-adv: Add kernel-doc to functions in headers 



Externally visible functions should be documented with kernel-doc. This
usually refers to non-static functions but also static inline files in
headers are visible in other files and should therefore be documented.

Signed-off-by: default avatarSven Eckelmann <sven@narfation.org>
Signed-off-by: default avatarSimon Wunderlich <sw@simonwunderlich.de>
parent 73844a8c

net/batman-adv/bitarray.h

+6 −1
Original line number Diff line number Diff line
@@ -47,7 +47,12 @@ static inline bool batadv_test_bit(const unsigned long *seq_bits, 
	return test_bit(diff, seq_bits) != 0;

}



/* turn corresponding bit on, so we can remember that we got the packet */

/**

 * batadv_set_bit() - Turn corresponding bit on, so we can remember that we got

 *  the packet

 * @seq_bits: bitmap of the packet receive window

 * @n: relative sequence number of newly received packet

 */

static inline void batadv_set_bit(unsigned long *seq_bits, s32 n)

{

	/* if too old, just drop it */

net/batman-adv/hard-interface.h

+6 −0
Original line number Diff line number Diff line
@@ -130,6 +130,12 @@ static inline void batadv_hardif_put(struct batadv_hard_iface *hard_iface) 
	kref_put(&hard_iface->refcount, batadv_hardif_release);

}



/**

 * batadv_primary_if_get_selected() - Get reference to primary interface

 * @bat_priv: the bat priv with all the soft interface information

 *

 * Return: primary interface (with increased refcnt), otherwise NULL

 */

static inline struct batadv_hard_iface *

batadv_primary_if_get_selected(struct batadv_priv *bat_priv)

{

net/batman-adv/hash.h

+9 −2
Original line number Diff line number Diff line
@@ -121,8 +121,15 @@ static inline int batadv_hash_add(struct batadv_hashtable *hash, 
	return ret;

}



/* removes data from hash, if found. data could be the structure you use with

 * just the key filled, we just need the key for comparing.

/**

 * batadv_hash_remove() - Removes data from hash, if found

 * @hash: hash table

 * @compare: callback to determine if 2 hash elements are identical

 * @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

 * the key for comparing.

 *

 * Return: returns pointer do data on success, so you can remove the used

 * structure yourself, or NULL on error

net/batman-adv/log.h

+34 −1
Original line number Diff line number Diff line
@@ -79,7 +79,14 @@ enum batadv_dbg_level { 
int batadv_debug_log(struct batadv_priv *bat_priv, const char *fmt, ...)

__printf(2, 3);



/* possibly ratelimited debug output */

/**

 * _batadv_dbg() - Store debug output with(out) ratelimiting

 * @type: type of debug message

 * @bat_priv: the bat priv with all the soft interface information

 * @ratelimited: whether output should be rate limited

 * @fmt: format string

 * @arg...: variable arguments

 */

#define _batadv_dbg(type, bat_priv, ratelimited, fmt, arg...)		\

	do {								\

		struct batadv_priv *__batpriv = (bat_priv);		\
@@ -98,11 +105,30 @@ static inline void _batadv_dbg(int type __always_unused, 
}

#endif



/**

 * batadv_dbg() - Store debug output without ratelimiting

 * @type: type of debug message

 * @bat_priv: the bat priv with all the soft interface information

 * @arg...: format string and variable arguments

 */

#define batadv_dbg(type, bat_priv, arg...) \

	_batadv_dbg(type, bat_priv, 0, ## arg)



/**

 * batadv_dbg_ratelimited() - Store debug output with ratelimiting

 * @type: type of debug message

 * @bat_priv: the bat priv with all the soft interface information

 * @arg...: format string and variable arguments

 */

#define batadv_dbg_ratelimited(type, bat_priv, arg...) \

	_batadv_dbg(type, bat_priv, 1, ## arg)



/**

 * batadv_info() - Store message in debug buffer and print it to kmsg buffer

 * @net_dev: the soft interface net device

 * @fmt: format string

 * @arg...: variable arguments

 */

#define batadv_info(net_dev, fmt, arg...)				\

	do {								\

		struct net_device *_netdev = (net_dev);                 \
@@ -110,6 +136,13 @@ static inline void _batadv_dbg(int type __always_unused, 
		batadv_dbg(BATADV_DBG_ALL, _batpriv, fmt, ## arg);	\

		pr_info("%s: " fmt, _netdev->name, ## arg);		\

	} while (0)



/**

 * batadv_err() - Store error in debug buffer and print it to kmsg buffer

 * @net_dev: the soft interface net device

 * @fmt: format string

 * @arg...: variable arguments

 */

#define batadv_err(net_dev, fmt, arg...)				\

	do {								\

		struct net_device *_netdev = (net_dev);                 \

net/batman-adv/main.h

+69 −13
Original line number Diff line number Diff line
@@ -298,40 +298,96 @@ static inline bool batadv_has_timed_out(unsigned long timestamp, 
	return time_is_before_jiffies(timestamp + msecs_to_jiffies(timeout));

}



/**

 * batadv_atomic_dec_not_zero() - Decrease unless the number is 0

 * @v: pointer of type atomic_t

 *

 * Return: non-zero if v was not 0, and zero otherwise.

 */

#define batadv_atomic_dec_not_zero(v)	atomic_add_unless((v), -1, 0)



/* Returns the smallest signed integer in two's complement with the sizeof x */

/**

 * batadv_smallest_signed_int() - Returns the smallest signed integer in two's

 *  complement with the sizeof x

 * @x: type of integer

 *

 * Return: smallest signed integer of type

 */

#define batadv_smallest_signed_int(x) (1u << (7u + 8u * (sizeof(x) - 1u)))



/* Checks if a sequence number x is a predecessor/successor of y.

 * they handle overflows/underflows and can correctly check for a

 * predecessor/successor unless the variable sequence number has grown by

 * more then 2**(bitwidth(x)-1)-1.

/**

 * batadv_seq_before() - Checks if a sequence number x is a predecessor of y

 * @x: potential predecessor of @y

 * @y: value to compare @x against

 *

 * It handles overflows/underflows and can correctly check for a predecessor

 * unless the variable sequence number has grown by more then

 * 2**(bitwidth(x)-1)-1.

 *

 * This means that for a u8 with the maximum value 255, it would think:

 *  - when adding nothing - it is neither a predecessor nor a successor

 *  - before adding more than 127 to the starting value - it is a predecessor,

 *  - when adding 128 - it is neither a predecessor nor a successor,

 *  - after adding more than 127 to the starting value - it is a successor

 *

 * * when adding nothing - it is neither a predecessor nor a successor

 * * before adding more than 127 to the starting value - it is a predecessor,

 * * when adding 128 - it is neither a predecessor nor a successor,

 * * after adding more than 127 to the starting value - it is a successor

 *

 * Return: true when x is a predecessor of y, false otherwise

 */

#define batadv_seq_before(x, y) ({typeof(x)_d1 = (x); \

				 typeof(y)_d2 = (y); \

				 typeof(x)_dummy = (_d1 - _d2); \

				 (void)(&_d1 == &_d2); \

				 _dummy > batadv_smallest_signed_int(_dummy); })



/**

 * batadv_seq_after() - Checks if a sequence number x is a successor of y

 * @x: potential sucessor of @y

 * @y: value to compare @x against

 *

 * It handles overflows/underflows and can correctly check for a successor

 * unless the variable sequence number has grown by more then

 * 2**(bitwidth(x)-1)-1.

 *

 * This means that for a u8 with the maximum value 255, it would think:

 *

 * * when adding nothing - it is neither a predecessor nor a successor

 * * before adding more than 127 to the starting value - it is a predecessor,

 * * when adding 128 - it is neither a predecessor nor a successor,

 * * after adding more than 127 to the starting value - it is a successor

 *

 * Return: true when x is a successor of y, false otherwise

 */

#define batadv_seq_after(x, y) batadv_seq_before(y, x)



/* Stop preemption on local cpu while incrementing the counter */

/**

 * batadv_add_counter() - Add to per cpu statistics counter of soft interface

 * @bat_priv: the bat priv with all the soft interface information

 * @idx: counter index which should be modified

 * @count: value to increase counter by

 *

 * Stop preemption on local cpu while incrementing the counter

 */

static inline void batadv_add_counter(struct batadv_priv *bat_priv, size_t idx,

				      size_t count)

{

	this_cpu_add(bat_priv->bat_counters[idx], count);

}



/**

 * batadv_inc_counter() - Increase per cpu statistics counter of soft interface

 * @b: the bat priv with all the soft interface information

 * @i: counter index which should be modified

 */

#define batadv_inc_counter(b, i) batadv_add_counter(b, i, 1)



/* Define a macro to reach the control buffer of the skb. The members of the

 * control buffer are defined in struct batadv_skb_cb in types.h.

 * The macro is inspired by the similar macro TCP_SKB_CB() in tcp.h.

/**

 * BATADV_SKB_CB() - Get batadv_skb_cb from skb control buffer

 * @__skb: skb holding the control buffer

 *

 * The members of the control buffer are defined in struct batadv_skb_cb in

 * types.h. The macro is inspired by the similar macro TCP_SKB_CB() in tcp.h.

 *

 * Return: pointer to the batadv_skb_cb of the skb

 */

#define BATADV_SKB_CB(__skb)       ((struct batadv_skb_cb *)&((__skb)->cb[0]))