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。