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