[PATCH RFC] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

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@xxxxxxxxxxxxxxxx>
---

This patch is a result of this week's discussion we had with regards to merging
a patch series from Sakari documenting the need of propagating streaming
control between sub-devices on some complex mc-centric devices.

One big gap on our documentation popped up: while we have distinct behavior
for mc-centric and devnode-centric types of V4L2 devices, we never clearly
documented about that.

This RFC patch is a first attempt to have a definition of those types, and to
standardize the names we use to distinguish between those types.

Comments are welcome.


 Documentation/media/uapi/v4l/open.rst | 37 +++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..9cf4f74c466a 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -6,6 +6,43 @@
 Opening and Closing Devices
 ***************************
 
+Types of V4L2 devices
+=====================
+
+V4L2 devices are usually complex: they're implemented via a main driver and
+several other drivers. The main driver always exposes a V4L2 device node
+(see :ref:`v4l2_device_naming`). The other devices are called **sub-devices**.
+They are usually controlled via a serial bus (I2C or SMBus).
+
+When V4L2 started, there was only one type of device, fully controlled via
+V4L2 device nodes. We call those devices as **devnode-centric devices**.
+Since the end of 2010, a new type of V4L2 device was added, in order to
+support complex devices that are common on embedded systems. Those devices
+are controlled mainly via the media controller. So, they're called:
+**mc-centric devices**.
+
+On a **devnode-centric device**, the device and their corresponding hardware
+pipelines are controlled via the V4L2 device node. They may optionally
+expose the hardware pipelines via the
+:ref:`media controller API <media_controller>`.
+
+On a **mc-centric device**, before using the V4L2 device, it is required to
+set the hardware pipelines via the
+:ref:`media controller API <media_controller>`. On those devices, the
+sub-devices' configuration can be controlled via the
+:ref:`sub-device API <subdev>`, with creates one device node per sub device.
+On such devices, the V4L2 device node is mainly responsible for controlling
+the streaming features, while the media controller and the subdevices device
+nodes are responsible for configuring the hardware.
+
+.. note::
+
+   Currently, it is forbidden for a **devnode-centric device** to expose
+   subdevices via :ref:`sub-device API <subdev>`, although this might
+   change in the future.
+
+
+.. _v4l2_device_naming:
 
 Device Naming
 =============
-- 
2.13.3