5.5. ioctl MEDIA_IOC_G_TOPOLOGY¶

5.5.1. 名稱¶

MEDIA_IOC_G_TOPOLOGY - 列舉圖形拓撲和圖形元素屬性

int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)

此 ioctl 的典型用法是呼叫兩次。在第一次呼叫時，應將 struct media_v2_topology 中定義的結構體清零。在返回時，如果沒有發生錯誤，此 ioctl 將返回 topology_version 以及實體、介面、pad 和連結的總數。

在第二次呼叫之前，使用者空間應分配陣列來儲存所需的圖形元素，將指向它們的指標放在 ptr_entities、ptr_interfaces、ptr_links 和/或 ptr_pads 上，並保持其他值不變。

如果 topology_version 保持不變，ioctl 應該用媒體圖形元素填充所需的陣列。

struct media_v2_topology¶
__u64	`topology_version`	媒體圖形拓撲的版本。建立圖形時，此欄位從零開始。每次新增或刪除圖形元素時，此欄位都會遞增。
__u32	`num_entities`	圖形中的實體數
__u32	`reserved1`	應用程式和驅動程式應將其設定為 0。
__u64	`ptr_entities`	指向將儲存實體陣列的記憶體區域的指標，轉換為 64 位整數。它可以為零。如果為零，ioctl 將不儲存實體。它只會更新 `num_entities`
__u32	`num_interfaces`	圖形中的介面數
__u32	`reserved2`	應用程式和驅動程式應將其設定為 0。
__u64	`ptr_interfaces`	指向將儲存介面陣列的記憶體區域的指標，轉換為 64 位整數。它可以為零。如果為零，ioctl 將不儲存介面。它只會更新 `num_interfaces`
__u32	`num_pads`	圖形中 pad 的總數
__u32	`reserved3`	應用程式和驅動程式應將其設定為 0。
__u64	`ptr_pads`	指向將儲存 pad 陣列的記憶體區域的指標，轉換為 64 位整數。它可以為零。如果為零，ioctl 將不儲存 pad。它只會更新 `num_pads`
__u32	`num_links`	圖形中資料和介面連結的總數
__u32	`reserved4`	應用程式和驅動程式應將其設定為 0。
__u64	`ptr_links`	指向將儲存連結陣列的記憶體區域的指標，轉換為 64 位整數。它可以為零。如果為零，ioctl 將不儲存連結。它只會更新 `num_links`

struct media_v2_entity¶
__u32	`id`	實體的唯一 ID。不要期望裝置的每個例項的 ID 始終相同。換句話說，不要在應用程式中硬編碼實體 ID。
char	`name`[64]	實體名稱，作為以 NULL 結尾的 UTF-8 字串。此名稱在媒體拓撲中必須是唯一的。
__u32	`function`	實體的主要功能，有關詳細資訊，請參閱媒體實體函式。
__u32	`flags`	實體標誌，有關詳細資訊，請參閱媒體實體標誌。僅當 `MEDIA_V2_ENTITY_HAS_FLAGS(media_version)` 返回 true 時才有效。`media_version` 在 struct `media_device_info` 中定義，可以使用 ioctl MEDIA_IOC_DEVICE_INFO 檢索。
__u32	`reserved`[5]	保留供將來擴充套件。驅動程式和應用程式必須將此陣列設定為零。

struct media_v2_interface¶
__u32	`id`	介面的唯一 ID。不要期望裝置的每個例項的 ID 始終相同。換句話說，不要在應用程式中硬編碼介面 ID。
__u32	`intf_type`	介面型別，有關詳細資訊，請參閱媒體介面型別。
__u32	`flags`	介面標誌。目前未使用。
__u32	`reserved`[9]	保留供將來擴充套件。驅動程式和應用程式必須將此陣列設定為零。
`struct media_v2_intf_devnode`	`devnode`	僅用於裝置節點介面。有關詳細資訊，請參閱 `media_v2_intf_devnode`。

struct media_v2_intf_devnode¶
__u32	`major`	裝置節點主編號。
__u32	`minor`	裝置節點次編號。

struct media_v2_pad¶
__u32	`id`	pad 的唯一 ID。不要期望裝置的每個例項的 ID 始終相同。換句話說，不要在應用程式中硬編碼 pad ID。
__u32	`entity_id`	此 pad 所屬的實體的唯一 ID。
__u32	`flags`	pad 標誌，有關更多詳細資訊，請參閱媒體 pad 標誌。
__u32	`index`	Pad 索引，從 0 開始。僅當 `MEDIA_V2_PAD_HAS_INDEX(media_version)` 返回 true 時才有效。`media_version` 在 struct `media_device_info` 中定義，可以使用 ioctl MEDIA_IOC_DEVICE_INFO 檢索。
__u32	`reserved`[4]	保留供將來擴充套件。驅動程式和應用程式必須將此陣列設定為零。

struct media_v2_link¶
__u32	`id`	連結的唯一 ID。不要期望裝置的每個例項的 ID 始終相同。換句話說，不要在應用程式中硬編碼連結 ID。
__u32	`source_id`	在 pad 到 pad 連結上：源 pad 的唯一 ID。在介面到實體連結上：介面的唯一 ID。
__u32	`sink_id`	在 pad 到 pad 連結上：目標 pad 的唯一 ID。在介面到實體連結上：實體的唯一 ID。
__u32	`flags`	連結標誌，有關更多詳細資訊，請參閱媒體連結標誌。
__u32	`reserved`[6]	保留供將來擴充套件。驅動程式和應用程式必須將此陣列設定為零。

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

ENOSPC: 當 num_entities、num_interfaces、num_links 或 num_pads 中的一個或多個為非零值且小於圖形中的實際元素數時，將返回此值。如果與上次呼叫此 ioctl 相比，topology_version 發生了更改，則可能會發生這種情況。使用者空間通常應該釋放指標的區域，將結構體元素清零，然後再次呼叫此 ioctl。