Documentation/doc-guide/parse-headers.rst GitHub 원문 ↗

Linux 6.18.37 · Documentation Guide

Including uAPI Header Files

parse_headers.pl로 uAPI C header를 Sphinx 교차 참조가 있는 reStructuredText로 변환하고 예외 규칙을 작성하는 방법을 설명합니다.

Source pathDocumentation/doc-guide/parse-headers.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

parse-headers.rst:1-192

parse_headers.pl로 uAPI C header를 Sphinx 교차 참조가 있는 reStructuredText로 변환하고 예외 규칙을 작성하는 방법을 설명합니다. 영어 원문 전체와 한국어 전문 번역을 함께 제공하며 함수명, symbol, source path, e-mail, 명령, ReST 역할과 원문 줄 좌표를 보존합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
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/userspace-api/media/Makefile`` for an example
14 about how to use it inside the Kernel tree.
15
16 .. _parse_headers:
17
18 parse_headers.pl
19 ^^^^^^^^^^^^^^^^
20
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
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 --usage.
36
37
38 OPTIONS
39 *******
40
41
42
43 \ **--debug**\
44
45 Put the script in verbose mode, useful for debugging.
46
47
48
49 \ **--usage**\
50
51 Prints a brief help message and exits.
52
53
54
55 \ **--help**\
56
57 Prints a more detailed help message and exits.
58
59
60 DESCRIPTION
61 ***********
62
63
64 Convert a C header or source file (C_FILE), into a reStructuredText
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 value
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
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
176 BUGS
177 ****
178
179
180 Report bugs to Mauro Carvalho Chehab <[email protected]>
181
182
183 COPYRIGHT
184 *********
185
186
187 Copyright (c) 2016 by Mauro Carvalho Chehab <[email protected]>.
188
189 License GPLv2: GNU GPL version 2 <https://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.
193

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

uAPI header를 문서에 포함하는 이유

1-15

userspace API를 설명하고 코드와 문서 사이의 교차 참조를 생성하려면 header file과 C example code를 문서에 포함하는 것이 유용할 때가 있습니다. userspace API 파일에 교차 참조를 추가하면 문서에서 symbol을 찾지 못할 때 Sphinx가 warning을 생성하므로, uAPI 문서를 kernel 변경과 동기화하는 데에도 도움이 됩니다.

`parse_headers.pl`은 이러한 교차 참조를 생성하는 방법을 제공합니다. 문서를 build하는 동안 Makefile을 통해 호출해야 하며, kernel tree에서 사용하는 예는 `Documentation/userspace-api/media/Makefile`을 참고합니다.

이름과 명령 형식

16-35

`parse_headers` anchor 아래의 `parse_headers.pl`은 C 파일을 분석해 함수, 구조체, enum, define을 식별하고 Sphinx book을 향한 교차 참조를 생성하는 도구입니다.

명령은 필수 `C_FILE`과 `OUT_FILE`, 선택적인 `EXCEPTIONS_FILE`을 받습니다. 사용할 수 있는 option은 `--debug`, `--help`, `--usage`입니다.

\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Where <options> can be: --debug, --help or --usage.

명령행 option

36-59
  • `--debug`는 script를 verbose mode로 실행하며 debugging에 유용합니다.
  • `--usage`는 짧은 도움말을 출력하고 종료합니다.
  • `--help`는 더 자세한 도움말을 출력하고 종료합니다.

입력·출력과 인식 가능한 C 요소

60-78

도구는 C header 또는 source file인 `C_FILE`을 API 설명 문서에서 교차 참조할 수 있는 `.. parsed-literal` block의 reStructuredText로 변환합니다. 선택적인 `EXCEPTIONS_FILE`은 무시할 요소와 기본값이 아닌 참조를 사용할 요소를 설명합니다. 변환 결과는 `OUT_FILE`에 기록합니다.

define, function, struct, typedef, enum, enum symbol을 식별해 모두에 대한 교차 참조를 만들 수 있습니다. Linux ioctl을 지정하는 데 사용된 `#define`과 일반 define도 구별합니다.

`EXCEPTIONS_FILE`에는 `ignore`와 `replace`라는 두 종류의 statement를 넣을 수 있습니다.

ignore와 replace 문법

79-95

`ignore` tag의 문법은 다음과 같습니다.

ignore \ **type**\  \ **name**\

`ignore`는 지정한 `type`에 속하는 `name` symbol의 교차 참조를 생성하지 않도록 합니다.

`replace` tag의 문법은 다음과 같습니다.

replace \ **type**\  \ **name**\  \ **new_value**\

`replace`는 지정한 `type`의 `name` symbol에 대한 교차 참조를 만들되, 기본 교체 규칙 대신 `new_value`를 사용하도록 합니다.

예외 statement의 type

96-142

두 statement에서 `type`은 다음 값 중 하나입니다.

  • `ioctl`은 Linux ioctl 정의에 ignore 또는 replace를 적용합니다.
  • `define`은 `C_FILE`에서 발견한 그 밖의 모든 `#define`에 적용합니다.
  • `typedef`는 `C_FILE`의 typedef statement에 적용합니다.
  • `struct`는 `C_FILE`의 struct statement 이름에 적용합니다.
  • `enum`은 `C_FILE`의 enum statement 이름에 적용합니다.
  • `symbol`은 enum value의 이름에 적용합니다.

`ioctl`이 인식하는 정의 형식의 예는 다음과 같습니다.

#define        VIDIOC_DBG_S_REGISTER          _IOW('V', 79, struct v4l2_dbg_register)

replace statement의 `new_value`는 `typedef`, `enum`, `struct` type에는 자동으로 `:c:type:` 참조를 사용하고, `ioctl`, `define`, `symbol` type에는 `:ref:`를 사용합니다. 참조 type은 replace statement에 명시적으로 지정할 수도 있습니다.

예외 파일 작성 예

143-174

다음 statement는 `C_FILE`의 `#define _VIDEODEV2_H`를 무시합니다.

ignore define _VIDEODEV2_H

다음 statement는 `PRIVATE` enum symbol을 무시합니다.

ignore symbol PRIVATE

예를 들어 다음 enum에서 `PRIVATE`에 대한 교차 참조는 생성하지 않습니다.

enum foo { BAR1, BAR2, PRIVATE };

다음 두 replace statement는 `BAR1`과 `BAR2`를 C domain의 `foo` type으로 참조하게 합니다.

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

이 규칙이 적용되는 enum 예는 다음과 같습니다.

enum foo { BAR1, BAR2, PRIVATE };

결과적으로 `BAR1`과 `BAR2` enum symbol은 C domain에 있는 `foo` symbol로 교차 참조됩니다.