rendered all-in-a-tumble.[ch]

Below you find the rendered reST markup, generated from kernel-doc comments of the example files all-in-a-tumble.h and all-in-a-tumble.c. This content will be produced by the kernel-doc parser and inserted in the document by using the following directives:

.. kernel-doc::  ./all-in-a-tumble.c
   :module: example

.. kernel-doc::  ./all-in-a-tumble.h
   :module: example

The option :module: is optional, to find out why we use this option here, see kernel-doc options.


all-in-a-tumble.h

About Examples

The files source all-in-a-tumble.c and source all-in-a-tumble.h are including all examples of the LinuxDoc HowTo documentation. These files are also used as a test of the kernel-doc parser, to see how kernel-doc content will be rendered and where the parser might fail.

And … The content itself is nonsense / don’t look to close ;-)

trace_block_touch_buffer

void trace_block_touch_buffer(struct buffer_head *bh)

mark a buffer accessed

Parameters
  • bh (struct buffer_head *) – buffer_head being touched

Description

Called from touch_buffer().

trace_block_dirty_buffer

void trace_block_dirty_buffer(struct buffer_head *bh)

mark a buffer dirty

Parameters
  • bh (struct buffer_head *) – buffer_head being dirtied

Description

Called from mark_buffer_dirty().

Theory of Operation

The whizbang foobar is a dilly of a gizmo. It can do whatever you want it to do, at any time. It reads your mind. Here’s how it works.

foo bar splat

The only drawback to this gizmo is that it can sometimes damage hardware, software, or its subject(s).

multiple DOC sections

It’s not recommended to place more than one “DOC:” section in the same comment block. To insert a new “DOC:” section, create a new comment block and to create a sub-section use the reST markup for headings, see documentation of function rst_mode()

lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

struct my_struct

struct my_struct

a struct with nested unions and structs

Definition

struct my_struct {
    union {
        struct {
            char arg1 : 1;
            char arg2 : 3;
        } ;
        struct {
            int arg1b;
            int arg2b;
        } ;
        struct {
            void *arg3;
            int arg4;
            int (*f1)(char foo, int bar);
        } ;
    } ;
    union {
        struct {
            int arg1;
            int arg2;
        } st1;
        struct {
            void *arg1;
            int arg2;
            int (*f2)(char foo, int bar);
        } st2, st3;
        int (*f3)(char foo, int bar);
    } bar;
    enum {
        FOO,
        BAR,
    } undoc_public;
}

Members

{unnamed_union}

anonymous

{unnamed_struct}

anonymous

arg1

first argument of anonymous union/anonymous struct

arg2

second argument of anonymous union/anonymous struct

{unnamed_struct}

anonymous

arg1b

first argument of anonymous union/anonymous struct

arg2b

second argument of anonymous union/anonymous struct

{unnamed_struct}

anonymous

arg3

third argument of anonymous union/anonymous struct

arg4

fourth argument of anonymous union/anonymous struct

f1

nested function on anonimous union/struct

bar

non-anonymous union

bar.st1

struct st1 inside bar

bar.st1.arg1

first argument of struct st1 on union bar

bar.st1.arg2

second argument of struct st1 on union bar

bar.st2

struct st2 inside bar

bar.st2.arg1

first argument of struct st2 on union bar

bar.st2.arg2

second argument of struct st2 on union bar

bar.st3

struct st3 inside bar

bar.st3.arg2

second argument of struct st3 on union bar

bar.st2.f2

nested function on named union/struct

undoc_public

undescribed

struct my_long_struct

struct my_long_struct

short description with my_struct->a and my_struct->b

Definition

struct my_long_struct {
    int foo;
    int bar;
    int baz;
    union {
        int foobar;
    } ;
    struct {
        int barbar;
    } bar2;
}

Members

foo

The Foo member.

bar

The Bar member.

baz

The Baz member. Here, the member description may contain several paragraphs.

{unnamed_union}

anonymous

foobar

Single line description.

bar2

Description for struct bar2 inside my_long_struct

bar2.barbar

Description for barbar inside my_long_struct.bar2

Description

Longer description

union my_union

union my_union

short description

Definition

union my_union {
    int a;
    int b;
}

Members

a

first member

b

second member

Description

Longer description

enum my_enum

enum my_enum

log level

Definition

enum my_enum {
    QUIET,
    INFO,
    WARN,
    DEBUG
};

Constants

QUIET

logs nothing

INFO

logs info messages

WARN

logs warn and info messages

DEBUG

logs debug, warn and info messages

typedef my_typedef

type my_typedef

useless typdef of int

rst_mode

int rst_mode(int a, char *b)

dummy to demonstrate reST & kernel-doc markup in comments

Parameters
  • a (int) – first argument

  • b (char *) – second argument Context: in_gizmo_mode().

Description

Long description. This function has two integer arguments. The first is parameter_a and the second is parameter_b.

As long as the reST / sphinx-doc toolchain uses intersphinx you can refer definitions outside like struct media_device. If the description of media_device struct is found in any of the intersphinx locations, a hyperref to this target is generated a build time.

Example

int main() {
  printf("Hello World\n");
  return 0;
}

Return

Sum of parameter_a and the second is parameter_b.

highlighting

The highlight pattern, are non regular reST markups. They are only available within kernel-doc comments, helping C developers to write short and compact documentation.

The kernel-doc parser translates the pattern above to the corresponding reST markups. You don’t have to use the highlight pattern, if you prefer pure reST, use the reST markup.

Since the prefixes $..., &... and @... are used to markup the highlight pattern, you have to escape them in other uses: $lorem, &lorem, %lorem and @lorem. To esacpe from function highlighting, use lorem().

Parser Mode

This is an example with activated reST additions, in this section you will find some common inline markups.

Within the reST mode the kernel-doc parser pass through all markups to the reST toolchain, except the vintage highlighting but including any whitespace. With this, the full reST markup is available in the comments.

This is a link to the Linux kernel source tree.

This description is only to show some reST inline markups like emphasise and emphasis strong. The following is a demo of a reST list markup:

Definition list

def1

lorem

def2

ipsum

Ordered List

  • item one

  • item two

  • item three with a linebreak

Literal blocks

The next example shows a literal block:

+------+          +------+
|\     |\        /|     /|
| +----+-+      +-+----+ |
| |    | |      | |    | |
+-+----+ |      | +----+-+
 \|     \|      |/     |/
  +------+      +------+
   foo()         bar()

Highlighted code blocks

The next example shows a code block, with highlighting C syntax in the output.

// Hello World program
#include<stdio.h>
int main()
{
   printf("Hello World");
}

reST sectioning

colon markup: sectioning by colon markup in reST mode is less ugly. ;-)

A kernel-doc section like this section is translated into a reST subsection. This means, you can only use the following sub-levels within a kernel-doc section.

a subsubsection

lorem ipsum

a paragraph

lorem ipsum

vintage

int vintage(int parameter_a, char parameter_b)

short description of this function

Parameters
  • parameter_a (int) – first argument

  • parameter_b (char) – second argument

Context

in_gizmo_mode().

Description

This is a test of a typical markup from *vintage* kernel-doc. Don’t look to close here, it is only for testing some kernel-doc parser stuff.

Long description. This function has two integer arguments. The first is parameter_a and the second is parameter_b.

Example

user_function(22);

Return

Sum of parameter_a and parameter_b.

highlighting

  • vintage() : function

  • parameter_a : name of a parameter

  • $ENVVAR : environmental variable

  • struct my_struct : name of a structure (up to two words including ``struct``)

  • CONST : name of a constant.

Parser Mode

*vintage* kernel-doc mode

Within the *vintage kernel-doc mode* ignores any whitespace or inline markup.

  • Inline markup like *emphasis* or **emphasis strong**

  • Literals and/or block indent:

a + b

In kernel-doc *vintage* mode, there are no special block or inline markups available. Markups like the one above result in ambiguous reST markup which could produce error messages in the subsequently sphinx-build process. Unexpected outputs are mostly the result.

This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/ to the Linux kernel source tree

colon markup

sectioning by colon markup in vintage mode is partial ugly. ;-)

struct nfp_flower_priv

struct nfp_flower_priv

Flower APP per-vNIC priv data

Definition

struct nfp_flower_priv {
    struct nfp_net *nn;
    u32 mask_id_seed;
    u64 flower_version;
    struct nfp_fl_mask_id mask_ids;
    DECLARE_HASHTABLE(mask_table, NFP_FLOWER_MASK_HASH_BITS);
    DECLARE_HASHTABLE(flow_table, NFP_FLOWER_HASH_BITS);
}

Members

nn

Pointer to vNIC

mask_id_seed

Seed used for mask hash table

flower_version

HW version of flower

mask_ids

List of free mask ids

mask_table

Hash table used to store masks

flow_table

Hash table used to store flower rules

enum foo

enum foo

foo

Definition

enum foo {
    F1,
    F2
};

Constants

F1

f1

F2

f2

struct something

struct something

Lorem ipsum dolor sit amet.

Definition

struct something {
    struct foo foofoo;
    struct bar barbar;
}

Members

foofoo

lorem

barbar

ipsum

struct lineevent_state

struct lineevent_state

contains the state of a userspace event

Definition

struct lineevent_state {
    struct gpio_device *gdev;
    const char *label;
    struct gpio_desc *desc;
    u32 eflags;
    int irq;
    wait_queue_head_t wait;
    DECLARE_KFIFO(events, struct gpioevent_data, 16);
    DECLARE_KFIFO_PTR(foobar, struct lirc_scancode);
    struct mutex read_lock;
}

Members

gdev

the GPIO device the event pertains to

label

consumer label used to tag descriptors

desc

the GPIO descriptor held by this event

eflags

the event flags this line was requested with

irq

the interrupt that trigger in response to events on this GPIO

wait

wait queue that handles blocking reads of events

events

KFIFO for the GPIO events (testing DECLARE_KFIFO)

foobar

testing DECLARE_KFIFO_PTR

read_lock

mutex lock to protect reads from colliding with adding new events to the FIFO

genpool_algo_t

unsigned long genpool_algo_t(unsigned long *map, unsigned long size, unsigned long start, unsigned int nr, void *data, struct gen_pool *pool, unsigned long start_addr)

Allocation callback function type definition

Parameters
  • map (unsigned long *) – Pointer to bitmap

  • size (unsigned long) – The bitmap size in bits

  • start (unsigned long) – The bitnumber to start searching at

  • nr (unsigned int) – The number of zeroed bits we’re looking for

  • data (void *) – optional additional data used by the callback

  • pool (struct gen_pool *) – the pool being allocated from

  • start_addr (unsigned long) – undescribed

v4l2_check_dv_timings_fnc

bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle)

timings check callback

Parameters
  • t (const struct v4l2_dv_timings *) – the v4l2_dv_timings struct.

  • handle (void *) – a handle from the driver.

Description

Returns true if the given timings are valid.


all-in-a-tumble.c

user_function

int user_function(int a, ...)

function that can only be called in user context

Parameters
  • a (int) – some argument

  • ellipsis (ellipsis) – ellipsis operator

Description

This function makes no sense, it’s only a kernel-doc demonstration.

Example

x = user_function(22);

Return

Returns first argument

user_sum

API_EXPORTED int user_sum(int a, int b)

another function that can only be called in user context

Parameters
  • a (int) – first argument

  • b (int) – second argument

Description

This function makes no sense, it’s only a kernel-doc demonstration.

Example

x = user_sum(1, 2);

Return

Returns the sum of the a and b

internal_function

int internal_function(void)

the answer

Parameters
  • void – no arguments

Context

!sanity()

Return

The answer to the ultimate question of life, the universe and everything.

sys_tgkill

long sys_tgkill(pid_t tgid, pid_t pid, int sig)

send signal to one specific thread

Parameters
  • tgid (pid_t) – the thread group ID of the thread

  • pid (pid_t) – the PID of the thread

  • sig (int) – signal to be sent

Description

This syscall also checks the tgid and returns -ESRCH even if the PID exists but it’s not belonging to the target process anymore. This method solves the problem of threads exiting and PIDs getting reused.

enum rarely_enum

enum rarely_enum

enum to test parsing rarely code styles

Definition

enum rarely_enum {
    F1,
    F2
};

Constants

F1

f1

F2

f2

struct rarely_struct

struct rarely_struct

struct to test parsing rarely code styles

Definition

struct rarely_struct {
    struct foo foofoo;
    struct bar barbar;
}

Members

foofoo

lorem

barbar

ipsum