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.

Sven Eckelmann committed 5 months ago

Commit 3ebcacc1 parent e558ee017 files · +711 −35Browse files

Unified · Split

17 files

include/uapi/linux/batadv_packet.h +11 −5
net/batman-adv/bat_algo.c +10 −0
net/batman-adv/bat_iv_ogm.c +160 −6
net/batman-adv/bat_v.c +52 −0
net/batman-adv/bitarray.c +8 −1
net/batman-adv/distributed-arp-table.c +38 −0
net/batman-adv/gateway_client.c +8 −0
net/batman-adv/hard-interface.c +82 −0
net/batman-adv/hash.c +4 −1
net/batman-adv/hash.h +24 −10
net/batman-adv/main.c +32 −4
net/batman-adv/mesh-interface.c +63 −0
net/batman-adv/netlink.c +7 −1
net/batman-adv/originator.c +7 −0
net/batman-adv/routing.c +31 −0
net/batman-adv/translation-table.c +172 −5
net/batman-adv/types.h +2 −2

include/uapi/linux/batadv_packet.h+11−5

@@ -192,13 +192,19 @@ enum batadv_tvlv_type { · 191 unmodified lines
192	192	};
193	193
194	194	#pragma pack(2)
195		−/* the destination hardware field in the ARP frame is used to
196		− * transport the claim type and the group id
	195	+/**
	196	+ * struct batadv_bla_claim_dst - layout of the destination MAC of a BLA claim
	197	+ * frame
	198	+ * @magic: fixed magic prefix (FF:43:05) identifying claim frames
	199	+ * @type: claim frame type, see &enum batadv_bla_claimframe
	200	+ * @group: group identifier of the announcing backbone gateway
	201	+ *
	202	+ * used in the destination hardware field of the ARP frame
197	203	*/
198	204	struct batadv_bla_claim_dst {
199		− __u8 magic[3]; /* FF:43:05 */
200		− __u8 type; /* bla_claimframe */
201		− __be16 group; /* group id */
	205	+ __u8 magic[3];
	206	+ __u8 type;
	207	+ __be16 group;
202	208	};
203	209
204	210	/**

net/batman-adv/bat_algo.c+10−0

@@ -116,6 +116,16 @@ int batadv_algo_select(struct batadv_priv bat_priv, const char name) · 115 unmodified lines
116	116	return 0;
117	117	}
118	118
	119	+/**
	120	+ * batadv_param_set_ra() - Validate and store routing_algo module parameter
	121	+ * @val: new value for the routing_algo module parameter
	122	+ * @kp: kernel parameter description used to store the value
	123	+ *
	124	+ * Check that the requested algorithm is known to batman-adv and then store
	125	+ * the name as the new default routing algorithm.
	126	+ *
	127	+ * Return: 0 on success or negative error number in case of failure
	128	+ */
119	129	static int batadv_param_set_ra(const char val, const struct kernel_param kp)
120	130	{
121	131	struct batadv_algo_ops *bat_algo_ops;

net/batman-adv/bat_iv_ogm.c+160−6

@@ -171,6 +171,14 @@ free_orig_node_hash: · 170 unmodified lines
171	171	return NULL;
172	172	}
173	173
	174	+/**
	175	+ * batadv_iv_ogm_neigh_new() - retrieve or create a B.A.T.M.A.N. IV neighbour
	176	+ * @hard_iface: the interface where the neighbour is connected to
	177	+ * @neigh_addr: the mac address of the neighbour
	178	+ * @orig_node: originator object representing the neighbour
	179	+ *
	180	+ * Return: pointer to the neigh_node or NULL in case of failure
	181	+ */
174	182	static struct batadv_neigh_node *
175	183	batadv_iv_ogm_neigh_new(struct batadv_hard_iface *hard_iface,
176	184	const u8 *neigh_addr,
@@ -183,6 +191,14 @@ batadv_iv_ogm_neigh_new(struct batadv_hard_iface *hard_iface, · 6 unmodified lines
183	191	return neigh_node;
184	192	}
185	193
	194	+/**
	195	+ * batadv_iv_ogm_iface_enable() - prepare an interface for B.A.T.M.A.N. IV
	196	+ * @hard_iface: the interface to prepare
	197	+ *
	198	+ * Allocate and prepare the per-interface OGM buffer
	199	+ *
	200	+ * Return: 0 on success or negative error number in case of failure
	201	+ */
186	202	static int batadv_iv_ogm_iface_enable(struct batadv_hard_iface *hard_iface)
187	203	{
188	204	struct batadv_ogm_packet *batadv_ogm_packet;
@@ -220,6 +236,14 @@ static int batadv_iv_ogm_iface_enable(struct batadv_hard_iface *hard_iface) · 31 unmodified lines
220	236	return 0;
221	237	}
222	238
	239	+/**
	240	+ * batadv_iv_ogm_iface_disable() - release B.A.T.M.A.N. IV resources of an
	241	+ * interface
	242	+ * @hard_iface: the interface which is shutting down
	243	+ *
	244	+ * Free the per-interface OGM buffer and cancel a possibly pending OGM
	245	+ * rescheduling work.
	246	+ */
223	247	static void batadv_iv_ogm_iface_disable(struct batadv_hard_iface *hard_iface)
224	248	{
225	249	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) · 7 unmodified lines
233	257	disable_delayed_work_sync(&hard_iface->bat_iv.reschedule_work);
234	258	}
235	259
	260	+/**
	261	+ * batadv_iv_ogm_iface_update_mac() - update the originator MAC stored in the
	262	+ * per-interface OGM buffer
	263	+ * @hard_iface: the interface for which the OGM buffer should be updated
	264	+ */
236	265	static void batadv_iv_ogm_iface_update_mac(struct batadv_hard_iface *hard_iface)
237	266	{
238	267	struct batadv_ogm_packet *batadv_ogm_packet;
@@ -254,6 +283,14 @@ unlock: · 15 unmodified lines
254	283	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
255	284	}
256	285
	286	+/**
	287	+ * batadv_iv_ogm_primary_iface_set() - apply primary interface state to
	288	+ * a batadv_hard_iface
	289	+ * @hard_iface: interface which just became the primary
	290	+ *
	291	+ * The primary interface uses the full TTL for its own OGMs, so adjust the TTL
	292	+ * stored in the OGM template buffer accordingly.
	293	+ */
257	294	static void
258	295	batadv_iv_ogm_primary_iface_set(struct batadv_hard_iface *hard_iface)
259	296	{
@@ -273,7 +310,17 @@ unlock: · 13 unmodified lines
273	310	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
274	311	}
275	312
276		−/* when do we schedule our own ogm to be sent */
	313	+/**
	314	+ * batadv_iv_ogm_emit_send_time() - calculate the jiffies when an own OGM
	315	+ * should be sent next
	316	+ * @bat_priv: the bat priv with all the mesh interface information
	317	+ *
	318	+ * The next emission point is the configured orig_interval randomised by
	319	+ * +/- BATADV_JITTER milliseconds to reduce chance of potential collisions
	320	+ * between neighbours.
	321	+ *
	322	+ * Return: jiffies value when the next OGM should be transmitted
	323	+ */
277	324	static unsigned long
278	325	batadv_iv_ogm_emit_send_time(const struct batadv_priv *bat_priv)
279	326	{
@@ -285,13 +332,24 @@ batadv_iv_ogm_emit_send_time(const struct batadv_priv *bat_priv) · 5 unmodified lines
285	332	return jiffies + msecs_to_jiffies(msecs);
286	333	}
287	334
288		−/* when do we schedule a ogm packet to be sent */
	335	+/**
	336	+ * batadv_iv_ogm_fwd_send_time() - calculate the jiffies when a forwarded OGM
	337	+ * should be sent next
	338	+ *
	339	+ * Return: jiffies value at which a forwarded OGM should be transmitted
	340	+ */
289	341	static unsigned long batadv_iv_ogm_fwd_send_time(void)
290	342	{
291	343	return jiffies + msecs_to_jiffies(get_random_u32_below(BATADV_JITTER / 2));
292	344	}
293	345
294		−/* apply hop penalty for a normal link */
	346	+/**
	347	+ * batadv_hop_penalty() - apply the configured hop penalty to a TQ value
	348	+ * @tq: input TQ value to be reduced
	349	+ * @bat_priv: the bat priv with all the mesh interface information
	350	+ *
	351	+ * Return: the TQ value after the hop penalty has been applied
	352	+ */
295	353	static u8 batadv_hop_penalty(u8 tq, const struct batadv_priv *bat_priv)
296	354	{
297	355	int hop_penalty = READ_ONCE(bat_priv->hop_penalty);
@@ -337,7 +395,15 @@ batadv_iv_ogm_aggr_packet(int buff_pos, int packet_len, · 39 unmodified lines
337	395	return next_buff_pos <= packet_len;
338	396	}
339	397
340		−/* send a batman ogm to a given interface */
	398	+/**
	399	+ * batadv_iv_ogm_send_to_if() - send a batman OGM to a given interface
	400	+ * @forw_packet: forward packet containing the OGM(s) to be transmitted
	401	+ * @hard_iface: interface to send the OGM out on
	402	+ *
	403	+ * Update the direct link flags of each aggregated OGM for the outgoing
	404	+ * interface, log the transmission and finally hand a clone of the skb to the
	405	+ * lower layer for broadcast.
	406	+ */
341	407	static void batadv_iv_ogm_send_to_if(struct batadv_forw_packet *forw_packet,
342	408	struct batadv_hard_iface *hard_iface)
343	409	{
@@ -401,7 +467,13 @@ static void batadv_iv_ogm_send_to_if(struct batadv_forw_packet *forw_packet, · 57 unmodified lines
401	467	}
402	468	}
403	469
404		−/* send a batman ogm packet */
	470	+/**
	471	+ * batadv_iv_ogm_emit() - emit an (aggregated) OGM packet
	472	+ * @forw_packet: forward packet which should be emitted
	473	+ *
	474	+ * The @forw_packet will be emitted but not consumed. When the interface is
	475	+ * no longer active, the transmission will be skipped.
	476	+ */
405	477	static void batadv_iv_ogm_emit(struct batadv_forw_packet *forw_packet)
406	478	{
407	479	if (!forw_packet->if_incoming) {
@@ -603,7 +675,14 @@ static bool batadv_iv_ogm_aggregate_new(const unsigned char *packet_buff, · 195 unmodified lines
603	675	return true;
604	676	}
605	677
606		−/* aggregate a new packet into the existing ogm packet */
	678	+/**
	679	+ * batadv_iv_ogm_aggregate() - append an OGM to an existing aggregated forward
	680	+ * packet
	681	+ * @forw_packet_aggr: aggregated forward packet to extend
	682	+ * @packet_buff: pointer to the OGM to append
	683	+ * @packet_len: length of the OGM to append
	684	+ * @direct_link: true if @packet_buff was received as a direct link OGM
	685	+ */
607	686	static void batadv_iv_ogm_aggregate(struct batadv_forw_packet *forw_packet_aggr,
608	687	const unsigned char *packet_buff,
609	688	int packet_len, bool direct_link)
@@ -699,6 +778,21 @@ static bool batadv_iv_ogm_queue_add(struct batadv_priv *bat_priv, · 89 unmodified lines
699	778	}
700	779	}
701	780
	781	+/**
	782	+ * batadv_iv_ogm_forward() - rebroadcast a received OGM
	783	+ * @orig_node: originator that sent the OGM
	784	+ * @ethhdr: ethernet header of the OGM packet
	785	+ * @batadv_ogm_packet: OGM packet to be forwarded
	786	+ * @is_single_hop_neigh: true if the OGM was received via a one-hop neighbour
	787	+ * @is_from_best_next_hop: true if the sender is the currently selected best
	788	+ * next hop towards @orig_node
	789	+ * @if_incoming: interface where the packet was received
	790	+ * @if_outgoing: interface for which the retransmission should be considered
	791	+ *
	792	+ * Decrement the TTL, apply the hop penalty and queue the OGM for
	793	+ * retransmission. OGMs that do not arrive over the best next hop are only
	794	+ * forwarded for link-quality measurement reasons (and marked accordingly).
	795	+ */
702	796	static void batadv_iv_ogm_forward(struct batadv_orig_node *orig_node,
703	797	const struct ethhdr *ethhdr,
704	798	struct batadv_ogm_packet *batadv_ogm_packet,
@@ -899,6 +993,13 @@ out: · 194 unmodified lines
899	993	batadv_hardif_put(primary_if);
900	994	}
901	995
	996	+/**
	997	+ * batadv_iv_ogm_schedule() - schedule the next OGM transmission on an
	998	+ * interface
	999	+ * @hard_iface: interface for which the next OGM should be scheduled
	1000	+ *
	1001	+ * Take the OGM buffer mutex and prepare the next OGM for transmission.
	1002	+ */
902	1003	static void batadv_iv_ogm_schedule(struct batadv_hard_iface *hard_iface)
903	1004	{
904	1005	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) · 4 unmodified lines
909	1010	mutex_unlock(&hard_iface->bat_iv.ogm_buff_mutex);
910	1011	}
911	1012
	1013	+/**
	1014	+ * batadv_iv_ogm_reschedule() - work-queue helper to rerun batadv_iv_ogm_schedule()
	1015	+ * @work: work item embedded in the hard interface
	1016	+ *
	1017	+ * Invoked from the per-interface reschedule_work delayed work when the
	1018	+ * previous attempt to enqueue the own OGM failed.
	1019	+ */
912	1020	static void batadv_iv_ogm_reschedule(struct work_struct *work)
913	1021	{
914	1022	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, · 850 unmodified lines
1765	1873	batadv_orig_node_put(orig_node);
1766	1874	}
1767	1875
	1876	+/**
	1877	+ * batadv_iv_send_outstanding_bat_ogm_packet() - work-queue helper to emit a
	1878	+ * queued forward packet
	1879	+ * @work: work item embedded in the forward packet
	1880	+ *
	1881	+ * Emit the queued OGM forward packet and, for own primary-interface packets,
	1882	+ * schedule the next periodic OGM. The forward packet is freed afterwards.
	1883	+ */
1768	1884	static void batadv_iv_send_outstanding_bat_ogm_packet(struct work_struct *work)
1769	1885	{
1770	1886	struct delayed_work *delayed_work;
@@ -1803,6 +1919,17 @@ out: · 32 unmodified lines
1803	1919	batadv_forw_packet_free(forw_packet, dropped);
1804	1920	}
1805	1921
	1922	+/**
	1923	+ * batadv_iv_ogm_receive() - receive a B.A.T.M.A.N. IV OGM packet
	1924	+ * @skb: skb containing the OGM packet
	1925	+ * @if_incoming: interface where the packet was received
	1926	+ *
	1927	+ * Validate the packet, then split the aggregated OGM packet into individual
	1928	+ * OGMs and hand each of them to batadv_iv_ogm_process(). Ownership of @skb is
	1929	+ * always taken over by this function.
	1930	+ *
	1931	+ * Return: NET_RX_SUCCESS or NET_RX_DROP
	1932	+ */
1806	1933	static int batadv_iv_ogm_receive(struct sk_buff *skb,
1807	1934	struct batadv_hard_iface *if_incoming)
1808	1935	{
@@ -2310,6 +2437,12 @@ batadv_iv_ogm_neigh_is_sob(struct batadv_neigh_node *neigh1, · 501 unmodified lines
2310	2437	return ret;
2311	2438	}
2312	2439
	2440	+/**
	2441	+ * batadv_iv_iface_enabled() - notification handler for activated interfaces
	2442	+ * @hard_iface: interface that was just activated
	2443	+ *
	2444	+ * Set up the per-interface reschedule work and start sending periodic OGMs.
	2445	+ */
2313	2446	static void batadv_iv_iface_enabled(struct batadv_hard_iface *hard_iface)
2314	2447	{
2315	2448	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) · 12 unmodified lines
2328	2461	WRITE_ONCE(bat_priv->gw.sel_class, 20);
2329	2462	}
2330	2463
	2464	+/**
	2465	+ * batadv_iv_gw_get_best_gw_node() - retrieve the best gateway node based on
	2466	+ * the B.A.T.M.A.N. IV metric and the configured GW selection class
	2467	+ * @bat_priv: the bat priv with all the mesh interface information
	2468	+ *
	2469	+ * Return: gateway node with the highest score for the current selection class,
	2470	+ * or NULL if no eligible gateway exists.
	2471	+ */
2331	2472	static struct batadv_gw_node *
2332	2473	batadv_iv_gw_get_best_gw_node(struct batadv_priv *bat_priv)
2333	2474	{
@@ -2405,6 +2546,19 @@ next: · 71 unmodified lines
2405	2546	return curr_gw;
2406	2547	}
2407	2548
	2549	+/**
	2550	+ * batadv_iv_gw_is_eligible() - check whether a new gateway should replace the
	2551	+ * currently selected one
	2552	+ * @bat_priv: the bat priv with all the mesh interface information
	2553	+ * @curr_gw_orig: originator of the currently selected gateway
	2554	+ * @orig_node: originator of the gateway candidate
	2555	+ *
	2556	+ * Compare the TQ values of @curr_gw_orig and @orig_node, taking the configured
	2557	+ * gateway selection class into account.
	2558	+ *
	2559	+ * Return: true if @orig_node should take over as the active gateway, false
	2560	+ * otherwise
	2561	+ */
2408	2562	static bool batadv_iv_gw_is_eligible(struct batadv_priv *bat_priv,
2409	2563	struct batadv_orig_node *curr_gw_orig,
2410	2564	struct batadv_orig_node *orig_node)

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

@@ -41,6 +41,13 @@ · 40 unmodified lines
41	41	#include "netlink.h"
42	42	#include "originator.h"
43	43
	44	+/**
	45	+ * batadv_v_iface_activate() - finalise the activation of a hard interface
	46	+ * @hard_iface: interface to activate
	47	+ *
	48	+ * Reuse the currently selected primary interface to seed the ELP packet.
	49	+ * Immediately activate the interface.
	50	+ */
44	51	static void batadv_v_iface_activate(struct batadv_hard_iface *hard_iface)
45	52	{
46	53	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) · 14 unmodified lines
61	68	hard_iface->if_status = BATADV_IF_ACTIVE;
62	69	}
63	70
	71	+/**
	72	+ * batadv_v_iface_enable() - enable the B.A.T.M.A.N. V protocol on an
	73	+ * interface
	74	+ * @hard_iface: interface to enable
	75	+ *
	76	+ * Enable the ELP and OGM components for @hard_iface. On error, the partially
	77	+ * enabled state is rolled back before returning.
	78	+ *
	79	+ * Return: 0 on success or negative error number in case of failure
	80	+ */
64	81	static int batadv_v_iface_enable(struct batadv_hard_iface *hard_iface)
65	82	{
66	83	int ret;
@@ -76,12 +93,21 @@ static int batadv_v_iface_enable(struct batadv_hard_iface *hard_iface) · 9 unmodified lines
76	93	return ret;
77	94	}
78	95
	96	+/**
	97	+ * batadv_v_iface_disable() - disable the B.A.T.M.A.N. V protocol on an
	98	+ * interface
	99	+ * @hard_iface: interface to disable
	100	+ */
79	101	static void batadv_v_iface_disable(struct batadv_hard_iface *hard_iface)
80	102	{
81	103	batadv_v_ogm_iface_disable(hard_iface);
82	104	batadv_v_elp_iface_disable(hard_iface);
83	105	}
84	106
	107	+/**
	108	+ * batadv_v_primary_iface_set() - apply primary interface state
	109	+ * @hard_iface: interface which just became the primary
	110	+ */
85	111	static void batadv_v_primary_iface_set(struct batadv_hard_iface *hard_iface)
86	112	{
87	113	batadv_v_elp_primary_iface_set(hard_iface);
@@ -109,6 +135,11 @@ out: · 21 unmodified lines
109	135	batadv_hardif_put(primary_if);
110	136	}
111	137
	138	+/**
	139	+ * batadv_v_hardif_neigh_init() - initialise the B.A.T.M.A.N. V state of a
	140	+ * hard interface neighbour
	141	+ * @hardif_neigh: hard interface neighbour to initialise
	142	+ */
112	143	static void
113	144	batadv_v_hardif_neigh_init(struct batadv_hardif_neigh_node *hardif_neigh)
114	145	{
@@ -444,6 +475,16 @@ batadv_v_orig_dump(struct sk_buff msg, struct netlink_callback cb, · 329 unmodified lines
444	475	cb->args[2] = sub;
445	476	}
446	477
	478	+/**
	479	+ * batadv_v_neigh_cmp() - compare two B.A.T.M.A.N. V neighbours by throughput
	480	+ * @neigh1: first neighbour to compare
	481	+ * @if_outgoing1: outgoing interface to use for @neigh1
	482	+ * @neigh2: second neighbour to compare
	483	+ * @if_outgoing2: outgoing interface to use for @neigh2
	484	+ *
	485	+ * Return: a positive value if @neigh1 is better, a negative value if @neigh2
	486	+ * is better and 0 if both have equal throughput
	487	+ */
447	488	static int batadv_v_neigh_cmp(struct batadv_neigh_node *neigh1,
448	489	struct batadv_hard_iface *if_outgoing1,
449	490	struct batadv_neigh_node *neigh2,
@@ -469,6 +510,17 @@ err_ifinfo1: · 19 unmodified lines
469	510	return ret;
470	511	}
471	512
	513	+/**
	514	+ * batadv_v_neigh_is_sob() - check whether two B.A.T.M.A.N. V neighbours have
	515	+ * a similar or better throughput
	516	+ * @neigh1: first neighbour to compare
	517	+ * @if_outgoing1: outgoing interface to use for @neigh1
	518	+ * @neigh2: second neighbour to compare
	519	+ * @if_outgoing2: outgoing interface to use for @neigh2
	520	+ *
	521	+ * Return: true if the throughput of @neigh2 is at least 3/4 of the
	522	+ * @neigh1 throughput
	523	+ */
472	524	static bool batadv_v_neigh_is_sob(struct batadv_neigh_node *neigh1,
473	525	struct batadv_hard_iface *if_outgoing1,
474	526	struct batadv_neigh_node *neigh2,

net/batman-adv/bitarray.c+8−1

@@ -11,7 +11,14 @@ · 10 unmodified lines
11	11
12	12	#include "log.h"
13	13
14		−/* shift the packet array by n places. */
	14	+/**
	15	+ * batadv_bitmap_shift_left() - shift the sequence number bitmap left
	16	+ * @seq_bits: the sequence number bitmap to shift
	17	+ * @n: number of positions to shift left
	18	+ *
	19	+ * Shift @seq_bits by @n positions. No-op if @n is not within the bounds of
	20	+ * the bitmap.
	21	+ */
15	22	static void batadv_bitmap_shift_left(unsigned long *seq_bits, s32 n)
16	23	{
17	24	if (n <= 0 \|\| n >= BATADV_TQ_LOCAL_WINDOW_SIZE)

net/batman-adv/distributed-arp-table.c+38−0

@@ -50,27 +50,65 @@ · 49 unmodified lines
50	50	#include "translation-table.h"
51	51	#include "tvlv.h"
52	52
	53	+/**
	54	+ * enum batadv_bootpop - BOOTP/DHCP message op codes
	55	+ */
53	56	enum batadv_bootpop {
	57	+ /** @BATADV_BOOTREPLY: server-to-client reply */
54	58	BATADV_BOOTREPLY = 2,
55	59	};
56	60
	61	+/**
	62	+ * enum batadv_boothtype - BOOTP/DHCP hardware address types
	63	+ */
57	64	enum batadv_boothtype {
	65	+ /** @BATADV_HTYPE_ETHERNET: Ethernet (10Mb) */
58	66	BATADV_HTYPE_ETHERNET = 1,
59	67	};
60	68
	69	+/**
	70	+ * enum batadv_dhcpoptioncode - DHCP option codes relevant for batman-adv DAT
	71	+ */
61	72	enum batadv_dhcpoptioncode {
	73	+ /** @BATADV_DHCP_OPT_PAD: pad option */
62	74	BATADV_DHCP_OPT_PAD = 0,
	75	+
	76	+ /** @BATADV_DHCP_OPT_MSG_TYPE: DHCP message type option */
63	77	BATADV_DHCP_OPT_MSG_TYPE = 53,
	78	+
	79	+ /** @BATADV_DHCP_OPT_END: end of options marker */
64	80	BATADV_DHCP_OPT_END = 255,
65	81	};
66	82
	83	+/**
	84	+ * enum batadv_dhcptype - DHCP message types relevant for batman-adv DAT
	85	+ */
67	86	enum batadv_dhcptype {
	87	+ /** @BATADV_DHCPACK: DHCPACK message */
68	88	BATADV_DHCPACK = 5,
69	89	};
70	90
71	91	/* { 99, 130, 83, 99 } */
72	92	#define BATADV_DHCP_MAGIC 1669485411
73	93
	94	+/**
	95	+ * struct batadv_dhcp_packet - BOOTP/DHCP packet header
	96	+ * @op: message op code / message type
	97	+ * @htype: hardware address type
	98	+ * @hlen: hardware address length
	99	+ * @hops: number of relay hops
	100	+ * @xid: transaction identifier
	101	+ * @secs: seconds elapsed since client started trying to boot
	102	+ * @flags: BOOTP/DHCP flags
	103	+ * @ciaddr: client IP address
	104	+ * @yiaddr: "your" (client) IP address as assigned by the server
	105	+ * @siaddr: IP address of next server to use in bootstrap
	106	+ * @giaddr: relay agent IP address
	107	+ * @chaddr: client hardware address
	108	+ * @sname: optional server host name
	109	+ * @file: boot file name
	110	+ * @magic: BOOTP/DHCP magic cookie identifying the start of options
	111	+ */
74	112	struct batadv_dhcp_packet {
75	113	__u8 op;
76	114	__u8 htype;

net/batman-adv/gateway_client.c+8−0

@@ -125,6 +125,14 @@ out: · 124 unmodified lines
125	125	return orig_node;
126	126	}
127	127
	128	+/**
	129	+ * batadv_gw_select() - select a new currently active gateway
	130	+ * @bat_priv: the bat priv with all the mesh interface information
	131	+ * @new_gw_node: gateway node to be set as the current gateway, may be NULL
	132	+ *
	133	+ * Atomically replace the currently active gateway with @new_gw_node and drop
	134	+ * the reference to the previous one.
	135	+ */
128	136	static void batadv_gw_select(struct batadv_priv *bat_priv,
129	137	struct batadv_gw_node *new_gw_node)
130	138	{

net/batman-adv/hard-interface.c+82−0

@@ -197,6 +197,17 @@ static bool batadv_is_on_batman_iface(const struct net_device *net_dev) · 196 unmodified lines
197	197	return ret;
198	198	}
199	199
	200	+/**
	201	+ * batadv_is_valid_iface() - check whether a net_device can be used as a hard
	202	+ * interface
	203	+ * @net_dev: the net_device to check
	204	+ *
	205	+ * Refuse loopback devices, non-Ethernet devices, devices with a non-Ethernet
	206	+ * address length and any device that is already part of a batman-adv mesh
	207	+ * interface stack.
	208	+ *
	209	+ * Return: true if @net_dev can be used as a hard interface, false otherwise
	210	+ */
200	211	static bool batadv_is_valid_iface(const struct net_device *net_dev)
201	212	{
202	213	if (net_dev->flags & IFF_LOOPBACK)
@@ -467,6 +478,14 @@ out: · 264 unmodified lines
467	478	return ret;
468	479	}
469	480
	481	+/**
	482	+ * batadv_hardif_get_active() - retrieve an active hard interface for a mesh
	483	+ * interface
	484	+ * @mesh_iface: mesh interface to search
	485	+ *
	486	+ * Return: first hard interface in BATADV_IF_ACTIVE state attached to
	487	+ * @mesh_iface, or NULL if none is active.
	488	+ */
470	489	static struct batadv_hard_iface *
471	490	batadv_hardif_get_active(struct net_device *mesh_iface)
472	491	{
@@ -487,6 +506,15 @@ out: · 14 unmodified lines
487	506	return hard_iface;
488	507	}
489	508
	509	+/**
	510	+ * batadv_primary_if_update_addr() - propagate the new primary interface MAC
	511	+ * address to all dependent components
	512	+ * @bat_priv: the bat priv with all the mesh interface information
	513	+ * @oldif: previously used primary interface, or NULL if none
	514	+ *
	515	+ * Inform DAT and BLA that the originator address has changed so they can
	516	+ * adjust their state accordingly.
	517	+ */
490	518	static void batadv_primary_if_update_addr(struct batadv_priv *bat_priv,
491	519	struct batadv_hard_iface *oldif)
492	520	{
@@ -502,6 +530,15 @@ out: · 9 unmodified lines
502	530	batadv_hardif_put(primary_if);
503	531	}
504	532
	533	+/**
	534	+ * batadv_primary_if_select() - select the new primary interface
	535	+ * @bat_priv: the bat priv with all the mesh interface information
	536	+ * @new_hard_iface: new primary interface, may be NULL
	537	+ *
	538	+ * Replace the currently selected primary interface with @new_hard_iface,
	539	+ * invoke the algorithm-specific primary_set hook and update the originator
	540	+ * MAC address.
	541	+ */
505	542	static void batadv_primary_if_select(struct batadv_priv *bat_priv,
506	543	struct batadv_hard_iface *new_hard_iface)
507	544	{
@@ -525,6 +562,13 @@ out: · 17 unmodified lines
525	562	batadv_hardif_put(curr_hard_iface);
526	563	}
527	564
	565	+/**
	566	+ * batadv_hardif_is_iface_up() - check whether the underlying net_device of a
	567	+ * hard interface is up
	568	+ * @hard_iface: the hard interface to check
	569	+ *
	570	+ * Return: true if the underlying net_device has the IFF_UP flag set
	571	+ */
528	572	static bool
529	573	batadv_hardif_is_iface_up(const struct batadv_hard_iface *hard_iface)
530	574	{
@@ -534,6 +578,15 @@ batadv_hardif_is_iface_up(const struct batadv_hard_iface *hard_iface) · 3 unmodified lines
534	578	return false;
535	579	}
536	580
	581	+/**
	582	+ * batadv_check_known_mac_addr() - warn about duplicate hard interface MAC
	583	+ * addresses
	584	+ * @hard_iface: hard interface that was just added or had its MAC changed
	585	+ *
	586	+ * Iterate over all hard interfaces of the same mesh interface and emit a
	587	+ * warning if another in-use interface shares the same MAC address as
	588	+ * @hard_iface.
	589	+ */
537	590	static void batadv_check_known_mac_addr(const struct batadv_hard_iface *hard_iface)
538	591	{
539	592	struct net_device *mesh_iface = hard_iface->mesh_iface;
@@ -666,6 +719,15 @@ void batadv_update_min_mtu(struct net_device *mesh_iface) · 126 unmodified lines
666	719	batadv_tt_local_resize_to_mtu(mesh_iface);
667	720	}
668	721
	722	+/**
	723	+ * batadv_hardif_activate_interface() - move a hard interface to the active
	724	+ * state
	725	+ * @hard_iface: the interface that has come up
	726	+ *
	727	+ * Activate an interface, select it as the primary interface if no
	728	+ * primary is currently active and invoke the algorithm-specific
	729	+ * activate hook.
	730	+ */
669	731	static void
670	732	batadv_hardif_activate_interface(struct batadv_hard_iface *hard_iface)
671	733	{
@@ -699,6 +761,14 @@ out: · 27 unmodified lines
699	761	batadv_hardif_put(primary_if);
700	762	}
701	763
	764	+/**
	765	+ * batadv_hardif_deactivate_interface() - move a hard interface to the
	766	+ * inactive state
	767	+ * @hard_iface: the interface that went down
	768	+ *
	769	+ * Demote @hard_iface to BATADV_IF_INACTIVE and recalculate the mesh minimum
	770	+ * MTU based on the remaining active interfaces.
	771	+ */
702	772	static void
703	773	batadv_hardif_deactivate_interface(struct batadv_hard_iface *hard_iface)
704	774	{
@@ -1020,6 +1090,18 @@ static void batadv_wifi_net_device_event(unsigned long event, · 315 unmodified lines
1020	1090	}
1021	1091	}
1022	1092
	1093	+/**
	1094	+ * batadv_hard_if_event() - netdevice notifier callback for hard interfaces
	1095	+ * @this: notifier block (unused)
	1096	+ * @event: the NETDEV_* event to handle
	1097	+ * @ptr: notifier info pointing to the affected net_device
	1098	+ *
	1099	+ * Dispatch netdevice events that affect potential or existing hard
	1100	+ * interfaces. Mesh interfaces are handled separately by
	1101	+ * batadv_hard_if_event_meshif().
	1102	+ *
	1103	+ * Return: NOTIFY_DONE
	1104	+ */
1023	1105	static int batadv_hard_if_event(struct notifier_block *this,
1024	1106	unsigned long event, void *ptr)
1025	1107	{

net/batman-adv/hash.c+4−1

@@ -11,7 +11,10 @@ · 10 unmodified lines
11	11	#include <linux/lockdep.h>
12	12	#include <linux/slab.h>
13	13
14		−/* clears the hash */
	14	+/**
	15	+ * batadv_hash_init() - clear all buckets of a hashtable
	16	+ * @hash: hashtable to clear
	17	+ */
15	18	static void batadv_hash_init(struct batadv_hashtable *hash)
16	19	{
17	20	u32 i;

net/batman-adv/hash.h+24−10

@@ -18,21 +18,35 @@ · 17 unmodified lines
18	18	#include <linux/stddef.h>
19	19	#include <linux/types.h>
20	20
21		−/* callback to a compare function. should compare 2 element data for their
22		− * keys
	21	+/**
	22	+ * typedef batadv_hashdata_compare_cb - hash element comparison callback
	23	+ * @node: hlist node of the element currently stored in the bucket
	24	+ * @key: opaque payload to compare @node's key against
	25	+ *
	26	+ * Compare hash element by its keys.
23	27	*
24		− * Return: true if same and false if not same
	28	+ * Return: true if both elements are considered equal, false otherwise.
25	29	*/
26		−typedef bool (batadv_hashdata_compare_cb)(const struct hlist_node ,
27		− const void *);
	30	+typedef bool (batadv_hashdata_compare_cb)(const struct hlist_node node,
	31	+ const void *key);
28	32
29		−/* the hashfunction
	33	+/**
	34	+ * typedef batadv_hashdata_choose_cb - hash bucket selection callback
	35	+ * @key: opaque payload whose key selects the bucket
	36	+ * @size: number of buckets in the hash table
	37	+ *
	38	+ * Return: bucket index derived from the key in @key and the table @size.
	39	+ */
	40	+typedef u32 (batadv_hashdata_choose_cb)(const void key, u32 size);
	41	+
	42	+/**
	43	+ * typedef batadv_hashdata_free_cb - hash element free callback
	44	+ * @node: hlist node of the element being removed
	45	+ * @arg: opaque caller-supplied argument forwarded from the caller
30	46	*
31		− * Return: an index based on the key in the data of the first argument and the
32		− * size the second
	47	+ * Release a previously inserted hash element.
33	48	*/
34		−typedef u32 (batadv_hashdata_choose_cb)(const void , u32);
35		−typedef void (batadv_hashdata_free_cb)(struct hlist_node , void *);
	49	+typedef void (batadv_hashdata_free_cb)(struct hlist_node node, void *arg);
36	50
37	51	/**
38	52	* struct batadv_hashtable - Wrapper of simple hlist based hashtable

net/batman-adv/main.c+32−4

@@ -82,6 +82,14 @@ static char *batadv_uev_type_str[] = { · 81 unmodified lines
82	82	"bla",
83	83	};
84	84
	85	+/**
	86	+ * batadv_init() - batman-adv module init function
	87	+ *
	88	+ * Initialise the global state used by all mesh interfaces, register the
	89	+ * netdevice notifier and the netlink/rtnl family.
	90	+ *
	91	+ * Return: 0 on success or negative error number in case of failure
	92	+ */
85	93	static int __init batadv_init(void)
86	94	{
87	95	int ret;
@@ -128,6 +136,12 @@ err_create_wq: · 40 unmodified lines
128	136	return ret;
129	137	}
130	138
	139	+/**
	140	+ * batadv_exit() - batman-adv module exit function
	141	+ *
	142	+ * Unregister the netdevice notifier and tear down all global state allocated
	143	+ * by batadv_init().
	144	+ */
131	145	static void __exit batadv_exit(void)
132	146	{
133	147	batadv_netlink_unregister();
@@ -398,6 +412,17 @@ void batadv_skb_set_priority(struct sk_buff *skb, int offset) · 264 unmodified lines
398	412	skb->priority = prio + 256;
399	413	}
400	414
	415	+/**
	416	+ * batadv_recv_unhandled_packet() - default RX handler for unsupported packet
	417	+ * types
	418	+ * @skb: incoming packet
	419	+ * @recv_if: interface on which the packet was received (unused)
	420	+ *
	421	+ * Drop incoming packets whose packet_type has no dedicated RX handler
	422	+ * registered.
	423	+ *
	424	+ * Return: NET_RX_DROP
	425	+ */
401	426	static int batadv_recv_unhandled_packet(struct sk_buff *skb,
402	427	struct batadv_hard_iface *recv_if)
403	428	{
@@ -406,10 +431,6 @@ static int batadv_recv_unhandled_packet(struct sk_buff *skb, · 2 unmodified lines
406	431	return NET_RX_DROP;
407	432	}
408	433
409		−/* incoming packets with the batman ethertype received on any active hard
410		− * interface
411		− */
412		−
413	434	/**
414	435	* batadv_batman_skb_recv() - Handle incoming message from an hard interface
415	436	* @skb: the received packet
@@ -492,6 +513,13 @@ err_out: · 76 unmodified lines
492	513	return NET_RX_DROP;
493	514	}
494	515
	516	+/**
	517	+ * batadv_recv_handler_init() - initialise the RX handler dispatch table
	518	+ *
	519	+ * Initialise all entries of the RX handler table as either "unhandled" or with
	520	+ * protocol indepentend handlers, and perform compile-time size sanity checks on
	521	+ * all on-wire packet structs.
	522	+ */
495	523	static void batadv_recv_handler_init(void)
496	524	{
497	525	int i;

net/batman-adv/mesh-interface.c+63−0

@@ -98,6 +98,15 @@ static u64 batadv_sum_counter(struct batadv_priv *bat_priv, size_t idx) · 97 unmodified lines
98	98	return sum;
99	99	}
100	100
	101	+/**
	102	+ * batadv_interface_stats() - return netdev stats for a mesh interface
	103	+ * @dev: the mesh interface to query
	104	+ *
	105	+ * Aggregate the per-CPU traffic counters into the standard netdev stats
	106	+ * structure.
	107	+ *
	108	+ * Return: pointer to the populated net_device_stats structure
	109	+ */
101	110	static struct net_device_stats batadv_interface_stats(struct net_device dev)
102	111	{
103	112	struct batadv_priv *bat_priv = netdev_priv(dev);
@@ -111,6 +120,18 @@ static struct net_device_stats batadv_interface_stats(struct net_device dev) · 7 unmodified lines
111	120	return stats;
112	121	}
113	122
	123	+/**
	124	+ * batadv_interface_set_mac_addr() - change the MAC address of a mesh
	125	+ * interface
	126	+ * @dev: the mesh interface to modify
	127	+ * @p: pointer to a struct sockaddr holding the new MAC address
	128	+ *
	129	+ * Replace the MAC address of the mesh interface. If the mesh is already
	130	+ * active, also update the local translation table entries for all configured
	131	+ * VLANs so that the new MAC is announced and the old one is removed.
	132	+ *
	133	+ * Return: 0 on success or negative error number in case of failure
	134	+ */
114	135	static int batadv_interface_set_mac_addr(struct net_device dev, void p)
115	136	{
116	137	struct batadv_priv *bat_priv = netdev_priv(dev);
@@ -140,6 +161,16 @@ static int batadv_interface_set_mac_addr(struct net_device dev, void p) · 23 unmodified lines
140	161	return 0;
141	162	}
142	163
	164	+/**
	165	+ * batadv_interface_change_mtu() - change the MTU of a mesh interface
	166	+ * @dev: the mesh interface to modify
	167	+ * @new_mtu: requested new MTU value
	168	+ *
	169	+ * Validate that @new_mtu fits within the range supported by the configured
	170	+ * hard interfaces and remember it as the user-configured MTU.
	171	+ *
	172	+ * Return: 0 on success or -EINVAL if @new_mtu is out of range
	173	+ */
143	174	static int batadv_interface_change_mtu(struct net_device *dev, int new_mtu)
144	175	{
145	176	struct batadv_priv *bat_priv = netdev_priv(dev);
@@ -166,6 +197,13 @@ static void batadv_interface_set_rx_mode(struct net_device *dev) · 20 unmodified lines
166	197	{
167	198	}
168	199
	200	+/**
	201	+ * batadv_interface_tx() - transmit a frame on a mesh interface
	202	+ * @skb: the frame to send
	203	+ * @mesh_iface: the mesh interface the frame was queued on
	204	+ *
	205	+ * Return: NETDEV_TX_OK on success
	206	+ */
169	207	static netdev_tx_t batadv_interface_tx(struct sk_buff *skb,
170	208	struct net_device *mesh_iface)
171	209	{
@@ -883,6 +921,11 @@ static const struct net_device_ops batadv_netdev_ops = { · 711 unmodified lines
883	921	.ndo_del_slave = batadv_meshif_slave_del,
884	922	};
885	923
	924	+/**
	925	+ * batadv_get_drvinfo() - ethtool driver info handler for mesh interfaces
	926	+ * @dev: the mesh interface (unused)
	927	+ * @info: ethtool_drvinfo struct to populate
	928	+ */
886	929	static void batadv_get_drvinfo(struct net_device *dev,
887	930	struct ethtool_drvinfo *info)
888	931	{
@@ -943,6 +986,12 @@ static const struct { · 54 unmodified lines
943	986	#endif
944	987	};
945	988
	989	+/**
	990	+ * batadv_get_strings() - ethtool string handler for mesh interfaces
	991	+ * @dev: the mesh interface (unused)
	992	+ * @stringset: ethtool string set to retrieve
	993	+ * @data: buffer to copy the requested string set into
	994	+ */
946	995	static void batadv_get_strings(struct net_device dev, u32 stringset, u8 data)
947	996	{
948	997	if (stringset == ETH_SS_STATS)
@@ -950,6 +999,12 @@ static void batadv_get_strings(struct net_device dev, u32 stringset, u8 data) · 1 unmodified line
950	999	sizeof(batadv_counters_strings));
951	1000	}
952	1001
	1002	+/**
	1003	+ * batadv_get_ethtool_stats() - ethtool stats handler for mesh interfaces
	1004	+ * @dev: the mesh interface to query
	1005	+ * @stats: ethtool_stats struct (unused)
	1006	+ * @data: destination array for the gathered counter values
	1007	+ */
953	1008	static void batadv_get_ethtool_stats(struct net_device *dev,
954	1009	struct ethtool_stats stats, u64 data)
955	1010	{
@@ -960,6 +1015,14 @@ static void batadv_get_ethtool_stats(struct net_device *dev, · 4 unmodified lines
960	1015	data[i] = batadv_sum_counter(bat_priv, i);
961	1016	}
962	1017
	1018	+/**
	1019	+ * batadv_get_sset_count() - ethtool stringset size handler for mesh interfaces
	1020	+ * @dev: the mesh interface (unused)
	1021	+ * @stringset: ethtool string set to query
	1022	+ *
	1023	+ * Return: number of entries in @stringset or -EOPNOTSUPP if @stringset is not
	1024	+ * supported
	1025	+ */
963	1026	static int batadv_get_sset_count(struct net_device *dev, int stringset)
964	1027	{
965	1028	if (stringset == ETH_SS_STATS)

net/batman-adv/netlink.c+7−1

@@ -52,9 +52,15 @@ · 51 unmodified lines
52	52
53	53	struct genl_family batadv_netlink_family;
54	54
55		−/* multicast groups */
	55	+/**
	56	+ * enum batadv_netlink_multicast_groups - batman-adv generic netlink multicast
	57	+ * groups
	58	+ */
56	59	enum batadv_netlink_multicast_groups {
	60	+ /** @BATADV_NL_MCGRP_CONFIG: configuration change notifications */
57	61	BATADV_NL_MCGRP_CONFIG,
	62	+
	63	+ /** @BATADV_NL_MCGRP_TPMETER: throughput meter result notifications */
58	64	BATADV_NL_MCGRP_TPMETER,
59	65	};
60	66

net/batman-adv/originator.c+7−0

@@ -1295,6 +1295,13 @@ void batadv_purge_orig_ref(struct batadv_priv *bat_priv) · 1294 unmodified lines
1295	1295	batadv_gw_election(bat_priv);
1296	1296	}
1297	1297
	1298	+/**
	1299	+ * batadv_purge_orig() - periodic worker to purge stale originator entries
	1300	+ * @work: delayed work embedded in the bat_priv
	1301	+ *
	1302	+ * Invoke batadv_purge_orig_ref() to drop stale originators and reschedule the
	1303	+ * next run after BATADV_ORIG_WORK_PERIOD milliseconds.
	1304	+ */
1298	1305	static void batadv_purge_orig(struct work_struct *work)
1299	1306	{
1300	1307	struct delayed_work *delayed_work;

net/batman-adv/routing.c+31−0

@@ -328,6 +328,16 @@ out: · 327 unmodified lines
328	328	return ret;
329	329	}
330	330
	331	+/**
	332	+ * batadv_recv_icmp_ttl_exceeded() - handle an ICMP packet that hit TTL 0
	333	+ * @bat_priv: the bat priv with all the mesh interface information
	334	+ * @skb: ICMP packet whose TTL has expired
	335	+ *
	336	+ * For traceroute-style ICMP echo requests, send a TTL exceeded reply back to
	337	+ * the source. Other ICMP types are simply dropped.
	338	+ *
	339	+ * Return: NET_XMIT_SUCCESS if the reply was queued, NET_RX_DROP otherwise
	340	+ */
331	341	static int batadv_recv_icmp_ttl_exceeded(struct batadv_priv *bat_priv,
332	342	struct sk_buff *skb)
333	343	{
@@ -706,6 +716,18 @@ next: · 372 unmodified lines
706	716	return router;
707	717	}
708	718
	719	+/**
	720	+ * batadv_route_unicast_packet() - forward a unicast packet towards its
	721	+ * destination originator
	722	+ * @skb: the received unicast packet
	723	+ * @recv_if: interface on which the packet was received
	724	+ *
	725	+ * Decrement the TTL, look up the originator for the destination address and
	726	+ * hand the packet over to batadv_send_skb_to_orig() for transmission. Drop
	727	+ * the packet when the TTL is exhausted or no route exists.
	728	+ *
	729	+ * Return: NET_RX_SUCCESS if the packet was forwarded, NET_RX_DROP otherwise
	730	+ */
709	731	static int batadv_route_unicast_packet(struct sk_buff *skb,
710	732	struct batadv_hard_iface *recv_if)
711	733	{
@@ -836,6 +858,15 @@ out: · 124 unmodified lines
836	858	return ret;
837	859	}
838	860
	861	+/**
	862	+ * batadv_check_unicast_ttvn() - check and adjust the TTVN of a unicast packet
	863	+ * @bat_priv: the bat priv with all the mesh interface information
	864	+ * @skb: the unicast packet to check
	865	+ * @hdr_len: length of the unicast header preceding the payload
	866	+ *
	867	+ * Return: true if the packet may be processed further, false if has to be
	868	+ * dropped by the caller
	869	+ */
839	870	static bool batadv_check_unicast_ttvn(struct batadv_priv *bat_priv,
840	871	struct sk_buff *skb, int hdr_len)
841	872	{

net/batman-adv/translation-table.c+172−5

@@ -535,6 +535,12 @@ static int batadv_tt_local_table_transmit_size(struct batadv_priv *bat_priv) · 534 unmodified lines
535	535	return hdr_size + batadv_tt_len(tt_local_entries);
536	536	}
537	537
	538	+/**
	539	+ * batadv_tt_local_init() - allocate and initialise the local translation table
	540	+ * @bat_priv: the bat priv with all the mesh interface information
	541	+ *
	542	+ * Return: 0 on success or -ENOMEM in case of allocation failure
	543	+ */
538	544	static int batadv_tt_local_init(struct batadv_priv *bat_priv)
539	545	{
540	546	if (bat_priv->tt.local_hash)
@@ -551,6 +557,15 @@ static int batadv_tt_local_init(struct batadv_priv *bat_priv) · 10 unmodified lines
551	557	return 0;
552	558	}
553	559
	560	+/**
	561	+ * batadv_tt_global_free() - drop a global translation table entry
	562	+ * @bat_priv: the bat priv with all the mesh interface information
	563	+ * @tt_global: the global TT entry to remove
	564	+ * @message: debug message explaining why the entry is being removed
	565	+ *
	566	+ * Remove @tt_global from the global TT hash and drop the reference held by
	567	+ * the hash.
	568	+ */
554	569	static void batadv_tt_global_free(struct batadv_priv *bat_priv,
555	570	struct batadv_tt_global_entry *tt_global,
556	571	const char *message)
@@ -1224,6 +1239,17 @@ int batadv_tt_local_dump(struct sk_buff msg, struct netlink_callback cb) · 667 unmodified lines
1224	1239	return ret;
1225	1240	}
1226	1241
	1242	+/**
	1243	+ * batadv_tt_local_set_pending() - mark a local TT entry as pending removal
	1244	+ * @bat_priv: the bat priv with all the mesh interface information
	1245	+ * @tt_local_entry: local TT entry to mark
	1246	+ * @flags: TT change flags to announce together with the pending removal
	1247	+ * @message: debug message describing the reason for the change
	1248	+ *
	1249	+ * Schedule the TT change announcement and set BATADV_TT_CLIENT_PENDING on the
	1250	+ * entry. The entry is kept in the local table until the next TTVN increment
	1251	+ * so that a consistency-check response can still be answered.
	1252	+ */
1227	1253	static void
1228	1254	batadv_tt_local_set_pending(struct batadv_priv *bat_priv,
1229	1255	struct batadv_tt_local_entry *tt_local_entry,
@@ -1367,6 +1393,13 @@ static void batadv_tt_local_purge(struct batadv_priv *bat_priv, · 137 unmodified lines
1367	1393	}
1368	1394	}
1369	1395
	1396	+/**
	1397	+ * batadv_tt_local_table_free() - release the local translation table
	1398	+ * @bat_priv: the bat priv with all the mesh interface information
	1399	+ *
	1400	+ * Drop every entry of the local TT hash, free their references and finally
	1401	+ * release the hashtable itself.
	1402	+ */
1370	1403	static void batadv_tt_local_table_free(struct batadv_priv *bat_priv)
1371	1404	{
1372	1405	struct batadv_hashtable *hash;
@@ -1404,6 +1437,13 @@ static void batadv_tt_local_table_free(struct batadv_priv *bat_priv) · 31 unmodified lines
1404	1437	bat_priv->tt.local_hash = NULL;
1405	1438	}
1406	1439
	1440	+/**
	1441	+ * batadv_tt_global_init() - allocate and initialise the global translation
	1442	+ * table
	1443	+ * @bat_priv: the bat priv with all the mesh interface information
	1444	+ *
	1445	+ * Return: 0 on success or -ENOMEM in case of allocation failure
	1446	+ */
1407	1447	static int batadv_tt_global_init(struct batadv_priv *bat_priv)
1408	1448	{
1409	1449	if (bat_priv->tt.global_hash)
@@ -1420,6 +1460,12 @@ static int batadv_tt_global_init(struct batadv_priv *bat_priv) · 10 unmodified lines
1420	1460	return 0;
1421	1461	}
1422	1462
	1463	+/**
	1464	+ * batadv_tt_changes_list_free() - drop all pending local TT changes
	1465	+ * @bat_priv: the bat priv with all the mesh interface information
	1466	+ *
	1467	+ * Discard every queued local TT change and reset the pending change counter.
	1468	+ */
1423	1469	static void batadv_tt_changes_list_free(struct batadv_priv *bat_priv)
1424	1470	{
1425	1471	struct batadv_tt_change_node entry, safe;
@@ -2024,7 +2070,11 @@ _batadv_tt_global_del_orig_entry(struct batadv_tt_global_entry *tt_global_entry, · 598 unmodified lines
2024	2070	batadv_tt_orig_list_entry_put(orig_entry);
2025	2071	}
2026	2072
2027		−/* deletes the orig list of a tt_global_entry */
	2073	+/**
	2074	+ * batadv_tt_global_del_orig_list() - drop every orig_list_entry of a global
	2075	+ * TT entry
	2076	+ * @tt_global_entry: the global TT entry to clear
	2077	+ */
2028	2078	static void
2029	2079	batadv_tt_global_del_orig_list(struct batadv_tt_global_entry *tt_global_entry)
2030	2080	{
@@ -2077,9 +2127,17 @@ batadv_tt_global_del_orig_node(struct batadv_priv *bat_priv, · 46 unmodified lines
2077	2127	spin_unlock_bh(&tt_global_entry->list_lock);
2078	2128	}
2079	2129
2080		−/* If the client is to be deleted, we check if it is the last origantor entry
2081		− * within tt_global entry. If yes, we set the BATADV_TT_CLIENT_ROAM flag and the
2082		− * timer, otherwise we simply remove the originator scheduled for deletion.
	2130	+/**
	2131	+ * batadv_tt_global_del_roaming() - remove a roaming client from a global TT
	2132	+ * entry
	2133	+ * @bat_priv: the bat priv with all the mesh interface information
	2134	+ * @tt_global_entry: the global TT entry of the roaming client
	2135	+ * @orig_node: the originator that the client has roamed away from
	2136	+ * @message: debug message describing the reason for the change
	2137	+ *
	2138	+ * If @orig_node was the last announced source for the client, mark the entry
	2139	+ * for roaming so it can be cleaned up after the roaming timer expires.
	2140	+ * Otherwise simply remove the orig_node entry from the announcer list.
2083	2141	*/
2084	2142	static void
2085	2143	batadv_tt_global_del_roaming(struct batadv_priv *bat_priv,
@@ -2241,6 +2299,15 @@ void batadv_tt_global_del_orig(struct batadv_priv *bat_priv, · 155 unmodified lines
2241	2299	clear_bit(BATADV_ORIG_CAPA_HAS_TT, &orig_node->capa_initialized);
2242	2300	}
2243	2301
	2302	+/**
	2303	+ * batadv_tt_global_to_purge() - check whether a global TT entry has to be
	2304	+ * purged
	2305	+ * @tt_global: global TT entry under consideration
	2306	+ * @msg: storage for a pointer to a human readable reason on return
	2307	+ *
	2308	+ * Return: true if the entry should be purged because its roaming or temporary
	2309	+ * timer has elapsed; false otherwise
	2310	+ */
2244	2311	static bool batadv_tt_global_to_purge(struct batadv_tt_global_entry *tt_global,
2245	2312	char **msg)
2246	2313	{
@@ -2263,6 +2330,13 @@ static bool batadv_tt_global_to_purge(struct batadv_tt_global_entry *tt_global, · 16 unmodified lines
2263	2330	return purge;
2264	2331	}
2265	2332
	2333	+/**
	2334	+ * batadv_tt_global_purge() - purge expired global translation table entries
	2335	+ * @bat_priv: the bat priv with all the mesh interface information
	2336	+ *
	2337	+ * Iterate over the global translation table and drop every entry that the
	2338	+ * roaming or temporary timer has expired for.
	2339	+ */
2266	2340	static void batadv_tt_global_purge(struct batadv_priv *bat_priv)
2267	2341	{
2268	2342	struct batadv_hashtable *hash = bat_priv->tt.global_hash;
@@ -2302,6 +2376,13 @@ static void batadv_tt_global_purge(struct batadv_priv *bat_priv) · 33 unmodified lines
2302	2376	}
2303	2377	}
2304	2378
	2379	+/**
	2380	+ * batadv_tt_global_table_free() - release the global translation table
	2381	+ * @bat_priv: the bat priv with all the mesh interface information
	2382	+ *
	2383	+ * Drop every entry of the global TT hash, free their references and finally
	2384	+ * release the hashtable itself.
	2385	+ */
2305	2386	static void batadv_tt_global_table_free(struct batadv_priv *bat_priv)
2306	2387	{
2307	2388	struct batadv_hashtable *hash;
@@ -2338,6 +2419,16 @@ static void batadv_tt_global_table_free(struct batadv_priv *bat_priv) · 30 unmodified lines
2338	2419	bat_priv->tt.global_hash = NULL;
2339	2420	}
2340	2421
	2422	+/**
	2423	+ * _batadv_is_ap_isolated() - check whether two clients are AP-isolated from
	2424	+ * each other
	2425	+ * @tt_local_entry: local TT entry of the sending client
	2426	+ * @tt_global_entry: global TT entry of the destination client
	2427	+ *
	2428	+ * Return: true if traffic between the two clients should be dropped because
	2429	+ * either both are WiFi clients or both carry the ISOLATION flag; false
	2430	+ * otherwise
	2431	+ */
2341	2432	static bool
2342	2433	_batadv_is_ap_isolated(struct batadv_tt_local_entry *tt_local_entry,
2343	2434	struct batadv_tt_global_entry *tt_global_entry)
@@ -2590,6 +2681,10 @@ static void batadv_tt_req_node_put(struct batadv_tt_req_node *tt_req_node) · 246 unmodified lines
2590	2681	kref_put(&tt_req_node->refcount, batadv_tt_req_node_release);
2591	2682	}
2592	2683
	2684	+/**
	2685	+ * batadv_tt_req_list_free() - drop all pending TT requests
	2686	+ * @bat_priv: the bat priv with all the mesh interface information
	2687	+ */
2593	2688	static void batadv_tt_req_list_free(struct batadv_priv *bat_priv)
2594	2689	{
2595	2690	struct batadv_tt_req_node *node;
@@ -2605,6 +2700,18 @@ static void batadv_tt_req_list_free(struct batadv_priv *bat_priv) · 9 unmodified lines
2605	2700	spin_unlock_bh(&bat_priv->tt.req_list_lock);
2606	2701	}
2607	2702
	2703	+/**
	2704	+ * batadv_tt_save_orig_buffer() - cache the latest TT TVLV payload of an
	2705	+ * originator
	2706	+ * @bat_priv: the bat priv with all the mesh interface information
	2707	+ * @orig_node: originator for which the buffer should be created
	2708	+ * @tt_buff: pointer to the TT TVLV payload to cache
	2709	+ * @tt_buff_len: length of @tt_buff in bytes
	2710	+ *
	2711	+ * Replace the previously cached TT payload of @orig_node with a copy of
	2712	+ * @tt_buff. The buffer is left untouched when @tt_buff_len is 0 so that
	2713	+ * empty OGM updates do not discard the previously cached data.
	2714	+ */
2608	2715	static void batadv_tt_save_orig_buffer(struct batadv_priv *bat_priv,
2609	2716	struct batadv_orig_node *orig_node,
2610	2717	const void *tt_buff,
@@ -2626,6 +2733,10 @@ static void batadv_tt_save_orig_buffer(struct batadv_priv *bat_priv, · 15 unmodified lines
2626	2733	spin_unlock_bh(&orig_node->tt_buff_lock);
2627	2734	}
2628	2735
	2736	+/**
	2737	+ * batadv_tt_req_purge() - drop timed-out TT requests
	2738	+ * @bat_priv: the bat priv with all the mesh interface information
	2739	+ */
2629	2740	static void batadv_tt_req_purge(struct batadv_priv *bat_priv)
2630	2741	{
2631	2742	struct batadv_tt_req_node *node;
@@ -3253,6 +3364,18 @@ static bool batadv_send_tt_response(struct batadv_priv *bat_priv, · 621 unmodified lines
3253	3364	req_dst);
3254	3365	}
3255	3366
	3367	+/**
	3368	+ * _batadv_tt_update_changes() - apply a list of TT changes to the global TT
	3369	+ * @bat_priv: the bat priv with all the mesh interface information
	3370	+ * @orig_node: originator announcing the changes
	3371	+ * @tt_change: array of TT change entries to apply
	3372	+ * @tt_num_changes: number of entries in @tt_change
	3373	+ * @ttvn: TTVN of @orig_node corresponding to @tt_change
	3374	+ *
	3375	+ * Walk @tt_change and add/remove the announced clients in the global TT.
	3376	+ * Abort early without marking the @orig_node TT as initialized if adding
	3377	+ * an entry fails, so that the next TT request can re-sync the full table.
	3378	+ */
3256	3379	static void _batadv_tt_update_changes(struct batadv_priv *bat_priv,
3257	3380	struct batadv_orig_node *orig_node,
3258	3381	struct batadv_tvlv_tt_change *tt_change,
@@ -3286,6 +3409,18 @@ static void _batadv_tt_update_changes(struct batadv_priv *bat_priv, · 27 unmodified lines
3286	3409	set_bit(BATADV_ORIG_CAPA_HAS_TT, &orig_node->capa_initialized);
3287	3410	}
3288	3411
	3412	+/**
	3413	+ * batadv_tt_fill_gtable() - replace the cached TT of an originator with a
	3414	+ * full table response
	3415	+ * @bat_priv: the bat priv with all the mesh interface information
	3416	+ * @tt_change: array of TT change entries describing the full table
	3417	+ * @ttvn: TTVN announced together with the full table
	3418	+ * @resp_src: MAC address of the responder
	3419	+ * @num_entries: number of entries in @tt_change
	3420	+ *
	3421	+ * Drop the previously known global TT entries of @resp_src and replace them
	3422	+ * with the entries from a freshly received full TT response.
	3423	+ */
3289	3424	static void batadv_tt_fill_gtable(struct batadv_priv *bat_priv,
3290	3425	struct batadv_tvlv_tt_change *tt_change,
3291	3426	u8 ttvn, u8 *resp_src,
@@ -3316,6 +3451,15 @@ out: · 24 unmodified lines
3316	3451	batadv_orig_node_put(orig_node);
3317	3452	}
3318	3453
	3454	+/**
	3455	+ * batadv_tt_update_changes() - apply an incremental TT changeset to the
	3456	+ * global TT
	3457	+ * @bat_priv: the bat priv with all the mesh interface information
	3458	+ * @orig_node: originator announcing the changes
	3459	+ * @tt_num_changes: number of entries in @tt_change
	3460	+ * @ttvn: TTVN of @orig_node corresponding to @tt_change
	3461	+ * @tt_change: array of TT change entries to apply
	3462	+ */
3319	3463	static void batadv_tt_update_changes(struct batadv_priv *bat_priv,
3320	3464	struct batadv_orig_node *orig_node,
3321	3465	u16 tt_num_changes, u8 ttvn,
@@ -3416,6 +3560,10 @@ out: · 94 unmodified lines
3416	3560	batadv_orig_node_put(orig_node);
3417	3561	}
3418	3562
	3563	+/**
	3564	+ * batadv_tt_roam_list_free() - drop all entries from the roaming clients list
	3565	+ * @bat_priv: the bat priv with all the mesh interface information
	3566	+ */
3419	3567	static void batadv_tt_roam_list_free(struct batadv_priv *bat_priv)
3420	3568	{
3421	3569	struct batadv_tt_roam_node node, safe;
@@ -3430,6 +3578,10 @@ static void batadv_tt_roam_list_free(struct batadv_priv *bat_priv) · 8 unmodified lines
3430	3578	spin_unlock_bh(&bat_priv->tt.roam_list_lock);
3431	3579	}
3432	3580
	3581	+/**
	3582	+ * batadv_tt_roam_purge() - drop timed-out roaming clients
	3583	+ * @bat_priv: the bat priv with all the mesh interface information
	3584	+ */
3433	3585	static void batadv_tt_roam_purge(struct batadv_priv *bat_priv)
3434	3586	{
3435	3587	struct batadv_tt_roam_node node, safe;
@@ -3552,6 +3704,14 @@ out: · 116 unmodified lines
3552	3704	batadv_hardif_put(primary_if);
3553	3705	}
3554	3706
	3707	+/**
	3708	+ * batadv_tt_purge() - periodic worker to maintain the translation table
	3709	+ * @work: delayed work embedded in the per-mesh-interface TT state
	3710	+ *
	3711	+ * Purge timed-out entries from the local and global TT, drop stale TT
	3712	+ * requests and roaming clients, and reschedule the next run after
	3713	+ * BATADV_TT_WORK_PERIOD milliseconds.
	3714	+ */
3555	3715	static void batadv_tt_purge(struct work_struct *work)
3556	3716	{
3557	3717	struct delayed_work *delayed_work;
@@ -3638,7 +3798,14 @@ static void batadv_tt_local_set_flags(struct batadv_priv *bat_priv, u16 flags, · 80 unmodified lines
3638	3798	}
3639	3799	}
3640	3800
3641		−/* Purge out all the tt local entries marked with BATADV_TT_CLIENT_PENDING */
	3801	+/**
	3802	+ * batadv_tt_local_purge_pending_clients() - finalise removal of pending local
	3803	+ * clients
	3804	+ * @bat_priv: the bat priv with all the mesh interface information
	3805	+ *
	3806	+ * Iterate over the local TT and physically remove every entry that has been
	3807	+ * marked as BATADV_TT_CLIENT_PENDING.
	3808	+ */
3642	3809	static void batadv_tt_local_purge_pending_clients(struct batadv_priv *bat_priv)
3643	3810	{
3644	3811	struct batadv_hashtable *hash = bat_priv->tt.local_hash;

net/batman-adv/types.h+2−2

@@ -1827,10 +1827,10 @@ struct batadv_bla_claim { · 1826 unmodified lines
1827	1827	/** @hash_entry: hlist node for &batadv_priv_bla.claim_hash */
1828	1828	struct hlist_node hash_entry;
1829	1829
1830		− /** @refcount: number of contexts the object is used */
	1830	+ /** @rcu: struct used for freeing in an RCU-safe manner */
1831	1831	struct rcu_head rcu;
1832	1832
1833		− /** @rcu: struct used for freeing in an RCU-safe manner */
	1833	+ /** @refcount: number of contexts the object is used */
1834	1834	struct kref refcount;
1835	1835	};
1836	1836	#endif