[libcamera-devel] [PATCH v3 2/5] media: media.h: Add new media link type

[Jean-Michel Hautbois]

Hi !

Thanks for the patch !

On 02/03/2022 23:03, Daniel Scally wrote:
> To describe in the kernel the connection between devices and their
> supporting peripherals (for example, a camera sensor and the vcm
> driving the focusing lens for it), add a new type of media link
> to introduce the concept of these ancillary links.
> 
> Add some elements to the uAPI documentation to explain the new link
> type, their purpose and some aspects of their current implementation.
> 
> Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> Signed-off-by: Daniel Scally <djrscally at gmail.com>

Reviewed-by: Jean-Michel Hautbois <jeanmichel.hautbois at ideasonboard.com>
> ---
> 
> Changes since v1:
> 
> 	- None
> 
> changes since the rfc:
> 
> 	- Split out into its own patch (mostly so it can be followed by patch
> 	#3, which corrects some media-core code that is otherwise broken by the
> 	new links)
> 
>   .../media/mediactl/media-controller-model.rst   |  6 ++++++
>   .../media/mediactl/media-types.rst              | 17 ++++++++++++-----
>   include/uapi/linux/media.h                      |  1 +
>   3 files changed, 19 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/mediactl/media-controller-model.rst b/Documentation/userspace-api/media/mediactl/media-controller-model.rst
> index 222cb99debb5..78bfdfb2a322 100644
> --- a/Documentation/userspace-api/media/mediactl/media-controller-model.rst
> +++ b/Documentation/userspace-api/media/mediactl/media-controller-model.rst
> @@ -33,3 +33,9 @@ are:
>   
>   -  An **interface link** is a point-to-point bidirectional control
>      connection between a Linux Kernel interface and an entity.
> +
> +- An **ancillary link** is a point-to-point connection denoting that two
> +  entities form a single logical unit. For example this could represent the
> +  fact that a particular camera sensor and lens controller form a single
> +  physical module, meaning this lens controller drives the lens for this
> +  camera sensor.
> \ No newline at end of file
> diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst
> index 0a26397bd01d..60747251d409 100644
> --- a/Documentation/userspace-api/media/mediactl/media-types.rst
> +++ b/Documentation/userspace-api/media/mediactl/media-types.rst
> @@ -412,14 +412,21 @@ must be set for every pad.
>   	  is set by drivers and is read-only for applications.
>   
>       *  -  ``MEDIA_LNK_FL_LINK_TYPE``
> -       -  This is a bitmask that defines the type of the link. Currently,
> -	  two types of links are supported:
> +       -  This is a bitmask that defines the type of the link. The following
> +	  link types are currently supported:
>   
>   	  .. _MEDIA-LNK-FL-DATA-LINK:
>   
> -	  ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
> +	  ``MEDIA_LNK_FL_DATA_LINK`` for links that represent a data connection
> +     between two pads.
>   
>   	  .. _MEDIA-LNK-FL-INTERFACE-LINK:
>   
> -	  ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
> -	  interface and an entity
> +	  ``MEDIA_LNK_FL_INTERFACE_LINK`` for links that associate an entity to its
> +     interface.
> +
> +	  .. _MEDIA-LNK-FL-ANCILLARY-LINK:
> +
> +	  ``MEDIA_LNK_FL_ANCILLARY_LINK`` for links that represent a physical
> +     relationship between two entities. The link may or may not be ummutable, so
> +     applications must not assume either case.
> \ No newline at end of file
> diff --git a/include/uapi/linux/media.h b/include/uapi/linux/media.h
> index 200fa8462b90..afbae7213d35 100644
> --- a/include/uapi/linux/media.h
> +++ b/include/uapi/linux/media.h
> @@ -226,6 +226,7 @@ struct media_pad_desc {
>   #define MEDIA_LNK_FL_LINK_TYPE			(0xf << 28)
>   #  define MEDIA_LNK_FL_DATA_LINK		(0 << 28)
>   #  define MEDIA_LNK_FL_INTERFACE_LINK		(1 << 28)
> +#  define MEDIA_LNK_FL_ANCILLARY_LINK		(2 << 28)
>   
>   struct media_link_desc {
>   	struct media_pad_desc source;