parse-headers.rst

  1===========================
  2Including uAPI header files
  3===========================
  4
  5Sometimes, it is useful to include header files and C example codes in
  6order to describe the userspace API and to generate cross-references
  7between the code and the documentation. Adding cross-references for
  8userspace API files has an additional advantage: Sphinx will generate warnings
  9if a symbol is not found at the documentation. That helps to keep the
 10uAPI documentation in sync with the Kernel changes.
 11The :ref:`parse_headers.py <parse_headers>` provides a way to generate such
 12cross-references. It has to be called via Makefile, while building the
 13documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
 14about how to use it inside the Kernel tree.
 15
 16.. _parse_headers:
 17
 18tools/docs/parse_headers.py
 19^^^^^^^^^^^^^^^^^^^^^^^^^^^
 20
 21NAME
 22****
 23
 24parse_headers.py - parse a C file, in order to identify functions, structs,
 25enums and defines and create cross-references to a Sphinx book.
 26
 27USAGE
 28*****
 29
 30parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
 31
 32SYNOPSIS
 33********
 34
 35Converts a C header or source file ``FILE_IN`` into a ReStructured Text
 36included via ..parsed-literal block with cross-references for the
 37documentation files that describe the API. It accepts an optional
 38``FILE_RULES`` file to describe what elements will be either ignored or
 39be pointed to a non-default reference type/name.
 40
 41The output is written at ``FILE_OUT``.
 42
 43It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum``
 44and enum ``symbol``, creating cross-references for all of them.
 45
 46It is also capable of distinguishing ``#define`` used for specifying
 47Linux-specific macros used to define ``ioctl``.
 48
 49The optional ``FILE_RULES`` contains a set of rules like::
 50
 51    ignore ioctl VIDIOC_ENUM_FMT
 52    replace ioctl VIDIOC_DQBUF vidioc_qbuf
 53    replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
 54
 55POSITIONAL ARGUMENTS
 56********************
 57
 58  ``FILE_IN``
 59      Input C file
 60
 61  ``FILE_OUT``
 62      Output RST file
 63
 64  ``FILE_RULES``
 65      Exceptions file (optional)
 66
 67OPTIONS
 68*******
 69
 70  ``-h``, ``--help``
 71      show a help message and exit
 72  ``-d``, ``--debug``
 73      Increase debug level. Can be used multiple times
 74  ``-t``, ``--toc``
 75      instead of a literal block, outputs a TOC table at the RST file
 76
 77
 78DESCRIPTION
 79***********
 80
 81Creates an enriched version of a Kernel header file with cross-links
 82to each C data structure type, from ``FILE_IN``, formatting it with
 83reStructuredText notation, either as-is or as a table of contents.
 84
 85It accepts an optional ``FILE_RULES`` which describes what elements will be
 86either ignored or be pointed to a non-default reference, and optionally
 87defines the C namespace to be used.
 88
 89It is meant to allow having more comprehensive documentation, where
 90uAPI headers will create cross-reference links to the code.
 91
 92The output is written at the ``FILE_OUT``.
 93
 94The ``FILE_RULES`` may contain contain three types of statements:
 95**ignore**, **replace** and **namespace**.
 96
 97By default, it create rules for all symbols and defines, but it also
 98allows parsing an exception file. Such file contains a set of rules
 99using the syntax below:
100
1011. Ignore rules:
102
103    ignore *type* *symbol*
104
105Removes the symbol from reference generation.
106
1072. Replace rules:
108
109    replace *type* *old_symbol* *new_reference*
110
111    Replaces *old_symbol* with a *new_reference*.
112    The *new_reference* can be:
113
114    - A simple symbol name;
115    - A full Sphinx reference.
116
1173. Namespace rules
118
119    namespace *namespace*
120
121    Sets C *namespace* to be used during cross-reference generation. Can
122    be overridden by replace rules.
123
124On ignore and replace rules, *type* can be:
125
126    - ioctl:
127        for defines of the form ``_IO*``, e.g., ioctl definitions
128
129    - define:
130        for other defines
131
132    - symbol:
133        for symbols defined within enums;
134
135    - typedef:
136        for typedefs;
137
138    - enum:
139        for the name of a non-anonymous enum;
140
141    - struct:
142        for structs.
143
144
145EXAMPLES
146********
147
148- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``::
149
150    ignore define _VIDEODEV2_H
151
152- On an data structure like this enum::
153
154    enum foo { BAR1, BAR2, PRIVATE };
155
156  It won't generate cross-references for ``PRIVATE``::
157
158    ignore symbol PRIVATE
159
160  At the same struct, instead of creating one cross reference per symbol,
161  make them all point to the ``enum foo`` C type::
162
163    replace symbol BAR1 :c:type:\`foo\`
164    replace symbol BAR2 :c:type:\`foo\`
165
166
167- Use C namespace ``MC`` for all symbols at ``FILE_IN``::
168
169    namespace MC
170
171BUGS
172****
173
174
175Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
176
177
178COPYRIGHT
179*********
180
181
182Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
183
184License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
185
186This is free software: you are free to change and redistribute it.
187There is NO WARRANTY, to the extent permitted by law.