[mirror_ubuntu-zesty-kernel.git] / Documentation / doc-guide / parse-headers.rst

===========================
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/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 --man.


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 statements
 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 <mchehab@s-opensource.com>


COPYRIGHT
*********


Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.

License GPLv2: GNU GPL version 2 <http://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.
Commit	Line	Data
2dde123b MCC	1	===========================
	2	Including uAPI header files
	3	===========================
	4
	5	Sometimes, it is useful to include header files and C example codes in
	6	order to describe the userspace API and to generate cross-references
	7	between the code and the documentation. Adding cross-references for
	8	userspace API files has an additional vantage: Sphinx will generate warnings
	9	if a symbol is not found at the documentation. That helps to keep the
	10	uAPI documentation in sync with the Kernel changes.
	11	The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such
	12	cross-references. It has to be called via Makefile, while building the
	13	documentation. Please see ``Documentation/media/Makefile`` for an example
	14	about how to use it inside the Kernel tree.
	15
	16	.. _parse_headers:
	17
327f5a75	18	parse_headers.pl
2dde123b MCC	19	^^^^^^^^^^^^^^^^
2dde123b MCC	20
327f5a75 MCC	21	NAME
	22	****
	23
	24
	25	parse_headers.pl - parse a C file, in order to identify functions, structs,
	26	enums and defines and create cross-references to a Sphinx book.
	27
	28
327f5a75 MCC	29	SYNOPSIS
	30	********
	31
	32
	33	\ parse_headers.pl\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
	34
	35	Where <options> can be: --debug, --help or --man.
	36
	37
327f5a75 MCC	38	OPTIONS
	39	*******
	40
	41
	42
	43	\ --debug\
	44
	45	Put the script in verbose mode, useful for debugging.
	46
	47
	48
c3396656	49	\ --usage\
327f5a75 MCC	50
	51	Prints a brief help message and exits.
	52
	53
	54
c3396656	55	\ --help\
327f5a75	56
c3396656	57	Prints a more detailed help message and exits.
327f5a75 MCC	58
327f5a75 MCC	59
327f5a75 MCC	60	DESCRIPTION
	61	***********
	62
	63
	64	Convert a C header or source file (C_FILE), into a ReStructured Text
	65	included via ..parsed-literal block with cross-references for the
	66	documentation files that describe the API. It accepts an optional
	67	EXCEPTIONS_FILE with describes what elements will be either ignored or
	68	be pointed to a non-default reference.
	69
	70	The output is written at the (OUT_FILE).
	71
	72	It is capable of identifying defines, functions, structs, typedefs,
	73	enums and enum symbols and create cross-references for all of them.
	74	It is also capable of distinguish #define used for specifying a Linux
	75	ioctl.
	76
	77	The EXCEPTIONS_FILE contain two types of statements: \ ignore\ or \ replace\ .
	78
	79	The syntax for the ignore tag is:
	80
	81
	82	ignore \ type\ \ name\
	83
	84	The \ ignore\ means that it won't generate cross references for a
	85	\ name\ symbol of type \ type\ .
	86
	87	The syntax for the replace tag is:
	88
	89
	90	replace \ type\ \ name\ \ new_value\
	91
	92	The \ replace\ means that it will generate cross references for a
	93	\ name\ symbol of type \ type\ , but, instead of using the default
	94	replacement rule, it will use \ new_value\ .
	95
	96	For both statements, \ type\ can be either one of the following:
	97
	98
	99	\ ioctl\
	100
	101	The ignore or replace statement will apply to ioctl definitions like:
	102
	103	#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
	104
	105
	106
	107	\ define\
	108
	109	The ignore or replace statement will apply to any other #define found
	110	at C_FILE.
	111
	112
	113
	114	\ typedef\
	115
	116	The ignore or replace statement will apply to typedef statements at C_FILE.
	117
	118
	119
	120	\ struct\
	121
	122	The ignore or replace statement will apply to the name of struct statements
	123	at C_FILE.
124
125
126
127	\ enum\
128
129	The ignore or replace statement will apply to the name of enum statements
130	at C_FILE.
131
132
133
134	\ symbol\
135
136	The ignore or replace statement will apply to the name of enum statements
137	at C_FILE.
138
139	For replace statements, \ new_value\ will automatically use :c:type:
140	references for \ typedef\ , \ enum\ and \ struct\ types. It will use :ref:
141	for \ ioctl\ , \ define\ and \ symbol\ types. The type of reference can
142	also be explicitly defined at the replace statement.
143
144
145
327f5a75 MCC	146	EXAMPLES
	147	********
	148
	149
	150	ignore define _VIDEODEV2_H
	151
	152
	153	Ignore a #define _VIDEODEV2_H at the C_FILE.
	154
	155	ignore symbol PRIVATE
	156
	157
	158	On a struct like:
	159
	160	enum foo { BAR1, BAR2, PRIVATE };
	161
	162	It won't generate cross-references for \ PRIVATE\ .
	163
	164	replace symbol BAR1 :c:type:\`foo\`
	165	replace symbol BAR2 :c:type:\`foo\`
	166
	167
	168	On a struct like:
	169
	170	enum foo { BAR1, BAR2, PRIVATE };
	171
	172	It will make the BAR1 and BAR2 enum symbols to cross reference the foo
	173	symbol at the C domain.
	174
	175
327f5a75 MCC	176	BUGS
	177	****
	178
	179
	180	Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
	181
	182
327f5a75 MCC	183	COPYRIGHT
	184	*********
	185
	186
	187	Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
	188
	189	License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
	190
	191	This is free software: you are free to change and redistribute it.
	192	There is NO WARRANTY, to the extent permitted by law.