From 8601494e0ec0a7697230b2abca25d786b793341b Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 29 Jun 2018 07:31:20 -0400 Subject: media: media-ioc-enum-entities.rst/-g-topology.rst: clarify ID/name usage Mention that IDs should not be hardcoded in applications and that the entity name must be unique within the media topology. Signed-off-by: Hans Verkuil Reviewed-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- .../media/uapi/mediactl/media-ioc-enum-entities.rst | 9 ++++++--- .../media/uapi/mediactl/media-ioc-g-topology.rst | 19 ++++++++++++++----- 2 files changed, 20 insertions(+), 8 deletions(-) (limited to 'Documentation/media/uapi') diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst index 961466ae821d..fc2e39c070c9 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst @@ -62,15 +62,18 @@ id's until they get an error. - ``id`` - - - - Entity id, set by the application. When the id is or'ed with + - Entity ID, set by the application. When the ID is or'ed with ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns - the first entity with a larger id. + the first entity with a larger ID. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode entity IDs in an application. * - char - ``name``\ [32] - - - - Entity name as an UTF-8 NULL-terminated string. + - Entity name as an UTF-8 NULL-terminated string. This name must be unique + within the media topology. * - __u32 - ``type`` diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst index d6f41a8e307f..bac128c7eda9 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -131,11 +131,14 @@ desired arrays with the media graph elements. * - __u32 - ``id`` - - Unique ID for the entity. + - Unique ID for the entity. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode entity IDs in an application. * - char - ``name``\ [64] - - Entity name as an UTF-8 NULL-terminated string. + - Entity name as an UTF-8 NULL-terminated string. This name must be unique + within the media topology. * - __u32 - ``function`` @@ -166,7 +169,9 @@ desired arrays with the media graph elements. * - __u32 - ``id`` - - Unique ID for the interface. + - Unique ID for the interface. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode interface IDs in an application. * - __u32 - ``intf_type`` @@ -215,7 +220,9 @@ desired arrays with the media graph elements. * - __u32 - ``id`` - - Unique ID for the pad. + - Unique ID for the pad. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode pad IDs in an application. * - __u32 - ``entity_id`` @@ -249,7 +256,9 @@ desired arrays with the media graph elements. * - __u32 - ``id`` - - Unique ID for the link. + - Unique ID for the link. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode link IDs in an application. * - __u32 - ``source_id`` -- cgit v1.2.3-59-g8ed1b