[PATCH v2 0/3] document types of hardware control for V4L2

[PATCH v2 0/3] document types of hardware control for V4L2

[Mauro Carvalho Chehab]

On 2010, we introduced a new way to control complex V4L2 devices used
on embedded systems, but this was never documented, nor it is possible
for an userspace applicatin to detect the kind of control a device supports.

This series fill the gap.

Mauro Carvalho Chehab (3):
  media: open.rst: better document device node naming
  media: open.rst: document devnode-centric and mc-centric types
  media: videodev2: add a flag for MC-centric devices

-

v2:

- added a patch at the beginning of the series better defining the
  device node naming rules;
- better defined the differenes between device hardware and V4L2 device node
  as suggested by Laurent and with changes proposed by Hans and Sakari
- changed the caps flag to indicate MC-centric devices
- removed the final patch that would use the new caps flag. I'll write it
  once we agree on the new caps flag.

 Documentation/media/uapi/v4l/open.rst            | 104 +++++++++++++++++++++--
 Documentation/media/uapi/v4l/vidioc-querycap.rst |   5 ++
 include/uapi/linux/videodev2.h                   |   2 +
 3 files changed, 106 insertions(+), 5 deletions(-)

-- 
2.13.3

[PATCH v2 1/3] media: open.rst: better document device node naming

[Mauro Carvalho Chehab]

Right now, only kAPI documentation describes the device naming.
However, such description is needed at the uAPI too. Add it,
and describe how to get an unique identify for a given device.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 40 ++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..9b98d10d5153 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,12 +7,12 @@ Opening and Closing Devices
 ***************************
 
 
-Device Naming
-=============
+V4L2 Device Node Naming
+=======================
 
 V4L2 drivers are implemented as kernel modules, loaded manually by the
 system administrator or automatically when a device is first discovered.
-The driver modules plug into the "videodev" kernel module. It provides
+The driver modules plug into the ``videodev`` kernel module. It provides
 helper functions and a common application interface specified in this
 document.
 
@@ -20,8 +20,38 @@ Each driver thus loaded registers one or more device nodes with major
 number 81 and a minor number between 0 and 255. Minor numbers are
 allocated dynamically unless the kernel is compiled with the kernel
 option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
-are allocated in ranges depending on the device node type (video, radio,
-etc.).
+are allocated in ranges depending on the device node type.
+
+The existing V4L2 device node types are:
+
+======================== ======================================================
+Default device node name Usage
+======================== ======================================================
+``/dev/videoX``		 Video input/output devices
+``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
+``/dev/radioX``		 Radio tuners
+``/dev/swradioX``	 Software Defined Radio tuners
+``/dev/v4l-touchX``	 Touch sensors
+======================== ======================================================
+
+Where ``X`` is a non-negative number.
+
+.. note::
+
+   1. The actual device node name is system-dependent, as udev rules may apply.
+   2. There's not warranty that ``X`` will remain the same for the same
+      device, as the number depends on the device driver's probe order.
+      If you need an unique name, udev default rules produce
+      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` that can use to uniquelly
+      identify a V4L2 device node::
+
+	$ tree /dev/v4l
+	/dev/v4l
+	├── by-id
+	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
+	└── by-path
+	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
+
 
 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
 options to select specific video/radio/vbi node numbers. This allows the
-- 
2.13.3

Re: [PATCH v2 1/3] media: open.rst: better document device node naming

[Mauro Carvalho Chehab]

Em Fri, 25 Aug 2017 09:52:40 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> Right now, only kAPI documentation describes the device naming.
> However, such description is needed at the uAPI too. Add it,
> and describe how to get an unique identify for a given device.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 40 ++++++++++++++++++++++++++++++-----
>  1 file changed, 35 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index afd116edb40d..9b98d10d5153 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,12 +7,12 @@ Opening and Closing Devices
>  ***************************
>  
>  
> -Device Naming
> -=============
> +V4L2 Device Node Naming
> +=======================
>  
>  V4L2 drivers are implemented as kernel modules, loaded manually by the
>  system administrator or automatically when a device is first discovered.
> -The driver modules plug into the "videodev" kernel module. It provides
> +The driver modules plug into the ``videodev`` kernel module. It provides
>  helper functions and a common application interface specified in this
>  document.
>  
> @@ -20,8 +20,38 @@ Each driver thus loaded registers one or more device nodes with major
>  number 81 and a minor number between 0 and 255. Minor numbers are
>  allocated dynamically unless the kernel is compiled with the kernel
>  option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
> -are allocated in ranges depending on the device node type (video, radio,
> -etc.).
> +are allocated in ranges depending on the device node type.
> +
> +The existing V4L2 device node types are:
> +
> +======================== ======================================================
> +Default device node name Usage
> +======================== ======================================================
> +``/dev/videoX``		 Video input/output devices
> +``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
> +``/dev/radioX``		 Radio tuners
> +``/dev/swradioX``	 Software Defined Radio tuners
> +``/dev/v4l-touchX``	 Touch sensors
> +======================== ======================================================
> +
> +Where ``X`` is a non-negative number.
> +
> +.. note::
> +
> +   1. The actual device node name is system-dependent, as udev rules may apply.
> +   2. There's not warranty that ``X`` will remain the same for the same
> +      device, as the number depends on the device driver's probe order.
> +      If you need an unique name, udev default rules produce
> +      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` that can use to uniquelly
> +      identify a V4L2 device node::
> +

In time:

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index c6ab5fef4443..3b93a32777c2 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -106,8 +106,8 @@ Where ``X`` is a non-negative number.
    2. There's not warranty that ``X`` will remain the same for the same
       device, as the number depends on the device driver's probe order.
       If you need an unique name, udev default rules produce
-      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` that can use to uniquelly
-      identify a V4L2 device node::
+      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` that can be used to
+      uniquely identify a V4L2 device node::
 
        $ tree /dev/v4l
        /dev/v4l


> +	$ tree /dev/v4l
> +	/dev/v4l
> +	├── by-id
> +	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
> +	└── by-path
> +	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
> +
>  
>  Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
>  options to select specific video/radio/vbi node numbers. This allows the



Thanks,
Mauro

Re: [PATCH v2 1/3] media: open.rst: better document device node naming

[Hans Verkuil]

On 25/08/17 14:52, Mauro Carvalho Chehab wrote:
> Right now, only kAPI documentation describes the device naming.
> However, such description is needed at the uAPI too. Add it,
> and describe how to get an unique identify for a given device.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 40 ++++++++++++++++++++++++++++++-----
>  1 file changed, 35 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index afd116edb40d..9b98d10d5153 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,12 +7,12 @@ Opening and Closing Devices
>  ***************************
>  
>  
> -Device Naming
> -=============
> +V4L2 Device Node Naming
> +=======================
>  
>  V4L2 drivers are implemented as kernel modules, loaded manually by the
>  system administrator or automatically when a device is first discovered.
> -The driver modules plug into the "videodev" kernel module. It provides
> +The driver modules plug into the ``videodev`` kernel module. It provides
>  helper functions and a common application interface specified in this
>  document.
>  
> @@ -20,8 +20,38 @@ Each driver thus loaded registers one or more device nodes with major
>  number 81 and a minor number between 0 and 255. Minor numbers are
>  allocated dynamically unless the kernel is compiled with the kernel
>  option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
> -are allocated in ranges depending on the device node type (video, radio,
> -etc.).
> +are allocated in ranges depending on the device node type.
> +
> +The existing V4L2 device node types are:
> +
> +======================== ======================================================
> +Default device node name Usage
> +======================== ======================================================
> +``/dev/videoX``		 Video input/output devices
> +``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
> +``/dev/radioX``		 Radio tuners

add: and modulators.

> +``/dev/swradioX``	 Software Defined Radio tuners

Ditto.

> +``/dev/v4l-touchX``	 Touch sensors
> +======================== ======================================================
> +
> +Where ``X`` is a non-negative number.
> +
> +.. note::
> +
> +   1. The actual device node name is system-dependent, as udev rules may apply.
> +   2. There's not warranty that ``X`` will remain the same for the same

"There is no"

> +      device, as the number depends on the device driver's probe order.
> +      If you need an unique name, udev default rules produce
> +      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` that can use to uniquelly

      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing links
	that be can used to uniquely

> +      identify a V4L2 device node::
> +
> +	$ tree /dev/v4l
> +	/dev/v4l
> +	├── by-id
> +	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
> +	└── by-path
> +	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
> +
>  
>  Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
>  options to select specific video/radio/vbi node numbers. This allows the
> 

With these changes:

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Thanks!

	Hans

[PATCH v2 2/3] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

From: "mchehab@s-opensource.com" <mchehab@s-opensource.com>

When we added support for omap3, back in 2010, we added a new
type of V4L2 devices that aren't fully controlled via the V4L2
device node. Yet, we never made it clear, at the V4L2 spec,
about the differences between both types.

Let's document them with the current implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 53 +++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 9b98d10d5153..bbd1887f83a0 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -6,6 +6,59 @@
 Opening and Closing Devices
 ***************************
 
+Types of V4L2 hardware control
+==============================
+
+V4L2 hardware is usually complex: support for the hardware is implemented
+via a main driver (also known as bridge driver) and often several
+additional drivers. The main driver always exposes one or
+more **V4L2 device nodes** (see :ref:`v4l2_device_naming`).
+
+The other drivers are called **V4L2 sub-devices** and provide control to
+other parts of the hardware usually connected via a serial bus (like
+I²C, SMBus or SPI). Depending on the main driver, they can be implicitly
+controlled directly by the main driver or explicitly via
+the **V4L2 sub-device API** (see :ref:`subdev`).
+
+When V4L2 was originally designed, there was only one type of hardware
+control. The entire V4L2 hardware is controlled via the
+**V4L2 device nodes**. We refer to this kind of control as
+**V4L2 device node centric** (or, simply, **vdev-centric**).
+
+Since the end of 2010, a new type of V4L2 hardware control was added, in
+order to support complex devices that are common for embedded systems.
+Those hardware are controlled mainly via the media controller and
+sub-devices. So, they are called: **Media controller centric**
+(or, simply, "**MC-centric**").
+
+For **vdev-centric** hardware control, the hardware is controlled via
+the **V4L2 device nodes**. They may optionally support the
+:ref:`media controller API <media_controller>` as well, in order to let
+the application to know with device nodes are available.
+
+.. note::
+
+   A **vdev-centric** may optionally expose V4L2 sub-devices via
+   :ref:`sub-device API <subdev>`. In that case, it has to implement
+   the :ref:`media controller API <media_controller>` as well.
+
+For **MC-centric** hardware control, before using the V4L2 hardware,
+it is required to set the pipelines via the
+:ref:`media controller API <media_controller>`. For those devices, the
+sub-devices' configuration can be controlled via the
+:ref:`sub-device API <subdev>`, whith creates one device node
+per sub-device.
+
+In summary, for **MC-centric** hardware control:
+
+- The **V4L2 device** node is responsible for controlling the streaming
+  features;
+- The **media controller device** is responsible to setup the pipelines;
+- The **V4L2 sub-devices** are responsible for sub-device
+  specific settings.
+
+
+.. _v4l2_device_naming:
 
 V4L2 Device Node Naming
 =======================
-- 
2.13.3

Re: [PATCH v2 2/3] media: open.rst: document devnode-centric and mc-centric types

[Hans Verkuil]

On 25/08/17 14:52, Mauro Carvalho Chehab wrote:
> From: "mchehab@s-opensource.com" <mchehab@s-opensource.com>
> 
> When we added support for omap3, back in 2010, we added a new
> type of V4L2 devices that aren't fully controlled via the V4L2
> device node. Yet, we never made it clear, at the V4L2 spec,
> about the differences between both types.
> 
> Let's document them with the current implementation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 53 +++++++++++++++++++++++++++++++++++
>  1 file changed, 53 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 9b98d10d5153..bbd1887f83a0 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -6,6 +6,59 @@
>  Opening and Closing Devices
>  ***************************
>  
> +Types of V4L2 hardware control
> +==============================
> +
> +V4L2 hardware is usually complex: support for the hardware is implemented
> +via a main driver (also known as bridge driver) and often several
> +additional drivers. The main driver always exposes one or
> +more **V4L2 device nodes** (see :ref:`v4l2_device_naming`).
> +
> +The other drivers are called **V4L2 sub-devices** and provide control to
> +other parts of the hardware usually connected via a serial bus (like
> +I²C, SMBus or SPI). Depending on the main driver, they can be implicitly
> +controlled directly by the main driver or explicitly via
> +the **V4L2 sub-device API** (see :ref:`subdev`).
> +
> +When V4L2 was originally designed, there was only one type of hardware
> +control. The entire V4L2 hardware is controlled via the
> +**V4L2 device nodes**. We refer to this kind of control as
> +**V4L2 device node centric** (or, simply, **vdev-centric**).
> +
> +Since the end of 2010, a new type of V4L2 hardware control was added, in

Just drop 'the end of'.

s/, in/ in/

> +order to support complex devices that are common for embedded systems.
> +Those hardware are controlled mainly via the media controller and

Such hardware is

> +sub-devices. So, they are called: **Media controller centric**
> +(or, simply, "**MC-centric**").
> +
> +For **vdev-centric** hardware control, the hardware is controlled via
> +the **V4L2 device nodes**. They may optionally support the
> +:ref:`media controller API <media_controller>` as well, in order to let
> +the application to know with device nodes are available.

to know with -> know which

> +
> +.. note::
> +
> +   A **vdev-centric** may optionally expose V4L2 sub-devices via

I propose adding 'also' before 'expose' to indicate that it is in
addition to the V4L2 device nodes that were mentioned in the previous
paragraph.

> +   :ref:`sub-device API <subdev>`. In that case, it has to implement
> +   the :ref:`media controller API <media_controller>` as well.
> +
> +For **MC-centric** hardware control, before using the V4L2 hardware,
> +it is required to set the pipelines via the

I'd reword this a bit:

For **MC-centric** hardware control it is required to configure the pipelines
via the :ref:`media controller API <media_controller>` before the hardware can be used.

> +:ref:`media controller API <media_controller>`. For those devices, the

s/those/such/

> +sub-devices' configuration can be controlled via the
> +:ref:`sub-device API <subdev>`, whith creates one device node

s/whith/which/

> +per sub-device.
> +
> +In summary, for **MC-centric** hardware control:
> +
> +- The **V4L2 device** node is responsible for controlling the streaming
> +  features;
> +- The **media controller device** is responsible to setup the pipelines;
> +- The **V4L2 sub-devices** are responsible for sub-device
> +  specific settings.
> +
> +
> +.. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming
>  =======================
> 

The only thing I am not sure about is vdev-centric vs V4L2-centric. 'Laziness while
typing' is not a convincing argument :-)

Regards,

	Hans

Re: [PATCH v2 2/3] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

Em Fri, 25 Aug 2017 15:42:21 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 25/08/17 14:52, Mauro Carvalho Chehab wrote:
> > From: "mchehab@s-opensource.com" <mchehab@s-opensource.com>
> > 
> > When we added support for omap3, back in 2010, we added a new
> > type of V4L2 devices that aren't fully controlled via the V4L2
> > device node. Yet, we never made it clear, at the V4L2 spec,
> > about the differences between both types.
> > 
> > Let's document them with the current implementation.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/media/uapi/v4l/open.rst | 53 +++++++++++++++++++++++++++++++++++
> >  1 file changed, 53 insertions(+)
> > 
> > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> > index 9b98d10d5153..bbd1887f83a0 100644
> > --- a/Documentation/media/uapi/v4l/open.rst
> > +++ b/Documentation/media/uapi/v4l/open.rst
> > @@ -6,6 +6,59 @@
> >  Opening and Closing Devices
> >  ***************************
> >  
> > +Types of V4L2 hardware control
> > +==============================
> > +
> > +V4L2 hardware is usually complex: support for the hardware is implemented
> > +via a main driver (also known as bridge driver) and often several
> > +additional drivers. The main driver always exposes one or
> > +more **V4L2 device nodes** (see :ref:`v4l2_device_naming`).
> > +
> > +The other drivers are called **V4L2 sub-devices** and provide control to
> > +other parts of the hardware usually connected via a serial bus (like
> > +I²C, SMBus or SPI). Depending on the main driver, they can be implicitly
> > +controlled directly by the main driver or explicitly via
> > +the **V4L2 sub-device API** (see :ref:`subdev`).
> > +
> > +When V4L2 was originally designed, there was only one type of hardware
> > +control. The entire V4L2 hardware is controlled via the
> > +**V4L2 device nodes**. We refer to this kind of control as
> > +**V4L2 device node centric** (or, simply, **vdev-centric**).
> > +
> > +Since the end of 2010, a new type of V4L2 hardware control was added, in  
> 
> Just drop 'the end of'.
> 
> s/, in/ in/

I anded by changing it to:

	Later (kernel 2.6.39),

> 
> > +order to support complex devices that are common for embedded systems.
> > +Those hardware are controlled mainly via the media controller and  
> 
> Such hardware is
> 
> > +sub-devices. So, they are called: **Media controller centric**
> > +(or, simply, "**MC-centric**").
> > +
> > +For **vdev-centric** hardware control, the hardware is controlled via
> > +the **V4L2 device nodes**. They may optionally support the
> > +:ref:`media controller API <media_controller>` as well, in order to let
> > +the application to know with device nodes are available.  
> 
> to know with -> know which
> 
> > +
> > +.. note::
> > +
> > +   A **vdev-centric** may optionally expose V4L2 sub-devices via  
> 
> I propose adding 'also' before 'expose' to indicate that it is in
> addition to the V4L2 device nodes that were mentioned in the previous
> paragraph.
> 
> > +   :ref:`sub-device API <subdev>`. In that case, it has to implement
> > +   the :ref:`media controller API <media_controller>` as well.
> > +
> > +For **MC-centric** hardware control, before using the V4L2 hardware,
> > +it is required to set the pipelines via the  
> 
> I'd reword this a bit:
> 
> For **MC-centric** hardware control it is required to configure the pipelines
> via the :ref:`media controller API <media_controller>` before the hardware can be used.
> 
> > +:ref:`media controller API <media_controller>`. For those devices, the  
> 
> s/those/such/
> 
> > +sub-devices' configuration can be controlled via the
> > +:ref:`sub-device API <subdev>`, whith creates one device node  
> 
> s/whith/which/
> 
> > +per sub-device.
> > +
> > +In summary, for **MC-centric** hardware control:
> > +
> > +- The **V4L2 device** node is responsible for controlling the streaming
> > +  features;
> > +- The **media controller device** is responsible to setup the pipelines;
> > +- The **V4L2 sub-devices** are responsible for sub-device
> > +  specific settings.
> > +
> > +
> > +.. _v4l2_device_naming:
> >  
> >  V4L2 Device Node Naming
> >  =======================

Changes done. I'll place on a new version of this series.

> >   
> 
> The only thing I am not sure about is vdev-centric vs V4L2-centric. 'Laziness while
> typing' is not a convincing argument :-)

Despite the laziness of playing a lot with shifts to type V4L2-centric,
the thing that bothers me with V4L2 is that the subdev API is part of
V4L2 spec. So, IMHO, it is still a confusing name.

As this actually refers to "V4L2 Device Node", with is now properly
specified (due to patch 1/3), "vdev" is a good shortcut for it.

Let's reverse the question: what's wrong with "vdev-centric"?

Thanks,
Mauro

[PATCH v2 3/3] media: videodev2: add a flag for MC-centric devices

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

As both vdev-centric and MC-centric devices may implement the
same APIs, we need a flag to allow userspace to distinguish
between them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst            | 11 +++++++++++
 Documentation/media/uapi/v4l/vidioc-querycap.rst |  5 +++++
 include/uapi/linux/videodev2.h                   |  2 ++
 3 files changed, 18 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index bbd1887f83a0..c6ab5fef4443 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -6,6 +6,10 @@
 Opening and Closing Devices
 ***************************
 
+
+.. _v4l2_hardware_control:
+
+
 Types of V4L2 hardware control
 ==============================
 
@@ -49,6 +53,13 @@ sub-devices' configuration can be controlled via the
 :ref:`sub-device API <subdev>`, whith creates one device node
 per sub-device.
 
+.. attention::
+
+   Devices that require **mc-centric** hardware control should report
+   a ``V4L2_MC_CENTRIC`` :c:type:`v4l2_capability` flag
+   (see :ref:`VIDIOC_QUERYCAP`).
+
+
 In summary, for **MC-centric** hardware control:
 
 - The **V4L2 device** node is responsible for controlling the streaming
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index 12e0d9a63cd8..2b08723375bc 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -252,6 +252,11 @@ specification the ioctl returns an ``EINVAL`` error code.
     * - ``V4L2_CAP_TOUCH``
       - 0x10000000
       - This is a touch device.
+    * - ``V4L2_MC_CENTRIC``
+      - 0x20000000
+      - Indicates that the device require **mc-centric** hardware
+        control, and thus can't be used by **v4l2-centric** applications.
+        See :ref:`v4l2_hardware_control` for more details.
     * - ``V4L2_CAP_DEVICE_CAPS``
       - 0x80000000
       - The driver fills the ``device_caps`` field. This capability can
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 45cf7359822c..7b490fe97980 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -460,6 +460,8 @@ struct v4l2_capability {
 
 #define V4L2_CAP_TOUCH                  0x10000000  /* Is a touch device */
 
+#define V4L2_CAP_MC_CENTRIC             0x20000000  /* Device require mc-centric hardware control */
+
 #define V4L2_CAP_DEVICE_CAPS            0x80000000  /* sets device capabilities field */
 
 /*
-- 
2.13.3