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 和实体、接口、焊盘和链接的总数。

在第二次调用之前，用户空间应分配数组以存储所需的图元素，将指向它们的指针放在 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`	图中焊盘的总数
__u32	`reserved3`	应用程序和驱动程序应将其设置为 0。
__u64	`ptr_pads`	指向将存储焊盘数组的内存区域的指针，转换为 64 位整数。它可以为零。如果为零，ioctl 将不会存储焊盘。它只会更新 `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]	实体名称，作为 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`	焊盘的唯一 ID。不要期望设备的每个实例的 ID 始终相同。换句话说，不要在应用程序中硬编码焊盘 ID。
__u32	`entity_id`	此焊盘所属实体的唯一 ID。
__u32	`flags`	焊盘标志，详见媒体焊盘标志以了解更多详细信息。
__u32	`index`	焊盘索引，从 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`	在焊盘到焊盘链接上：源焊盘的唯一 ID。在接口到实体链接上：接口的唯一 ID。
__u32	`sink_id`	在焊盘到焊盘链接上：接收器焊盘的唯一 ID。在接口到实体链接上：实体的唯一 ID。
__u32	`flags`	链接标志，详见媒体链接标志以了解更多详细信息。
__u32	`reserved`[6]	保留供将来扩展。驱动程序和应用程序必须将此数组设置为零。

成功时返回 0，错误时返回 -1，并适当设置 errno 变量。通用错误代码在通用错误代码章节中描述。

ENOSPC: 当 num_entities、num_interfaces、num_links 或 num_pads 中的一个或多个非零且小于图中元素的实际数量时，将返回此值。如果与上次调用此 ioctl 时相比，topology_version 发生了更改，则可能会发生这种情况。用户空间通常应释放指针的区域，将结构体元素清零并再次调用此 ioctl。