batman-adv: Update/repair bridge loop avoidance kerneldoc

Signed-off-by: Simon Wunderlich <sw@simonwunderlich.de> Signed-off-by: Marek Lindner <mareklindner@neomailbox.ch> Signed-off-by: Antonio Quartulli <a@unstable.cc>

batman-adv: Update/repair bridge loop avoidance kerneldoc
Signed-off-by: Simon Wunderlich <sw@simonwunderlich.de> Signed-off-by: Marek Lindner <mareklindner@neomailbox.ch> Signed-off-by: Antonio Quartulli <a@unstable.cc>
Simon Wunderlich · Antonio Quartulli
1 parent 672e797850
Showing 1 changed file with 130 additions and 48 deletions Side-by-side Diff
net/batman-adv/bridge_loop_avoidance.c
@@ -59,9 +59,11 @@
 			 struct batadv_bla_backbone_gw *backbone_gw);
  
 /**
- * batadv_choose_claim
+ * batadv_choose_claim - choose the right bucket for a claim.
+ * @data: data to hash
+ * @size: size of the hash table
  *
- * Return: the index of the claim
+ * Return: the hash index of the claim
  */
 static inline u32 batadv_choose_claim(const void *data, u32 size)
 {
  
@@ -75,9 +77,11 @@
 }
  
 /**
- * batadv_choose_backbone_gw
+ * batadv_choose_backbone_gw - choose the right bucket for a backbone gateway.
+ * @data: data to hash
+ * @size: size of the hash table
  *
- * Return: the index of the backbone gateway
+ * Return: the hash index of the backbone gateway
  */
 static inline u32 batadv_choose_backbone_gw(const void *data, u32 size)
 {
@@ -90,7 +94,13 @@
 	return hash % size;
 }
  
-/* compares address and vid of two backbone gws */
+/**
+ * batadv_compare_backbone_gw - compare address and vid of two backbone gws
+ * @node: list node of the first entry to compare
+ * @data2: pointer to the second backbone gateway
+ *
+ * Return: 1 if the backbones have the same data, 0 otherwise
+ */
 static int batadv_compare_backbone_gw(const struct hlist_node *node,
 				      const void *data2)
 {
@@ -108,7 +118,13 @@
 	return 1;
 }
  
-/* compares address and vid of two claims */
+/**
+ * batadv_compare_backbone_gw - compare address and vid of two claims
+ * @node: list node of the first entry to compare
+ * @data2: pointer to the second claims
+ *
+ * Return: 1 if the claim have the same data, 0 otherwise
+ */
 static int batadv_compare_claim(const struct hlist_node *node,
 				const void *data2)
 {
@@ -126,7 +142,10 @@
 	return 1;
 }
  
-/* free a backbone gw */
+/**
+ * batadv_compare_backbone_gw - free backbone gw
+ * @backbone_gw: backbone gateway to be free'd
+ */
 static void
 batadv_backbone_gw_free_ref(struct batadv_bla_backbone_gw *backbone_gw)
 {
  
@@ -134,14 +153,21 @@
 		kfree_rcu(backbone_gw, rcu);
 }
  
-/* finally deinitialize the claim */
+/**
+ * batadv_claim_release - release claim from lists and queue for free after rcu
+ *  grace period
+ * @ref: kref pointer of the claim
+ */
 static void batadv_claim_release(struct batadv_bla_claim *claim)
 {
 	batadv_backbone_gw_free_ref(claim->backbone_gw);
 	kfree_rcu(claim, rcu);
 }
  
-/* free a claim, call claim_free_rcu if its the last reference */
+/**
+ * batadv_claim_free_rcu - free a claim
+ * @claim: claim to be free'd
+ */
 static void batadv_claim_free_ref(struct batadv_bla_claim *claim)
 {
 	if (atomic_dec_and_test(&claim->refcount))
  
@@ -149,12 +175,10 @@
 }
  
 /**
- * batadv_claim_hash_find
+ * batadv_claim_hash_find - looks for a claim in the claim hash
  * @bat_priv: the bat priv with all the soft interface information
  * @data: search data (may be local/static data)
  *
- * looks for a claim in the hash
- *
  * Return: claim if found or NULL otherwise.
  */
 static struct batadv_bla_claim
  
@@ -190,12 +214,12 @@
 }
  
 /**
- * batadv_backbone_hash_find - looks for a claim in the hash
+ * batadv_backbone_hash_find - looks for a backbone gateway in the hash
  * @bat_priv: the bat priv with all the soft interface information
  * @addr: the address of the originator
  * @vid: the VLAN ID
  *
- * Return: claim if found or NULL otherwise.
+ * Return: backbone gateway if found or NULL otherwise
  */
 static struct batadv_bla_backbone_gw *
 batadv_backbone_hash_find(struct batadv_priv *bat_priv, u8 *addr,
@@ -233,7 +257,10 @@
 	return backbone_gw_tmp;
 }
  
-/* delete all claims for a backbone */
+/**
+ * batadv_bla_del_backbone_claims - delete all claims for a backbone
+ * @backbone_gw: backbone gateway where the claims should be removed
+ */
 static void
 batadv_bla_del_backbone_claims(struct batadv_bla_backbone_gw *backbone_gw)
 {
  
@@ -381,14 +408,13 @@
 }
  
 /**
- * batadv_bla_get_backbone_gw
+ * batadv_bla_get_backbone_gw - finds or creates a backbone gateway
  * @bat_priv: the bat priv with all the soft interface information
  * @orig: the mac address of the originator
  * @vid: the VLAN ID
  * @own_backbone: set if the requested backbone is local
  *
- * searches for the backbone gw or creates a new one if it could not
- * be found.
+ * Return: the (possibly created) backbone gateway or NULL on error
  */
 static struct batadv_bla_backbone_gw *
 batadv_bla_get_backbone_gw(struct batadv_priv *bat_priv, u8 *orig,
@@ -454,7 +480,13 @@
 	return entry;
 }
  
-/* update or add the own backbone gw to make sure we announce
+/**
+ * batadv_bla_update_own_backbone_gw - updates the own backbone gw for a VLAN
+ * @bat_priv: the bat priv with all the soft interface information
+ * @primary_if: the selected primary interface
+ * @vid: VLAN identifier
+ *
+ * update or add the own backbone gw to make sure we announce
  * where we receive other backbone gws
  */
 static void
  
@@ -551,12 +583,9 @@
 }
  
 /**
- * batadv_bla_send_announce
+ * batadv_bla_send_announce - Send an announcement frame
  * @bat_priv: the bat priv with all the soft interface information
  * @backbone_gw: our backbone gateway which should be announced
- *
- * This function sends an announcement. It is called from multiple
- * places.
  */
 static void batadv_bla_send_announce(struct batadv_priv *bat_priv,
 				     struct batadv_bla_backbone_gw *backbone_gw)
@@ -646,8 +675,11 @@
 	batadv_claim_free_ref(claim);
 }
  
-/* Delete a claim from the claim hash which has the
- * given mac address and vid.
+/**
+ * batadv_bla_del_claim - delete a claim from the claim hash
+ * @bat_priv: the bat priv with all the soft interface information
+ * @mac: mac address of the claim to be removed
+ * @vid: VLAN id for the claim to be removed
  */
 static void batadv_bla_del_claim(struct batadv_priv *bat_priv,
 				 const u8 *mac, const unsigned short vid)
@@ -677,6 +709,10 @@
  
 /**
  * batadv_handle_announce - check for ANNOUNCE frame
+ * @bat_priv: the bat priv with all the soft interface information
+ * @an_addr: announcement mac address (ARP Sender HW address)
+ * @backbone_addr: originator address of the sender (Ethernet source MAC)
+ * @vid: the VLAN ID of the frame
  *
  * Return: 1 if handled
  */
@@ -731,6 +767,11 @@
  
 /**
  * batadv_handle_request - check for REQUEST frame
+ * @bat_priv: the bat priv with all the soft interface information
+ * @primary_if: the primary hard interface of this batman soft interface
+ * @backbone_addr: backbone address to be requested (ARP sender HW MAC)
+ * @ethhdr: ethernet header of a packet
+ * @vid: the VLAN ID of the frame
  *
  * Return: 1 if handled
  */
@@ -759,6 +800,11 @@
  
 /**
  * batadv_handle_unclaim - check for UNCLAIM frame
+ * @bat_priv: the bat priv with all the soft interface information
+ * @primary_if: the primary hard interface of this batman soft interface
+ * @backbone_addr: originator address of the backbone (Ethernet source)
+ * @claim_addr: Client to be unclaimed (ARP sender HW MAC)
+ * @vid: the VLAN ID of the frame
  *
  * Return: 1 if handled
  */
@@ -792,6 +838,11 @@
  
 /**
  * batadv_handle_claim - check for CLAIM frame
+ * @bat_priv: the bat priv with all the soft interface information
+ * @primary_if: the primary hard interface of this batman soft interface
+ * @backbone_addr: originator address of the backbone (Ethernet Source)
+ * @claim_addr: client mac address to be claimed (ARP sender HW MAC)
+ * @vid: the VLAN ID of the frame
  *
  * Return: 1 if handled
  */
@@ -823,7 +874,7 @@
 }
  
 /**
- * batadv_check_claim_group
+ * batadv_check_claim_group - check for claim group membership
  * @bat_priv: the bat priv with all the soft interface information
  * @primary_if: the primary interface of this batman interface
  * @hw_src: the Hardware source in the ARP Header
  
@@ -898,13 +949,11 @@
 }
  
 /**
- * batadv_bla_process_claim
+ * batadv_bla_process_claim - Check if this is a claim frame, and process it
  * @bat_priv: the bat priv with all the soft interface information
  * @primary_if: the primary hard interface of this batman soft interface
  * @skb: the frame to be checked
  *
- * Check if this is a claim frame, and process it accordingly.
- *
  * Return: 1 if it was a claim frame, otherwise return 0 to
  * tell the callee that it can use the frame on its own.
  */
@@ -1036,7 +1085,13 @@
 	return 1;
 }
  
-/* Check when we last heard from other nodes, and remove them in case of
+/**
+ * batadv_bla_purge_backbone_gw - Remove backbone gateways after a timeout or
+ *  immediately
+ * @bat_priv: the bat priv with all the soft interface information
+ * @now: whether the whole hash shall be wiped now
+ *
+ * Check when we last heard from other nodes, and remove them in case of
  * a time out, or clean all backbone gws if now is set.
  */
 static void batadv_bla_purge_backbone_gw(struct batadv_priv *bat_priv, int now)
@@ -1084,7 +1139,7 @@
 }
  
 /**
- * batadv_bla_purge_claims
+ * batadv_bla_purge_claims - Remove claims after a timeout or immediately
  * @bat_priv: the bat priv with all the soft interface information
  * @primary_if: the selected primary interface, may be NULL if now is set
  * @now: whether the whole hash shall be wiped now
  
@@ -1133,12 +1188,11 @@
 }
  
 /**
- * batadv_bla_update_orig_address
+ * batadv_bla_update_orig_address - Update the backbone gateways when the own
+ *  originator address changes
  * @bat_priv: the bat priv with all the soft interface information
  * @primary_if: the new selected primary_if
  * @oldif: the old primary interface, may be NULL
- *
- * Update the backbone gateways when the own orig address changes.
  */
 void batadv_bla_update_orig_address(struct batadv_priv *bat_priv,
 				    struct batadv_hard_iface *primary_if,
@@ -1209,7 +1263,11 @@
 	batadv_hardif_free_ref(primary_if);
 }
  
-/* periodic work to do:
+/**
+ * batadv_bla_periodic_work - performs periodic bla work
+ * @work: kernel work struct
+ *
+ * periodic work to do:
  *  * purge structures when they are too old
  *  * send announcements
  */
@@ -1290,7 +1348,12 @@
 static struct lock_class_key batadv_claim_hash_lock_class_key;
 static struct lock_class_key batadv_backbone_hash_lock_class_key;
  
-/* initialize all bla structures */
+/**
+ * batadv_bla_init - initialize all bla structures
+ * @bat_priv: the bat priv with all the soft interface information
+ *
+ * Return: 0 on success, < 0 on error.
+ */
 int batadv_bla_init(struct batadv_priv *bat_priv)
 {
 	int i;
@@ -1345,7 +1408,7 @@
 }
  
 /**
- * batadv_bla_check_bcast_duplist
+ * batadv_bla_check_bcast_duplist - Check if a frame is in the broadcast dup.
  * @bat_priv: the bat priv with all the soft interface information
  * @skb: contains the bcast_packet to be checked
  *
@@ -1357,6 +1420,8 @@
  * with a good chance that it is the same packet. If it is furthermore
  * sent by another host, drop it. We allow equal packets from
  * the same host however as this might be intended.
+ *
+ * Return: 1 if a packet is in the duplicate list, 0 otherwise.
  */
 int batadv_bla_check_bcast_duplist(struct batadv_priv *bat_priv,
 				   struct sk_buff *skb)
  
@@ -1415,13 +1480,12 @@
 }
  
 /**
- * batadv_bla_is_backbone_gw_orig
+ * batadv_bla_is_backbone_gw_orig - Check if the originator is a gateway for
+ *  the VLAN identified by vid.
  * @bat_priv: the bat priv with all the soft interface information
  * @orig: originator mac address
  * @vid: VLAN identifier
  *
- * Check if the originator is a gateway for the VLAN identified by vid.
- *
  * Return: true if orig is a backbone for this vid, false otherwise.
  */
 bool batadv_bla_is_backbone_gw_orig(struct batadv_priv *bat_priv, u8 *orig,
  
@@ -1456,13 +1520,11 @@
 }
  
 /**
- * batadv_bla_is_backbone_gw
+ * batadv_bla_is_backbone_gw - check if originator is a backbone gw for a VLAN.
  * @skb: the frame to be checked
  * @orig_node: the orig_node of the frame
  * @hdr_size: maximum length of the frame
  *
- * bla_is_backbone_gw inspects the skb for the VLAN ID
- *
  * Return: 1 if the orig_node is also a gateway on the soft interface, otherwise
  * it returns 0.
  */
@@ -1491,7 +1553,12 @@
 	return 1;
 }
  
-/* free all bla structures (for softinterface free or module unload) */
+/**
+ * batadv_bla_init - free all bla structures
+ * @bat_priv: the bat priv with all the soft interface information
+ *
+ * for softinterface free or module unload
+ */
 void batadv_bla_free(struct batadv_priv *bat_priv)
 {
 	struct batadv_hard_iface *primary_if;
  
@@ -1514,13 +1581,13 @@
 }
  
 /**
- * batadv_bla_rx
+ * batadv_bla_rx - check packets coming from the mesh.
  * @bat_priv: the bat priv with all the soft interface information
  * @skb: the frame to be checked
  * @vid: the VLAN ID of the frame
  * @is_bcast: the packet came in a broadcast packet type.
  *
- * bla_rx avoidance checks if:
+ * batadv_bla_rx avoidance checks if:
  *  * we have to race for a claim
  *  * if the frame is allowed on the LAN
  *
  
@@ -1610,12 +1677,12 @@
 }
  
 /**
- * batadv_bla_tx
+ * batadv_bla_tx - check packets going into the mesh
  * @bat_priv: the bat priv with all the soft interface information
  * @skb: the frame to be checked
  * @vid: the VLAN ID of the frame
  *
- * bla_tx checks if:
+ * batadv_bla_tx checks if:
  *  * a claim was received which has to be processed
  *  * the frame is allowed on the mesh
  *
@@ -1698,6 +1765,13 @@
 	return ret;
 }
  
+/**
+ * batadv_bla_claim_table_seq_print_text - print the claim table in a seq file
+ * @seq: seq file to print on
+ * @offset: not used
+ *
+ * Return: always 0
+ */
 int batadv_bla_claim_table_seq_print_text(struct seq_file *seq, void *offset)
 {
 	struct net_device *net_dev = (struct net_device *)seq->private;
@@ -1747,6 +1821,14 @@
 	return 0;
 }
  
+/**
+ * batadv_bla_backbone_table_seq_print_text - print the backbone table in a seq
+ *  file
+ * @seq: seq file to print on
+ * @offset: not used
+ *
+ * Return: always 0
+ */
 int batadv_bla_backbone_table_seq_print_text(struct seq_file *seq, void *offset)
 {
 	struct net_device *net_dev = (struct net_device *)seq->private;
...	...	@@ -59,9 +59,11 @@
59	59	struct batadv_bla_backbone_gw *backbone_gw);
60	60
61	61	/**
62		- * batadv_choose_claim
	62	+ * batadv_choose_claim - choose the right bucket for a claim.
	63	+ * @data: data to hash
	64	+ * @size: size of the hash table
63	65	*
64		- * Return: the index of the claim
	66	+ * Return: the hash index of the claim
65	67	*/
66	68	static inline u32 batadv_choose_claim(const void *data, u32 size)
67	69	{
68	70
...	...	@@ -75,9 +77,11 @@
75	77	}
76	78
77	79	/**
78		- * batadv_choose_backbone_gw
	80	+ * batadv_choose_backbone_gw - choose the right bucket for a backbone gateway.
	81	+ * @data: data to hash
	82	+ * @size: size of the hash table
79	83	*
80		- * Return: the index of the backbone gateway
	84	+ * Return: the hash index of the backbone gateway
81	85	*/
82	86	static inline u32 batadv_choose_backbone_gw(const void *data, u32 size)
83	87	{
...	...	@@ -90,7 +94,13 @@
90	94	return hash % size;
91	95	}
92	96
93		-/* compares address and vid of two backbone gws */
	97	+/**
	98	+ * batadv_compare_backbone_gw - compare address and vid of two backbone gws
	99	+ * @node: list node of the first entry to compare
	100	+ * @data2: pointer to the second backbone gateway
	101	+ *
	102	+ * Return: 1 if the backbones have the same data, 0 otherwise
	103	+ */
94	104	static int batadv_compare_backbone_gw(const struct hlist_node *node,
95	105	const void *data2)
96	106	{
...	...	@@ -108,7 +118,13 @@
108	118	return 1;
109	119	}
110	120
111		-/* compares address and vid of two claims */
	121	+/**
	122	+ * batadv_compare_backbone_gw - compare address and vid of two claims
	123	+ * @node: list node of the first entry to compare
	124	+ * @data2: pointer to the second claims
	125	+ *
	126	+ * Return: 1 if the claim have the same data, 0 otherwise
	127	+ */
112	128	static int batadv_compare_claim(const struct hlist_node *node,
113	129	const void *data2)
114	130	{
...	...	@@ -126,7 +142,10 @@
126	142	return 1;
127	143	}
128	144
129		-/* free a backbone gw */
	145	+/**
	146	+ * batadv_compare_backbone_gw - free backbone gw
	147	+ * @backbone_gw: backbone gateway to be free'd
	148	+ */
130	149	static void
131	150	batadv_backbone_gw_free_ref(struct batadv_bla_backbone_gw *backbone_gw)
132	151	{
133	152
...	...	@@ -134,14 +153,21 @@
134	153	kfree_rcu(backbone_gw, rcu);
135	154	}
136	155
137		-/* finally deinitialize the claim */
	156	+/**
	157	+ * batadv_claim_release - release claim from lists and queue for free after rcu
	158	+ * grace period
	159	+ * @ref: kref pointer of the claim
	160	+ */
138	161	static void batadv_claim_release(struct batadv_bla_claim *claim)
139	162	{
140	163	batadv_backbone_gw_free_ref(claim->backbone_gw);
141	164	kfree_rcu(claim, rcu);
142	165	}
143	166
144		-/* free a claim, call claim_free_rcu if its the last reference */
	167	+/**
	168	+ * batadv_claim_free_rcu - free a claim
	169	+ * @claim: claim to be free'd
	170	+ */
145	171	static void batadv_claim_free_ref(struct batadv_bla_claim *claim)
146	172	{
147	173	if (atomic_dec_and_test(&claim->refcount))
148	174
...	...	@@ -149,12 +175,10 @@
149	175	}
150	176
151	177	/**
152		- * batadv_claim_hash_find
	178	+ * batadv_claim_hash_find - looks for a claim in the claim hash
153	179	* @bat_priv: the bat priv with all the soft interface information
154	180	* @data: search data (may be local/static data)
155	181	*
156		- * looks for a claim in the hash
157		- *
158	182	* Return: claim if found or NULL otherwise.
159	183	*/
160	184	static struct batadv_bla_claim
161	185
...	...	@@ -190,12 +214,12 @@
190	214	}
191	215
192	216	/**
193		- * batadv_backbone_hash_find - looks for a claim in the hash
	217	+ * batadv_backbone_hash_find - looks for a backbone gateway in the hash
194	218	* @bat_priv: the bat priv with all the soft interface information
195	219	* @addr: the address of the originator
196	220	* @vid: the VLAN ID
197	221	*
198		- * Return: claim if found or NULL otherwise.
	222	+ * Return: backbone gateway if found or NULL otherwise
199	223	*/
200	224	static struct batadv_bla_backbone_gw *
201	225	batadv_backbone_hash_find(struct batadv_priv bat_priv, u8 addr,
...	...	@@ -233,7 +257,10 @@
233	257	return backbone_gw_tmp;
234	258	}
235	259
236		-/* delete all claims for a backbone */
	260	+/**
	261	+ * batadv_bla_del_backbone_claims - delete all claims for a backbone
	262	+ * @backbone_gw: backbone gateway where the claims should be removed
	263	+ */
237	264	static void
238	265	batadv_bla_del_backbone_claims(struct batadv_bla_backbone_gw *backbone_gw)
239	266	{
240	267
...	...	@@ -381,14 +408,13 @@
381	408	}
382	409
383	410	/**
384		- * batadv_bla_get_backbone_gw
	411	+ * batadv_bla_get_backbone_gw - finds or creates a backbone gateway
385	412	* @bat_priv: the bat priv with all the soft interface information
386	413	* @orig: the mac address of the originator
387	414	* @vid: the VLAN ID
388	415	* @own_backbone: set if the requested backbone is local
389	416	*
390		- * searches for the backbone gw or creates a new one if it could not
391		- * be found.
	417	+ * Return: the (possibly created) backbone gateway or NULL on error
392	418	*/
393	419	static struct batadv_bla_backbone_gw *
394	420	batadv_bla_get_backbone_gw(struct batadv_priv bat_priv, u8 orig,
...	...	@@ -454,7 +480,13 @@
454	480	return entry;
455	481	}
456	482
457		-/* update or add the own backbone gw to make sure we announce
	483	+/**
	484	+ * batadv_bla_update_own_backbone_gw - updates the own backbone gw for a VLAN
	485	+ * @bat_priv: the bat priv with all the soft interface information
	486	+ * @primary_if: the selected primary interface
	487	+ * @vid: VLAN identifier
	488	+ *
	489	+ * update or add the own backbone gw to make sure we announce
458	490	* where we receive other backbone gws
459	491	*/
460	492	static void
461	493
...	...	@@ -551,12 +583,9 @@
551	583	}
552	584
553	585	/**
554		- * batadv_bla_send_announce
	586	+ * batadv_bla_send_announce - Send an announcement frame
555	587	* @bat_priv: the bat priv with all the soft interface information
556	588	* @backbone_gw: our backbone gateway which should be announced
557		- *
558		- * This function sends an announcement. It is called from multiple
559		- * places.
560	589	*/
561	590	static void batadv_bla_send_announce(struct batadv_priv *bat_priv,
562	591	struct batadv_bla_backbone_gw *backbone_gw)
...	...	@@ -646,8 +675,11 @@
646	675	batadv_claim_free_ref(claim);
647	676	}
648	677
649		-/* Delete a claim from the claim hash which has the
650		- * given mac address and vid.
	678	+/**
	679	+ * batadv_bla_del_claim - delete a claim from the claim hash
	680	+ * @bat_priv: the bat priv with all the soft interface information
	681	+ * @mac: mac address of the claim to be removed
	682	+ * @vid: VLAN id for the claim to be removed
651	683	*/
652	684	static void batadv_bla_del_claim(struct batadv_priv *bat_priv,
653	685	const u8 *mac, const unsigned short vid)
...	...	@@ -677,6 +709,10 @@
677	709
678	710	/**
679	711	* batadv_handle_announce - check for ANNOUNCE frame
	712	+ * @bat_priv: the bat priv with all the soft interface information
	713	+ * @an_addr: announcement mac address (ARP Sender HW address)
	714	+ * @backbone_addr: originator address of the sender (Ethernet source MAC)
	715	+ * @vid: the VLAN ID of the frame
680	716	*
681	717	* Return: 1 if handled
682	718	*/
...	...	@@ -731,6 +767,11 @@
731	767
732	768	/**
733	769	* batadv_handle_request - check for REQUEST frame
	770	+ * @bat_priv: the bat priv with all the soft interface information
	771	+ * @primary_if: the primary hard interface of this batman soft interface
	772	+ * @backbone_addr: backbone address to be requested (ARP sender HW MAC)
	773	+ * @ethhdr: ethernet header of a packet
	774	+ * @vid: the VLAN ID of the frame
734	775	*
735	776	* Return: 1 if handled
736	777	*/
...	...	@@ -759,6 +800,11 @@
759	800
760	801	/**
761	802	* batadv_handle_unclaim - check for UNCLAIM frame
	803	+ * @bat_priv: the bat priv with all the soft interface information
	804	+ * @primary_if: the primary hard interface of this batman soft interface
	805	+ * @backbone_addr: originator address of the backbone (Ethernet source)
	806	+ * @claim_addr: Client to be unclaimed (ARP sender HW MAC)
	807	+ * @vid: the VLAN ID of the frame
762	808	*
763	809	* Return: 1 if handled
764	810	*/
...	...	@@ -792,6 +838,11 @@
792	838
793	839	/**
794	840	* batadv_handle_claim - check for CLAIM frame
	841	+ * @bat_priv: the bat priv with all the soft interface information
	842	+ * @primary_if: the primary hard interface of this batman soft interface
	843	+ * @backbone_addr: originator address of the backbone (Ethernet Source)
	844	+ * @claim_addr: client mac address to be claimed (ARP sender HW MAC)
	845	+ * @vid: the VLAN ID of the frame
795	846	*
796	847	* Return: 1 if handled
797	848	*/
...	...	@@ -823,7 +874,7 @@
823	874	}
824	875
825	876	/**
826		- * batadv_check_claim_group
	877	+ * batadv_check_claim_group - check for claim group membership
827	878	* @bat_priv: the bat priv with all the soft interface information
828	879	* @primary_if: the primary interface of this batman interface
829	880	* @hw_src: the Hardware source in the ARP Header
830	881
...	...	@@ -898,13 +949,11 @@
898	949	}
899	950
900	951	/**
901		- * batadv_bla_process_claim
	952	+ * batadv_bla_process_claim - Check if this is a claim frame, and process it
902	953	* @bat_priv: the bat priv with all the soft interface information
903	954	* @primary_if: the primary hard interface of this batman soft interface
904	955	* @skb: the frame to be checked
905	956	*
906		- * Check if this is a claim frame, and process it accordingly.
907		- *
908	957	* Return: 1 if it was a claim frame, otherwise return 0 to
909	958	* tell the callee that it can use the frame on its own.
910	959	*/
...	...	@@ -1036,7 +1085,13 @@
1036	1085	return 1;
1037	1086	}
1038	1087
1039		-/* Check when we last heard from other nodes, and remove them in case of
	1088	+/**
	1089	+ * batadv_bla_purge_backbone_gw - Remove backbone gateways after a timeout or
	1090	+ * immediately
	1091	+ * @bat_priv: the bat priv with all the soft interface information
	1092	+ * @now: whether the whole hash shall be wiped now
	1093	+ *
	1094	+ * Check when we last heard from other nodes, and remove them in case of
1040	1095	* a time out, or clean all backbone gws if now is set.
1041	1096	*/
1042	1097	static void batadv_bla_purge_backbone_gw(struct batadv_priv *bat_priv, int now)
...	...	@@ -1084,7 +1139,7 @@
1084	1139	}
1085	1140
1086	1141	/**
1087		- * batadv_bla_purge_claims
	1142	+ * batadv_bla_purge_claims - Remove claims after a timeout or immediately
1088	1143	* @bat_priv: the bat priv with all the soft interface information
1089	1144	* @primary_if: the selected primary interface, may be NULL if now is set
1090	1145	* @now: whether the whole hash shall be wiped now
1091	1146
...	...	@@ -1133,12 +1188,11 @@
1133	1188	}
1134	1189
1135	1190	/**
1136		- * batadv_bla_update_orig_address
	1191	+ * batadv_bla_update_orig_address - Update the backbone gateways when the own
	1192	+ * originator address changes
1137	1193	* @bat_priv: the bat priv with all the soft interface information
1138	1194	* @primary_if: the new selected primary_if
1139	1195	* @oldif: the old primary interface, may be NULL
1140		- *
1141		- * Update the backbone gateways when the own orig address changes.
1142	1196	*/
1143	1197	void batadv_bla_update_orig_address(struct batadv_priv *bat_priv,
1144	1198	struct batadv_hard_iface *primary_if,
...	...	@@ -1209,7 +1263,11 @@
1209	1263	batadv_hardif_free_ref(primary_if);
1210	1264	}
1211	1265
1212		-/* periodic work to do:
	1266	+/**
	1267	+ * batadv_bla_periodic_work - performs periodic bla work
	1268	+ * @work: kernel work struct
	1269	+ *
	1270	+ * periodic work to do:
1213	1271	* * purge structures when they are too old
1214	1272	* * send announcements
1215	1273	*/
...	...	@@ -1290,7 +1348,12 @@
1290	1348	static struct lock_class_key batadv_claim_hash_lock_class_key;
1291	1349	static struct lock_class_key batadv_backbone_hash_lock_class_key;
1292	1350
1293		-/* initialize all bla structures */
	1351	+/**
	1352	+ * batadv_bla_init - initialize all bla structures
	1353	+ * @bat_priv: the bat priv with all the soft interface information
	1354	+ *
	1355	+ * Return: 0 on success, < 0 on error.
	1356	+ */
1294	1357	int batadv_bla_init(struct batadv_priv *bat_priv)
1295	1358	{
1296	1359	int i;
...	...	@@ -1345,7 +1408,7 @@
1345	1408	}
1346	1409
1347	1410	/**
1348		- * batadv_bla_check_bcast_duplist
	1411	+ * batadv_bla_check_bcast_duplist - Check if a frame is in the broadcast dup.
1349	1412	* @bat_priv: the bat priv with all the soft interface information
1350	1413	* @skb: contains the bcast_packet to be checked
1351	1414	*
...	...	@@ -1357,6 +1420,8 @@
1357	1420	* with a good chance that it is the same packet. If it is furthermore
1358	1421	* sent by another host, drop it. We allow equal packets from
1359	1422	* the same host however as this might be intended.
	1423	+ *
	1424	+ * Return: 1 if a packet is in the duplicate list, 0 otherwise.
1360	1425	*/
1361	1426	int batadv_bla_check_bcast_duplist(struct batadv_priv *bat_priv,
1362	1427	struct sk_buff *skb)
1363	1428
...	...	@@ -1415,13 +1480,12 @@
1415	1480	}
1416	1481
1417	1482	/**
1418		- * batadv_bla_is_backbone_gw_orig
	1483	+ * batadv_bla_is_backbone_gw_orig - Check if the originator is a gateway for
	1484	+ * the VLAN identified by vid.
1419	1485	* @bat_priv: the bat priv with all the soft interface information
1420	1486	* @orig: originator mac address
1421	1487	* @vid: VLAN identifier
1422	1488	*
1423		- * Check if the originator is a gateway for the VLAN identified by vid.
1424		- *
1425	1489	* Return: true if orig is a backbone for this vid, false otherwise.
1426	1490	*/
1427	1491	bool batadv_bla_is_backbone_gw_orig(struct batadv_priv bat_priv, u8 orig,
1428	1492
...	...	@@ -1456,13 +1520,11 @@
1456	1520	}
1457	1521
1458	1522	/**
1459		- * batadv_bla_is_backbone_gw
	1523	+ * batadv_bla_is_backbone_gw - check if originator is a backbone gw for a VLAN.
1460	1524	* @skb: the frame to be checked
1461	1525	* @orig_node: the orig_node of the frame
1462	1526	* @hdr_size: maximum length of the frame
1463	1527	*
1464		- * bla_is_backbone_gw inspects the skb for the VLAN ID
1465		- *
1466	1528	* Return: 1 if the orig_node is also a gateway on the soft interface, otherwise
1467	1529	* it returns 0.
1468	1530	*/
...	...	@@ -1491,7 +1553,12 @@
1491	1553	return 1;
1492	1554	}
1493	1555
1494		-/* free all bla structures (for softinterface free or module unload) */
	1556	+/**
	1557	+ * batadv_bla_init - free all bla structures
	1558	+ * @bat_priv: the bat priv with all the soft interface information
	1559	+ *
	1560	+ * for softinterface free or module unload
	1561	+ */
1495	1562	void batadv_bla_free(struct batadv_priv *bat_priv)
1496	1563	{
1497	1564	struct batadv_hard_iface *primary_if;
1498	1565
...	...	@@ -1514,13 +1581,13 @@
1514	1581	}
1515	1582
1516	1583	/**
1517		- * batadv_bla_rx
	1584	+ * batadv_bla_rx - check packets coming from the mesh.
1518	1585	* @bat_priv: the bat priv with all the soft interface information
1519	1586	* @skb: the frame to be checked
1520	1587	* @vid: the VLAN ID of the frame
1521	1588	* @is_bcast: the packet came in a broadcast packet type.
1522	1589	*
1523		- * bla_rx avoidance checks if:
	1590	+ * batadv_bla_rx avoidance checks if:
1524	1591	* * we have to race for a claim
1525	1592	* * if the frame is allowed on the LAN
1526	1593	*
1527	1594
...	...	@@ -1610,12 +1677,12 @@
1610	1677	}
1611	1678
1612	1679	/**
1613		- * batadv_bla_tx
	1680	+ * batadv_bla_tx - check packets going into the mesh
1614	1681	* @bat_priv: the bat priv with all the soft interface information
1615	1682	* @skb: the frame to be checked
1616	1683	* @vid: the VLAN ID of the frame
1617	1684	*
1618		- * bla_tx checks if:
	1685	+ * batadv_bla_tx checks if:
1619	1686	* * a claim was received which has to be processed
1620	1687	* * the frame is allowed on the mesh
1621	1688	*
...	...	@@ -1698,6 +1765,13 @@
1698	1765	return ret;
1699	1766	}
1700	1767
	1768	+/**
	1769	+ * batadv_bla_claim_table_seq_print_text - print the claim table in a seq file
	1770	+ * @seq: seq file to print on
	1771	+ * @offset: not used
	1772	+ *
	1773	+ * Return: always 0
	1774	+ */
1701	1775	int batadv_bla_claim_table_seq_print_text(struct seq_file seq, void offset)
1702	1776	{
1703	1777	struct net_device net_dev = (struct net_device )seq->private;
...	...	@@ -1747,6 +1821,14 @@
1747	1821	return 0;
1748	1822	}
1749	1823
	1824	+/**
	1825	+ * batadv_bla_backbone_table_seq_print_text - print the backbone table in a seq
	1826	+ * file
	1827	+ * @seq: seq file to print on
	1828	+ * @offset: not used
	1829	+ *
	1830	+ * Return: always 0
	1831	+ */
1750	1832	int batadv_bla_backbone_table_seq_print_text(struct seq_file seq, void offset)
1751	1833	{
1752	1834	struct net_device net_dev = (struct net_device )seq->private;