kernel-doc from all-in-a-tumble.[ch]

Below you find the reST markup, generated from kernel-doc comments of the example files source all-in-a-tumble.h and source all-in-a-tumble.c. This markup 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: foo

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

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

• kernel-doc from all-in-a-tumble.h

• kernel-doc from all-in-a-tumble.c

kernel-doc from all-in-a-tumble.h

.. c:namespace-push:: foo

.. _`foo.about-examples`:

About Examples
==============

The files :ref:`all-in-a-tumble.c-src` and :ref:`all-in-a-tumble.h-src` are
including all examples of the :ref:`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 ;-)

.. _`foo.callback`:

callback
========

.. c:function:: void callback(void (*fct_ptr)(void *))

    Callback function with a function pointer argument

    :param fct\_ptr:
        Function to call.
    :type fct\_ptr: void (\*)(void \*)

.. _`foo.trace_block_touch_buffer`:

trace_block_touch_buffer
========================

.. c:function:: void trace_block_touch_buffer(struct buffer_head *bh)

    mark a buffer accessed

    :param bh:
        buffer_head being touched
    :type bh: struct buffer\_head \*

.. _`foo.trace_block_touch_buffer.description`:

Description
-----------

Called from \ :c:func:`touch_buffer`\ .

.. _`foo.trace_block_dirty_buffer`:

trace_block_dirty_buffer
========================

.. c:function:: void trace_block_dirty_buffer(struct buffer_head *bh)

    mark a buffer dirty

    :param bh:
        buffer_head being dirtied
    :type bh: struct buffer\_head \*

.. _`foo.trace_block_dirty_buffer.description`:

Description
-----------

Called from \ :c:func:`mark_buffer_dirty`\ .

.. _`foo.theory-of-operation`:

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).

.. _`foo.multiple-doc-sections`:

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 \ :c:func:`rst_mode`\ 

.. _`foo.lorem-ipsum`:

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.

.. _`foo.my_struct`:

struct my_struct
================

.. c:struct:: my_struct

    a struct with nested unions and structs

.. _`foo.my_struct.definition`:

Definition
----------

.. code-block:: c

    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;
    }

.. _`foo.my_struct.members`:

Members
-------

{unnamed_union}
    anonymous

{unnamed_struct}
    anonymous

arg1
    first argument of anonymous union/anonymous struct
    lorem ipsum ...

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*

.. _`foo.my_long_struct`:

struct my_long_struct
=====================

.. c:struct:: my_long_struct

    short description with \ :c:type:`my_struct->a <my_struct>`\  and \ :c:type:`my_struct->b <my_struct>`\ 

.. _`foo.my_long_struct.definition`:

Definition
----------

.. code-block:: c

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

.. _`foo.my_long_struct.members`:

Members
-------

foo
    The Foo member.

bar
    The Bar member,
    lorem ipsum ..

baz
    The Baz member,
    lorem ipsum ..

    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``\ 

.. _`foo.my_long_struct.description`:

Description
-----------

Longer description

.. _`foo.my_union`:

union my_union
==============

.. c:union:: my_union

    short description

.. _`foo.my_union.definition`:

Definition
----------

.. code-block:: c

    union my_union {
        int a;
        int b;
    }

.. _`foo.my_union.members`:

Members
-------

a
    first member

b
    second member

.. _`foo.my_union.description`:

Description
-----------

Longer description

.. _`foo.my_enum`:

enum my_enum
============

.. c:enum:: my_enum

    log level

.. _`foo.my_enum.definition`:

Definition
----------

.. code-block:: c

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

.. _`foo.my_enum.constants`:

Constants
---------

QUIET
    logs nothing

INFO
    logs info messages

WARN
    logs warn and info messages

DEBUG
    logs debug, warn and info messages

.. _`foo.my_typedef`:

typedef my_typedef
==================

.. c:type:: my_typedef

    useless typdef of int

.. _`foo.rst_mode`:

rst_mode
========

.. c:function:: int rst_mode(int a, char *b)

    dummy to demonstrate reST & kernel-doc markup in comments

    :param a:
        first argument
    :type a: int

    :param b:
        second argument
        Context: :c:func:`in_gizmo_mode`.
    :type b: char \*

.. _`foo.rst_mode.description`:

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
<http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer
definitions *outside* like :c:type:`struct media_device <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.

.. _`foo.rst_mode.example`:

Example
-------

.. code-block:: c

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


.. _`foo.rst_mode.return`:

Return
------

Sum of ``parameter_a`` and the second is ``parameter_b``.

.. _`foo.rst_mode.highlighting`:

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.

- \ :c:func:`user_function`\  : function
- \ ``a``\  : name of a parameter
- \ :c:type:`struct my_struct <my_struct>`\  : name of a structure (including the word struct)
- \ :c:type:`union my_union <my_union>`\  : name of a union
- \ :c:type:`my_struct->a <my_struct>`\  or \ :c:type:`my_struct.b <my_struct>`\  -  member of a struct or union.
- \ :c:type:`enum my_enum <my_enum>`\  : name of a enum
- \ :c:type:`typedef my_typedef <my_typedef>`\  : name of a typedef
- \ ``CONST``\  : name of a constant.
- \ ``$ENVVAR``\  : environmental variable

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.

- :c:func:`user_function` : function
- ``a`` : name of a parameter
- :c:type:`struct my_struct <my_struct>` : name of a structure (including the word struct)
- :c:type:`union my_union <my_union>` : name of a union
- :c:type:`my_struct->a <my_struct>` or :c:type:`my_struct.b <my_struct>` -  member of a struct or union.
- :c:type:`enum my_enum <my_enum>` : name of a enum
- :c:type:`typedef my_typedef <my_typedef>` : name of a typedef
- ``CONST`` : name of a constant.
- ``$ENVVAR`` : environmental variable

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().

.. _`foo.rst_mode.parser-mode`:

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
<https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_.

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:

.. _`foo.rst_mode.definition-list`:

Definition list
---------------

:def1: lorem
:def2: ipsum

.. _`foo.rst_mode.ordered-list`:

Ordered List
------------

- item one
- item two
- item three with
  a linebreak

.. _`foo.rst_mode.literal-blocks`:

Literal blocks
--------------

The next example shows a literal block::

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

.. _`foo.rst_mode.highlighted-code-blocks`:

Highlighted code blocks
-----------------------

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

.. code-block:: c

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

.. _`foo.rst_mode.rest-sectioning`:

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

.. _`foo.vintage`:

vintage
=======

.. c:function:: int vintage(int parameter_a, char parameter_b)

    short description of this function

    :param parameter\_a:
        first argument
    :type parameter\_a: int

    :param parameter\_b:
        second argument
    :type parameter\_b: char

.. _`foo.vintage.context`:

Context
-------

\ :c:func:`in_gizmo_mode`\ .

.. _`foo.vintage.description`:

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``\ .

.. _`foo.vintage.example`:

Example
-------

.. code-block:: c

    user_function(22);


.. _`foo.vintage.return`:

Return
------

Sum of \ ``parameter_a``\  and \ ``parameter_b``\ .

.. _`foo.vintage.highlighting`:

highlighting
------------


- \ :c:func:`vintage`\     : function
- \ ``parameter_a``\  : name of a parameter
- \ ``$ENVVAR``\       : environmental variable
- \ :c:type:`struct my_struct <my_struct>`\    : name of a structure (up to two words including \`\`struct\`\`)
- \ ``CONST``\        : name of a constant.

.. _`foo.vintage.parser-mode`:

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

.. _`foo.vintage.colon-markup`:

colon markup
------------

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

.. _`foo.nfp_flower_priv`:

struct nfp_flower_priv
======================

.. c:struct:: nfp_flower_priv

    Flower APP per-vNIC priv data

.. _`foo.nfp_flower_priv.definition`:

Definition
----------

.. code-block:: c

    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);
    }

.. _`foo.nfp_flower_priv.members`:

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

.. _`foo.foo`:

enum foo
========

.. c:enum:: foo

    foo

.. _`foo.foo.definition`:

Definition
----------

.. code-block:: c

    enum foo {
        F1,
        F2
    };

.. _`foo.foo.constants`:

Constants
---------

F1
    f1

F2
    f2

.. _`foo.something`:

struct something
================

.. c:struct:: something

    Lorem ipsum dolor sit amet.

.. _`foo.something.definition`:

Definition
----------

.. code-block:: c

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

.. _`foo.something.members`:

Members
-------

foofoo
    lorem

barbar
    ipsum

.. _`foo.lineevent_state`:

struct lineevent_state
======================

.. c:struct:: lineevent_state

    contains the state of a userspace event

.. _`foo.lineevent_state.definition`:

Definition
----------

.. code-block:: c

    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;
    }

.. _`foo.lineevent_state.members`:

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

.. _`foo.genpool_algo_t`:

typedef genpool_algo_t
======================

.. c:function:: 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

    :param map:
        Pointer to bitmap
    :type map: unsigned long \*

    :param size:
        The bitmap size in bits
    :type size: unsigned long

    :param start:
        The bitnumber to start searching at
    :type start: unsigned long

    :param nr:
        The number of zeroed bits we're looking for
    :type nr: unsigned int

    :param data:
        optional additional data used by the callback
    :type data: void \*

    :param pool:
        the pool being allocated from
    :type pool: struct gen\_pool \*

    :param start\_addr:
        *undescribed*
    :type start\_addr: unsigned long

.. _`foo.v4l2_check_dv_timings_fnc`:

typedef v4l2_check_dv_timings_fnc
=================================

.. c:function:: bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle)

    timings check callback

    :param t:
        the v4l2_dv_timings struct.
    :type t: const struct v4l2\_dv\_timings \*

    :param handle:
        a handle from the driver.
    :type handle: void \*

.. _`foo.v4l2_check_dv_timings_fnc.description`:

Description
-----------

Returns true if the given timings are valid.

.. _`foo.add`:

macro ADD
=========

.. c:macro::  ADD( first,  second)

    Function like macro to add two values

    :param first:
        first value

    :param second:
        second value

.. _`foo.add.description`:

Description
-----------

Is replaced by a addition of \ ``first``\  and \ ``second``\ .

.. _`foo.iosys_map_wr_field`:

macro iosys_map_wr_field
========================

.. c:macro::  iosys_map_wr_field( map__,  struct_offset__,  struct_type__,  field__,  val__)

    Write to a member of a struct in the iosys_map

    :param map\_\_:
        The iosys_map structure

    :param struct\_offset\_\_:
        Offset from the beggining of the map, where the struct
        is located

    :param struct\_type\_\_:
        The struct describing the layout of the mapping

    :param field\_\_:
        Member of the struct to read

    :param val\_\_:
        Value to write

.. _`foo.iosys_map_wr_field.description`:

Description
-----------

Write a value to the iosys_map considering its layout is described by a C
struct starting at \ ``struct_offset__``\ . The field offset and size is calculated
and the \ ``val_``\ \_ is written. If the field access would incur in un-aligned
access, then either \ :c:func:`iosys_map_memcpy_to`\  needs to be used or the
architecture must support it. Refer to \ :c:func:`iosys_map_rd_field`\  for expected
usage and memory layout.

.. c:namespace-pop::

kernel-doc from all-in-a-tumble.c

.. c:namespace-push:: foo

.. _`foo.user_function`:

user_function
=============

.. c:function:: int user_function(int a,  ...)

    function that can only be called in user context

    :param a:
        some argument
    :type a: int

    :param ellipsis ellipsis:
        ellipsis operator

.. _`foo.user_function.description`:

Description
-----------

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

.. _`foo.user_function.example`:

Example
-------

.. code-block:: c

    x = user_function(22);


.. _`foo.user_function.return`:

Return
------

Returns first argument

.. _`foo.user_sum`:

user_sum
========

.. c:function:: API_EXPORTED int user_sum(int a, int b)

    another function that can only be called in user context

    :param a:
        first argument
    :type a: int

    :param b:
        second argument
    :type b: int

.. _`foo.user_sum.description`:

Description
-----------

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

.. _`foo.user_sum.example`:

Example
-------

.. code-block:: c

    x = user_sum(1, 2);


.. _`foo.user_sum.return`:

Return
------

Returns the sum of the \ ``a``\  and \ ``b``\ 

.. _`foo.sys_tgkill`:

sys_tgkill
==========

.. c:function:: long sys_tgkill(pid_t tgid, pid_t pid, int sig)

    send signal to one specific thread

    :param tgid:
        the thread group ID of the thread
    :type tgid: pid\_t

    :param pid:
        the PID of the thread
    :type pid: pid\_t

    :param sig:
        signal to be sent
    :type sig: int

.. _`foo.sys_tgkill.description`:

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.

.. _`foo.rarely_enum`:

enum rarely_enum
================

.. c:enum:: rarely_enum

    enum to test parsing rarely code styles

.. _`foo.rarely_enum.definition`:

Definition
----------

.. code-block:: c

    enum rarely_enum {
        F1,
        F2
    };

.. _`foo.rarely_enum.constants`:

Constants
---------

F1
    f1

F2
    f2

.. _`foo.rarely_struct`:

struct rarely_struct
====================

.. c:struct:: rarely_struct

    struct to test parsing rarely code styles

.. _`foo.rarely_struct.definition`:

Definition
----------

.. code-block:: c

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

.. _`foo.rarely_struct.members`:

Members
-------

foofoo
    lorem

barbar
    ipsum

.. c:namespace-pop::