11. Linux USB 影片類 (UVC) 驅動程式¶

本文件記錄了 UVC 驅動程式的某些特定於驅動程式的方面，例如特定於驅動程式的 ioctl 和實現說明。

問題和意見可以傳送到 Linux UVC 開發郵件列表：linux-media@vger.kernel.org。

11.1. 擴充套件單元 (XU) 支援¶

11.1.1. 簡介¶

UVC 規範允許透過擴充套件單元 (XU) 進行供應商特定的擴充套件。Linux UVC 驅動程式透過兩種不同的機制支援擴充套件單元控制元件 (XU 控制元件)

透過將 XU 控制元件對映到 V4L2 控制元件

透過特定於驅動程式的 ioctl 介面

第一種機制允許通用 V4L2 應用程式透過將某些 XU 控制元件對映到 V4L2 控制元件來使用 XU 控制元件，這些控制元件隨後會在普通控制元件列舉期間顯示。

第二種機制要求應用程式具有 uvcvideo 特定的知識才能訪問 XU 控制元件，但會將整個 UVC XU 概念公開給使用者空間，以實現最大的靈活性。

這兩種機制相互補充，並在下面進行更詳細的描述。

11.1.2. 控制元件對映¶

UVC 驅動程式提供了一個 API，供使用者空間應用程式在執行時定義所謂的控制元件對映。這些對映允許將單個 XU 控制元件或其中的位元組範圍對映到新的 V4L2 控制元件。這些控制元件的出現和功能與正常的 V4L2 控制元件完全相同（即庫存控制元件，例如亮度、對比度等）。但是，讀取或寫入此類 V4L2 控制元件會觸發關聯的 XU 控制元件的讀取或寫入。

用於建立這些控制元件對映的 ioctl 稱為 UVCIOC_CTRL_MAP。之前的驅動程式版本（0.2.0 之前）需要預先使用另一個 ioctl (UVCIOC_CTRL_ADD) 將 XU 控制元件資訊傳遞給 UVC 驅動程式。由於較新的 uvcvideo 版本直接從裝置查詢資訊，因此不再需要這樣做。

有關 UVCIOC_CTRL_MAP ioctl 的詳細資訊，請參閱下面標題為“IOCTL 參考”的部分。

驅動程式特定的 XU 控制元件介面

對於需要直接訪問 XU 控制元件的應用程式，例如出於測試目的、韌體上傳或訪問二進位制控制元件，提供了第二種機制，以驅動程式特定的 ioctl 的形式訪問 XU 控制元件，即 UVCIOC_CTRL_QUERY。

呼叫此 ioctl 允許應用程式向 UVC 驅動程式傳送查詢，這些查詢直接對映到低階 UVC 控制元件請求。

為了發出這樣的請求，需要知道控制元件的擴充套件單元的 UVC 單元 ID 和控制元件選擇器。此資訊要麼需要在應用程式中硬編碼，要麼使用其他方式查詢，例如透過解析 UVC 描述符，或者如果可用，使用媒體控制器 API 列舉裝置的實體。

除非控制元件大小已知，否則首先需要發出 UVC_GET_LEN 請求，以便能夠分配足夠大的緩衝區並將緩衝區大小設定為正確的值。同樣，要確定 UVC_GET_CUR 或 UVC_SET_CUR 是否是給定控制元件的有效請求，應發出 UVC_GET_INFO 請求。結果位元組的位 0（支援 GET）和 1（支援 SET）指示哪些請求有效。

隨著 UVCIOC_CTRL_QUERY ioctl 的新增，UVCIOC_CTRL_GET 和 UVCIOC_CTRL_SET ioctl 已經過時，因為它們的功能是前一個 ioctl 的子集。目前仍然支援它們，但鼓勵應用程式開發人員改用 UVCIOC_CTRL_QUERY。

有關 UVCIOC_CTRL_QUERY ioctl 的詳細資訊，請參閱下面標題為“IOCTL 參考”的部分。

11.1.3. 安全性¶

該 API 目前沒有提供細粒度的訪問控制設施。UVCIOC_CTRL_ADD 和 UVCIOC_CTRL_MAP ioctl 需要超級使用者許可權。

歡迎提出有關如何改進此功能的建議。

11.1.4. 除錯¶

為了除錯與 XU 控制元件或一般控制元件相關的問題，建議在模組引數“trace”中啟用 UVC_TRACE_CONTROL 位。這會導致額外的輸出寫入系統日誌。

11.1.5. IOCTL 參考¶

11.1.5.1. UVCIOC_CTRL_MAP - 將 UVC 控制元件對映到 V4L2 控制元件¶

引數：struct uvc_xu_control_mapping

描述:

此 ioctl 在 UVC 控制元件或 UVC 控制元件的一部分與 V4L2 控制元件之間建立對映。一旦定義了對映，使用者空間應用程式就可以透過 V4L2 控制元件 API 訪問供應商定義的 UVC 控制元件。

要建立對映，應用程式需要使用 UVCIOC_CTRL_ADD 定義的現有 UVC 控制元件和新的 V4L2 控制元件的資訊填充 uvc_xu_control_mapping 結構。

一個 UVC 控制元件可以對映到多個 V4L2 控制元件。例如，一個 UVC 平移/傾斜控制元件可以對映到單獨的平移和傾斜 V4L2 控制元件。UVC 控制元件使用“size”和“offset”欄位劃分為非重疊欄位，然後獨立對映到 V4L2 控制元件。

對於有符號整數 V4L2 控制元件，data_type 欄位應設定為 UVC_CTRL_DATA_TYPE_SIGNED。當前忽略其他值。

返回值:

成功返回 0。發生錯誤時，返回 -1 並且 errno 會被適當地設定。

ENOMEM
沒有足夠的記憶體來執行操作。

EPERM
許可權不足（需要超級使用者許可權）。

EINVAL
沒有這樣的 UVC 控制元件。

EOVERFLOW
請求的偏移量和大小會溢位 UVC 控制元件。

EEXIST
對映已存在。

資料型別:

* struct uvc_xu_control_mapping

__u32   id              V4L2 control identifier
__u8    name[32]        V4L2 control name
__u8    entity[16]      UVC extension unit GUID
__u8    selector        UVC control selector
__u8    size            V4L2 control size (in bits)
__u8    offset          V4L2 control offset (in bits)
enum v4l2_ctrl_type
        v4l2_type       V4L2 control type
enum uvc_control_data_type
        data_type       UVC control data type
struct uvc_menu_info
        *menu_info      Array of menu entries (for menu controls only)
__u32   menu_count      Number of menu entries (for menu controls only)

* struct uvc_menu_info

__u32   value           Menu entry value used by the device
__u8    name[32]        Menu entry name


* enum uvc_control_data_type

UVC_CTRL_DATA_TYPE_RAW          Raw control (byte array)
UVC_CTRL_DATA_TYPE_SIGNED       Signed integer
UVC_CTRL_DATA_TYPE_UNSIGNED     Unsigned integer
UVC_CTRL_DATA_TYPE_BOOLEAN      Boolean
UVC_CTRL_DATA_TYPE_ENUM         Enumeration
UVC_CTRL_DATA_TYPE_BITMASK      Bitmask
UVC_CTRL_DATA_TYPE_RECT         Rectangular area

11.1.5.2. UVCIOC_CTRL_QUERY - 查詢 UVC XU 控制元件¶

引數：struct uvc_xu_control_query

描述:

此 ioctl 查詢由其擴充套件單元 ID 和控制元件選擇器標識的 UVC XU 控制元件。

有許多不同的查詢可用，它們與 UVC 規範中描述的低階控制元件請求密切對應。這些請求是

UVC_GET_CUR
獲取控制元件的當前值。

UVC_GET_MIN
獲取控制元件的最小值。

UVC_GET_MAX
獲取控制元件的最大值。

UVC_GET_DEF
獲取控制元件的預設值。

UVC_GET_RES
查詢控制元件的解析度，即允許的控制元件值的步長。

UVC_GET_LEN
查詢控制元件的大小（以位元組為單位）。

UVC_GET_INFO
查詢控制元件資訊點陣圖，該點陣圖指示是否支援 get/set 請求。

UVC_SET_CUR
更新控制元件的值。

應用程式必須將“size”欄位設定為控制元件的正確長度。例外情況是 UVC_GET_LEN 和 UVC_GET_INFO 查詢，其大小必須分別設定為 2 和 1。“data”欄位必須指向足夠大的有效可寫緩衝區，以容納指示的資料位元組數。

資料直接從裝置複製，沒有任何驅動程式端處理。應用程式負責資料緩衝區格式化，包括小端/大端轉換。這對於 UVC_GET_LEN 請求的結果尤為重要，該請求始終由裝置返回為小端 16 位整數。

返回值:

成功返回 0。發生錯誤時，返回 -1 並且 errno 會被適當地設定。

ENOENT
裝置不支援給定的控制元件，或者找不到指定的擴充套件單元。

ENOBUFS
指定的緩衝區大小不正確（太大或太小）。

EINVAL
傳遞了無效的請求程式碼。

EBADRQC
給定控制元件不支援給定的請求。

EFAULT
資料指標引用了無法訪問的記憶體區域。

資料型別:

* struct uvc_xu_control_query

__u8    unit            Extension unit ID
__u8    selector        Control selector
__u8    query           Request code to send to the device
__u16   size            Control data size (in bytes)
__u8    *data           Control value

11.2. 特定於驅動程式的 V4L2 控制元件¶

uvcvideo 驅動程式實現了以下特定於 UVC 的控制元件

V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)

此控制元件確定感興趣區域 (ROI)。ROI 是一個由 struct v4l2_rect 表示的矩形區域。該矩形位於全域性感測器座標中，使用畫素單位。它獨立於視場，不受任何裁剪或縮放的影響。

使用 V4L2_CTRL_WHICH_MIN_VAL 和 V4L2_CTRL_WHICH_MAX_VAL 查詢矩形大小的範圍。

設定 ROI 允許相機針對該區域最佳化捕獲。 V4L2_CID_REGION_OF_INTEREST_AUTO 控制元件的值確定了詳細的行為。

可以在以下位置找到使用此控制元件的示例：Chrome OS USB 相機 HAL。 <https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/>

V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)

這確定了哪些（如果有）板載功能應跟蹤到由 V4L2_CID_UVD__REGION_OF_INTEREST_RECT 的當前值指定的感興趣區域。

最大值是一個指示所有支援的自動控制的掩碼。

`V4L2_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE`	設定此位會導致自動曝光跟蹤感興趣區域而不是整個影像。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS`	設定此位會導致自動光圈跟蹤感興趣區域而不是整個影像。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE`	設定此位會導致自動白平衡跟蹤感興趣區域而不是整個影像。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS`	設定此位會導致自動對焦調整跟蹤感興趣區域而不是整個影像。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT`	設定此位會導致自動人臉檢測跟蹤感興趣區域而不是整個影像。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_DETECT_AND_TRACK`	設定此位將啟用自動人臉檢測和跟蹤。驅動程式可能會更新 `V4L2_CID_REGION_OF_INTEREST_RECT` 的當前值。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_IMAGE_STABILIZATION`	設定此位將啟用自動影像穩定。驅動程式可能會更新 `V4L2_CID_REGION_OF_INTEREST_RECT` 的當前值。
`V4L2_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY`	如果可能，設定此位將啟用自動捕獲指定區域並提高質量。

Linux 核心

目錄

本頁