forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
192 lines
4.3 KiB
192 lines
4.3 KiB
=========================== |
|
Including uAPI header files |
|
=========================== |
|
|
|
Sometimes, it is useful to include header files and C example codes in |
|
order to describe the userspace API and to generate cross-references |
|
between the code and the documentation. Adding cross-references for |
|
userspace API files has an additional vantage: Sphinx will generate warnings |
|
if a symbol is not found at the documentation. That helps to keep the |
|
uAPI documentation in sync with the Kernel changes. |
|
The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such |
|
cross-references. It has to be called via Makefile, while building the |
|
documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example |
|
about how to use it inside the Kernel tree. |
|
|
|
.. _parse_headers: |
|
|
|
parse_headers.pl |
|
^^^^^^^^^^^^^^^^ |
|
|
|
NAME |
|
**** |
|
|
|
|
|
parse_headers.pl - parse a C file, in order to identify functions, structs, |
|
enums and defines and create cross-references to a Sphinx book. |
|
|
|
|
|
SYNOPSIS |
|
******** |
|
|
|
|
|
\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] |
|
|
|
Where <options> can be: --debug, --help or --usage. |
|
|
|
|
|
OPTIONS |
|
******* |
|
|
|
|
|
|
|
\ **--debug**\ |
|
|
|
Put the script in verbose mode, useful for debugging. |
|
|
|
|
|
|
|
\ **--usage**\ |
|
|
|
Prints a brief help message and exits. |
|
|
|
|
|
|
|
\ **--help**\ |
|
|
|
Prints a more detailed help message and exits. |
|
|
|
|
|
DESCRIPTION |
|
*********** |
|
|
|
|
|
Convert a C header or source file (C_FILE), into a ReStructured Text |
|
included via ..parsed-literal block with cross-references for the |
|
documentation files that describe the API. It accepts an optional |
|
EXCEPTIONS_FILE with describes what elements will be either ignored or |
|
be pointed to a non-default reference. |
|
|
|
The output is written at the (OUT_FILE). |
|
|
|
It is capable of identifying defines, functions, structs, typedefs, |
|
enums and enum symbols and create cross-references for all of them. |
|
It is also capable of distinguish #define used for specifying a Linux |
|
ioctl. |
|
|
|
The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . |
|
|
|
The syntax for the ignore tag is: |
|
|
|
|
|
ignore \ **type**\ \ **name**\ |
|
|
|
The \ **ignore**\ means that it won't generate cross references for a |
|
\ **name**\ symbol of type \ **type**\ . |
|
|
|
The syntax for the replace tag is: |
|
|
|
|
|
replace \ **type**\ \ **name**\ \ **new_value**\ |
|
|
|
The \ **replace**\ means that it will generate cross references for a |
|
\ **name**\ symbol of type \ **type**\ , but, instead of using the default |
|
replacement rule, it will use \ **new_value**\ . |
|
|
|
For both statements, \ **type**\ can be either one of the following: |
|
|
|
|
|
\ **ioctl**\ |
|
|
|
The ignore or replace statement will apply to ioctl definitions like: |
|
|
|
#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) |
|
|
|
|
|
|
|
\ **define**\ |
|
|
|
The ignore or replace statement will apply to any other #define found |
|
at C_FILE. |
|
|
|
|
|
|
|
\ **typedef**\ |
|
|
|
The ignore or replace statement will apply to typedef statements at C_FILE. |
|
|
|
|
|
|
|
\ **struct**\ |
|
|
|
The ignore or replace statement will apply to the name of struct statements |
|
at C_FILE. |
|
|
|
|
|
|
|
\ **enum**\ |
|
|
|
The ignore or replace statement will apply to the name of enum statements |
|
at C_FILE. |
|
|
|
|
|
|
|
\ **symbol**\ |
|
|
|
The ignore or replace statement will apply to the name of enum value |
|
at C_FILE. |
|
|
|
For replace statements, \ **new_value**\ will automatically use :c:type: |
|
references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: |
|
for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can |
|
also be explicitly defined at the replace statement. |
|
|
|
|
|
|
|
EXAMPLES |
|
******** |
|
|
|
|
|
ignore define _VIDEODEV2_H |
|
|
|
|
|
Ignore a #define _VIDEODEV2_H at the C_FILE. |
|
|
|
ignore symbol PRIVATE |
|
|
|
|
|
On a struct like: |
|
|
|
enum foo { BAR1, BAR2, PRIVATE }; |
|
|
|
It won't generate cross-references for \ **PRIVATE**\ . |
|
|
|
replace symbol BAR1 :c:type:\`foo\` |
|
replace symbol BAR2 :c:type:\`foo\` |
|
|
|
|
|
On a struct like: |
|
|
|
enum foo { BAR1, BAR2, PRIVATE }; |
|
|
|
It will make the BAR1 and BAR2 enum symbols to cross reference the foo |
|
symbol at the C domain. |
|
|
|
|
|
BUGS |
|
**** |
|
|
|
|
|
Report bugs to Mauro Carvalho Chehab <[email protected]> |
|
|
|
|
|
COPYRIGHT |
|
********* |
|
|
|
|
|
Copyright (c) 2016 by Mauro Carvalho Chehab <[email protected]>. |
|
|
|
License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. |
|
|
|
This is free software: you are free to change and redistribute it. |
|
There is NO WARRANTY, to the extent permitted by law.
|
|
|