英文

包含 uAPI 头文件

有时，包含头文件和 C 示例代码以描述用户空间 API 以及在代码和文档之间生成交叉引用会很有用。为用户空间 API 文件添加交叉引用还有一个额外的好处：如果在文档中找不到符号，Sphinx 将生成警告。这有助于使 uAPI 文档与内核更改保持同步。 parse_headers.pl 提供了一种生成此类交叉引用的方法。它必须在构建文档时通过 Makefile 调用。有关如何在内核树中使用它的示例，请参见 Documentation/userspace-api/media/Makefile。

parse_headers.pl

名称

parse_headers.pl - 解析 C 文件，以识别函数、结构体、枚举和定义，并创建与 Sphinx 书籍的交叉引用。

概要

parse_headers.pl [<选项>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

其中 <选项> 可以是：--debug、--help 或 --usage。

选项

--debug

将脚本置于详细模式，用于调试。

--usage

打印简短的帮助消息并退出。

--help

打印更详细的帮助消息并退出。

描述

将 C 头文件或源文件 (C_FILE) 转换为 reStructuredText，该文本通过 ..parsed-literal 块包含，并带有对描述 API 的文档文件的交叉引用。它接受一个可选的 EXCEPTIONS_FILE，用于描述哪些元素将被忽略或指向非默认引用。

输出写入 (OUT_FILE)。

它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为所有这些创建交叉引用。 它还能够区分用于指定 Linux ioctl 的 #define。

EXCEPTIONS_FILE 包含两种类型的语句：ignore 或 replace。

ignore 标签的语法是

ignore type name

ignore 表示它不会为 type 类型的 name 符号生成交叉引用。

replace 标签的语法是

replace type name new_value

replace 表示它将为 type 类型的 name 符号生成交叉引用，但是，它将使用 new_value，而不是使用默认替换规则。

对于这两个语句，type 可以是以下之一

ioctl

ignore 或 replace 语句将应用于像这样的 ioctl 定义

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

define

ignore 或 replace 语句将应用于 C_FILE 中找到的任何其他 #define。

typedef

ignore 或 replace 语句将应用于 C_FILE 中的 typedef 语句。

struct

ignore 或 replace 语句将应用于 C_FILE 中 struct 语句的名称。

enum

ignore 或 replace 语句将应用于 C_FILE 中 enum 语句的名称。

symbol

ignore 或 replace 语句将应用于 C_FILE 中枚举值的名称。

对于 replace 语句，new_value 将自动为 typedef、enum 和 struct 类型使用 :c:type: 引用。 它将为 ioctl、define 和 symbol 类型使用 :ref:。 引用类型也可以在 replace 语句中显式定义。

示例

ignore define _VIDEODEV2_H

忽略 C_FILE 中的 #define _VIDEODEV2_H。

ignore symbol PRIVATE

在像这样的结构体中

enum foo { BAR1, BAR2, PRIVATE };

它不会为 PRIVATE 生成交叉引用。

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

在像这样的结构体中

enum foo { BAR1, BAR2, PRIVATE };

它将使 BAR1 和 BAR2 枚举符号在 C 域中交叉引用 foo 符号。

BUGS

将错误报告给 Mauro Carvalho Chehab <mchehab@kernel.org>