Including uAPI header files

Sometimes, it is useful to include header files and C example codes inorder to describe the userspace API and to generate cross-referencesbetween the code and the documentation. Adding cross-references foruserspace API files has an additional advantage: Sphinx will generate warningsif a symbol is not found at the documentation. That helps to keep theuAPI documentation in sync with the Kernel changes.Theparse_headers.py provides a way to generate suchcross-references. It has to be called via Makefile, while building thedocumentation. Please seeDocumentation/userspace-api/media/Makefile for an exampleabout 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_INFILE_OUTFILE_RULES

SYNOPSIS

Converts a C header or source fileFILE_IN into a ReStructured Textincluded via ..parsed-literal block with cross-references for thedocumentation files that describe the API. It accepts an optionalFILE_RULES file to describe what elements will be either ignored orbe pointed to a non-default reference type/name.

The output is written atFILE_OUT.

It is capable of identifyingdefine,struct,typedef,enumand enumsymbol, creating cross-references for all of them.

It is also capable of distinguishing#define used for specifyingLinux-specific macros used to defineioctl.

The optionalFILE_RULES contains a set of rules like:

ignore ioctl VIDIOC_ENUM_FMTreplace ioctl VIDIOC_DQBUF vidioc_qbufreplace 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-linksto each C data structure type, fromFILE_IN, formatting it withreStructuredText notation, either as-is or as a table of contents.

It accepts an optionalFILE_RULES which describes what elements will beeither ignored or be pointed to a non-default reference, and optionallydefines the C namespace to be used.

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

The output is written at theFILE_OUT.

TheFILE_RULES may contain contain three types of statements:ignore,replace andnamespace.

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

  1. Ignore rules:

    ignoretypesymbol

Removes the symbol from reference generation.

  1. Replace rules:

    replacetypeold_symbolnew_reference

    Replacesold_symbol with anew_reference.Thenew_reference can be:

    • A simple symbol name;

    • A full Sphinx reference.

  2. Namespace rules

    namespacenamespace

    Sets Cnamespace to be used during cross-reference generation. Canbe 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 atFILE_IN:

    ignore define _VIDEODEV2_H

  • On an data structure like this enum:

    enum foo { BAR1, BAR2, PRIVATE };

    It won’t generate cross-references forPRIVATE:

    ignore symbol PRIVATE

    At the same struct, instead of creating one cross reference per symbol,make them all point to theenumfoo C type:

    replace symbol BAR1 :c:type:\`foo\`replace symbol BAR2 :c:type:\`foo\`

  • Use C namespaceMC for all symbols atFILE_IN:

    namespace MC

BUGS

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

COPYRIGHT

Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.

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.