source of all-in-a-tumble.[ch]¶
Below you find the source code from the example files
Within these source files here you see some:
/* parse-SNIP: ... */
aka Snippets, which we will use in section: kernel-doc Test.
source all-in-a-tumble.h¶
1/* parse-markup: reST */
2
3/**
4 * DOC: About Examples
5 *
6 * The files :ref:`all-in-a-tumble.c-src` and :ref:`all-in-a-tumble.h-src` are
7 * including all examples of the :ref:`linuxdoc-howto` documentation. These
8 * files are also used as a test of the kernel-doc parser, to see how kernel-doc
9 * content will be rendered and where the parser might fail.
10 *
11 * And ... The content itself is nonsense / don’t look to close ;-)
12 */
13
14// testing:
15//
16// .. kernel-doc:: ./all-in-a-tumble.c
17// :export: ./all-in-a-tumble.h
18
19/* parse-SNIP: EXPORT_SYMBOL */
20EXPORT_SYMBOL(user_function)
21
22int user_function(int a, ...)
23/* parse-SNAP: */
24
25/* parse-SNIP: user_sum-h */
26int user_sum(int a, int b);
27/* parse-SNAP: */
28
29/* parse-SNIP: function pointer argument */
30/**
31 * callback() - Callback function with a function pointer argument
32 * @fct_ptr: Function to call.
33 *
34 */
35void callback(void (*fct_ptr)(void *));
36/* parse-SNAP: */
37
38/**
39 * block_touch_buffer - mark a buffer accessed
40 * @bh: buffer_head being touched
41 *
42 * Called from touch_buffer().
43 */
44DEFINE_EVENT(block_buffer, block_touch_buffer,
45
46 TP_PROTO(struct buffer_head *bh),
47
48 TP_ARGS(bh)
49);
50
51/**
52 * block_dirty_buffer - mark a buffer dirty
53 * @bh: buffer_head being dirtied
54 *
55 * Called from mark_buffer_dirty().
56 */
57DEFINE_EVENT(block_buffer, block_dirty_buffer,
58
59 TP_PROTO(struct buffer_head *bh),
60
61 TP_ARGS(bh)
62);
63
64// The parse-SNIP/SNAP comments are used to include the C sorce code as snippets
65// into a reST document. These are the examples of the kernel-doc-HOWTO book.
66
67/* parse-SNIP: theory-of-operation */
68/**
69 * DOC: Theory of Operation
70 *
71 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
72 * want it to do, at any time. It reads your mind. Here's how it works.
73 *
74 * foo bar splat
75 * -------------
76 *
77 * The only drawback to this gizmo is that it can sometimes damage hardware,
78 * software, or its subject(s).
79 *
80 * DOC: multiple DOC sections
81 *
82 * It's not recommended to place more than one "DOC:" section in the same
83 * comment block. To insert a new "DOC:" section, create a new comment block and
84 * to create a sub-section use the reST markup for headings, see documentation
85 * of function rst_mode()
86 */
87/* parse-SNAP: */
88
89/* parse-SNIP: lorem */
90/**
91 * DOC: lorem ipsum
92 *
93 * Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor
94 * incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
95 * nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi
96 * consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore
97 * eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident,
98 * sunt in culpa qui officia deserunt mollit anim id est laborum.
99 */
100/* parse-SNAP: */
101
102
103/* parse-SNIP: my_struct */
104/**
105* struct my_struct - a struct with nested unions and structs
106* @arg1: first argument of anonymous union/anonymous struct
107* lorem ipsum ...
108* @arg2: second argument of anonymous union/anonymous struct
109* @arg1b: first argument of anonymous union/anonymous struct
110* @arg2b: second argument of anonymous union/anonymous struct
111* @arg3: third argument of anonymous union/anonymous struct
112* @arg4: fourth argument of anonymous union/anonymous struct
113* @bar: non-anonymous union
114* @bar.st1: struct st1 inside @bar
115* @bar.st1.arg1: first argument of struct st1 on union bar
116* @bar.st1.arg2: second argument of struct st1 on union bar
117* @bar.st2: struct st2 inside @bar
118* @bar.st2.arg1: first argument of struct st2 on union bar
119* @bar.st2.arg2: second argument of struct st2 on union bar
120* @bar.st3: struct st3 inside @bar
121* @bar.st3.arg2: second argument of struct st3 on union bar
122* @f1: nested function on anonimous union/struct
123* @bar.st2.f2: nested function on named union/struct
124*/
125struct my_struct {
126 /* Anonymous union/struct*/
127 union {
128 struct {
129 char arg1 : 1;
130 char arg2 : 3;
131 };
132 struct {
133 int arg1b;
134 int arg2b;
135 };
136 struct {
137 void *arg3;
138 int arg4;
139 int (*f1)(char foo, int bar);
140 };
141 };
142 union {
143 struct {
144 int arg1;
145 int arg2;
146 } st1;
147 struct {
148 void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
149 int arg2;
150 int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
151 } st2, st3;
152 int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
153 } bar; /* bar is undocumented, cause a warning */
154
155 /* private: */
156 int undoc_privat; /* is undocumented but private, no warning */
157
158 /* public: */
159 enum {
160 FOO,
161 BAR,
162 } undoc_public; /* is undocumented, cause a warning */
163
164};
165/* parse-SNAP: */
166
167/* parse-SNIP: my_long_struct */
168/**
169 * struct my_long_struct - short description with &my_struct->a and &my_struct->b
170 * @foo: The Foo member.
171 *
172 * Longer description
173 */
174struct my_long_struct {
175 int foo;
176 /**
177 * @bar: The Bar member,
178 * lorem ipsum ..
179 */
180 int bar;
181 /**
182 * @baz: The Baz member,
183 * lorem ipsum ..
184 *
185 * Here, the member description may contain several paragraphs.
186 */
187 int baz;
188 union {
189 /** @foobar: Single line description. */
190 int foobar;
191 };
192 /** @bar2: Description for struct @bar2 inside @my_long_struct */
193 struct {
194 /**
195 * @bar2.barbar: Description for @barbar inside @my_long_struct.bar2
196 */
197 int barbar;
198 } bar2;
199};
200/* parse-SNAP: */
201
202
203/* parse-SNIP: my_union */
204/**
205 * union my_union - short description
206 * @a: first member
207 * @b: second member
208 *
209 * Longer description
210 */
211union my_union {
212 int a;
213 int b;
214};
215/* parse-SNAP: */
216
217
218/* parse-SNIP: my_enum */
219/**
220 * enum my_enum - log level
221 * @QUIET: logs nothing
222 * @INFO: logs info messages
223 * @WARN: logs warn and info messages
224 * @DEBUG: logs debug, warn and info messages
225 */
226
227enum my_enum {
228 QUIET,
229 INFO,
230 WARN,
231 DEBUG
232};
233/* parse-SNAP: */
234
235
236/* parse-SNIP: my_typedef */
237/**
238 * typedef my_typedef - useless typdef of int
239 *
240 */
241typedef int my_typedef;
242/* parse-SNAP: */
243
244
245/* parse-SNIP: rst_mode */
246/**
247 * rst_mode - dummy to demonstrate reST & kernel-doc markup in comments
248 * @a: first argument
249 * @b: second argument
250 * Context: :c:func:`in_gizmo_mode`.
251 *
252 * Long description. This function has two integer arguments. The first is
253 * ``parameter_a`` and the second is ``parameter_b``.
254 *
255 * As long as the reST / sphinx-doc toolchain uses `intersphinx
256 * <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer
257 * definitions *outside* like :c:type:`struct media_device <media_device>`. If
258 * the description of ``media_device`` struct is found in any of the intersphinx
259 * locations, a hyperref to this target is generated a build time.
260 *
261 * Example:
262 * int main() {
263 * printf("Hello World\n");
264 * return 0;
265 * }
266 *
267 * Return: Sum of ``parameter_a`` and the second is ``parameter_b``.
268 *
269 * highlighting:
270 * The highlight pattern, are non regular reST markups. They are only available
271 * within kernel-doc comments, helping C developers to write short and compact
272 * documentation.
273 *
274 * - user_function() : function
275 * - @a : name of a parameter
276 * - &struct my_struct : name of a structure (including the word struct)
277 * - &union my_union : name of a union
278 * - &my_struct->a or &my_struct.b - member of a struct or union.
279 * - &enum my_enum : name of a enum
280 * - &typedef my_typedef : name of a typedef
281 * - %CONST : name of a constant.
282 * - $ENVVAR : environmental variable
283 *
284 * The kernel-doc parser translates the pattern above to the corresponding reST
285 * markups. You don't have to use the *highlight* pattern, if you prefer *pure*
286 * reST, use the reST markup.
287 *
288 * - :c:func:`user_function` : function
289 * - ``a`` : name of a parameter
290 * - :c:type:`struct my_struct <my_struct>` : name of a structure (including the word struct)
291 * - :c:type:`union my_union <my_union>` : name of a union
292 * - :c:type:`my_struct->a <my_struct>` or :c:type:`my_struct.b <my_struct>` - member of a struct or union.
293 * - :c:type:`enum my_enum <my_enum>` : name of a enum
294 * - :c:type:`typedef my_typedef <my_typedef>` : name of a typedef
295 * - ``CONST`` : name of a constant.
296 * - ``\$ENVVAR`` : environmental variable
297 *
298 * Since the prefixes ``$...``, ``&...`` and ``@...`` are used to markup the
299 * highlight pattern, you have to escape them in other uses: \$lorem, \&lorem,
300 * \%lorem and \@lorem. To esacpe from function highlighting, use lorem\().
301 *
302 * Parser Mode:
303 * This is an example with activated reST additions, in this section you will
304 * find some common inline markups.
305 *
306 * Within the *reST mode* the kernel-doc parser pass through all markups to the
307 * reST toolchain, except the *vintage highlighting* but including any
308 * whitespace. With this, the full reST markup is available in the comments.
309 *
310 * This is a link to the `Linux kernel source tree
311 * <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_.
312 *
313 * This description is only to show some reST inline markups like *emphasise*
314 * and **emphasis strong**. The following is a demo of a reST list markup:
315 *
316 * Definition list:
317 * :def1: lorem
318 * :def2: ipsum
319 *
320 * Ordered List:
321 * - item one
322 * - item two
323 * - item three with
324 * a linebreak
325 *
326 * Literal blocks:
327 * The next example shows a literal block::
328 *
329 * +------+ +------+
330 * |\ |\ /| /|
331 * | +----+-+ +-+----+ |
332 * | | | | | | | |
333 * +-+----+ | | +----+-+
334 * \| \| |/ |/
335 * +------+ +------+
336 * foo() bar()
337 *
338 * Highlighted code blocks:
339 * The next example shows a code block, with highlighting C syntax in the
340 * output.
341 *
342 * .. code-block:: c
343 *
344 * // Hello World program
345 * #include<stdio.h>
346 * int main()
347 * {
348 * printf("Hello World");
349 * }
350 *
351 *
352 * reST sectioning:
353 *
354 * colon markup: sectioning by colon markup in reST mode is less ugly. ;-)
355 *
356 * A kernel-doc section like *this* section is translated into a reST
357 * *subsection*. This means, you can only use the following *sub-levels* within a
358 * kernel-doc section.
359 *
360 * a subsubsection
361 * ^^^^^^^^^^^^^^^
362 *
363 * lorem ipsum
364 *
365 * a paragraph
366 * """""""""""
367 *
368 * lorem ipsum
369 *
370 */
371int rst_mode(int a, char *b)
372{
373 return a + b;
374}
375/* parse-SNAP: */
376
377
378/* parse-markup: kernel-doc */
379
380/**
381 * vintage - short description of this function
382 * @parameter_a: first argument
383 * @parameter_b: second argument
384 * Context: in_gizmo_mode().
385 *
386 * This is a test of a typical markup from *vintage* kernel-doc. Don't look to
387 * close here, it is only for testing some kernel-doc parser stuff.
388 *
389 * Long description. This function has two integer arguments. The first is
390 * @parameter_a and the second is @parameter_b.
391 *
392 * Example: user_function(22);
393 *
394 * Return: Sum of @parameter_a and @parameter_b.
395 *
396 * highlighting:
397 *
398 * - vintage() : function
399 * - @parameter_a : name of a parameter
400 * - $ENVVAR : environmental variable
401 * - &my_struct : name of a structure (up to two words including ``struct``)
402 * - %CONST : name of a constant.
403 *
404 * Parser Mode: *vintage* kernel-doc mode
405 *
406 * Within the *vintage kernel-doc mode* ignores any whitespace or inline
407 * markup.
408 *
409 * - Inline markup like *emphasis* or **emphasis strong**
410 * - Literals and/or block indent:
411 *
412 * a + b
413 *
414 * In kernel-doc *vintage* mode, there are no special block or inline markups
415 * available. Markups like the one above result in ambiguous reST markup which
416 * could produce error messages in the subsequently sphinx-build
417 * process. Unexpected outputs are mostly the result.
418 *
419 * This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/
420 * to the Linux kernel source tree
421 *
422 * colon markup: sectioning by colon markup in vintage mode is partial ugly. ;-)
423 *
424 */
425int vintage(int parameter_a, char parameter_b)
426{
427 return a + b;
428}
429
430/* some C&P for extended tests
431 */
432
433/**
434* struct nfp_flower_priv - Flower APP per-vNIC priv data
435* @nn: Pointer to vNIC
436* @mask_id_seed: Seed used for mask hash table
437* @flower_version: HW version of flower
438* @mask_ids: List of free mask ids
439* @mask_table: Hash table used to store masks
440* @flow_table: Hash table used to store flower rules
441*/
442struct nfp_flower_priv {
443 struct nfp_net *nn;
444 u32 mask_id_seed;
445 u64 flower_version;
446 struct nfp_fl_mask_id mask_ids;
447 DECLARE_HASHTABLE(mask_table, NFP_FLOWER_MASK_HASH_BITS);
448 DECLARE_HASHTABLE(flow_table, NFP_FLOWER_HASH_BITS);
449};
450
451/**
452 * enum foo - foo
453 * @F1: f1
454 * @F2: f2
455 */
456enum foo {
457 F1,
458
459 F2,
460};
461
462
463/**
464* struct something - Lorem ipsum dolor sit amet.
465* @foofoo: lorem
466* @barbar: ipsum
467*/
468
469struct something {
470 struct foo
471
472 foofoo;
473
474 struct bar
475
476 barbar;
477};
478
479/**
480 * struct lineevent_state - contains the state of a userspace event
481 * @gdev: the GPIO device the event pertains to
482 * @label: consumer label used to tag descriptors
483 * @desc: the GPIO descriptor held by this event
484 * @eflags: the event flags this line was requested with
485 * @irq: the interrupt that trigger in response to events on this GPIO
486 * @wait: wait queue that handles blocking reads of events
487 * @events: KFIFO for the GPIO events (testing DECLARE_KFIFO)
488 * @foobar: testing DECLARE_KFIFO_PTR
489 * @read_lock: mutex lock to protect reads from colliding with adding
490 * new events to the FIFO
491 */
492struct lineevent_state {
493 struct gpio_device *gdev;
494 const char *label;
495 struct gpio_desc *desc;
496 u32 eflags;
497 int irq;
498 wait_queue_head_t wait;
499 DECLARE_KFIFO(events, struct gpioevent_data, 16);
500 DECLARE_KFIFO_PTR(foobar, struct lirc_scancode);
501 struct mutex read_lock;
502};
503
504
505/**
506 * typedef genpool_algo_t: Allocation callback function type definition
507 * @map: Pointer to bitmap
508 * @size: The bitmap size in bits
509 * @start: The bitnumber to start searching at
510 * @nr: The number of zeroed bits we're looking for
511 * @data: optional additional data used by the callback
512 * @pool: the pool being allocated from
513 */
514typedef unsigned long (*genpool_algo_t)(unsigned long *map,
515 unsigned long size,
516 unsigned long start,
517 unsigned int nr,
518 void *data, struct gen_pool *pool,
519 unsigned long start_addr);
520
521/**
522 * typedef v4l2_check_dv_timings_fnc - timings check callback
523 *
524 * @t: the v4l2_dv_timings struct.
525 * @handle: a handle from the driver.
526 *
527 * Returns true if the given timings are valid.
528 */
529typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
530
531
532/* parse-SNIP: ADD_macro */
533/**
534 * macro ADD - Function like macro to add two values
535 *
536 * @first: first value
537 * @second: second value
538 *
539 * Is replaced by a addition of @first and @second.
540 */
541#define ADD(first, second) (first) + (second)
542/* parse-SNAP: */
543
544/**
545 * iosys_map_wr_field - Write to a member of a struct in the iosys_map
546 *
547 * @map__: The iosys_map structure
548 * @struct_offset__: Offset from the beggining of the map, where the struct
549 * is located
550 * @struct_type__: The struct describing the layout of the mapping
551 * @field__: Member of the struct to read
552 * @val__: Value to write
553 *
554 * Write a value to the iosys_map considering its layout is described by a C
555 * struct starting at @struct_offset__. The field offset and size is calculated
556 * and the @val__ is written. If the field access would incur in un-aligned
557 * access, then either iosys_map_memcpy_to() needs to be used or the
558 * architecture must support it. Refer to iosys_map_rd_field() for expected
559 * usage and memory layout.
560 */
561#define iosys_map_wr_field(map__, struct_offset__, struct_type__, field__, val__) ({ \
562 struct_type__ *s; \
563 iosys_map_wr(map__, struct_offset__ + offsetof(struct_type__, field__), \
564 typeof(s->field__), val__); \
565})
source all-in-a-tumble.c¶
1// this test some kernel-doc stuff
2
3/* parse-SNIP: hello-world */
4#include<stdio.h>
5int main() {
6 printf("Hello World\n");
7 return 0;
8}
9/* parse-SNAP: */
10
11/* parse-SNIP: user_function */
12/**
13 * user_function() - function that can only be called in user context
14 * @a: some argument
15 * @...: ellipsis operator
16 *
17 * This function makes no sense, it's only a kernel-doc demonstration.
18 *
19 * Example:
20 * x = user_function(22);
21 *
22 * Return:
23 * Returns first argument
24 */
25int
26user_function(int a, ...)
27{
28 return a;
29}
30/* parse-SNAP: */
31
32
33/* parse-SNIP: user_sum-c */
34/**
35 * user_sum() - another function that can only be called in user context
36 * @a: first argument
37 * @b: second argument
38 *
39 * This function makes no sense, it's only a kernel-doc demonstration.
40 *
41 * Example:
42 * x = user_sum(1, 2);
43 *
44 * Return:
45 * Returns the sum of the @a and @b
46 */
47API_EXPORTED
48int user_sum(int a, int b)
49{
50 return a + b;
51}
52/* parse-SNAP: */
53
54
55/* parse-SNIP: test_SYSCALL */
56/**
57 * sys_tgkill - send signal to one specific thread
58 * @tgid: the thread group ID of the thread
59 * @pid: the PID of the thread
60 * @sig: signal to be sent
61 *
62 * This syscall also checks the @tgid and returns -ESRCH even if the PID
63 * exists but it's not belonging to the target process anymore. This
64 * method solves the problem of threads exiting and PIDs getting reused.
65 */
66SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
67{
68 ...
69}
70
71/* parse-SNAP: */
72
73/* parse-SNIP: rarely_code_styles*/
74/**
75* enum rarely_enum - enum to test parsing rarely code styles
76* @F1: f1
77* @F2: f2
78*/
79enum rarely_enum {
80 F1,
81
82 F2,
83};
84
85
86/**
87* struct rarely_struct - struct to test parsing rarely code styles
88* @foofoo: lorem
89* @barbar: ipsum
90*/
91
92struct rarely_struct {
93 struct foo
94
95 foofoo;
96
97 struct bar
98
99 barbar;
100};
101
102/* parse-SNIP: xxxx */
103
104
