英文

包含 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>