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_GPL_FUTURE(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
30/**
31 * block_touch_buffer - mark a buffer accessed
32 * @bh: buffer_head being touched
33 *
34 * Called from touch_buffer().
35 */
36DEFINE_EVENT(block_buffer, block_touch_buffer,
37
38 TP_PROTO(struct buffer_head *bh),
39
40 TP_ARGS(bh)
41);
42
43/**
44 * block_dirty_buffer - mark a buffer dirty
45 * @bh: buffer_head being dirtied
46 *
47 * Called from mark_buffer_dirty().
48 */
49DEFINE_EVENT(block_buffer, block_dirty_buffer,
50
51 TP_PROTO(struct buffer_head *bh),
52
53 TP_ARGS(bh)
54);
55
56// The parse-SNIP/SNAP comments are used to include the C sorce code as snippets
57// into a reST document. These are the examples of the kernel-doc-HOWTO book.
58
59/* parse-SNIP: theory-of-operation */
60/**
61 * DOC: Theory of Operation
62 *
63 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
64 * want it to do, at any time. It reads your mind. Here's how it works.
65 *
66 * foo bar splat
67 * -------------
68 *
69 * The only drawback to this gizmo is that it can sometimes damage hardware,
70 * software, or its subject(s).
71 *
72 * DOC: multiple DOC sections
73 *
74 * It's not recommended to place more than one "DOC:" section in the same
75 * comment block. To insert a new "DOC:" section, create a new comment block and
76 * to create a sub-section use the reST markup for headings, see documentation
77 * of function rst_mode()
78 */
79/* parse-SNAP: */
80
81/* parse-SNIP: lorem */
82/**
83 * DOC: lorem ipsum
84 *
85 * Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor
86 * incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
87 * nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi
88 * consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore
89 * eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident,
90 * sunt in culpa qui officia deserunt mollit anim id est laborum.
91 */
92/* parse-SNAP: */
93
94
95/* parse-SNIP: my_long_struct */
96/**
97 * struct my_long_struct - short description with &my_struct->a and &my_struct->b
98 * @foo: The Foo member.
99 *
100 * Longer description
101 */
102struct my_long_struct {
103 int foo;
104 /**
105 * @bar: The Bar member.
106 */
107 int bar;
108 /**
109 * @baz: The Baz member.
110 *
111 * Here, the member description may contain several paragraphs.
112 */
113 int baz;
114 union {
115 /** @foobar: Single line description. */
116 int foobar;
117 };
118 /** @bar2: Description for struct @bar2 inside @my_long_struct */
119 struct {
120 /**
121 * @bar2.barbar: Description for @barbar inside @my_long_struct.bar2
122 */
123 int barbar;
124 } bar2;
125};
126/* parse-SNAP: */
127
128
129/* parse-SNIP: my_union */
130/**
131 * union my_union - short description
132 * @a: first member
133 * @b: second member
134 *
135 * Longer description
136 */
137union my_union {
138 int a;
139 int b;
140};
141/* parse-SNAP: */
142
143
144/* parse-SNIP: my_enum */
145/**
146 * enum my_enum - log level
147 * @QUIET: logs nothing
148 * @INFO: logs info messages
149 * @WARN: logs warn and info messages
150 * @DEBUG: logs debug, warn and info messages
151 */
152
153enum my_enum {
154 QUIET,
155 INFO,
156 WARN,
157 DEBUG
158};
159/* parse-SNAP: */
160
161
162/* parse-SNIP: my_typedef */
163/**
164 * typedef my_typedef - useless typdef of int
165 *
166 */
167typedef int my_typedef;
168/* parse-SNAP: */
169
170
171/* parse-SNIP: rst_mode */
172/**
173 * rst_mode - dummy to demonstrate reST & kernel-doc markup in comments
174 * @a: first argument
175 * @b: second argument
176 * Context: :c:func:`in_gizmo_mode`.
177 *
178 * Long description. This function has two integer arguments. The first is
179 * ``parameter_a`` and the second is ``parameter_b``.
180 *
181 * As long as the reST / sphinx-doc toolchain uses `intersphinx
182 * <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer
183 * definitions *outside* like :c:type:`struct media_device <media_device>`. If
184 * the description of ``media_device`` struct is found in any of the intersphinx
185 * locations, a hyperref to this target is generated a build time.
186 *
187 * Example:
188 * int main() {
189 * printf("Hello World\n");
190 * return 0;
191 * }
192 *
193 * Return: Sum of ``parameter_a`` and the second is ``parameter_b``.
194 *
195 * highlighting:
196 * The highlight pattern, are non regular reST markups. They are only available
197 * within kernel-doc comments, helping C developers to write short and compact
198 * documentation.
199 *
200 * - user_function() : function
201 * - @a : name of a parameter
202 * - &struct my_struct : name of a structure (including the word struct)
203 * - &union my_union : name of a union
204 * - &my_struct->a or &my_struct.b - member of a struct or union.
205 * - &enum my_enum : name of a enum
206 * - &typedef my_typedef : name of a typedef
207 * - %CONST : name of a constant.
208 * - $ENVVAR : environmental variable
209 *
210 * The kernel-doc parser translates the pattern above to the corresponding reST
211 * markups. You don't have to use the *highlight* pattern, if you prefer *pure*
212 * reST, use the reST markup.
213 *
214 * - :c:func:`user_function` : function
215 * - ``a`` : name of a parameter
216 * - :c:type:`struct my_struct <my_struct>` : name of a structure (including the word struct)
217 * - :c:type:`union my_union <my_union>` : name of a union
218 * - :c:type:`my_struct->a <my_struct>` or :c:type:`my_struct.b <my_struct>` - member of a struct or union.
219 * - :c:type:`enum my_enum <my_enum>` : name of a enum
220 * - :c:type:`typedef my_typedef <my_typedef>` : name of a typedef
221 * - ``CONST`` : name of a constant.
222 * - ``\$ENVVAR`` : environmental variable
223 *
224 * Since the prefixes ``$...``, ``&...`` and ``@...`` are used to markup the
225 * highlight pattern, you have to escape them in other uses: \$lorem, \&lorem,
226 * \%lorem and \@lorem. To esacpe from function highlighting, use lorem\().
227 *
228 * Parser Mode:
229 * This is an example with activated reST additions, in this section you will
230 * find some common inline markups.
231 *
232 * Within the *reST mode* the kernel-doc parser pass through all markups to the
233 * reST toolchain, except the *vintage highlighting* but including any
234 * whitespace. With this, the full reST markup is available in the comments.
235 *
236 * This is a link to the `Linux kernel source tree
237 * <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_.
238 *
239 * This description is only to show some reST inline markups like *emphasise*
240 * and **emphasis strong**. The following is a demo of a reST list markup:
241 *
242 * Definition list:
243 * :def1: lorem
244 * :def2: ipsum
245 *
246 * Ordered List:
247 * - item one
248 * - item two
249 * - item three with
250 * a linebreak
251 *
252 * Literal blocks:
253 * The next example shows a literal block::
254 *
255 * +------+ +------+
256 * |\ |\ /| /|
257 * | +----+-+ +-+----+ |
258 * | | | | | | | |
259 * +-+----+ | | +----+-+
260 * \| \| |/ |/
261 * +------+ +------+
262 * foo() bar()
263 *
264 * Highlighted code blocks:
265 * The next example shows a code block, with highlighting C syntax in the
266 * output.
267 *
268 * .. code-block:: c
269 *
270 * // Hello World program
271 * #include<stdio.h>
272 * int main()
273 * {
274 * printf("Hello World");
275 * }
276 *
277 *
278 * reST sectioning:
279 *
280 * colon markup: sectioning by colon markup in reST mode is less ugly. ;-)
281 *
282 * A kernel-doc section like *this* section is translated into a reST
283 * *subsection*. This means, you can only use the following *sub-levels* within a
284 * kernel-doc section.
285 *
286 * a subsubsection
287 * ^^^^^^^^^^^^^^^
288 *
289 * lorem ipsum
290 *
291 * a paragraph
292 * """""""""""
293 *
294 * lorem ipsum
295 *
296 */
297int rst_mode(int a, char *b)
298{
299 return a + b;
300}
301/* parse-SNAP: */
302
303
304/* parse-markup: kernel-doc */
305
306/**
307 * vintage - short description of this function
308 * @parameter_a: first argument
309 * @parameter_b: second argument
310 * Context: in_gizmo_mode().
311 *
312 * This is a test of a typical markup from *vintage* kernel-doc. Don't look to
313 * close here, it is only for testing some kernel-doc parser stuff.
314 *
315 * Long description. This function has two integer arguments. The first is
316 * @parameter_a and the second is @parameter_b.
317 *
318 * Example: user_function(22);
319 *
320 * Return: Sum of @parameter_a and @parameter_b.
321 *
322 * highlighting:
323 *
324 * - vintage() : function
325 * - @parameter_a : name of a parameter
326 * - $ENVVAR : environmental variable
327 * - &my_struct : name of a structure (up to two words including ``struct``)
328 * - %CONST : name of a constant.
329 *
330 * Parser Mode: *vintage* kernel-doc mode
331 *
332 * Within the *vintage kernel-doc mode* ignores any whitespace or inline
333 * markup.
334 *
335 * - Inline markup like *emphasis* or **emphasis strong**
336 * - Literals and/or block indent:
337 *
338 * a + b
339 *
340 * In kernel-doc *vintage* mode, there are no special block or inline markups
341 * available. Markups like the one above result in ambiguous reST markup which
342 * could produce error messages in the subsequently sphinx-build
343 * process. Unexpected outputs are mostly the result.
344 *
345 * This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/
346 * to the Linux kernel source tree
347 *
348 * colon markup: sectioning by colon markup in vintage mode is partial ugly. ;-)
349 *
350 */
351int vintage(int parameter_a, char parameter_b)
352{
353 return a + b;
354}
355
356/* some C&P for extended tests
357 */
358
359/**
360* struct nfp_flower_priv - Flower APP per-vNIC priv data
361* @nn: Pointer to vNIC
362* @mask_id_seed: Seed used for mask hash table
363* @flower_version: HW version of flower
364* @mask_ids: List of free mask ids
365* @mask_table: Hash table used to store masks
366* @flow_table: Hash table used to store flower rules
367*/
368struct nfp_flower_priv {
369 struct nfp_net *nn;
370 u32 mask_id_seed;
371 u64 flower_version;
372 struct nfp_fl_mask_id mask_ids;
373 DECLARE_HASHTABLE(mask_table, NFP_FLOWER_MASK_HASH_BITS);
374 DECLARE_HASHTABLE(flow_table, NFP_FLOWER_HASH_BITS);
375};
376
377/**
378 * enum foo - foo
379 * @F1: f1
380 * @F2: f2
381 */
382enum foo {
383 F1,
384
385 F2,
386};
387
388
389/**
390* struct something - Lorem ipsum dolor sit amet.
391* @foofoo: lorem
392* @barbar: ipsum
393*/
394
395struct something {
396 struct foo
397
398 foofoo;
399
400 struct bar
401
402 barbar;
403};
404
405/**
406 * struct lineevent_state - contains the state of a userspace event
407 * @gdev: the GPIO device the event pertains to
408 * @label: consumer label used to tag descriptors
409 * @desc: the GPIO descriptor held by this event
410 * @eflags: the event flags this line was requested with
411 * @irq: the interrupt that trigger in response to events on this GPIO
412 * @wait: wait queue that handles blocking reads of events
413 * @events: KFIFO for the GPIO events (testing DECLARE_KFIFO)
414 * @foobar: testing DECLARE_KFIFO_PTR
415 * @read_lock: mutex lock to protect reads from colliding with adding
416 * new events to the FIFO
417 */
418struct lineevent_state {
419 struct gpio_device *gdev;
420 const char *label;
421 struct gpio_desc *desc;
422 u32 eflags;
423 int irq;
424 wait_queue_head_t wait;
425 DECLARE_KFIFO(events, struct gpioevent_data, 16);
426 DECLARE_KFIFO_PTR(foobar, struct lirc_scancode);
427 struct mutex read_lock;
428};
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/* parse-SNIP: internal_function */
55/**
56 * internal_function - the answer
57 *
58 * Context: !sanity()
59 *
60 * Return:
61 * The answer to the ultimate question of life, the universe and everything.
62 */
63int internal_function()
64{
65 return 42;
66}
67/* parse-SNAP: */
68
69/* parse-SNIP: test_SYSCALL */
70/**
71 * sys_tgkill - send signal to one specific thread
72 * @tgid: the thread group ID of the thread
73 * @pid: the PID of the thread
74 * @sig: signal to be sent
75 *
76 * Return:
77 *
78 * This syscall also checks the @tgid and returns -ESRCH even if the PID
79 * exists but it's not belonging to the target process anymore. This
80 * method solves the problem of threads exiting and PIDs getting reused.
81 */
82SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
83{
84 ...
85}
86
87/* parse-SNAP: */
88
89/* parse-SNIP: rarely_code_styles*/
90/**
91* enum rarely_enum - enum to test parsing rarely code styles
92* @F1: f1
93* @F2: f2
94*/
95enum rarely_enum {
96 F1,
97
98 F2,
99};
100
101
102/**
103* struct rarely_struct - struct to test parsing rarely code styles
104* @foofoo: lorem
105* @barbar: ipsum
106*/
107
108struct rarely_struct {
109 struct foo
110
111 foofoo;
112
113 struct bar
114
115 barbar;
116};
117
118
