GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing docs.kernel.org — Including uAPI header files — The Linux Kernel documentation

English

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 advantage: 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 parse-headers.py provides a way to generate such cross-references. During the documentation build, the same parser is used by the kernel-include directive with the :generate-cross-refs: option. Please see Documentation/userspace-api/media/cec/cec-header.rst for an example about how to use it inside the Kernel tree.

tools/docs/parse-headers.py¶

NAME¶

parse-headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book.

USAGE¶

parse-headers.py [-h] [-d] [-t] FILE_IN FILE_OUT [FILE_RULES]

SYNOPSIS¶

Converts a C header or source file FILE_IN into a ReStructured Text included via ..parsed-literal block with cross-references for the documentation files that describe the API. It accepts an optional FILE_RULES file to describe what elements will be either ignored or be pointed to a non-default reference type/name.

The output is written at FILE_OUT.

It is capable of identifying define, struct, typedef, enum and enum symbol, creating cross-references for all of them.

It is also capable of distinguishing #define used for specifying Linux-specific macros used to define ioctl.

The optional FILE_RULES contains a set of rules like:

ignore ioctl VIDIOC_ENUM_FMT
replace ioctl VIDIOC_DQBUF vidioc_qbuf
replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`

POSITIONAL ARGUMENTS¶

FILE_IN
Input C file

FILE_OUT
Output RST file

FILE_RULES
Exceptions file (optional)

OPTIONS¶

-h, --help
show a help message and exit

-d, --debug
Increase debug level. Can be used multiple times

-t, --toc
instead of a literal block, outputs a TOC table at the RST file

DESCRIPTION¶

Creates an enriched version of a Kernel header file with cross-links to each C data structure type, from FILE_IN, formatting it with reStructuredText notation, either as-is or as a table of contents.

It accepts an optional FILE_RULES which describes what elements will be either ignored or be pointed to a non-default reference, and optionally defines the C namespace to be used.

It is meant to allow having more comprehensive documentation, where uAPI headers will create cross-reference links to the code.

The output is written at the FILE_OUT.

The FILE_RULES may contain contain three types of statements: ignore, replace and namespace.

By default, it create rules for all symbols and defines, but it also allows parsing an exception file. Such file contains a set of rules using the syntax below:

Ignore rules:

ignore type symbol

Removes the symbol from reference generation.

Replace rules:
replace type old_symbol new_reference

Replaces old_symbol with a new_reference. The new_reference can be:
- A simple symbol name;
- A full Sphinx reference.
Namespace rules

namespace namespace

Sets C namespace to be used during cross-reference generation. Can be overridden by replace rules.

On ignore and replace rules, type can be:

ioctl:
for defines of the form _IO*, e.g., ioctl definitions

define:
for other defines

symbol:
for symbols defined within enums;

typedef:
for typedefs;

enum:
for the name of a non-anonymous enum;

struct:
for structs.

EXAMPLES¶

Ignore a define _VIDEODEV2_H at FILE_IN:
```
ignore define _VIDEODEV2_H
```
On an data structure like this enum:
```
enum foo { BAR1, BAR2, PRIVATE };
```
It won’t generate cross-references for PRIVATE:
```
ignore symbol PRIVATE
```
At the same struct, instead of creating one cross reference per symbol, make them all point to the enum foo C type:
```
replace symbol BAR1 :c:type:\`foo\`
replace symbol BAR2 :c:type:\`foo\`
```
Use C namespace MC for all symbols at FILE_IN:
```
namespace MC
```

BUGS¶

Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>

COPYRIGHT¶

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.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.