7.52. ioctl VIDIOC_REQBUFS

7.52.1. 名稱

VIDIOC_REQBUFS - 啟動記憶體對映、使用者指標I/O或DMA緩衝區I/O

7.52.2. 概要

VIDIOC_REQBUFS

int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)

7.52.3. 引數

fd

open() 返回的檔案描述符。

argp

指向結構體 v4l2_requestbuffers 的指標。

7.52.4. 描述

此ioctl用於啟動 記憶體對映、使用者指標 或 DMABUF 基於I/O。 記憶體對映緩衝區位於裝置記憶體中，必須在使用此ioctl分配後才能對映到應用程式的地址空間中。 使用者緩衝區由應用程式本身分配，此ioctl僅用於將驅動程式切換到使用者指標I/O模式並設定一些內部結構。 同樣，DMABUF緩衝區由應用程式透過裝置驅動程式分配，此ioctl僅將驅動程式配置為DMABUF I/O模式，而不執行任何直接分配。

為了分配裝置緩衝區，應用程式初始化結構體 v4l2_requestbuffers 結構的所有欄位。 它們將 type 欄位設定為相應的流或緩衝區型別，將 count 欄位設定為所需的緩衝區數量，memory 必須設定為請求的I/O方法，並且 reserved 陣列必須為零。 當使用指向此結構的指標呼叫ioctl時，驅動程式將嘗試分配請求的緩衝區數量，並將實際分配的數量儲存在 count 欄位中。 當驅動程式耗盡可用記憶體時，它可能小於請求的數量，甚至為零。 當驅動程式需要更多緩衝區才能正常工作時，也可能出現更大的數字。 例如，影片輸出至少需要兩個緩衝區，一個顯示，另一個由應用程式填充。

當不支援I/O方法時，ioctl返回 EINVAL 錯誤程式碼。

應用程式可以再次呼叫 ioctl VIDIOC_REQBUFS 以更改緩衝區數量。 請注意，如果任何緩衝區仍透過DMABUF對映或匯出，則只有在設定了 V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS 功能時，ioctl VIDIOC_REQBUFS 才能成功。 否則，ioctl VIDIOC_REQBUFS 將返回 EBUSY 錯誤程式碼。 如果設定了 V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS，則這些緩衝區將成為孤立緩衝區，並在取消對映或關閉匯出的DMABUF fd時釋放。 count 值為零會釋放或孤立所有緩衝區，在中止或完成任何正在進行的DMA之後，這是一個隱式的 VIDIOC_STREAMOFF。

type v4l2_requestbuffers

結構體 v4l2_requestbuffers

__u32	count	請求或授予的緩衝區數量。
__u32	type	流或緩衝區的型別，這與結構體 v4l2_format type 欄位相同。 有關有效值，請參見 v4l2_buf_type。
__u32	memory	應用程式將此欄位設定為 V4L2_MEMORY_MMAP，V4L2_MEMORY_DMABUF 或 V4L2_MEMORY_USERPTR。 請參見 v4l2_memory。
__u32	capabilities	由驅動程式設定。 如果為0，則驅動程式不支援功能。 在這種情況下，您所知道的是驅動程式保證支援 V4L2_MEMORY_MMAP 並且可能支援其他 v4l2_memory 型別。 它將不支援任何其他功能。 如果您想查詢具有最小副作用的功能，則可以呼叫此函式，將 count 設定為0，memory 設定為 V4L2_MEMORY_MMAP，並將 type 設定為緩衝區型別。 這將釋放任何先前分配的緩衝區，因此這通常是在應用程式啟動時完成的操作。
__u8	flags	指定其他緩衝區管理屬性。 請參見 記憶體一致性標誌。
__u8	reserved[3]	保留用於將來的擴充套件。

V4L2 緩衝區功能標誌

V4L2_BUF_CAP_SUPPORTS_MMAP	0x00000001	此緩衝區型別支援 V4L2_MEMORY_MMAP 流模式。
V4L2_BUF_CAP_SUPPORTS_USERPTR	0x00000002	此緩衝區型別支援 V4L2_MEMORY_USERPTR 流模式。
V4L2_BUF_CAP_SUPPORTS_DMABUF	0x00000004	此緩衝區型別支援 V4L2_MEMORY_DMABUF 流模式。
V4L2_BUF_CAP_SUPPORTS_REQUESTS	0x00000008	此緩衝區型別支援 請求。
V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS	0x00000010	核心允許在緩衝區仍透過DMABUF對映或匯出時呼叫 ioctl VIDIOC_REQBUFS。 這些孤立緩衝區將在取消對映或關閉匯出的DMABUF fd時釋放。
V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF	0x00000020	僅對無狀態解碼器有效。 如果設定，則使用者空間可以設定 V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF 標誌，以延遲返回捕獲緩衝區，直到OUTPUT時間戳更改。
V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS	0x00000040	此功能由驅動程式設定，以指示佇列支援快取和記憶體管理提示。 但是，只有在佇列用於 記憶體對映 流I/O時才有效。 請參見 V4L2_BUF_FLAG_NO_CACHE_INVALIDATE，V4L2_BUF_FLAG_NO_CACHE_CLEAN 和 V4L2_MEMORY_FLAG_NON_COHERENT。
V4L2_BUF_CAP_SUPPORTS_MAX_NUM_BUFFERS	0x00000080	如果設定，則 struct v4l2_create_buffers 中的 max_num_buffers 欄位有效。 如果未設定，則最大值為 VIDEO_MAX_FRAME 緩衝區。
V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS	0x00000100	如果設定，則支援 VIDIOC_REMOVE_BUFS。

記憶體一致性標誌

V4L2_MEMORY_FLAG_NON_COHERENT

0x00000001

緩衝區是在一致性記憶體（它將在CPU和匯流排之間自動一致）或非一致性記憶體中分配的。 後者可以提供效能提升，例如，如果緩衝區僅由相應的裝置訪問，並且CPU不讀取/寫入該緩衝區，則可以避免CPU快取同步/重新整理操作。 但是，這需要驅動程式格外小心 - 它必須在需要一致性時透過發出快取重新整理/同步來保證記憶體一致性。 如果設定了此標誌，V4L2將嘗試在非一致性記憶體中分配緩衝區。 該標誌僅在緩衝區用於 記憶體對映 I/O 並且佇列報告 V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS 功能時才生效。

7.52.5. 返回值

成功時返回0，錯誤時返回-1，並適當設定 errno 變數。 通用錯誤程式碼在 通用錯誤程式碼 章節中描述。

EINVAL

不支援緩衝區型別（type 欄位）或請求的I/O方法（memory）。