1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0 2 2 3 .. include:: ../disclaimer-zh_CN.rst 3 .. include:: ../disclaimer-zh_CN.rst 4 4 5 :Original: Documentation/doc-guide/parse-heade 5 :Original: Documentation/doc-guide/parse-headers.rst 6 6 7 :译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email. 7 :译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> 8 8 9 ===================== 9 ===================== 10 包å«ç”¨æˆ·ç©ºé—´API头文件 10 包å«ç”¨æˆ·ç©ºé—´API头文件 11 ===================== 11 ===================== 12 12 13 有时,为了æ述用户空间API并在代ç 13 有时,为了æ述用户空间API并在代ç 和文档之间生æˆäº¤å‰å¼•ç”¨ï¼Œéœ€è¦åŒ…å«å¤´æ–‡ä»¶å’Œç¤ºä¾‹ 14 C代ç 。为用户空间APIæ–‡ä»¶æ·»åŠ äº¤å‰ 14 C代ç 。为用户空间APIæ–‡ä»¶æ·»åŠ äº¤å‰å¼•ç”¨è¿˜æœ‰ä¸€ä¸ªå¥½å¤„:如果在文档ä¸æ‰¾ä¸åˆ°ç›¸åº”符å·ï¼Œ 15 Sphinx将生æˆè¦å‘Šã€‚这有助于ä¿æŒç”¨æ 15 Sphinx将生æˆè¦å‘Šã€‚这有助于ä¿æŒç”¨æˆ·ç©ºé—´APIæ–‡æ¡£ä¸Žå†…æ ¸æ›´æ”¹åŒæ¥ã€‚ 16 :ref:`parse_headers.pl <parse_headers_zh>` æ 16 :ref:`parse_headers.pl <parse_headers_zh>` æ供了生æˆæ¤ç±»äº¤å‰å¼•ç”¨çš„一ç§æ–¹æ³•ã€‚ 17 在构建文档时,必须通过Makefileè°ƒç” 17 在构建文档时,必须通过Makefileè°ƒç”¨å®ƒã€‚æœ‰å…³å¦‚ä½•åœ¨å†…æ ¸æ ‘ä¸ä½¿ç”¨å®ƒçš„示例,请å‚阅 18 ``Documentation/userspace-api/media/Makefile`` 18 ``Documentation/userspace-api/media/Makefile`` 。 19 19 20 .. _parse_headers_zh: 20 .. _parse_headers_zh: 21 21 22 parse_headers.pl 22 parse_headers.pl 23 ---------------- 23 ---------------- 24 24 25 脚本å称 25 脚本å称 26 ~~~~~~~~ 26 ~~~~~~~~ 27 27 28 28 29 parse_headers.pl——解æžä¸€ä¸ªCæ–‡ä»¶ï¼Œè¯ 29 parse_headers.pl——解æžä¸€ä¸ªC文件,识别函数ã€ç»“构体ã€æžšä¸¾ã€å®šä¹‰å¹¶å¯¹Sphinx文档 30 创建交å‰å¼•ç”¨ã€‚ 30 创建交å‰å¼•ç”¨ã€‚ 31 31 32 32 33 ç”¨æ³•æ¦‚è¦ 33 ç”¨æ³•æ¦‚è¦ 34 ~~~~~~~~ 34 ~~~~~~~~ 35 35 36 36 37 \ **parse_headers.pl**\ [<选项>] <C文件> 37 \ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] 38 38 39 <选项> å¯ä»¥æ˜¯ï¼š --debug, --help 或 --us 39 <选项> å¯ä»¥æ˜¯ï¼š --debug, --help 或 --usage 。 40 40 41 41 42 选项 42 选项 43 ~~~~ 43 ~~~~ 44 44 45 45 46 46 47 \ **--debug**\ 47 \ **--debug**\ 48 48 49 å¼€å¯è„šæœ¬è¯¦ç»†æ¨¡å¼ï¼Œåœ¨è°ƒè¯•æ—¶å¾ˆæœ‰ 49 å¼€å¯è„šæœ¬è¯¦ç»†æ¨¡å¼ï¼Œåœ¨è°ƒè¯•æ—¶å¾ˆæœ‰ç”¨ã€‚ 50 50 51 51 52 \ **--usage**\ 52 \ **--usage**\ 53 53 54 打å°ç®€çŸçš„帮助信æ¯å¹¶é€€å‡ºã€‚ 54 打å°ç®€çŸçš„帮助信æ¯å¹¶é€€å‡ºã€‚ 55 55 56 56 57 57 58 \ **--help**\ 58 \ **--help**\ 59 59 60 打å°æ›´è¯¦ç»†çš„帮助信æ¯å¹¶é€€å‡ºã€‚ 60 打å°æ›´è¯¦ç»†çš„帮助信æ¯å¹¶é€€å‡ºã€‚ 61 61 62 62 63 说明 63 说明 64 ~~~~ 64 ~~~~ 65 65 66 通过C头文件或æºæ–‡ä»¶ï¼ˆ<C文件>ï¼‰ä¸ 66 通过C头文件或æºæ–‡ä»¶ï¼ˆ<C文件>)ä¸ä¸ºæè¿°API的文档编写的带交å‰å¼•ç”¨çš„ ..é¢„æ ¼å¼åŒ– 67 文本 å—将文件转æ¢æˆé‡æž„文本(RST 67 文本 å—将文件转æ¢æˆé‡æž„文本(RST)。它接å—一个å¯é€‰çš„<例外文件>,其ä¸æ述了 68 å“ªäº›å…ƒç´ å°†è¢«å¿½ç•¥æˆ–æŒ‡å‘éžé»˜è®¤å¼•ç 68 å“ªäº›å…ƒç´ å°†è¢«å¿½ç•¥æˆ–æŒ‡å‘éžé»˜è®¤å¼•ç”¨ã€‚ 69 69 70 输出被写入到<输出文件>。 70 输出被写入到<输出文件>。 71 71 72 它能够识别定义ã€å‡½æ•°ã€ç»“构体ã€t 72 它能够识别定义ã€å‡½æ•°ã€ç»“构体ã€typedefã€æžšä¸¾å’Œæžšä¸¾ç¬¦å·ï¼Œå¹¶ä¸ºå®ƒä»¬åˆ›å»ºäº¤å‰å¼•ç”¨ã€‚ 73 它还能够区分用于指定Linux ioctlçš„ ` 73 它还能够区分用于指定Linux ioctlçš„ ``#define`` 。 74 74 75 <例外文件> 包å«ä¸¤ç§ç±»åž‹çš„è¯å¥ï¼š 75 <例外文件> 包å«ä¸¤ç§ç±»åž‹çš„è¯å¥ï¼š \ **ignore**\ 或 \ **replace**\ . 76 76 77 ignoreæ ‡è®°çš„è¯æ³•ä¸ºï¼š 77 ignoreæ ‡è®°çš„è¯æ³•ä¸ºï¼š 78 78 79 79 80 ignore \ **type**\ \ **name**\ 80 ignore \ **type**\ \ **name**\ 81 81 82 The \ **ignore**\ æ„味ç€å®ƒä¸ä¼šä¸ºç±»åž‹ 82 The \ **ignore**\ æ„味ç€å®ƒä¸ä¼šä¸ºç±»åž‹ä¸º \ **type**\ çš„ \ **name**\ 符å·ç”Ÿæˆ 83 交å‰å¼•ç”¨ã€‚ 83 交å‰å¼•ç”¨ã€‚ 84 84 85 85 86 replaceæ ‡è®°çš„è¯æ³•ä¸ºï¼š 86 replaceæ ‡è®°çš„è¯æ³•ä¸ºï¼š 87 87 88 88 89 replace \ **type**\ \ **name**\ \ **new_valu 89 replace \ **type**\ \ **name**\ \ **new_value**\ 90 90 91 The \ **replace**\ 味ç€å®ƒå°†ä¸º \ **type** 91 The \ **replace**\ 味ç€å®ƒå°†ä¸º \ **type**\ 类型的 \ **name**\ 符å·ç”Ÿæˆäº¤å‰å¼• 92 用,但是它将使用 \ **new_value**\ æ¥å 92 用,但是它将使用 \ **new_value**\ æ¥å–代默认的替æ¢è§„则。 93 93 94 94 95 这两ç§è¯å¥ä¸ï¼Œ \ **type**\ å¯ä»¥æ˜¯ä»¥ 95 这两ç§è¯å¥ä¸ï¼Œ \ **type**\ å¯ä»¥æ˜¯ä»¥ä¸‹ä»»ä¸€é¡¹ï¼š 96 96 97 97 98 \ **ioctl**\ 98 \ **ioctl**\ 99 99 100 ignore 或 replace è¯å¥åº”用于ioctl定义 100 ignore 或 replace è¯å¥åº”用于ioctl定义,如: 101 101 102 #define VIDIOC_DBG_S_REGISTER _IOW( 102 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) 103 103 104 104 105 105 106 \ **define**\ 106 \ **define**\ 107 107 108 ignore 或 replace è¯å¥åº”用于在<C文件 108 ignore 或 replace è¯å¥åº”用于在<C文件>ä¸æ‰¾åˆ°çš„任何其他 ``#define`` 。 109 109 110 110 111 111 112 \ **typedef**\ 112 \ **typedef**\ 113 113 114 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸ 114 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„typedefè¯å¥ã€‚ 115 115 116 116 117 117 118 \ **struct**\ 118 \ **struct**\ 119 119 120 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸ 120 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„结构体å称è¯å¥ã€‚ 121 121 122 122 123 123 124 \ **enum**\ 124 \ **enum**\ 125 125 126 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸ 126 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„枚举å称è¯å¥ã€‚ 127 127 128 128 129 129 130 \ **symbol**\ 130 \ **symbol**\ 131 131 132 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸ 132 ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„枚举值å称è¯å¥ã€‚ 133 133 134 replaceè¯å¥ä¸ï¼Œ \ **new_value**\ 会自å 134 replaceè¯å¥ä¸ï¼Œ \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ 135 å’Œ \ **struct**\ 类型的 :c:type: å¼•ç”¨ï¼ 135 å’Œ \ **struct**\ 类型的 :c:type: å¼•ç”¨ï¼›ä»¥åŠ \ **ioctl**\ , \ **define**\ å’Œ 136 \ **symbol**\ 类型的 :ref: ã€‚å¼•ç”¨çš„ç± 136 \ **symbol**\ 类型的 :ref: 。引用的类型也å¯ä»¥åœ¨replaceè¯å¥ä¸æ˜¾å¼å®šä¹‰ã€‚ 137 137 138 138 139 示例 139 示例 140 ~~~~ 140 ~~~~ 141 141 142 142 143 ignore define _VIDEODEV2_H 143 ignore define _VIDEODEV2_H 144 144 145 145 146 忽略<C文件>ä¸çš„ #define _VIDEODEV2_H 。 146 忽略<C文件>ä¸çš„ #define _VIDEODEV2_H 。 147 147 148 ignore symbol PRIVATE 148 ignore symbol PRIVATE 149 149 150 150 151 如下结构体: 151 如下结构体: 152 152 153 enum foo { BAR1, BAR2, PRIVATE }; 153 enum foo { BAR1, BAR2, PRIVATE }; 154 154 155 ä¸ä¼šä¸º \ **PRIVATE**\ 生æˆäº¤å‰å¼•ç”¨ã€‚ 155 ä¸ä¼šä¸º \ **PRIVATE**\ 生æˆäº¤å‰å¼•ç”¨ã€‚ 156 156 157 replace symbol BAR1 :c:type:\`foo\` 157 replace symbol BAR1 :c:type:\`foo\` 158 replace symbol BAR2 :c:type:\`foo\` 158 replace symbol BAR2 :c:type:\`foo\` 159 159 160 160 161 如下结构体: 161 如下结构体: 162 162 163 enum foo { BAR1, BAR2, PRIVATE }; 163 enum foo { BAR1, BAR2, PRIVATE }; 164 164 165 它会让BAR1å’ŒBAR2枚举符å·äº¤å‰å¼•ç”¨Cå 165 它会让BAR1å’ŒBAR2枚举符å·äº¤å‰å¼•ç”¨C域ä¸çš„foo符å·ã€‚ 166 166 167 167 168 168 169 缺陷 169 缺陷 170 ~~~~ 170 ~~~~ 171 171 172 172 173 请å‘Mauro Carvalho Chehab <mchehab@kernel.org 173 请å‘Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 174 174 175 ä¸æ–‡ç¿»è¯‘问题请找ä¸æ–‡ç¿»è¯‘维护者ã 175 ä¸æ–‡ç¿»è¯‘问题请找ä¸æ–‡ç¿»è¯‘维护者。 176 176 177 177 178 ç‰ˆæƒ 178 ç‰ˆæƒ 179 ~~~~ 179 ~~~~ 180 180 181 181 182 版æƒæ‰€æœ‰ (c) 2016 Mauro Carvalho Chehab <mc 182 版æƒæ‰€æœ‰ (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> 183 183 184 许å¯è¯ GPLv2:GNU GPL version 2 <https://g 184 许å¯è¯ GPLv2:GNU GPL version 2 <https://gnu.org/licenses/gpl.html> 185 185 186 è¿™æ˜¯è‡ªç”±è½¯ä»¶ï¼šä½ å¯ä»¥è‡ªç”±åœ°ä¿®æ”¹å 186 è¿™æ˜¯è‡ªç”±è½¯ä»¶ï¼šä½ å¯ä»¥è‡ªç”±åœ°ä¿®æ”¹å’Œé‡æ–°å‘布它。 187 在法律å…许的范围内,**ä¸æä¾›ä»»ä½ 187 在法律å…许的范围内,**ä¸æ供任何ä¿è¯**。
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.