History

batman-adv: use inline kernel-doc for uapi constants

The enums of constants for netlink tends to become rather large over time. Documenting them is easier when the kernel-doc is actually next to constant and not in a different block above the enum. Also inline kernel-doc allows multi-paragraph description. This could be required to better document the netlink command types and the expected return values.

Sven Eckelmann committed 9 years ago

Commit 40b16b91 parent 6a4bc441 file · +290 −79Browse files

Showing the changes to include/uapi/linux (1 of 1 file). Show all

Unified · Split

include/uapi/linux/batman_adv.h+290−79
@@ -24,20 +24,6 @@ · 23 unmodified lines
2424
2525 /**
2626 * enum batadv_tt_client_flags - TT client specific flags
27− * @BATADV_TT_CLIENT_DEL: the client has to be deleted from the table
28− * @BATADV_TT_CLIENT_ROAM: the client roamed to/from another node and the new
29− * update telling its new real location has not been received/sent yet
30− * @BATADV_TT_CLIENT_WIFI: this client is connected through a wifi interface.
31− * This information is used by the "AP Isolation" feature
32− * @BATADV_TT_CLIENT_ISOLA: this client is considered "isolated". This
33− * information is used by the Extended Isolation feature
34− * @BATADV_TT_CLIENT_NOPURGE: this client should never be removed from the table
35− * @BATADV_TT_CLIENT_NEW: this client has been added to the local table but has
36− * not been announced yet
37− * @BATADV_TT_CLIENT_PENDING: this client is marked for removal but it is kept
38− * in the table for one more originator interval for consistency purposes
39− * @BATADV_TT_CLIENT_TEMP: this global client has been detected to be part of
40− * the network but no nnode has already announced it
4127 *
4228 * Bits from 0 to 7 are called _remote flags_ because they are sent on the wire.
4329 * Bits from 8 to 15 are called _local flags_ because they are used for local
@@ -48,160 +34,385 @@ · 4 unmodified lines
4834 * in the TT CRC computation.
4935 */
5036 enum batadv_tt_client_flags {
37+ /**
38+ * @BATADV_TT_CLIENT_DEL: the client has to be deleted from the table
39+ */
5140 BATADV_TT_CLIENT_DEL = (1 << 0),
41+
42+ /**
43+ * @BATADV_TT_CLIENT_ROAM: the client roamed to/from another node and
44+ * the new update telling its new real location has not been
45+ * received/sent yet
46+ */
5247 BATADV_TT_CLIENT_ROAM = (1 << 1),
48+
49+ /**
50+ * @BATADV_TT_CLIENT_WIFI: this client is connected through a wifi
51+ * interface. This information is used by the "AP Isolation" feature
52+ */
5353 BATADV_TT_CLIENT_WIFI = (1 << 4),
54+
55+ /**
56+ * @BATADV_TT_CLIENT_ISOLA: this client is considered "isolated". This
57+ * information is used by the Extended Isolation feature
58+ */
5459 BATADV_TT_CLIENT_ISOLA = (1 << 5),
60+
61+ /**
62+ * @BATADV_TT_CLIENT_NOPURGE: this client should never be removed from
63+ * the table
64+ */
5565 BATADV_TT_CLIENT_NOPURGE = (1 << 8),
66+
67+ /**
68+ * @BATADV_TT_CLIENT_NEW: this client has been added to the local table
69+ * but has not been announced yet
70+ */
5671 BATADV_TT_CLIENT_NEW = (1 << 9),
72+
73+ /**
74+ * @BATADV_TT_CLIENT_PENDING: this client is marked for removal but it
75+ * is kept in the table for one more originator interval for consistency
76+ * purposes
77+ */
5778 BATADV_TT_CLIENT_PENDING = (1 << 10),
79+
80+ /**
81+ * @BATADV_TT_CLIENT_TEMP: this global client has been detected to be
82+ * part of the network but no nnode has already announced it
83+ */
5884 BATADV_TT_CLIENT_TEMP = (1 << 11),
5985 };
6086
6187 /**
6288 * enum batadv_nl_attrs - batman-adv netlink attributes
63− *
64− * @BATADV_ATTR_UNSPEC: unspecified attribute to catch errors
65− * @BATADV_ATTR_VERSION: batman-adv version string
66− * @BATADV_ATTR_ALGO_NAME: name of routing algorithm
67− * @BATADV_ATTR_MESH_IFINDEX: index of the batman-adv interface
68− * @BATADV_ATTR_MESH_IFNAME: name of the batman-adv interface
69− * @BATADV_ATTR_MESH_ADDRESS: mac address of the batman-adv interface
70− * @BATADV_ATTR_HARD_IFINDEX: index of the non-batman-adv interface
71− * @BATADV_ATTR_HARD_IFNAME: name of the non-batman-adv interface
72− * @BATADV_ATTR_HARD_ADDRESS: mac address of the non-batman-adv interface
73− * @BATADV_ATTR_ORIG_ADDRESS: originator mac address
74− * @BATADV_ATTR_TPMETER_RESULT: result of run (see batadv_tp_meter_status)
75− * @BATADV_ATTR_TPMETER_TEST_TIME: time (msec) the run took
76− * @BATADV_ATTR_TPMETER_BYTES: amount of acked bytes during run
77− * @BATADV_ATTR_TPMETER_COOKIE: session cookie to match tp_meter session
78− * @BATADV_ATTR_PAD: attribute used for padding for 64-bit alignment
79− * @BATADV_ATTR_ACTIVE: Flag indicating if the hard interface is active
80− * @BATADV_ATTR_TT_ADDRESS: Client MAC address
81− * @BATADV_ATTR_TT_TTVN: Translation table version
82− * @BATADV_ATTR_TT_LAST_TTVN: Previous translation table version
83− * @BATADV_ATTR_TT_CRC32: CRC32 over translation table
84− * @BATADV_ATTR_TT_VID: VLAN ID
85− * @BATADV_ATTR_TT_FLAGS: Translation table client flags
86− * @BATADV_ATTR_FLAG_BEST: Flags indicating entry is the best
87− * @BATADV_ATTR_LAST_SEEN_MSECS: Time in milliseconds since last seen
88− * @BATADV_ATTR_NEIGH_ADDRESS: Neighbour MAC address
89− * @BATADV_ATTR_TQ: TQ to neighbour
90− * @BATADV_ATTR_THROUGHPUT: Estimated throughput to Neighbour
91− * @BATADV_ATTR_BANDWIDTH_UP: Reported uplink bandwidth
92− * @BATADV_ATTR_BANDWIDTH_DOWN: Reported downlink bandwidth
93− * @BATADV_ATTR_ROUTER: Gateway router MAC address
94− * @BATADV_ATTR_BLA_OWN: Flag indicating own originator
95− * @BATADV_ATTR_BLA_ADDRESS: Bridge loop avoidance claim MAC address
96− * @BATADV_ATTR_BLA_VID: BLA VLAN ID
97− * @BATADV_ATTR_BLA_BACKBONE: BLA gateway originator MAC address
98− * @BATADV_ATTR_BLA_CRC: BLA CRC
99− * @__BATADV_ATTR_AFTER_LAST: internal use
100− * @NUM_BATADV_ATTR: total number of batadv_nl_attrs available
101− * @BATADV_ATTR_MAX: highest attribute number currently defined
10289 */
10390 enum batadv_nl_attrs {
91+ /**
92+ * @BATADV_ATTR_UNSPEC: unspecified attribute to catch errors
93+ */
10494 BATADV_ATTR_UNSPEC,
95+
96+ /**
97+ * @BATADV_ATTR_VERSION: batman-adv version string
98+ */
10599 BATADV_ATTR_VERSION,
100+
101+ /**
102+ * @BATADV_ATTR_ALGO_NAME: name of routing algorithm
103+ */
106104 BATADV_ATTR_ALGO_NAME,
105+
106+ /**
107+ * @BATADV_ATTR_MESH_IFINDEX: index of the batman-adv interface
108+ */
107109 BATADV_ATTR_MESH_IFINDEX,
110+
111+ /**
112+ * @BATADV_ATTR_MESH_IFNAME: name of the batman-adv interface
113+ */
108114 BATADV_ATTR_MESH_IFNAME,
115+
116+ /**
117+ * @BATADV_ATTR_MESH_ADDRESS: mac address of the batman-adv interface
118+ */
109119 BATADV_ATTR_MESH_ADDRESS,
120+
121+ /**
122+ * @BATADV_ATTR_HARD_IFINDEX: index of the non-batman-adv interface
123+ */
110124 BATADV_ATTR_HARD_IFINDEX,
125+
126+ /**
127+ * @BATADV_ATTR_HARD_IFNAME: name of the non-batman-adv interface
128+ */
111129 BATADV_ATTR_HARD_IFNAME,
130+
131+ /**
132+ * @BATADV_ATTR_HARD_ADDRESS: mac address of the non-batman-adv
133+ * interface
134+ */
112135 BATADV_ATTR_HARD_ADDRESS,
136+
137+ /**
138+ * @BATADV_ATTR_ORIG_ADDRESS: originator mac address
139+ */
113140 BATADV_ATTR_ORIG_ADDRESS,
141+
142+ /**
143+ * @BATADV_ATTR_TPMETER_RESULT: result of run (see
144+ * batadv_tp_meter_status)
145+ */
114146 BATADV_ATTR_TPMETER_RESULT,
147+
148+ /**
149+ * @BATADV_ATTR_TPMETER_TEST_TIME: time (msec) the run took
150+ */
115151 BATADV_ATTR_TPMETER_TEST_TIME,
152+
153+ /**
154+ * @BATADV_ATTR_TPMETER_BYTES: amount of acked bytes during run
155+ */
116156 BATADV_ATTR_TPMETER_BYTES,
157+
158+ /**
159+ * @BATADV_ATTR_TPMETER_COOKIE: session cookie to match tp_meter session
160+ */
117161 BATADV_ATTR_TPMETER_COOKIE,
162+
163+ /**
164+ * @BATADV_ATTR_PAD: attribute used for padding for 64-bit alignment
165+ */
118166 BATADV_ATTR_PAD,
167+
168+ /**
169+ * @BATADV_ATTR_ACTIVE: Flag indicating if the hard interface is active
170+ */
119171 BATADV_ATTR_ACTIVE,
172+
173+ /**
174+ * @BATADV_ATTR_TT_ADDRESS: Client MAC address
175+ */
120176 BATADV_ATTR_TT_ADDRESS,
177+
178+ /**
179+ * @BATADV_ATTR_TT_TTVN: Translation table version
180+ */
121181 BATADV_ATTR_TT_TTVN,
182+
183+ /**
184+ * @BATADV_ATTR_TT_LAST_TTVN: Previous translation table version
185+ */
122186 BATADV_ATTR_TT_LAST_TTVN,
187+
188+ /**
189+ * @BATADV_ATTR_TT_CRC32: CRC32 over translation table
190+ */
123191 BATADV_ATTR_TT_CRC32,
192+
193+ /**
194+ * @BATADV_ATTR_TT_VID: VLAN ID
195+ */
124196 BATADV_ATTR_TT_VID,
197+
198+ /**
199+ * @BATADV_ATTR_TT_FLAGS: Translation table client flags
200+ */
125201 BATADV_ATTR_TT_FLAGS,
202+
203+ /**
204+ * @BATADV_ATTR_FLAG_BEST: Flags indicating entry is the best
205+ */
126206 BATADV_ATTR_FLAG_BEST,
207+
208+ /**
209+ * @BATADV_ATTR_LAST_SEEN_MSECS: Time in milliseconds since last seen
210+ */
127211 BATADV_ATTR_LAST_SEEN_MSECS,
212+
213+ /**
214+ * @BATADV_ATTR_NEIGH_ADDRESS: Neighbour MAC address
215+ */
128216 BATADV_ATTR_NEIGH_ADDRESS,
217+
218+ /**
219+ * @BATADV_ATTR_TQ: TQ to neighbour
220+ */
129221 BATADV_ATTR_TQ,
222+
223+ /**
224+ * @BATADV_ATTR_THROUGHPUT: Estimated throughput to Neighbour
225+ */
130226 BATADV_ATTR_THROUGHPUT,
227+
228+ /**
229+ * @BATADV_ATTR_BANDWIDTH_UP: Reported uplink bandwidth
230+ */
131231 BATADV_ATTR_BANDWIDTH_UP,
232+
233+ /**
234+ * @BATADV_ATTR_BANDWIDTH_DOWN: Reported downlink bandwidth
235+ */
132236 BATADV_ATTR_BANDWIDTH_DOWN,
237+
238+ /**
239+ * @BATADV_ATTR_ROUTER: Gateway router MAC address
240+ */
133241 BATADV_ATTR_ROUTER,
242+
243+ /**
244+ * @BATADV_ATTR_BLA_OWN: Flag indicating own originator
245+ */
134246 BATADV_ATTR_BLA_OWN,
247+
248+ /**
249+ * @BATADV_ATTR_BLA_ADDRESS: Bridge loop avoidance claim MAC address
250+ */
135251 BATADV_ATTR_BLA_ADDRESS,
252+
253+ /**
254+ * @BATADV_ATTR_BLA_VID: BLA VLAN ID
255+ */
136256 BATADV_ATTR_BLA_VID,
257+
258+ /**
259+ * @BATADV_ATTR_BLA_BACKBONE: BLA gateway originator MAC address
260+ */
137261 BATADV_ATTR_BLA_BACKBONE,
262+
263+ /**
264+ * @BATADV_ATTR_BLA_CRC: BLA CRC
265+ */
138266 BATADV_ATTR_BLA_CRC,
267+
139268 /* add attributes above here, update the policy in netlink.c */
269+
270+ /**
271+ * @__BATADV_ATTR_AFTER_LAST: internal use
272+ */
140273 __BATADV_ATTR_AFTER_LAST,
274+
275+ /**
276+ * @NUM_BATADV_ATTR: total number of batadv_nl_attrs available
277+ */
141278 NUM_BATADV_ATTR = __BATADV_ATTR_AFTER_LAST,
279+
280+ /**
281+ * @BATADV_ATTR_MAX: highest attribute number currently defined
282+ */
142283 BATADV_ATTR_MAX = __BATADV_ATTR_AFTER_LAST - 1
143284 };
144285
145286 /**
146287 * enum batadv_nl_commands - supported batman-adv netlink commands
147− *
148− * @BATADV_CMD_UNSPEC: unspecified command to catch errors
149− * @BATADV_CMD_GET_MESH_INFO: Query basic information about batman-adv device
150− * @BATADV_CMD_TP_METER: Start a tp meter session
151− * @BATADV_CMD_TP_METER_CANCEL: Cancel a tp meter session
152− * @BATADV_CMD_GET_ROUTING_ALGOS: Query the list of routing algorithms.
153− * @BATADV_CMD_GET_HARDIFS: Query list of hard interfaces
154− * @BATADV_CMD_GET_TRANSTABLE_LOCAL: Query list of local translations
155− * @BATADV_CMD_GET_TRANSTABLE_GLOBAL Query list of global translations
156− * @BATADV_CMD_GET_ORIGINATORS: Query list of originators
157− * @BATADV_CMD_GET_NEIGHBORS: Query list of neighbours
158− * @BATADV_CMD_GET_GATEWAYS: Query list of gateways
159− * @BATADV_CMD_GET_BLA_CLAIM: Query list of bridge loop avoidance claims
160− * @BATADV_CMD_GET_BLA_BACKBONE: Query list of bridge loop avoidance backbones
161− * @__BATADV_CMD_AFTER_LAST: internal use
162− * @BATADV_CMD_MAX: highest used command number
163288 */
164289 enum batadv_nl_commands {
290+ /**
291+ * @BATADV_CMD_UNSPEC: unspecified command to catch errors
292+ */
165293 BATADV_CMD_UNSPEC,
294+
295+ /**
296+ * @BATADV_CMD_GET_MESH_INFO: Query basic information about batman-adv
297+ * device
298+ */
166299 BATADV_CMD_GET_MESH_INFO,
300+
301+ /**
302+ * @BATADV_CMD_TP_METER: Start a tp meter session
303+ */
167304 BATADV_CMD_TP_METER,
305+
306+ /**
307+ * @BATADV_CMD_TP_METER_CANCEL: Cancel a tp meter session
308+ */
168309 BATADV_CMD_TP_METER_CANCEL,
310+
311+ /**
312+ * @BATADV_CMD_GET_ROUTING_ALGOS: Query the list of routing algorithms.
313+ */
169314 BATADV_CMD_GET_ROUTING_ALGOS,
315+
316+ /**
317+ * @BATADV_CMD_GET_HARDIFS: Query list of hard interfaces
318+ */
170319 BATADV_CMD_GET_HARDIFS,
320+
321+ /**
322+ * @BATADV_CMD_GET_TRANSTABLE_LOCAL: Query list of local translations
323+ */
171324 BATADV_CMD_GET_TRANSTABLE_LOCAL,
325+
326+ /**
327+ * @BATADV_CMD_GET_TRANSTABLE_GLOBAL: Query list of global translations
328+ */
172329 BATADV_CMD_GET_TRANSTABLE_GLOBAL,
330+
331+ /**
332+ * @BATADV_CMD_GET_ORIGINATORS: Query list of originators
333+ */
173334 BATADV_CMD_GET_ORIGINATORS,
335+
336+ /**
337+ * @BATADV_CMD_GET_NEIGHBORS: Query list of neighbours
338+ */
174339 BATADV_CMD_GET_NEIGHBORS,
340+
341+ /**
342+ * @BATADV_CMD_GET_GATEWAYS: Query list of gateways
343+ */
175344 BATADV_CMD_GET_GATEWAYS,
345+
346+ /**
347+ * @BATADV_CMD_GET_BLA_CLAIM: Query list of bridge loop avoidance claims
348+ */
176349 BATADV_CMD_GET_BLA_CLAIM,
350+
351+ /**
352+ * @BATADV_CMD_GET_BLA_BACKBONE: Query list of bridge loop avoidance
353+ * backbones
354+ */
177355 BATADV_CMD_GET_BLA_BACKBONE,
356+
178357 /* add new commands above here */
358+
359+ /**
360+ * @__BATADV_CMD_AFTER_LAST: internal use
361+ */
179362 __BATADV_CMD_AFTER_LAST,
363+
364+ /**
365+ * @BATADV_CMD_MAX: highest used command number
366+ */
180367 BATADV_CMD_MAX = __BATADV_CMD_AFTER_LAST - 1
181368 };
182369
183370 /**
184371 * enum batadv_tp_meter_reason - reason of a tp meter test run stop
185− * @BATADV_TP_REASON_COMPLETE: sender finished tp run
186− * @BATADV_TP_REASON_CANCEL: sender was stopped during run
187− * @BATADV_TP_REASON_DST_UNREACHABLE: receiver could not be reached or didn't
188− * answer
189− * @BATADV_TP_REASON_RESEND_LIMIT: (unused) sender retry reached limit
190− * @BATADV_TP_REASON_ALREADY_ONGOING: test to or from the same node already
191− * ongoing
192− * @BATADV_TP_REASON_MEMORY_ERROR: test was stopped due to low memory
193− * @BATADV_TP_REASON_CANT_SEND: failed to send via outgoing interface
194− * @BATADV_TP_REASON_TOO_MANY: too many ongoing sessions
195372 */
196373 enum batadv_tp_meter_reason {
374+ /**
375+ * @BATADV_TP_REASON_COMPLETE: sender finished tp run
376+ */
197377 BATADV_TP_REASON_COMPLETE = 3,
378+
379+ /**
380+ * @BATADV_TP_REASON_CANCEL: sender was stopped during run
381+ */
198382 BATADV_TP_REASON_CANCEL = 4,
383+
199384 /* error status >= 128 */
385+
386+ /**
387+ * @BATADV_TP_REASON_DST_UNREACHABLE: receiver could not be reached or
388+ * didn't answer
389+ */
200390 BATADV_TP_REASON_DST_UNREACHABLE = 128,
391+
392+ /**
393+ * @BATADV_TP_REASON_RESEND_LIMIT: (unused) sender retry reached limit
394+ */
201395 BATADV_TP_REASON_RESEND_LIMIT = 129,
396+
397+ /**
398+ * @BATADV_TP_REASON_ALREADY_ONGOING: test to or from the same node
399+ * already ongoing
400+ */
202401 BATADV_TP_REASON_ALREADY_ONGOING = 130,
402+
403+ /**
404+ * @BATADV_TP_REASON_MEMORY_ERROR: test was stopped due to low memory
405+ */
203406 BATADV_TP_REASON_MEMORY_ERROR = 131,
407+
408+ /**
409+ * @BATADV_TP_REASON_CANT_SEND: failed to send via outgoing interface
410+ */
204411 BATADV_TP_REASON_CANT_SEND = 132,
412+
413+ /**
414+ * @BATADV_TP_REASON_TOO_MANY: too many ongoing sessions
415+ */
205416 BATADV_TP_REASON_TOO_MANY = 133,
206417 };
207418