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