[PATCH v7 0/7] document types of hardware control for V4L2

[PATCH v7 0/7] document types of hardware control for V4L2

[Mauro Carvalho Chehab]

On Kernel 2.6.39, the omap3 driver was introduced together with a new way
to control complex V4L2 devices used on embedded systems, but this was
never documented, as the original idea were to have "soon" support for
standard apps to use it as well, via libv4l, but that didn't happen so far.

Also, it is not possible for an userspace applicatin to detect the kind of
control a device supports.

This series fill the gap, by documenting the new type of hardware
control and adding a way for userspace to detect if the device can be
used or not by an standard V4L2 application.

Notes:
====

1) For the sake of better review, this series start with the addition of a
glossary, as requested by Laurent. Please notice, however, that
the glossary there references some new captions that will only be added
by subsequent patches. So, when this series get applied, the glossary
patch should actually be merged after the patches that introduce those
new captions, in order to avoid warnings for non-existing references.

2) This series doesn't contain patches that actually use the new flag.
This will be added after such patch gets reviewed.

v7:
- Altered some nomenclature at the glossary as suggested by Hans
  and used git-filter to change it on all patches.

v6:
- Some editorial changes based on comments from Hans and Sakari.

v5:
- Added more terms to the glossary
- Adjusted some wording as proposed by Hans on a few patches
  and added his ack on others

v4:

- Addressed Hans comments for v2;
- Fixed broken references at the glossary.rst

v3:

- Add a glossary to be used by the new documentation about hardware control;
- Add a patch removing minor number range
- Use glossary terms at open.rst
- Split the notice about subdev-API on vdev-centric, as this change
   will require further discussions.

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.

Mauro Carvalho Chehab (7):
  media: add glossary.rst with a glossary of terms used at V4L2 spec
  media: open.rst: better document device node naming
  media: open.rst: remove the minor number range
  media: open.rst: document devnode-centric and mc-centric types
  media: open.rst: Adjust some terms to match the glossary
  media: videodev2: add a flag for MC-centric devices
  media: open.rst: add a notice about subdev-API on vdev-centric

 Documentation/media/uapi/v4l/glossary.rst        | 136 +++++++++++++++++++++++
 Documentation/media/uapi/v4l/open.rst            | 119 +++++++++++++++++---
 Documentation/media/uapi/v4l/v4l2.rst            |   1 +
 Documentation/media/uapi/v4l/vidioc-querycap.rst |   5 +
 Documentation/media/videodev2.h.rst.exceptions   |   1 +
 include/uapi/linux/videodev2.h                   |   2 +
 6 files changed, 250 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

-- 
2.13.5

[PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Add a glossary of terms for V4L2, as several concepts are complex
enough to cause misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
 Documentation/media/uapi/v4l/v4l2.rst     |   1 +
 2 files changed, 137 insertions(+)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
new file mode 100644
index 000000000000..b6767da1a46e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,136 @@
+========
+Glossary
+========
+
+.. note::
+
+   This goal of section is to standardize the terms used within the V4L2
+   documentation. It is written incrementally as they are standardized in
+   the V4L2 documentation. So, it is a Work In Progress.
+
+.. Please keep the glossary entries in alphabetical order
+
+.. glossary::
+
+    Bridge driver
+	The same as V4L2 main driver.
+
+    Device Node
+	A character device node in the file system used to control and do
+	input/output data transfers from/to a Kernel driver.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational needs of digital signal processing.
+
+    Driver
+	The part of the Linux Kernel that implements support
+	for a hardware component.
+
+    Field-programmable Gate Array - FPGA
+	A field-programmable gate array (FPGA) is an integrated circuit
+	designed to be configured by a customer or a designer after
+	manufacturing.
+
+	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+    Hardware component
+	A subset of the media hardware. For example an I²C or SPI device,
+	or an IP block inside an SoC or FPGA.
+
+    Image Signal Processor - ISP
+	A specialised processor that implements a set of algorithms for
+	processing image data. ISPs may implement algorithms for lens
+	shading correction, demosaic, scaling and pixel format conversion
+	as well as produce statistics for the use of the control
+	algorithms (e.g. automatic exposure, white balance and focus).
+
+    Inter-Integrated Circuit - I²C
+	A  multi-master, multi-slave, packet switched, single-ended,
+	serial computer bus used to control V4L2 sub-devices.
+
+	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+    Integrated circuit - IC
+	A set of electronic circuits on one small flat piece of
+	semiconductor material, normally silicon.
+
+	Also known as chip.
+
+    Intellectual property core - IP core
+	In electronic design a semiconductor intellectual property core,
+	is a reusable unit of logic, cell, or integrated circuit layout
+	design that is the intellectual property of one party.
+	IP cores may be licensed to another party or can be owned
+	and used by a single party alone.
+
+	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
+
+    IP block
+	The same as IP core.
+
+    MC-centric
+	V4L2 hardware that requires a Media controller.
+
+	See :ref:`v4l2_hardware_control`.
+
+    Media Controller
+	An API designed to expose and control devices and sub-devices
+	relationships to applications.
+
+	See :ref:`media_controller`.
+
+    Media hardware
+	A group of hardware components that together make a larger
+	user-facing functional media hardware. For instance the SoC ISP IP
+	cores and external camera sensors together make a
+	camera media hardware.
+
+    Media hardware control
+	Type of control for a media hardware supported by V4L2 drivers.
+
+	See :ref:`v4l2_hardware_control`.
+
+    Microprocessor
+	An electronic circuitry that carries out the instructions
+	of a computer program by performing the basic arithmetic, logical,
+	control and input/output (I/O) operations specified by the
+	instructions on a single integrated circuit.
+
+    SMBus
+	A subset of I²C, with defines a stricter usage of the bus.
+
+    Serial Peripheral Interface Bus - SPI
+	Synchronous serial communication interface specification used for
+	short distance communication, primarily in embedded systems.
+
+    System on a Chip - SoC
+	An integrated circuit that integrates all components of a computer
+	or other electronic systems.
+
+    V4L2 device node
+	A device node that is associated to a V4L2 main driver,
+	as specified in :ref:`v4l2_device_naming`.
+
+    V4L2 hardware
+	A hardware used to on a media device supported by the V4L2
+	subsystem.
+
+    V4L2 main driver
+	The V4L2 device driver that implements the main logic to talk with
+	the V4L2 hardware.
+
+	Also known as bridge driver.
+
+	See :ref:`v4l2_hardware_control`.
+
+    V4L2 sub-device
+	Part of the media hardware that is implemented via a
+	V4L2 sub-device driver.
+
+	See :ref:`subdev`.
+
+    Vdevnode-centric
+	V4L2 hardware that it is controlled via V4L2 device nodes.
+
+	See :ref:`v4l2_hardware_control`.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index 2128717299b3..698c060939f0 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
     videodev
     capture-example
     v4l2grab-example
+    glossary
     biblio
 
 
-- 
2.13.5

[PATCH v7 2/7] 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.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 44 ++++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..7e7aad784388 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,12 +7,14 @@ Opening and Closing Devices
 ***************************
 
 
-Device Naming
-=============
+.. _v4l2_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.
 
@@ -23,6 +25,42 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
 are allocated in ranges depending on the device node type (video, radio,
 etc.).
 
+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 and modulators
+``/dev/swradioX``	 Software Defined Radio tuners and modulators
+``/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 is no guarantee 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/`` directories containing
+      links that can be used uniquely to 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
+
+   3. **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) provide a
+      different API and aren't considered as V4L2 device nodes.
+
+      They are covered at :ref:`subdev`.
+
+
 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
 options to select specific video/radio/vbi node numbers. This allows the
 user to request that the device node is named e.g. /dev/video5 instead
-- 
2.13.5

[PATCH v7 3/7] media: open.rst: remove the minor number range

[Mauro Carvalho Chehab]

minor numbers use to range between 0 to 255, but that
was changed a long time ago. While it still applies when
CONFIG_VIDEO_FIXED_MINOR_RANGES, when the minor number is
dynamically allocated, this may not be true. In any case,
this is not relevant, as udev will take care of it.

So, remove this useless misinformation.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 7e7aad784388..18030131ef77 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -19,11 +19,10 @@ helper functions and a common application interface specified in this
 document.
 
 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.).
+number 81. 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.
 
 The existing V4L2 device node types are:
 
-- 
2.13.5

[PATCH v7 4/7] 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 have never clearly documented in the V4L2 specification
the differences between the two types.

Let's document them based on the the current implementation.

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

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 18030131ef77..f603bc9b49a0 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,6 +7,46 @@ Opening and Closing Devices
 ***************************
 
 
+.. _v4l2_hardware_control:
+
+
+Types of V4L2 media hardware control
+====================================
+
+V4L2 hardware periferal is usually complex: support for it is
+implemented via a V4L2 main driver and often by several additional drivers.
+The main driver always exposes one or more **V4L2 device nodes**
+(see :ref:`v4l2_device_naming`) with are responsible for implementing
+data streaming, if applicable.
+
+The other drivers are called **V4L2 sub-devices** and provide control to
+other hardware components 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
+media hardware control: via the **V4L2 device nodes**. We refer to this kind
+of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**").
+
+Later (kernel 2.6.39), a new type of periferal control was
+added in order to support complex media hardware that are common for embedded
+systems. This type of periferal is controlled mainly via the media
+controller and V4L2 sub-devices. So, it is called
+**Media controller centric** (or, simply, "**MC-centric**") control.
+
+For **vdevnode-centric** media hardware control, the media hardware is
+controlled via the **V4L2 device nodes**. They may optionally support the
+:ref:`media controller API <media_controller>` as well,
+in order to inform the application which device nodes are available
+(see :ref:`related`).
+
+For **MC-centric** media hardware control it is required to configure
+the pipelines via the :ref:`media controller API <media_controller>` before
+the periferal can be used. For such devices, the sub-devices' configuration
+can be controlled via the :ref:`sub-device API <subdev>`, which creates one
+device node per sub-device.
+
 .. _v4l2_device_naming:
 
 V4L2 Device Node Naming
-- 
2.13.5

[PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Mauro Carvalho Chehab]

As we now have a glossary, some terms used on open.rst
require adjustments.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index f603bc9b49a0..0daf0c122c19 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -143,7 +143,7 @@ Related Devices
 Devices can support several functions. For example video capturing, VBI
 capturing and radio support.
 
-The V4L2 API creates different nodes for each of these functions.
+The V4L2 API creates different V4L2 device nodes for each of these functions.
 
 The V4L2 API was designed with the idea that one device node could
 support all functions. However, in practice this never worked: this
@@ -153,17 +153,17 @@ switching a device node between different functions only works when
 using the streaming I/O API, not with the
 :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
 
-Today each device node supports just one function.
+Today each V4L2 device node supports just one function.
 
 Besides video input or output the hardware may also support audio
 sampling or playback. If so, these functions are implemented as ALSA PCM
 devices with optional ALSA audio mixer devices.
 
 One problem with all these devices is that the V4L2 API makes no
-provisions to find these related devices. Some really complex devices
-use the Media Controller (see :ref:`media_controller`) which can be
-used for this purpose. But most drivers do not use it, and while some
-code exists that uses sysfs to discover related devices (see
+provisions to find these related V4L2 device nodes. Some really complex
+hardware use the Media Controller (see :ref:`media_controller`) which can
+be used for this purpose. But several drivers do not use it, and while some
+code exists that uses sysfs to discover related V4L2 device nodes (see
 libmedia_dev in the
 `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
 repository), there is no library yet that can provide a single API
-- 
2.13.5

[PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices

[Mauro Carvalho Chehab]

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@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst            | 7 +++++++
 Documentation/media/uapi/v4l/vidioc-querycap.rst | 5 +++++
 Documentation/media/videodev2.h.rst.exceptions   | 1 +
 include/uapi/linux/videodev2.h                   | 2 ++
 4 files changed, 15 insertions(+)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 0daf0c122c19..75ccc9d6614d 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -47,6 +47,13 @@ the periferal can be used. For such devices, the sub-devices' configuration
 can be controlled via the :ref:`sub-device API <subdev>`, which creates one
 device node per sub-device.
 
+.. attention::
+
+   Devices that require **MC-centric** media hardware control should
+   report a ``V4L2_MC_CENTRIC`` :c:type:`v4l2_capability` flag
+   (see :ref:`VIDIOC_QUERYCAP`).
+
+
 .. _v4l2_device_naming:
 
 V4L2 Device Node Naming
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index 66fb1b3d6e6e..944bc5ba484f 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -254,6 +254,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 **vdevnode-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/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions
index a5cb0a8686ac..b51a575f9f75 100644
--- a/Documentation/media/videodev2.h.rst.exceptions
+++ b/Documentation/media/videodev2.h.rst.exceptions
@@ -157,6 +157,7 @@ replace define V4L2_CAP_META_CAPTURE device-capabilities
 replace define V4L2_CAP_READWRITE device-capabilities
 replace define V4L2_CAP_ASYNCIO device-capabilities
 replace define V4L2_CAP_STREAMING device-capabilities
+replace define V4L2_CAP_MC_CENTRIC device-capabilities
 replace define V4L2_CAP_DEVICE_CAPS device-capabilities
 replace define V4L2_CAP_TOUCH device-capabilities
 
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 185d6a0acc06..4ff1224719a7 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.5

[PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric

[Mauro Carvalho Chehab]

The documentation doesn't mention if vdev-centric hardware
control would have subdev API or not.

Add a notice about that, reflecting the current status, where
three drivers use it, in order to support some subdev-specific
controls.

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

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 75ccc9d6614d..ed011ed123cc 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -47,6 +47,13 @@ the periferal can be used. For such devices, the sub-devices' configuration
 can be controlled via the :ref:`sub-device API <subdev>`, which creates one
 device node per sub-device.
 
+.. note::
+
+   A **vdevnode-centric** may also 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.
+
+
 .. attention::
 
    Devices that require **MC-centric** media hardware control should
-- 
2.13.5

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Randy Dunlap]

On 09/27/17 15:23, Mauro Carvalho Chehab wrote:
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 18030131ef77..f603bc9b49a0 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,6 +7,46 @@ Opening and Closing Devices
>  ***************************
>  
>  
> +.. _v4l2_hardware_control:
> +
> +
> +Types of V4L2 media hardware control
> +====================================
> +
> +V4L2 hardware periferal is usually complex: support for it is

                 peripheral (in several places...)

> +implemented via a V4L2 main driver and often by several additional drivers.
> +The main driver always exposes one or more **V4L2 device nodes**
> +(see :ref:`v4l2_device_naming`) with are responsible for implementing
> +data streaming, if applicable.
> +
> +The other drivers are called **V4L2 sub-devices** and provide control to
> +other hardware components 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
> +media hardware control: via the **V4L2 device nodes**. We refer to this kind
> +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**").
> +
> +Later (kernel 2.6.39), a new type of periferal control was
> +added in order to support complex media hardware that are common for embedded
> +systems. This type of periferal is controlled mainly via the media
> +controller and V4L2 sub-devices. So, it is called
> +**Media controller centric** (or, simply, "**MC-centric**") control.
> +
> +For **vdevnode-centric** media hardware control, the media hardware is
> +controlled via the **V4L2 device nodes**. They may optionally support the
> +:ref:`media controller API <media_controller>` as well,
> +in order to inform the application which device nodes are available
> +(see :ref:`related`).
> +
> +For **MC-centric** media hardware control it is required to configure
> +the pipelines via the :ref:`media controller API <media_controller>` before
> +the periferal can be used. For such devices, the sub-devices' configuration
> +can be controlled via the :ref:`sub-device API <subdev>`, which creates one
> +device node per sub-device.
> +
>  .. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming
> 


-- 
~Randy

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

Hi Randy,

Em Wed, 27 Sep 2017 15:32:12 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> > +Types of V4L2 media hardware control
> > +====================================
> > +
> > +V4L2 hardware periferal is usually complex: support for it is  
> 
>                  peripheral (in several places...)

Thanks for noticing! My brain is hardwired to automatically replace
ph -> f, as "ph" only exists on archaic Brazilian Portuguese ;-)

Just fixed everything with:

	$ git filter-branch -f --tree-filter 'for i in $(git grep -l periferal Documentation/media); do sed s,periferal,peripheral,g -i $i; done' v4.14-rc1..

And pushed to my development's tree:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=mc-centric-flag-v7

Thanks,
Mauro

Re: [PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric

[Sakari Ailus]

On Wed, Sep 27, 2017 at 07:23:49PM -0300, Mauro Carvalho Chehab wrote:
> The documentation doesn't mention if vdev-centric hardware
> control would have subdev API or not.
> 
> Add a notice about that, reflecting the current status, where
> three drivers use it, in order to support some subdev-specific
> controls.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Thanks!

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices

[Sakari Ailus]

On Wed, Sep 27, 2017 at 07:23:48PM -0300, Mauro Carvalho Chehab wrote:
> 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@s-opensource.com>

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

Thanks for continuing the work on this!

On Wed, Sep 27, 2017 at 07:23:43PM -0300, Mauro Carvalho Chehab wrote:
> Add a glossary of terms for V4L2, as several concepts are complex
> enough to cause misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
>  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
>  2 files changed, 137 insertions(+)
>  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> 
> diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> new file mode 100644
> index 000000000000..b6767da1a46e
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/glossary.rst
> @@ -0,0 +1,136 @@
> +========
> +Glossary
> +========
> +
> +.. note::
> +
> +   This goal of section is to standardize the terms used within the V4L2
> +   documentation. It is written incrementally as they are standardized in
> +   the V4L2 documentation. So, it is a Work In Progress.
> +
> +.. Please keep the glossary entries in alphabetical order
> +
> +.. glossary::
> +
> +    Bridge driver
> +	The same as V4L2 main driver.

Not all V4L2 main drivers can be bridge drivers. Mem-to-mem devices, for
instance. How about:

A driver for a device receiving image data from another device (or
transmitting it to a sub-device) controlled by a sub-device driver. Bridge
drivers typically act as V4L2 main drivers.

> +
> +    Device Node
> +	A character device node in the file system used to control and do
> +	input/output data transfers from/to a Kernel driver.
> +
> +    Digital Signal Processor - DSP
> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.
> +
> +    Driver
> +	The part of the Linux Kernel that implements support
> +	for a hardware component.
> +
> +    Field-programmable Gate Array - FPGA
> +	A field-programmable gate array (FPGA) is an integrated circuit
> +	designed to be configured by a customer or a designer after
> +	manufacturing.
> +
> +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> +
> +    Hardware component
> +	A subset of the media hardware. For example an I²C or SPI device,
> +	or an IP block inside an SoC or FPGA.
> +
> +    Image Signal Processor - ISP
> +	A specialised processor that implements a set of algorithms for
> +	processing image data. ISPs may implement algorithms for lens
> +	shading correction, demosaic, scaling and pixel format conversion
> +	as well as produce statistics for the use of the control
> +	algorithms (e.g. automatic exposure, white balance and focus).

And perhaps add:

ISP drivers often contain a receiver for image data from external source
such as a sensor and act as V4L2 main driver.

> +
> +    Inter-Integrated Circuit - I²C
> +	A  multi-master, multi-slave, packet switched, single-ended,
> +	serial computer bus used to control V4L2 sub-devices.
> +
> +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> +
> +    Integrated circuit - IC
> +	A set of electronic circuits on one small flat piece of
> +	semiconductor material, normally silicon.
> +
> +	Also known as chip.
> +
> +    Intellectual property core - IP core
> +	In electronic design a semiconductor intellectual property core,
> +	is a reusable unit of logic, cell, or integrated circuit layout
> +	design that is the intellectual property of one party.
> +	IP cores may be licensed to another party or can be owned
> +	and used by a single party alone.
> +
> +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> +
> +    IP block
> +	The same as IP core.
> +
> +    MC-centric
> +	V4L2 hardware that requires a Media controller.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    Media Controller
> +	An API designed to expose and control devices and sub-devices
> +	relationships to applications.
> +
> +	See :ref:`media_controller`.
> +
> +    Media hardware
> +	A group of hardware components that together make a larger
> +	user-facing functional media hardware. For instance the SoC ISP IP
> +	cores and external camera sensors together make a
> +	camera media hardware.
> +
> +    Media hardware control
> +	Type of control for a media hardware supported by V4L2 drivers.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    Microprocessor
> +	An electronic circuitry that carries out the instructions
> +	of a computer program by performing the basic arithmetic, logical,
> +	control and input/output (I/O) operations specified by the
> +	instructions on a single integrated circuit.
> +
> +    SMBus
> +	A subset of I²C, with defines a stricter usage of the bus.
> +
> +    Serial Peripheral Interface Bus - SPI
> +	Synchronous serial communication interface specification used for
> +	short distance communication, primarily in embedded systems.
> +
> +    System on a Chip - SoC
> +	An integrated circuit that integrates all components of a computer
> +	or other electronic systems.
> +
> +    V4L2 device node
> +	A device node that is associated to a V4L2 main driver,
> +	as specified in :ref:`v4l2_device_naming`.
> +
> +    V4L2 hardware
> +	A hardware used to on a media device supported by the V4L2
> +	subsystem.

I'm not sure what this means. Nor I think the proposed term is good for the
reasons elaborated earlier. "Media hardware" above has similar issues.

What we would need a name for is a device that consists of other devices
that are not usable individually, but instead as an ensemble.

I think "aggregate device", for instance, would be good as it catches the
essence of the nature of the system. We'd have "Media aggregate device" and
"V4L2 aggregate device".

An alternative would be simply to leave this out for now, but then we'll
have issues elsewhere. I'm certainly open for better options if someone can
come up with a better name.

> +
> +    V4L2 main driver
> +	The V4L2 device driver that implements the main logic to talk with
> +	the V4L2 hardware.
> +
> +	Also known as bridge driver.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    V4L2 sub-device
> +	Part of the media hardware that is implemented via a
> +	V4L2 sub-device driver.
> +
> +	See :ref:`subdev`.
> +
> +    Vdevnode-centric

I think this looks quite awkward. How about "Video device node centric" or
"Video node centric"? I don't think it'd be too long.

> +	V4L2 hardware that it is controlled via V4L2 device nodes.
> +
> +	See :ref:`v4l2_hardware_control`.
> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> index 2128717299b3..698c060939f0 100644
> --- a/Documentation/media/uapi/v4l/v4l2.rst
> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
>      videodev
>      capture-example
>      v4l2grab-example
> +    glossary
>      biblio
>  
>  

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

On Fri, Oct 06, 2017 at 01:22:29PM +0300, Sakari Ailus wrote:
> > +    V4L2 device node
> > +	A device node that is associated to a V4L2 main driver,
> > +	as specified in :ref:`v4l2_device_naming`.

I think we need to name the interface, not so much their instances.

How about adding:

    V4L2
	Video4Linux 2 interface. The interface implemented by **V4L2 device
	nodes**.

and:

    V4L2 device node
	A device node implementing the **V4L2** interface.

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Sakari Ailus]

Hi Mauro,

On Wed, Sep 27, 2017 at 07:23:46PM -0300, Mauro Carvalho Chehab wrote:
> 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 have never clearly documented in the V4L2 specification
> the differences between the two types.
> 
> Let's document them based on the the current implementation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 18030131ef77..f603bc9b49a0 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,6 +7,46 @@ Opening and Closing Devices
>  ***************************
>  
>  
> +.. _v4l2_hardware_control:
> +
> +
> +Types of V4L2 media hardware control
> +====================================
> +
> +V4L2 hardware periferal is usually complex: support for it is
> +implemented via a V4L2 main driver and often by several additional drivers.
> +The main driver always exposes one or more **V4L2 device nodes**
> +(see :ref:`v4l2_device_naming`) with are responsible for implementing
> +data streaming, if applicable.
> +
> +The other drivers are called **V4L2 sub-devices** and provide control to

s/drivers/devices/

> +other hardware components 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
> +media hardware control: via the **V4L2 device nodes**. We refer to this kind
> +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**").

I think this could be easier understood if we start with the differences
instead of what we call the types. I'd also refer to interfaces rather than
their instances.

How about (pending finalising discussion on naming):

When **V4L2** was originally designed, the **V4L2 device** served the
purpose of both control and data interfaces and there was no separation
between the two interface-wise. V4L2 controls, setting inputs and outputs,
format configuration and buffer related operations were all performed
through the same **V4L2 device nodes**. Devices offering such interface are
called **V4L2 device node centric**.

Later on, support for the **Media controller** interface was added to V4L2
in order to better support complex **V4L2 aggregate devices** where the
**V4L2** interface alone could no longer meaningfully serve as both a
control and a data interface. On such aggregate devices, **V4L2** interface
remains a data interface whereas control takes place through the **Media
controller** and **V4L2 sub-device** interfaces. Stream control is an
exception to this: streaming is enabled and disabled through the **V4L2**
interface. These devices are called **Media controller centric**.

**MC-centric** aggregate devices provide more versatile control of the
hardware than **V4L2 device node centric** devices. On **MC-centric**
aggregate devices the **V4L2 sub-device nodes** represent specific parts of
the **V4L2 aggregate device**, to which they enable control.

Also, the additional versatility of **MC-centric** aggregate devices comes
with additional responsibilities, the main one of which is the requirements
of the user configuring the device pipeline before starting streaming. This
typically involves configuring the links using the **Media controller**
interface and the media bus formats on pads (at both ends of the links)
using the **V4L2 sub-device** interface.

> +
> +Later (kernel 2.6.39), a new type of periferal control was
> +added in order to support complex media hardware that are common for embedded
> +systems. This type of periferal is controlled mainly via the media
> +controller and V4L2 sub-devices. So, it is called
> +**Media controller centric** (or, simply, "**MC-centric**") control.
> +
> +For **vdevnode-centric** media hardware control, the media hardware is
> +controlled via the **V4L2 device nodes**. They may optionally support the
> +:ref:`media controller API <media_controller>` as well,
> +in order to inform the application which device nodes are available
> +(see :ref:`related`).
> +
> +For **MC-centric** media hardware control it is required to configure
> +the pipelines via the :ref:`media controller API <media_controller>` before
> +the periferal can be used. For such devices, the sub-devices' configuration
> +can be controlled via the :ref:`sub-device API <subdev>`, which creates one
> +device node per sub-device.
> +
>  .. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Sakari Ailus]

Hi Mauro,

On Wed, Sep 27, 2017 at 07:23:47PM -0300, Mauro Carvalho Chehab wrote:
> As we now have a glossary, some terms used on open.rst
> require adjustments.
> 
> Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index f603bc9b49a0..0daf0c122c19 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -143,7 +143,7 @@ Related Devices
>  Devices can support several functions. For example video capturing, VBI
>  capturing and radio support.
>  
> -The V4L2 API creates different nodes for each of these functions.
> +The V4L2 API creates different V4L2 device nodes for each of these functions.

A V4L2 device node is an instance of the V4L2 API. At the very least we
should call them "V4L2 device node types", not device nodes only. This
simply would suggests they're separate.

s/creates/defines/ ?

>  
>  The V4L2 API was designed with the idea that one device node could
>  support all functions. However, in practice this never worked: this
> @@ -153,17 +153,17 @@ switching a device node between different functions only works when
>  using the streaming I/O API, not with the
>  :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
>  
> -Today each device node supports just one function.
> +Today each V4L2 device node supports just one function.
>  
>  Besides video input or output the hardware may also support audio
>  sampling or playback. If so, these functions are implemented as ALSA PCM
>  devices with optional ALSA audio mixer devices.
>  
>  One problem with all these devices is that the V4L2 API makes no
> -provisions to find these related devices. Some really complex devices
> -use the Media Controller (see :ref:`media_controller`) which can be
> -used for this purpose. But most drivers do not use it, and while some
> -code exists that uses sysfs to discover related devices (see
> +provisions to find these related V4L2 device nodes. Some really complex
> +hardware use the Media Controller (see :ref:`media_controller`) which can
> +be used for this purpose. But several drivers do not use it, and while some
> +code exists that uses sysfs to discover related V4L2 device nodes (see
>  libmedia_dev in the
>  `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
>  repository), there is no library yet that can provide a single API

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Hans Verkuil]

On 09/28/2017 12:23 AM, Mauro Carvalho Chehab wrote:
> Add a glossary of terms for V4L2, as several concepts are complex
> enough to cause misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
>  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
>  2 files changed, 137 insertions(+)
>  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> 
> diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> new file mode 100644
> index 000000000000..b6767da1a46e
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/glossary.rst
> @@ -0,0 +1,136 @@
> +========
> +Glossary
> +========
> +
> +.. note::
> +
> +   This goal of section is to standardize the terms used within the V4L2
> +   documentation. It is written incrementally as they are standardized in
> +   the V4L2 documentation. So, it is a Work In Progress.
> +
> +.. Please keep the glossary entries in alphabetical order
> +
> +.. glossary::
> +
> +    Bridge driver
> +	The same as V4L2 main driver.

Change this to the more standard phrase:

See: V4L2 main driver.

> +
> +    Device Node
> +	A character device node in the file system used to control and do

and -> and/or

> +	input/output data transfers from/to a Kernel driver.
> +
> +    Digital Signal Processor - DSP
> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.

I'd say 'requirements' instead of 'needs'. I think that's a better term.

> +
> +    Driver
> +	The part of the Linux Kernel that implements support
> +	for a hardware component.
> +
> +    Field-programmable Gate Array - FPGA
> +	A field-programmable gate array (FPGA) is an integrated circuit
> +	designed to be configured by a customer or a designer after
> +	manufacturing.
> +
> +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> +
> +    Hardware component
> +	A subset of the media hardware. For example an I²C or SPI device,
> +	or an IP block inside an SoC or FPGA.
> +
> +    Image Signal Processor - ISP
> +	A specialised processor that implements a set of algorithms for
> +	processing image data. ISPs may implement algorithms for lens
> +	shading correction, demosaic, scaling and pixel format conversion
> +	as well as produce statistics for the use of the control
> +	algorithms (e.g. automatic exposure, white balance and focus).
> +
> +    Inter-Integrated Circuit - I²C
> +	A  multi-master, multi-slave, packet switched, single-ended,
> +	serial computer bus used to control V4L2 sub-devices.

I'd rephrase this a bit:

	A  multi-master, multi-slave, packet switched, single-ended,
	serial computer bus. Most V4L2 sub-devices are controlled via
	this bus.

Your text suggested that i2c is used exclusively for V4L2 subdevs, but
of course it is used for many other devices as well.

> +
> +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> +
> +    Integrated circuit - IC
> +	A set of electronic circuits on one small flat piece of
> +	semiconductor material, normally silicon.
> +
> +	Also known as chip.

Perhaps add an entry for 'Chip' as well, with a 'See: Integrated circuit' as
description? Just to be consistent.

> +
> +    Intellectual property core - IP core
> +	In electronic design a semiconductor intellectual property core,
> +	is a reusable unit of logic, cell, or integrated circuit layout
> +	design that is the intellectual property of one party.
> +	IP cores may be licensed to another party or can be owned
> +	and used by a single party alone.
> +
> +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> +
> +    IP block
> +	The same as IP core.

'See: '

> +
> +    MC-centric
> +	V4L2 hardware that requires a Media controller.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    Media Controller
> +	An API designed to expose and control devices and sub-devices
> +	relationships to applications.

This sentence is not clear. I propose this:

	An API designed to expose and control the relationships of the Media
	Harware to applications.

> +
> +	See :ref:`media_controller`.
> +
> +    Media hardware
> +	A group of hardware components that together make a larger
> +	user-facing functional media hardware. For instance the SoC ISP IP

I'd just say "form the functional". The term 'user-facing' is out of place here.

> +	cores and external camera sensors together make a

make a -> form the

Possible synonym for 'form': 'constitute'. I'm OK with either.

> +	camera media hardware.
> +
> +    Media hardware control
> +	Type of control for a media hardware supported by V4L2 drivers.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    Microprocessor
> +	An electronic circuitry that carries out the instructions
> +	of a computer program by performing the basic arithmetic, logical,
> +	control and input/output (I/O) operations specified by the
> +	instructions on a single integrated circuit.
> +
> +    SMBus
> +	A subset of I²C, with defines a stricter usage of the bus.
> +
> +    Serial Peripheral Interface Bus - SPI
> +	Synchronous serial communication interface specification used for
> +	short distance communication, primarily in embedded systems.
> +
> +    System on a Chip - SoC
> +	An integrated circuit that integrates all components of a computer
> +	or other electronic systems.
> +
> +    V4L2 device node
> +	A device node that is associated to a V4L2 main driver,
> +	as specified in :ref:`v4l2_device_naming`.
> +
> +    V4L2 hardware
> +	A hardware used to on a media device supported by the V4L2
> +	subsystem.

No idea what you mean here. Perhaps this:

Hardware that is controlled by a V4L2 main driver or a V4L2 sub-device driver.
V4L2 hardware is a subset of the Media hardware. Often the two are the same,
but Media hardware can also contain other non-V4L2 hardware such as DVB hardware.

> +
> +    V4L2 main driver
> +	The V4L2 device driver that implements the main logic to talk with
> +	the V4L2 hardware.
> +
> +	Also known as bridge driver.
> +
> +	See :ref:`v4l2_hardware_control`.
> +
> +    V4L2 sub-device
> +	Part of the media hardware that is implemented via a
> +	V4L2 sub-device driver.

When we talk about 'V4L2 sub-device' we talk about a driver that implement
the subdev kernel API. I suggest that you change 'V4L2 sub-device' to
'V4L2 sub-device driver', then explain that such a driver implements support
for a Hardware component.

> +
> +	See :ref:`subdev`.
> +
> +    Vdevnode-centric
> +	V4L2 hardware that it is controlled via V4L2 device nodes.

'that it' -> 'that'

This also needs a reference:

	See :ref:`v4l2_hardware_control`.

> +
> +	See :ref:`v4l2_hardware_control`.
> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> index 2128717299b3..698c060939f0 100644
> --- a/Documentation/media/uapi/v4l/v4l2.rst
> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
>      videodev
>      capture-example
>      v4l2grab-example
> +    glossary
>      biblio
>  
>  
> 

Regards,

	Hans

Re: [PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices

[Hans Verkuil]

On 09/28/2017 12:23 AM, Mauro Carvalho Chehab wrote:
> 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@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst            | 7 +++++++
>  Documentation/media/uapi/v4l/vidioc-querycap.rst | 5 +++++
>  Documentation/media/videodev2.h.rst.exceptions   | 1 +
>  include/uapi/linux/videodev2.h                   | 2 ++
>  4 files changed, 15 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 0daf0c122c19..75ccc9d6614d 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -47,6 +47,13 @@ the periferal can be used. For such devices, the sub-devices' configuration
>  can be controlled via the :ref:`sub-device API <subdev>`, which creates one
>  device node per sub-device.
>  
> +.. attention::
> +
> +   Devices that require **MC-centric** media hardware control should

should -> shall

After that change you can add my:

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

Regards,

	Hans


> +   report a ``V4L2_MC_CENTRIC`` :c:type:`v4l2_capability` flag
> +   (see :ref:`VIDIOC_QUERYCAP`).
> +
> +
>  .. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming
> diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
> index 66fb1b3d6e6e..944bc5ba484f 100644
> --- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
> +++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
> @@ -254,6 +254,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 **vdevnode-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/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions
> index a5cb0a8686ac..b51a575f9f75 100644
> --- a/Documentation/media/videodev2.h.rst.exceptions
> +++ b/Documentation/media/videodev2.h.rst.exceptions
> @@ -157,6 +157,7 @@ replace define V4L2_CAP_META_CAPTURE device-capabilities
>  replace define V4L2_CAP_READWRITE device-capabilities
>  replace define V4L2_CAP_ASYNCIO device-capabilities
>  replace define V4L2_CAP_STREAMING device-capabilities
> +replace define V4L2_CAP_MC_CENTRIC device-capabilities
>  replace define V4L2_CAP_DEVICE_CAPS device-capabilities
>  replace define V4L2_CAP_TOUCH device-capabilities
>  
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 185d6a0acc06..4ff1224719a7 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 */
>  
>  /*
> 

Re: [PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric

[Hans Verkuil]

On 09/28/2017 12:23 AM, Mauro Carvalho Chehab wrote:
> The documentation doesn't mention if vdev-centric hardware
> control would have subdev API or not.
> 
> Add a notice about that, reflecting the current status, where
> three drivers use it, in order to support some subdev-specific
> controls.

Just to note that there is a pull request pending from me that
removes this from the cobalt driver. So once that's merged there
are only two drivers that do this.

Anyway:

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

Regards,

	Hans

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 75ccc9d6614d..ed011ed123cc 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -47,6 +47,13 @@ the periferal can be used. For such devices, the sub-devices' configuration
>  can be controlled via the :ref:`sub-device API <subdev>`, which creates one
>  device node per sub-device.
>  
> +.. note::
> +
> +   A **vdevnode-centric** may also 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.
> +
> +
>  .. attention::
>  
>     Devices that require **MC-centric** media hardware control should
> 

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Tue, 10 Oct 2017 09:47:13 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 09/28/2017 12:23 AM, Mauro Carvalho Chehab wrote:
> > Add a glossary of terms for V4L2, as several concepts are complex
> > enough to cause misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
> >  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
> >  2 files changed, 137 insertions(+)
> >  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> > 
> > diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> > new file mode 100644
> > index 000000000000..b6767da1a46e
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > @@ -0,0 +1,136 @@
> > +========
> > +Glossary
> > +========
> > +
> > +.. note::
> > +
> > +   This goal of section is to standardize the terms used within the V4L2
> > +   documentation. It is written incrementally as they are standardized in
> > +   the V4L2 documentation. So, it is a Work In Progress.
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +    Bridge driver
> > +	The same as V4L2 main driver.  
> 
> Change this to the more standard phrase:
> 
> See: V4L2 main driver.
> 
> > +
> > +    Device Node
> > +	A character device node in the file system used to control and do  
> 
> and -> and/or
> 
> > +	input/output data transfers from/to a Kernel driver.
> > +
> > +    Digital Signal Processor - DSP
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.  
> 
> I'd say 'requirements' instead of 'needs'. I think that's a better term.
> 
> > +
> > +    Driver
> > +	The part of the Linux Kernel that implements support
> > +	for a hardware component.
> > +
> > +    Field-programmable Gate Array - FPGA
> > +	A field-programmable gate array (FPGA) is an integrated circuit
> > +	designed to be configured by a customer or a designer after
> > +	manufacturing.
> > +
> > +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> > +
> > +    Hardware component
> > +	A subset of the media hardware. For example an I²C or SPI device,
> > +	or an IP block inside an SoC or FPGA.
> > +
> > +    Image Signal Processor - ISP
> > +	A specialised processor that implements a set of algorithms for
> > +	processing image data. ISPs may implement algorithms for lens
> > +	shading correction, demosaic, scaling and pixel format conversion
> > +	as well as produce statistics for the use of the control
> > +	algorithms (e.g. automatic exposure, white balance and focus).
> > +
> > +    Inter-Integrated Circuit - I²C
> > +	A  multi-master, multi-slave, packet switched, single-ended,
> > +	serial computer bus used to control V4L2 sub-devices.  
> 
> I'd rephrase this a bit:
> 
> 	A  multi-master, multi-slave, packet switched, single-ended,
> 	serial computer bus. Most V4L2 sub-devices are controlled via
> 	this bus.
> 
> Your text suggested that i2c is used exclusively for V4L2 subdevs, but
> of course it is used for many other devices as well.
> 
> > +
> > +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> > +
> > +    Integrated circuit - IC
> > +	A set of electronic circuits on one small flat piece of
> > +	semiconductor material, normally silicon.
> > +
> > +	Also known as chip.  
> 
> Perhaps add an entry for 'Chip' as well, with a 'See: Integrated circuit' as
> description? Just to be consistent.
> 
> > +
> > +    Intellectual property core - IP core
> > +	In electronic design a semiconductor intellectual property core,
> > +	is a reusable unit of logic, cell, or integrated circuit layout
> > +	design that is the intellectual property of one party.
> > +	IP cores may be licensed to another party or can be owned
> > +	and used by a single party alone.
> > +
> > +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> > +
> > +    IP block
> > +	The same as IP core.  
> 
> 'See: '
> 
> > +
> > +    MC-centric
> > +	V4L2 hardware that requires a Media controller.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    Media Controller
> > +	An API designed to expose and control devices and sub-devices
> > +	relationships to applications.  
> 
> This sentence is not clear. I propose this:
> 
> 	An API designed to expose and control the relationships of the Media
> 	Harware to applications.
> 
> > +
> > +	See :ref:`media_controller`.
> > +
> > +    Media hardware
> > +	A group of hardware components that together make a larger
> > +	user-facing functional media hardware. For instance the SoC ISP IP  
> 
> I'd just say "form the functional". The term 'user-facing' is out of place here.
> 
> > +	cores and external camera sensors together make a  
> 
> make a -> form the
> 
> Possible synonym for 'form': 'constitute'. I'm OK with either.
> 
> > +	camera media hardware.
> > +
> > +    Media hardware control
> > +	Type of control for a media hardware supported by V4L2 drivers.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    Microprocessor
> > +	An electronic circuitry that carries out the instructions
> > +	of a computer program by performing the basic arithmetic, logical,
> > +	control and input/output (I/O) operations specified by the
> > +	instructions on a single integrated circuit.
> > +
> > +    SMBus
> > +	A subset of I²C, with defines a stricter usage of the bus.
> > +
> > +    Serial Peripheral Interface Bus - SPI
> > +	Synchronous serial communication interface specification used for
> > +	short distance communication, primarily in embedded systems.
> > +
> > +    System on a Chip - SoC
> > +	An integrated circuit that integrates all components of a computer
> > +	or other electronic systems.
> > +
> > +    V4L2 device node
> > +	A device node that is associated to a V4L2 main driver,
> > +	as specified in :ref:`v4l2_device_naming`.
> > +
> > +    V4L2 hardware
> > +	A hardware used to on a media device supported by the V4L2
> > +	subsystem.  
> 
> No idea what you mean here. Perhaps this:
> 
> Hardware that is controlled by a V4L2 main driver or a V4L2 sub-device driver.
> V4L2 hardware is a subset of the Media hardware. Often the two are the same,
> but Media hardware can also contain other non-V4L2 hardware such as DVB hardware.
> 
> > +
> > +    V4L2 main driver
> > +	The V4L2 device driver that implements the main logic to talk with
> > +	the V4L2 hardware.
> > +
> > +	Also known as bridge driver.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    V4L2 sub-device
> > +	Part of the media hardware that is implemented via a
> > +	V4L2 sub-device driver.  
> 
> When we talk about 'V4L2 sub-device' we talk about a driver that implement
> the subdev kernel API. I suggest that you change 'V4L2 sub-device' to
> 'V4L2 sub-device driver', then explain that such a driver implements support
> for a Hardware component.
> 
> > +
> > +	See :ref:`subdev`.
> > +
> > +    Vdevnode-centric
> > +	V4L2 hardware that it is controlled via V4L2 device nodes.  
> 
> 'that it' -> 'that'
> 
> This also needs a reference:
> 
> 	See :ref:`v4l2_hardware_control`.
> 
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> > index 2128717299b3..698c060939f0 100644
> > --- a/Documentation/media/uapi/v4l/v4l2.rst
> > +++ b/Documentation/media/uapi/v4l/v4l2.rst
> > @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
> >      videodev
> >      capture-example
> >      v4l2grab-example
> > +    glossary
> >      biblio
> >  
> >  
> >   
> 
> Regards,
> 
> 	Hans

I agree with all proposed changes. I'm folding the attached patch to it.

Thanks,
Mauro

diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
index b6767da1a46e..e95820d91bac 100644
--- a/Documentation/media/uapi/v4l/glossary.rst
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -13,15 +13,18 @@ Glossary
 .. glossary::
 
     Bridge driver
-	The same as V4L2 main driver.
+	See: V4L2 main driver.
+
+    Chip:
+	See: Integrated circuit.
 
     Device Node
-	A character device node in the file system used to control and do
-	input/output data transfers from/to a Kernel driver.
+	A character device node in the file system used to control and/or
+	do input/output data transfers from/to a Kernel driver.
 
     Digital Signal Processor - DSP
 	A specialized microprocessor, with its architecture optimized for
-	the operational needs of digital signal processing.
+	the operational requirements of digital signal processing.
 
     Driver
 	The part of the Linux Kernel that implements support
@@ -47,7 +50,8 @@ Glossary
 
     Inter-Integrated Circuit - I²C
 	A  multi-master, multi-slave, packet switched, single-ended,
-	serial computer bus used to control V4L2 sub-devices.
+	serial computer bus. Most V4L2 sub-device are controlled
+	via this bus.
 
 	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
 
@@ -67,7 +71,7 @@ Glossary
 	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
 
     IP block
-	The same as IP core.
+	See: IP core.
 
     MC-centric
 	V4L2 hardware that requires a Media controller.
@@ -75,15 +79,15 @@ Glossary
 	See :ref:`v4l2_hardware_control`.
 
     Media Controller
-	An API designed to expose and control devices and sub-devices
-	relationships to applications.
+	An API designed to expose and control the relationships of the Media
+	Harware to applications.
 
 	See :ref:`media_controller`.
 
     Media hardware
-	A group of hardware components that together make a larger
-	user-facing functional media hardware. For instance the SoC ISP IP
-	cores and external camera sensors together make a
+	A group of hardware components that together form the
+	functional media hardware. For instance the SoC ISP IP
+	cores and external camera sensors together form the
 	camera media hardware.
 
     Media hardware control
@@ -113,8 +117,10 @@ Glossary
 	as specified in :ref:`v4l2_device_naming`.
 
     V4L2 hardware
-	A hardware used to on a media device supported by the V4L2
-	subsystem.
+	Hardware that is controlled by a V4L2 main driver or a V4L2
+	sub-device driver. V4L2 hardware is a subset of the
+	Media hardware. Often the two are the same, but Media hardware
+	can also contain other non-V4L2 hardware such as DVB hardware.
 
     V4L2 main driver
 	The V4L2 device driver that implements the main logic to talk with
@@ -125,12 +131,15 @@ Glossary
 	See :ref:`v4l2_hardware_control`.
 
     V4L2 sub-device
-	Part of the media hardware that is implemented via a
-	V4L2 sub-device driver.
+	See: :ref:`V4L2 sub-device driver`
+
+    V4L2 sub-device driver
+	Part of the media hardware that implements support for
+	a hardware component.
 
 	See :ref:`subdev`.
 
     Vdevnode-centric
-	V4L2 hardware that it is controlled via V4L2 device nodes.
+	V4L2 hardware that is controlled via V4L2 device nodes.
 
 	See :ref:`v4l2_hardware_control`.

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Hans Verkuil]

On 10/10/2017 10:20 AM, Mauro Carvalho Chehab wrote:
> Em Tue, 10 Oct 2017 09:47:13 +0200
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> On 09/28/2017 12:23 AM, Mauro Carvalho Chehab wrote:
>>> Add a glossary of terms for V4L2, as several concepts are complex
>>> enough to cause misunderstandings.
>>>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>>> ---
>>>  Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
>>>  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
>>>  2 files changed, 137 insertions(+)
>>>  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
>>>
>>> diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
>>> new file mode 100644
>>> index 000000000000..b6767da1a46e
>>> --- /dev/null
>>> +++ b/Documentation/media/uapi/v4l/glossary.rst
>>> @@ -0,0 +1,136 @@
>>> +========
>>> +Glossary
>>> +========
>>> +
>>> +.. note::
>>> +
>>> +   This goal of section is to standardize the terms used within the V4L2
>>> +   documentation. It is written incrementally as they are standardized in
>>> +   the V4L2 documentation. So, it is a Work In Progress.
>>> +
>>> +.. Please keep the glossary entries in alphabetical order
>>> +
>>> +.. glossary::
>>> +
>>> +    Bridge driver
>>> +	The same as V4L2 main driver.  
>>
>> Change this to the more standard phrase:
>>
>> See: V4L2 main driver.
>>
>>> +
>>> +    Device Node
>>> +	A character device node in the file system used to control and do  
>>
>> and -> and/or
>>
>>> +	input/output data transfers from/to a Kernel driver.
>>> +
>>> +    Digital Signal Processor - DSP
>>> +	A specialized microprocessor, with its architecture optimized for
>>> +	the operational needs of digital signal processing.  
>>
>> I'd say 'requirements' instead of 'needs'. I think that's a better term.
>>
>>> +
>>> +    Driver
>>> +	The part of the Linux Kernel that implements support
>>> +	for a hardware component.
>>> +
>>> +    Field-programmable Gate Array - FPGA
>>> +	A field-programmable gate array (FPGA) is an integrated circuit
>>> +	designed to be configured by a customer or a designer after
>>> +	manufacturing.
>>> +
>>> +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
>>> +
>>> +    Hardware component
>>> +	A subset of the media hardware. For example an I²C or SPI device,
>>> +	or an IP block inside an SoC or FPGA.
>>> +
>>> +    Image Signal Processor - ISP
>>> +	A specialised processor that implements a set of algorithms for
>>> +	processing image data. ISPs may implement algorithms for lens
>>> +	shading correction, demosaic, scaling and pixel format conversion
>>> +	as well as produce statistics for the use of the control
>>> +	algorithms (e.g. automatic exposure, white balance and focus).
>>> +
>>> +    Inter-Integrated Circuit - I²C
>>> +	A  multi-master, multi-slave, packet switched, single-ended,
>>> +	serial computer bus used to control V4L2 sub-devices.  
>>
>> I'd rephrase this a bit:
>>
>> 	A  multi-master, multi-slave, packet switched, single-ended,
>> 	serial computer bus. Most V4L2 sub-devices are controlled via
>> 	this bus.
>>
>> Your text suggested that i2c is used exclusively for V4L2 subdevs, but
>> of course it is used for many other devices as well.
>>
>>> +
>>> +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
>>> +
>>> +    Integrated circuit - IC
>>> +	A set of electronic circuits on one small flat piece of
>>> +	semiconductor material, normally silicon.
>>> +
>>> +	Also known as chip.  
>>
>> Perhaps add an entry for 'Chip' as well, with a 'See: Integrated circuit' as
>> description? Just to be consistent.
>>
>>> +
>>> +    Intellectual property core - IP core
>>> +	In electronic design a semiconductor intellectual property core,
>>> +	is a reusable unit of logic, cell, or integrated circuit layout
>>> +	design that is the intellectual property of one party.
>>> +	IP cores may be licensed to another party or can be owned
>>> +	and used by a single party alone.
>>> +
>>> +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
>>> +
>>> +    IP block
>>> +	The same as IP core.  
>>
>> 'See: '
>>
>>> +
>>> +    MC-centric
>>> +	V4L2 hardware that requires a Media controller.
>>> +
>>> +	See :ref:`v4l2_hardware_control`.
>>> +
>>> +    Media Controller
>>> +	An API designed to expose and control devices and sub-devices
>>> +	relationships to applications.  
>>
>> This sentence is not clear. I propose this:
>>
>> 	An API designed to expose and control the relationships of the Media
>> 	Harware to applications.
>>
>>> +
>>> +	See :ref:`media_controller`.
>>> +
>>> +    Media hardware
>>> +	A group of hardware components that together make a larger
>>> +	user-facing functional media hardware. For instance the SoC ISP IP  
>>
>> I'd just say "form the functional". The term 'user-facing' is out of place here.
>>
>>> +	cores and external camera sensors together make a  
>>
>> make a -> form the
>>
>> Possible synonym for 'form': 'constitute'. I'm OK with either.
>>
>>> +	camera media hardware.
>>> +
>>> +    Media hardware control
>>> +	Type of control for a media hardware supported by V4L2 drivers.
>>> +
>>> +	See :ref:`v4l2_hardware_control`.
>>> +
>>> +    Microprocessor
>>> +	An electronic circuitry that carries out the instructions
>>> +	of a computer program by performing the basic arithmetic, logical,
>>> +	control and input/output (I/O) operations specified by the
>>> +	instructions on a single integrated circuit.
>>> +
>>> +    SMBus
>>> +	A subset of I²C, with defines a stricter usage of the bus.
>>> +
>>> +    Serial Peripheral Interface Bus - SPI
>>> +	Synchronous serial communication interface specification used for
>>> +	short distance communication, primarily in embedded systems.
>>> +
>>> +    System on a Chip - SoC
>>> +	An integrated circuit that integrates all components of a computer
>>> +	or other electronic systems.
>>> +
>>> +    V4L2 device node
>>> +	A device node that is associated to a V4L2 main driver,
>>> +	as specified in :ref:`v4l2_device_naming`.
>>> +
>>> +    V4L2 hardware
>>> +	A hardware used to on a media device supported by the V4L2
>>> +	subsystem.  
>>
>> No idea what you mean here. Perhaps this:
>>
>> Hardware that is controlled by a V4L2 main driver or a V4L2 sub-device driver.
>> V4L2 hardware is a subset of the Media hardware. Often the two are the same,
>> but Media hardware can also contain other non-V4L2 hardware such as DVB hardware.
>>
>>> +
>>> +    V4L2 main driver
>>> +	The V4L2 device driver that implements the main logic to talk with
>>> +	the V4L2 hardware.
>>> +
>>> +	Also known as bridge driver.
>>> +
>>> +	See :ref:`v4l2_hardware_control`.
>>> +
>>> +    V4L2 sub-device
>>> +	Part of the media hardware that is implemented via a
>>> +	V4L2 sub-device driver.  
>>
>> When we talk about 'V4L2 sub-device' we talk about a driver that implement
>> the subdev kernel API. I suggest that you change 'V4L2 sub-device' to
>> 'V4L2 sub-device driver', then explain that such a driver implements support
>> for a Hardware component.
>>
>>> +
>>> +	See :ref:`subdev`.
>>> +
>>> +    Vdevnode-centric
>>> +	V4L2 hardware that it is controlled via V4L2 device nodes.  
>>
>> 'that it' -> 'that'
>>
>> This also needs a reference:
>>
>> 	See :ref:`v4l2_hardware_control`.
>>
>>> +
>>> +	See :ref:`v4l2_hardware_control`.
>>> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
>>> index 2128717299b3..698c060939f0 100644
>>> --- a/Documentation/media/uapi/v4l/v4l2.rst
>>> +++ b/Documentation/media/uapi/v4l/v4l2.rst
>>> @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
>>>      videodev
>>>      capture-example
>>>      v4l2grab-example
>>> +    glossary
>>>      biblio
>>>  
>>>  
>>>   
>>
>> Regards,
>>
>> 	Hans
> 
> I agree with all proposed changes. I'm folding the attached patch to it.
> 
> Thanks,
> Mauro
> 
> diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> index b6767da1a46e..e95820d91bac 100644
> --- a/Documentation/media/uapi/v4l/glossary.rst
> +++ b/Documentation/media/uapi/v4l/glossary.rst
> @@ -13,15 +13,18 @@ Glossary
>  .. glossary::
>  
>      Bridge driver
> -	The same as V4L2 main driver.
> +	See: V4L2 main driver.
> +
> +    Chip:
> +	See: Integrated circuit.
>  
>      Device Node
> -	A character device node in the file system used to control and do
> -	input/output data transfers from/to a Kernel driver.
> +	A character device node in the file system used to control and/or
> +	do input/output data transfers from/to a Kernel driver.
>  
>      Digital Signal Processor - DSP
>  	A specialized microprocessor, with its architecture optimized for
> -	the operational needs of digital signal processing.
> +	the operational requirements of digital signal processing.
>  
>      Driver
>  	The part of the Linux Kernel that implements support
> @@ -47,7 +50,8 @@ Glossary
>  
>      Inter-Integrated Circuit - I²C
>  	A  multi-master, multi-slave, packet switched, single-ended,
> -	serial computer bus used to control V4L2 sub-devices.
> +	serial computer bus. Most V4L2 sub-device are controlled
> +	via this bus.
>  
>  	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
>  
> @@ -67,7 +71,7 @@ Glossary
>  	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
>  
>      IP block
> -	The same as IP core.
> +	See: IP core.
>  
>      MC-centric
>  	V4L2 hardware that requires a Media controller.
> @@ -75,15 +79,15 @@ Glossary
>  	See :ref:`v4l2_hardware_control`.
>  
>      Media Controller
> -	An API designed to expose and control devices and sub-devices
> -	relationships to applications.
> +	An API designed to expose and control the relationships of the Media
> +	Harware to applications.
>  
>  	See :ref:`media_controller`.
>  
>      Media hardware
> -	A group of hardware components that together make a larger
> -	user-facing functional media hardware. For instance the SoC ISP IP
> -	cores and external camera sensors together make a
> +	A group of hardware components that together form the
> +	functional media hardware. For instance the SoC ISP IP
> +	cores and external camera sensors together form the
>  	camera media hardware.
>  
>      Media hardware control
> @@ -113,8 +117,10 @@ Glossary
>  	as specified in :ref:`v4l2_device_naming`.
>  
>      V4L2 hardware
> -	A hardware used to on a media device supported by the V4L2
> -	subsystem.
> +	Hardware that is controlled by a V4L2 main driver or a V4L2
> +	sub-device driver. V4L2 hardware is a subset of the
> +	Media hardware. Often the two are the same, but Media hardware
> +	can also contain other non-V4L2 hardware such as DVB hardware.
>  
>      V4L2 main driver
>  	The V4L2 device driver that implements the main logic to talk with
> @@ -125,12 +131,15 @@ Glossary
>  	See :ref:`v4l2_hardware_control`.
>  
>      V4L2 sub-device
> -	Part of the media hardware that is implemented via a
> -	V4L2 sub-device driver.
> +	See: :ref:`V4L2 sub-device driver`
> +
> +    V4L2 sub-device driver
> +	Part of the media hardware that implements support for
> +	a hardware component.

The description now no longer fits the term. I suggest:

"The V4L2 driver that implements support for a hardware component."

Otherwise this looks good.

Regards,

	Hans

>  
>  	See :ref:`subdev`.
>  
>      Vdevnode-centric
> -	V4L2 hardware that it is controlled via V4L2 device nodes.
> +	V4L2 hardware that is controlled via V4L2 device nodes.
>  
>  	See :ref:`v4l2_hardware_control`.
> 
> 

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Fri, 6 Oct 2017 13:22:29 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> > +    Bridge driver
> > +	The same as V4L2 main driver.  
> 
> Not all V4L2 main drivers can be bridge drivers. Mem-to-mem devices, for
> instance. How about:
> 
> A driver for a device receiving image data from another device (or
> transmitting it to a sub-device) controlled by a sub-device driver. Bridge
> drivers typically act as V4L2 main drivers.

That is not true for some device drivers we have.

The GSPCA drivers are bridge drivers, but they don't use any sub-device
(well, it should, but nobody will redesign it, as the efforts would
be huge, for a very little gain). Also uvcdriver doesn't need sub-device
drivers, as the camera's internal firmware does the interface with the
sensors.

We could, instead define it as:

    Bridge driver
	A driver that provides a bridge between the CPU's bus to the
	data and control buses of a media hardware. Often, the
	bridge driver is the same as V4L2 main driver.

Thanks,
Mauro

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Tue, 10 Oct 2017 10:27:12 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> > +    V4L2 sub-device driver
> > +	Part of the media hardware that implements support for
> > +	a hardware component.  
> 
> The description now no longer fits the term. I suggest:
> 
> "The V4L2 driver that implements support for a hardware component."

Look how we defined the term driver:

    Driver
	The part of the Linux Kernel that implements support
        for a hardware component.

If we define sub-device driver as you're proposing, we're basically
saying that:
	sub-device driver == Driver

with is not true.

I guess the proper definition would be, instead:

    V4L2 sub-device driver
	A driver for a media component whose bus(es) connects it
	to the hardware controlled via the V4L2 main driver.
	


Thanks,
Mauro

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Fri, 6 Oct 2017 13:22:29 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> Thanks for continuing the work on this!
> 
> On Wed, Sep 27, 2017 at 07:23:43PM -0300, Mauro Carvalho Chehab wrote:
> > Add a glossary of terms for V4L2, as several concepts are complex
> > enough to cause misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/media/uapi/v4l/glossary.rst | 136 ++++++++++++++++++++++++++++++
> >  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
> >  2 files changed, 137 insertions(+)
> >  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> > 
> > diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> > new file mode 100644
> > index 000000000000..b6767da1a46e
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > @@ -0,0 +1,136 @@
> > +========
> > +Glossary
> > +========
> > +
> > +.. note::
> > +
> > +   This goal of section is to standardize the terms used within the V4L2
> > +   documentation. It is written incrementally as they are standardized in
> > +   the V4L2 documentation. So, it is a Work In Progress.
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +    Bridge driver
> > +	The same as V4L2 main driver.  
> 
> Not all V4L2 main drivers can be bridge drivers. Mem-to-mem devices, for
> instance. How about:
> 
> A driver for a device receiving image data from another device (or
> transmitting it to a sub-device) controlled by a sub-device driver. Bridge
> drivers typically act as V4L2 main drivers.
> 
> > +
> > +    Device Node
> > +	A character device node in the file system used to control and do
> > +	input/output data transfers from/to a Kernel driver.
> > +
> > +    Digital Signal Processor - DSP
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.
> > +
> > +    Driver
> > +	The part of the Linux Kernel that implements support
> > +	for a hardware component.
> > +
> > +    Field-programmable Gate Array - FPGA
> > +	A field-programmable gate array (FPGA) is an integrated circuit
> > +	designed to be configured by a customer or a designer after
> > +	manufacturing.
> > +
> > +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> > +
> > +    Hardware component
> > +	A subset of the media hardware. For example an I²C or SPI device,
> > +	or an IP block inside an SoC or FPGA.
> > +
> > +    Image Signal Processor - ISP
> > +	A specialised processor that implements a set of algorithms for
> > +	processing image data. ISPs may implement algorithms for lens
> > +	shading correction, demosaic, scaling and pixel format conversion
> > +	as well as produce statistics for the use of the control
> > +	algorithms (e.g. automatic exposure, white balance and focus).  
> 
> And perhaps add:
> 
> ISP drivers often contain a receiver for image data from external source
> such as a sensor and act as V4L2 main driver.

OK.

> 
> > +
> > +    Inter-Integrated Circuit - I²C
> > +	A  multi-master, multi-slave, packet switched, single-ended,
> > +	serial computer bus used to control V4L2 sub-devices.
> > +
> > +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> > +
> > +    Integrated circuit - IC
> > +	A set of electronic circuits on one small flat piece of
> > +	semiconductor material, normally silicon.
> > +
> > +	Also known as chip.
> > +
> > +    Intellectual property core - IP core
> > +	In electronic design a semiconductor intellectual property core,
> > +	is a reusable unit of logic, cell, or integrated circuit layout
> > +	design that is the intellectual property of one party.
> > +	IP cores may be licensed to another party or can be owned
> > +	and used by a single party alone.
> > +
> > +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> > +
> > +    IP block
> > +	The same as IP core.
> > +
> > +    MC-centric
> > +	V4L2 hardware that requires a Media controller.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    Media Controller
> > +	An API designed to expose and control devices and sub-devices
> > +	relationships to applications.
> > +
> > +	See :ref:`media_controller`.
> > +
> > +    Media hardware
> > +	A group of hardware components that together make a larger
> > +	user-facing functional media hardware. For instance the SoC ISP IP
> > +	cores and external camera sensors together make a
> > +	camera media hardware.
> > +
> > +    Media hardware control
> > +	Type of control for a media hardware supported by V4L2 drivers.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    Microprocessor
> > +	An electronic circuitry that carries out the instructions
> > +	of a computer program by performing the basic arithmetic, logical,
> > +	control and input/output (I/O) operations specified by the
> > +	instructions on a single integrated circuit.
> > +
> > +    SMBus
> > +	A subset of I²C, with defines a stricter usage of the bus.
> > +
> > +    Serial Peripheral Interface Bus - SPI
> > +	Synchronous serial communication interface specification used for
> > +	short distance communication, primarily in embedded systems.
> > +
> > +    System on a Chip - SoC
> > +	An integrated circuit that integrates all components of a computer
> > +	or other electronic systems.
> > +
> > +    V4L2 device node
> > +	A device node that is associated to a V4L2 main driver,
> > +	as specified in :ref:`v4l2_device_naming`.
> > +
> > +    V4L2 hardware
> > +	A hardware used to on a media device supported by the V4L2
> > +	subsystem.  
> 
> I'm not sure what this means. Nor I think the proposed term is good for the
> reasons elaborated earlier. "Media hardware" above has similar issues.
> 
> What we would need a name for is a device that consists of other devices
> that are not usable individually, but instead as an ensemble.
> 
> I think "aggregate device", for instance, would be good as it catches the
> essence of the nature of the system. We'd have "Media aggregate device" and
> "V4L2 aggregate device".
> 
> An alternative would be simply to leave this out for now, but then we'll
> have issues elsewhere. I'm certainly open for better options if someone can
> come up with a better name.

I liked Hans proposal for it:

    V4L2 hardware
        Hardware that is controlled by a V4L2 main driver or a V4L2
        sub-device driver. V4L2 hardware is a subset of the
        Media hardware. Often the two are the same, but Media hardware
        can also contain other non-V4L2 hardware such as DVB hardware.

Perhaps we could change it a little bit to contain the word "ensemble",
e. g.:

    V4L2 hardware
	Ensembles the hardware that is controlled by a V4L2 main driver
	and by the associated V4L2 sub-device drivers. V4L2 hardware is
	a subset of the Media hardware. Often the two are the same,
	but Media hardware can also contain other non-V4L2 hardware
	such as DVB hardware.

> 
> > +
> > +    V4L2 main driver
> > +	The V4L2 device driver that implements the main logic to talk with
> > +	the V4L2 hardware.
> > +
> > +	Also known as bridge driver.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > +
> > +    V4L2 sub-device
> > +	Part of the media hardware that is implemented via a
> > +	V4L2 sub-device driver.
> > +
> > +	See :ref:`subdev`.
> > +
> > +    Vdevnode-centric  
> 
> I think this looks quite awkward. How about "Video device node centric" or
> "Video node centric"? I don't think it'd be too long.

I'll add the full name here and for MC-centric.

> 
> > +	V4L2 hardware that it is controlled via V4L2 device nodes.
> > +
> > +	See :ref:`v4l2_hardware_control`.
> > diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> > index 2128717299b3..698c060939f0 100644
> > --- a/Documentation/media/uapi/v4l/v4l2.rst
> > +++ b/Documentation/media/uapi/v4l/v4l2.rst
> > @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
> >      videodev
> >      capture-example
> >      v4l2grab-example
> > +    glossary
> >      biblio
> >  
> >    
> 

I'm enclosing the diff, against v7, that should hopefully cover all
the points that both you and Hans mentioned.

Thanks,
Mauro


diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
index b6767da1a46e..08980e9cb98e 100644
--- a/Documentation/media/uapi/v4l/glossary.rst
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -13,15 +13,20 @@ Glossary
 .. glossary::
 
     Bridge driver
-	The same as V4L2 main driver.
+	A driver that provides a bridge between the CPU's bus to the
+	data and control buses of a media hardware. Often, the
+	bridge driver is the same as V4L2 main driver.
+
+    Chip:
+	See: Integrated circuit.
 
     Device Node
-	A character device node in the file system used to control and do
-	input/output data transfers from/to a Kernel driver.
+	A character device node in the file system used to control and/or
+	do input/output data transfers from/to a Kernel driver.
 
     Digital Signal Processor - DSP
 	A specialized microprocessor, with its architecture optimized for
-	the operational needs of digital signal processing.
+	the operational requirements of digital signal processing.
 
     Driver
 	The part of the Linux Kernel that implements support
@@ -45,9 +50,13 @@ Glossary
 	as well as produce statistics for the use of the control
 	algorithms (e.g. automatic exposure, white balance and focus).
 
+	ISP drivers often contain a receiver for image data from external
+	sources such as sensors and act as V4L2 main driver.
+
     Inter-Integrated Circuit - I²C
 	A  multi-master, multi-slave, packet switched, single-ended,
-	serial computer bus used to control V4L2 sub-devices.
+	serial computer bus. Most V4L2 sub-devices are controlled
+	via this bus.
 
 	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
 
@@ -67,23 +76,23 @@ Glossary
 	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
 
     IP block
-	The same as IP core.
-
-    MC-centric
-	V4L2 hardware that requires a Media controller.
-
-	See :ref:`v4l2_hardware_control`.
+	See: IP core.
 
     Media Controller
-	An API designed to expose and control devices and sub-devices
-	relationships to applications.
+	An API designed to expose and control the relationships of the Media
+	Harware to applications.
 
 	See :ref:`media_controller`.
 
+    Media Controller centric - MC-centric
+	V4L2 hardware that requires a Media controller.
+
+	See :ref:`v4l2_hardware_control`.
+
     Media hardware
-	A group of hardware components that together make a larger
-	user-facing functional media hardware. For instance the SoC ISP IP
-	cores and external camera sensors together make a
+	A group of hardware components that together form the
+	functional media hardware. For instance the SoC ISP IP
+	cores and external camera sensors together form the
 	camera media hardware.
 
     Media hardware control
@@ -113,8 +122,10 @@ Glossary
 	as specified in :ref:`v4l2_device_naming`.
 
     V4L2 hardware
-	A hardware used to on a media device supported by the V4L2
-	subsystem.
+	Hardware that is controlled by a V4L2 main driver or a V4L2
+	sub-device driver. V4L2 hardware is a subset of the
+	Media hardware. Often the two are the same, but Media hardware
+	can also contain other non-V4L2 hardware such as DVB hardware.
 
     V4L2 main driver
 	The V4L2 device driver that implements the main logic to talk with
@@ -125,12 +136,15 @@ Glossary
 	See :ref:`v4l2_hardware_control`.
 
     V4L2 sub-device
-	Part of the media hardware that is implemented via a
-	V4L2 sub-device driver.
+	See: :ref:`V4L2 sub-device driver`
+
+    V4L2 sub-device driver
+	A driver for a media component whose bus(es) connects it
+	to the hardware controlled via the V4L2 main driver.
 
 	See :ref:`subdev`.
 
-    Vdevnode-centric
-	V4L2 hardware that it is controlled via V4L2 device nodes.
+    Video device node centric - Vdevnode-centric
+	V4L2 hardware that is controlled via V4L2 device nodes.
 
 	See :ref:`v4l2_hardware_control`.

[PATCH] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Add a glossary of terms for V4L2, as several concepts are complex
enough to cause misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/glossary.rst | 150 ++++++++++++++++++++++++++++++
 Documentation/media/uapi/v4l/v4l2.rst     |   1 +
 2 files changed, 151 insertions(+)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
new file mode 100644
index 000000000000..08980e9cb98e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,150 @@
+========
+Glossary
+========
+
+.. note::
+
+   This goal of section is to standardize the terms used within the V4L2
+   documentation. It is written incrementally as they are standardized in
+   the V4L2 documentation. So, it is a Work In Progress.
+
+.. Please keep the glossary entries in alphabetical order
+
+.. glossary::
+
+    Bridge driver
+	A driver that provides a bridge between the CPU's bus to the
+	data and control buses of a media hardware. Often, the
+	bridge driver is the same as V4L2 main driver.
+
+    Chip:
+	See: Integrated circuit.
+
+    Device Node
+	A character device node in the file system used to control and/or
+	do input/output data transfers from/to a Kernel driver.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational requirements of digital signal processing.
+
+    Driver
+	The part of the Linux Kernel that implements support
+	for a hardware component.
+
+    Field-programmable Gate Array - FPGA
+	A field-programmable gate array (FPGA) is an integrated circuit
+	designed to be configured by a customer or a designer after
+	manufacturing.
+
+	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+    Hardware component
+	A subset of the media hardware. For example an I²C or SPI device,
+	or an IP block inside an SoC or FPGA.
+
+    Image Signal Processor - ISP
+	A specialised processor that implements a set of algorithms for
+	processing image data. ISPs may implement algorithms for lens
+	shading correction, demosaic, scaling and pixel format conversion
+	as well as produce statistics for the use of the control
+	algorithms (e.g. automatic exposure, white balance and focus).
+
+	ISP drivers often contain a receiver for image data from external
+	sources such as sensors and act as V4L2 main driver.
+
+    Inter-Integrated Circuit - I²C
+	A  multi-master, multi-slave, packet switched, single-ended,
+	serial computer bus. Most V4L2 sub-devices are controlled
+	via this bus.
+
+	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+    Integrated circuit - IC
+	A set of electronic circuits on one small flat piece of
+	semiconductor material, normally silicon.
+
+	Also known as chip.
+
+    Intellectual property core - IP core
+	In electronic design a semiconductor intellectual property core,
+	is a reusable unit of logic, cell, or integrated circuit layout
+	design that is the intellectual property of one party.
+	IP cores may be licensed to another party or can be owned
+	and used by a single party alone.
+
+	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
+
+    IP block
+	See: IP core.
+
+    Media Controller
+	An API designed to expose and control the relationships of the Media
+	Harware to applications.
+
+	See :ref:`media_controller`.
+
+    Media Controller centric - MC-centric
+	V4L2 hardware that requires a Media controller.
+
+	See :ref:`v4l2_hardware_control`.
+
+    Media hardware
+	A group of hardware components that together form the
+	functional media hardware. For instance the SoC ISP IP
+	cores and external camera sensors together form the
+	camera media hardware.
+
+    Media hardware control
+	Type of control for a media hardware supported by V4L2 drivers.
+
+	See :ref:`v4l2_hardware_control`.
+
+    Microprocessor
+	An electronic circuitry that carries out the instructions
+	of a computer program by performing the basic arithmetic, logical,
+	control and input/output (I/O) operations specified by the
+	instructions on a single integrated circuit.
+
+    SMBus
+	A subset of I²C, with defines a stricter usage of the bus.
+
+    Serial Peripheral Interface Bus - SPI
+	Synchronous serial communication interface specification used for
+	short distance communication, primarily in embedded systems.
+
+    System on a Chip - SoC
+	An integrated circuit that integrates all components of a computer
+	or other electronic systems.
+
+    V4L2 device node
+	A device node that is associated to a V4L2 main driver,
+	as specified in :ref:`v4l2_device_naming`.
+
+    V4L2 hardware
+	Hardware that is controlled by a V4L2 main driver or a V4L2
+	sub-device driver. V4L2 hardware is a subset of the
+	Media hardware. Often the two are the same, but Media hardware
+	can also contain other non-V4L2 hardware such as DVB hardware.
+
+    V4L2 main driver
+	The V4L2 device driver that implements the main logic to talk with
+	the V4L2 hardware.
+
+	Also known as bridge driver.
+
+	See :ref:`v4l2_hardware_control`.
+
+    V4L2 sub-device
+	See: :ref:`V4L2 sub-device driver`
+
+    V4L2 sub-device driver
+	A driver for a media component whose bus(es) connects it
+	to the hardware controlled via the V4L2 main driver.
+
+	See :ref:`subdev`.
+
+    Video device node centric - Vdevnode-centric
+	V4L2 hardware that is controlled via V4L2 device nodes.
+
+	See :ref:`v4l2_hardware_control`.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index 2128717299b3..698c060939f0 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
     videodev
     capture-example
     v4l2grab-example
+    glossary
     biblio
 
 
-- 
2.13.6

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

On Tue, Oct 10, 2017 at 05:30:04AM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 6 Oct 2017 13:22:29 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > > +    Bridge driver
> > > +	The same as V4L2 main driver.  
> > 
> > Not all V4L2 main drivers can be bridge drivers. Mem-to-mem devices, for
> > instance. How about:
> > 
> > A driver for a device receiving image data from another device (or
> > transmitting it to a sub-device) controlled by a sub-device driver. Bridge
> > drivers typically act as V4L2 main drivers.
> 
> That is not true for some device drivers we have.
> 
> The GSPCA drivers are bridge drivers, but they don't use any sub-device
> (well, it should, but nobody will redesign it, as the efforts would
> be huge, for a very little gain). Also uvcdriver doesn't need sub-device
> drivers, as the camera's internal firmware does the interface with the
> sensors.
> 
> We could, instead define it as:
> 
>     Bridge driver
> 	A driver that provides a bridge between the CPU's bus to the
> 	data and control buses of a media hardware. Often, the
> 	bridge driver is the same as V4L2 main driver.

Looks good to me.

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Fri, 6 Oct 2017 14:51:06 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Fri, Oct 06, 2017 at 01:22:29PM +0300, Sakari Ailus wrote:
> > > +    V4L2 device node
> > > +	A device node that is associated to a V4L2 main driver,
> > > +	as specified in :ref:`v4l2_device_naming`.  
> 
> I think we need to name the interface, not so much their instances.
> 
> How about adding:
> 
>     V4L2
> 	Video4Linux 2 interface. The interface implemented by **V4L2 device
> 	nodes**.
> 
> and:
> 
>     V4L2 device node
> 	A device node implementing the **V4L2** interface.

Not sure if I answered it already. subdev API is part of V4L2.
So, a change like that would cause more harm than good ;-)

The definition should let it clear that only the devnodes 
implemented by the V4L2 main driver are considered as
V4L2 device nodes.

Regards,
Mauro

Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types

[Mauro Carvalho Chehab]

Em Fri, 6 Oct 2017 15:24:27 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> > +When V4L2 was originally designed, there was only one type of
> > +media hardware control: via the **V4L2 device nodes**. We refer to this kind
> > +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**").  
> 
> I think this could be easier understood if we start with the differences
> instead of what we call the types. I'd also refer to interfaces rather than
> their instances.
> 
> How about (pending finalising discussion on naming):
> 
> When **V4L2** was originally designed, the **V4L2 device** served the
> purpose of both control and data interfaces and there was no separation
> between the two interface-wise. V4L2 controls, setting inputs and outputs,
> format configuration and buffer related operations were all performed
> through the same **V4L2 device nodes**. Devices offering such interface are
> called **V4L2 device node centric**.
> 
> Later on, support for the **Media controller** interface was added to V4L2
> in order to better support complex **V4L2 aggregate devices** where the
> **V4L2** interface alone could no longer meaningfully serve as both a
> control and a data interface. On such aggregate devices, **V4L2** interface
> remains a data interface whereas control takes place through the **Media
> controller** and **V4L2 sub-device** interfaces. Stream control is an
> exception to this: streaming is enabled and disabled through the **V4L2**
> interface. These devices are called **Media controller centric**.
> 
> **MC-centric** aggregate devices provide more versatile control of the
> hardware than **V4L2 device node centric** devices. On **MC-centric**
> aggregate devices the **V4L2 sub-device nodes** represent specific parts of
> the **V4L2 aggregate device**, to which they enable control.
> 
> Also, the additional versatility of **MC-centric** aggregate devices comes
> with additional responsibilities, the main one of which is the requirements
> of the user configuring the device pipeline before starting streaming. This
> typically involves configuring the links using the **Media controller**
> interface and the media bus formats on pads (at both ends of the links)
> using the **V4L2 sub-device** interface.

Works for me. 

Except that I didn't like the idea of "aggregate devices". So, I kept
the previously agreed term "V4L2 hardware".

Also, as everything comes with a price, I added it on this paragraph:

	**MC-centric** V4L2 hardware provide more versatile control of the
	hardware than **V4L2 device node centric** devices at the expense of
	requiring device-specific userspace settings.

Finally, I'm now using :term:`foo` Sphinx directive on the patchset
(I'll send a new version soon) at the first time a term appears inside
a section[1].

[1] We might repeat that on every occurrence of a term, but:
	a) it sounded overkill to me;
	b) if we decide to change some term, there will be a lot
	   more stuff to be fixed, specially for terms in plural,
	   as a plural for :term:`device` would be
	   :term:`devices <device>`.
    Once we set this patchset into a stone, it could make sense to
    run some script that would replace every other occurrence of the
    glossary terms within Documentation/media/uapi/v4l to link to
    the glossary reference - but let's postpone this to be applied
    on a separate patchset.
    Btw, it probably makes sense to make the glossary as a general
    media book glossary - but again, this is out of topic for this
    patchset.


With this, the version I'm adding is:

<snippet>
When **V4L2** was originally designed, the
:term:`V4L2 device nodes <v4l2 device node>` served the purpose of both
control and data interfaces and there was no separation
between the two interface-wise. V4L2 controls, setting inputs and outputs,
format configuration and buffer related operations were all performed
through the same **V4L2 device nodes**. Devices offering such interface are
called **V4L2 device node centric**.

Later on, support for the :term:`media controller` interface was added
to V4L2 in order to better support complex :term:`V4L2 hardware` where the 
**V4L2** interface alone could no longer meaningfully serve as both a
control and a data interface. On such V4L2 hardware, **V4L2** interface
remains a data interface whereas control takes place through the 
:term:`media controller` and :term:`V4L2 sub-device` interfaces. Stream
control is an exception to this: streaming is enabled and disabled
through the **V4L2** interface. These devices are called
**Media controller centric**.

**MC-centric** V4L2 hardware provide more versatile control of the
hardware than **V4L2 device node centric** devices at the expense of
requiring device-specific userspace settings.

On **MC-centric** V4L2 hardware, the **V4L2 sub-device nodes** 
represent specific parts of the V4L2 hardware, to which they enable
control.

Also, the additional versatility of **MC-centric** V4L2 hardware comes
with additional responsibilities, the main one of which is the requirements
of the user configuring the device pipeline before starting streaming. This
typically involves configuring the links using the **Media controller**
interface and the media bus formats on pads (at both ends of the links)
using the **V4L2 sub-device** interface.
</snippet>



Thanks,
Mauro

Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Mauro Carvalho Chehab]

Em Fri, 6 Oct 2017 15:48:22 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Wed, Sep 27, 2017 at 07:23:47PM -0300, Mauro Carvalho Chehab wrote:
> > As we now have a glossary, some terms used on open.rst
> > require adjustments.
> > 
> > Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/media/uapi/v4l/open.rst | 12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> > 
> > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> > index f603bc9b49a0..0daf0c122c19 100644
> > --- a/Documentation/media/uapi/v4l/open.rst
> > +++ b/Documentation/media/uapi/v4l/open.rst
> > @@ -143,7 +143,7 @@ Related Devices
> >  Devices can support several functions. For example video capturing, VBI
> >  capturing and radio support.
> >  
> > -The V4L2 API creates different nodes for each of these functions.
> > +The V4L2 API creates different V4L2 device nodes for each of these functions.  
> 
> A V4L2 device node is an instance of the V4L2 API. At the very least we
> should call them "V4L2 device node types", not device nodes only. This
> simply would suggests they're separate.

OK, I added "types" there.

> 
> s/creates/defines/ ?

It is meant to say create.

A device that supports both radio, video and VBI for the same V4L2
input will create three device nodes:
	/dev/video0
	/dev/radio0
	/dev/vbi0

As all are associated to the same video input, and an ioctl send 
to one device may affect the other devices too, as they all associated
with the same hardware.

Thanks,
Mauro

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

On Tue, Oct 10, 2017 at 06:15:03AM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 6 Oct 2017 14:51:06 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > Hi Mauro,
> > 
> > On Fri, Oct 06, 2017 at 01:22:29PM +0300, Sakari Ailus wrote:
> > > > +    V4L2 device node
> > > > +	A device node that is associated to a V4L2 main driver,
> > > > +	as specified in :ref:`v4l2_device_naming`.  
> > 
> > I think we need to name the interface, not so much their instances.
> > 
> > How about adding:
> > 
> >     V4L2
> > 	Video4Linux 2 interface. The interface implemented by **V4L2 device
> > 	nodes**.
> > 
> > and:
> > 
> >     V4L2 device node
> > 	A device node implementing the **V4L2** interface.
> 
> Not sure if I answered it already. subdev API is part of V4L2.
> So, a change like that would cause more harm than good ;-)

Hmm. There seems to be a gap here. It'd be much easier to maintain
consistency in naming and definitions if V4L2 sub-device nodes were also
documented to be V4L2 device nodes, just as any other device nodes exposed
by drivers through the V4L2 framework.

> 
> The definition should let it clear that only the devnodes 
> implemented by the V4L2 main driver are considered as
> V4L2 device nodes.

Why? I don't think we should make assumptions on which driver exposes a
device node; this is not visible to the user space after all.

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Tue, 10 Oct 2017 14:54:35 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> On Tue, Oct 10, 2017 at 06:15:03AM -0300, Mauro Carvalho Chehab wrote:
> > Em Fri, 6 Oct 2017 14:51:06 +0300
> > Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > On Fri, Oct 06, 2017 at 01:22:29PM +0300, Sakari Ailus wrote:  
> > > > > +    V4L2 device node
> > > > > +	A device node that is associated to a V4L2 main driver,
> > > > > +	as specified in :ref:`v4l2_device_naming`.    
> > > 
> > > I think we need to name the interface, not so much their instances.
> > > 
> > > How about adding:
> > > 
> > >     V4L2
> > > 	Video4Linux 2 interface. The interface implemented by **V4L2 device
> > > 	nodes**.
> > > 
> > > and:
> > > 
> > >     V4L2 device node
> > > 	A device node implementing the **V4L2** interface.  
> > 
> > Not sure if I answered it already. subdev API is part of V4L2.
> > So, a change like that would cause more harm than good ;-)  
> 
> Hmm. There seems to be a gap here. It'd be much easier to maintain
> consistency in naming and definitions if V4L2 sub-device nodes were also
> documented to be V4L2 device nodes, just as any other device nodes exposed
> by drivers through the V4L2 framework.
> 
> > 
> > The definition should let it clear that only the devnodes 
> > implemented by the V4L2 main driver are considered as
> > V4L2 device nodes.  
> 
> Why? I don't think we should make assumptions on which driver exposes a
> device node; this is not visible to the user space after all.

Because the V4L2 spec documents, with the exception of the subdev.rst
(and where otherwise noticed), assumes that a V4L2 device node doesn't
include subdevs.

So, if you loo, for example, at the chapter 1 name:
	"common API elements"

it implies that every single V4L2 device node supports what's there.
But that's not the case, for example, for what's described at
Documentation/media/uapi/v4l/querycap.rst (with is part of
chapter 1).

There are a couple of possible alternatives:

1) define V4L2 device nodes excluding /dev/subdev, with is the
   current approach;

2) rewrite the entire V4L2 uAPI spec to explicitly talk, on each
   section, if it applies or not to sub-devices;

3) "promote" subdev API to a separate part of the media spec,
   just like what it was done for media controller, e. g. adding
   a /Documentation/media/uapi/subdev directory and add there
   descriptions for all syscalls that apply to subdevs
   (open, close, ioctl). That would be weird from kAPI point of
   view, as splitting it from V4L2 won't make sense there. So,
   we'll likely need to add some notes at both kAPI and uAPI to
   explain that the subdev API userspace API is just a different
   way to expose V4L2 hardware control, but, internally, both
   are implemented by the same V4L2 core.

This patchset assumes (1). I'm ok if someone wants to do either
(2) or (3), but I won't have the required time to do such
changes.


Thanks,
Mauro

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

On Tue, Oct 10, 2017 at 09:49:38AM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 10 Oct 2017 14:54:35 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > On Tue, Oct 10, 2017 at 06:15:03AM -0300, Mauro Carvalho Chehab wrote:
> > > Em Fri, 6 Oct 2017 14:51:06 +0300
> > > Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> > >   
> > > > Hi Mauro,
> > > > 
> > > > On Fri, Oct 06, 2017 at 01:22:29PM +0300, Sakari Ailus wrote:  
> > > > > > +    V4L2 device node
> > > > > > +	A device node that is associated to a V4L2 main driver,
> > > > > > +	as specified in :ref:`v4l2_device_naming`.    
> > > > 
> > > > I think we need to name the interface, not so much their instances.
> > > > 
> > > > How about adding:
> > > > 
> > > >     V4L2
> > > > 	Video4Linux 2 interface. The interface implemented by **V4L2 device
> > > > 	nodes**.
> > > > 
> > > > and:
> > > > 
> > > >     V4L2 device node
> > > > 	A device node implementing the **V4L2** interface.  
> > > 
> > > Not sure if I answered it already. subdev API is part of V4L2.
> > > So, a change like that would cause more harm than good ;-)  
> > 
> > Hmm. There seems to be a gap here. It'd be much easier to maintain
> > consistency in naming and definitions if V4L2 sub-device nodes were also
> > documented to be V4L2 device nodes, just as any other device nodes exposed
> > by drivers through the V4L2 framework.
> > 
> > > 
> > > The definition should let it clear that only the devnodes 
> > > implemented by the V4L2 main driver are considered as
> > > V4L2 device nodes.  
> > 
> > Why? I don't think we should make assumptions on which driver exposes a
> > device node; this is not visible to the user space after all.
> 
> Because the V4L2 spec documents, with the exception of the subdev.rst
> (and where otherwise noticed), assumes that a V4L2 device node doesn't
> include subdevs.
> 
> So, if you loo, for example, at the chapter 1 name:
> 	"common API elements"
> 
> it implies that every single V4L2 device node supports what's there.
> But that's not the case, for example, for what's described at
> Documentation/media/uapi/v4l/querycap.rst (with is part of
> chapter 1).

Ah. I see what you mean.

> 
> There are a couple of possible alternatives:
> 
> 1) define V4L2 device nodes excluding /dev/subdev, with is the
>    current approach;
> 
> 2) rewrite the entire V4L2 uAPI spec to explicitly talk, on each
>    section, if it applies or not to sub-devices;

There are exceptions in the common API elements section even now. For
instance, it mentions that radio devices don't support video streaming
related IOCTLs. Under common API elements, also the first section (opening
and closing devices) refers to the interfaces section which, as we know,
contains sub-device documentation.

Do you see that something else is needed than telling which common API
elements aren't relevant for sub-devices? (I didn't find explicit
information in other sections, by a quick glance at least, telling which
interfaces they apply to.)

Should we make such a change, this would be an additional argument for
supporting VIDIOC_QUERYCAP on sub-devices. Further on, section 8, "Common
definitions for V4L2 and V4L2 subdev interfaces", should probably be merged
with the "common API elements" section.

Just my thougts. Anyway... let's continue tomorrow.

> 
> 3) "promote" subdev API to a separate part of the media spec,
>    just like what it was done for media controller, e. g. adding
>    a /Documentation/media/uapi/subdev directory and add there
>    descriptions for all syscalls that apply to subdevs
>    (open, close, ioctl). That would be weird from kAPI point of
>    view, as splitting it from V4L2 won't make sense there. So,
>    we'll likely need to add some notes at both kAPI and uAPI to
>    explain that the subdev API userspace API is just a different
>    way to expose V4L2 hardware control, but, internally, both
>    are implemented by the same V4L2 core.
> 
> This patchset assumes (1). I'm ok if someone wants to do either
> (2) or (3), but I won't have the required time to do such
> changes.

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Sakari Ailus]

Hi Mauro,

On Tue, Oct 10, 2017 at 08:37:43AM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 6 Oct 2017 15:48:22 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > Hi Mauro,
> > 
> > On Wed, Sep 27, 2017 at 07:23:47PM -0300, Mauro Carvalho Chehab wrote:
> > > As we now have a glossary, some terms used on open.rst
> > > require adjustments.
> > > 
> > > Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > ---
> > >  Documentation/media/uapi/v4l/open.rst | 12 ++++++------
> > >  1 file changed, 6 insertions(+), 6 deletions(-)
> > > 
> > > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> > > index f603bc9b49a0..0daf0c122c19 100644
> > > --- a/Documentation/media/uapi/v4l/open.rst
> > > +++ b/Documentation/media/uapi/v4l/open.rst
> > > @@ -143,7 +143,7 @@ Related Devices
> > >  Devices can support several functions. For example video capturing, VBI
> > >  capturing and radio support.
> > >  
> > > -The V4L2 API creates different nodes for each of these functions.
> > > +The V4L2 API creates different V4L2 device nodes for each of these functions.  
> > 
> > A V4L2 device node is an instance of the V4L2 API. At the very least we
> > should call them "V4L2 device node types", not device nodes only. This
> > simply would suggests they're separate.
> 
> OK, I added "types" there.
> 
> > 
> > s/creates/defines/ ?
> 
> It is meant to say create.
> 
> A device that supports both radio, video and VBI for the same V4L2
> input will create three device nodes:
> 	/dev/video0
> 	/dev/radio0
> 	/dev/vbi0
> 
> As all are associated to the same video input, and an ioctl send 
> to one device may affect the other devices too, as they all associated
> with the same hardware.

Right. In this case I'd change the sentence. What would you think of this?

"Each of these functions is available via separate V4L2 device node."

For it's not the V4L2 API that creates them. I failed to grasp what the
original sentence meant. Was it about API, or framework, or were the
devices nodes just separate or unlike as well?

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary

[Mauro Carvalho Chehab]

Em Wed, 11 Oct 2017 01:41:00 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Tue, Oct 10, 2017 at 08:37:43AM -0300, Mauro Carvalho Chehab wrote:
> > Em Fri, 6 Oct 2017 15:48:22 +0300
> > Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > On Wed, Sep 27, 2017 at 07:23:47PM -0300, Mauro Carvalho Chehab wrote:  
> > > > As we now have a glossary, some terms used on open.rst
> > > > require adjustments.
> > > > 
> > > > Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > > ---
> > > >  Documentation/media/uapi/v4l/open.rst | 12 ++++++------
> > > >  1 file changed, 6 insertions(+), 6 deletions(-)
> > > > 
> > > > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> > > > index f603bc9b49a0..0daf0c122c19 100644
> > > > --- a/Documentation/media/uapi/v4l/open.rst
> > > > +++ b/Documentation/media/uapi/v4l/open.rst
> > > > @@ -143,7 +143,7 @@ Related Devices
> > > >  Devices can support several functions. For example video capturing, VBI
> > > >  capturing and radio support.
> > > >  
> > > > -The V4L2 API creates different nodes for each of these functions.
> > > > +The V4L2 API creates different V4L2 device nodes for each of these functions.    
> > > 
> > > A V4L2 device node is an instance of the V4L2 API. At the very least we
> > > should call them "V4L2 device node types", not device nodes only. This
> > > simply would suggests they're separate.  
> > 
> > OK, I added "types" there.
> >   
> > > 
> > > s/creates/defines/ ?  
> > 
> > It is meant to say create.
> > 
> > A device that supports both radio, video and VBI for the same V4L2
> > input will create three device nodes:
> > 	/dev/video0
> > 	/dev/radio0
> > 	/dev/vbi0
> > 
> > As all are associated to the same video input, and an ioctl send 
> > to one device may affect the other devices too, as they all associated
> > with the same hardware.  
> 
> Right. In this case I'd change the sentence. What would you think of this?
> 
> "Each of these functions is available via separate V4L2 device node."

Maybe replacing "is" by "should be" (or shall be?) would express the
requirement.

> 
> For it's not the V4L2 API that creates them. I failed to grasp what the
> original sentence meant. Was it about API, or framework, or were the
> devices nodes just separate or unlike as well?

Short answer:

>From uAPI PoV, it doesn't matter if it is the driver or the framework
that creates multiple device nodes.

What matters is that, if multiple types of capture/input are possible, 
multiple devnodes are created. Also, if one wants to control a radio
function, it should use /dev/radio, instead of /dev/video.

Long answer:

At kAPI, a typical register code, found on almost all non-webcam drivers is:

	ret = video_register_device(&v4l2->vdev, VFL_TYPE_GRABBER,
				    video_nr[dev->devno]);
	if (ret)
		goto error;

	if (vbi_supported(dev)) {
		ret = video_register_device(&v4l2->vbi_dev, VFL_TYPE_VBI,
					    vbi_nr[dev->devno]);
		if (ret)
			goto error;
	}

	if (radio_supported(dev)) {
		ret = video_register_device(&v4l2->radio_dev, VFL_TYPE_RADIO,
					    radio_nr[dev->devno]);
		if (ret)
			goto error;
	}

	(note: it doesn't make sense to mention the above kAPI code at
	 the uAPI documentation)


All tree devnodes are associated to the same capture or input device.

In the past, it was possible to use a /dev/radio to watch a video,
or /dev/video to listen radio, as they both corresponds to the same
V4L2 device, and the ioctl arguments used for radio and VBI are 
different. In other words, "/dev/radio" and "/dev/vbi" worked like a
sort of alias to the same device. Such support, however, required the
V4L2 core to do some tricks to identify the type of usage between
radio and video modes when handling tuner ioctls, like
VIDIOC_G_FREQUENCY/VIDIOC_S_FREQUENCY, making harder to prevent the
simultaneous usage of the device by a radio and a video application,
and causing some bugs (like returning a FM frequency on TV, or an
UHF frequency on radio).

So, several years ago, the API spec was modified to forbid such
usage, and support for switching the mode between radio/video mode
based on ioctl set usage was removed.

Yet, the v4l2 core use a coarse logic there: it only handles
differently stuff that are required to be different (like frequencies).
It won't check if, for example, a CTRL belongs to radio or video.
So, one can change a control using any device node, no matter if
the control belongs to video or radio.

So, in summary, the goal of the "Related Devices" at uAPI is to
mention that, if a V4L2 device supports multiple types, multiple
device nodes will be created, one for each (V4L2 device, type)
tuple[1].

[1] So, a driver for a board that supports four V4L2 devices, each
    with radio, vbi and video will create 12 device nodes.

Thanks,
Mauro

Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Wed, 11 Oct 2017 01:18:58 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> > So, if you look, for example, at the chapter 1 name:
> > 	"common API elements"
> > 
> > it implies that every single V4L2 device node supports what's there.
> > But that's not the case, for example, for what's described at
> > Documentation/media/uapi/v4l/querycap.rst (with is part of
> > chapter 1).  
> 
> Ah. I see what you mean.
> 
> > 
> > There are a couple of possible alternatives:
> > 
> > 1) define V4L2 device nodes excluding /dev/subdev, with is the
> >    current approach;
> > 
> > 2) rewrite the entire V4L2 uAPI spec to explicitly talk, on each
> >    section, if it applies or not to sub-devices;  
> 
> There are exceptions in the common API elements section even now. For
> instance, it mentions that radio devices don't support video streaming
> related IOCTLs. 

FYI, when this chapter was written, radio devices did support video
streaming ioctls :-)

As I explained on a previous email, Only several years after V4L2
spec was written, it was decided to nack using a radio device to 
control a video stream.

The real issue is that radio sets frequencies on multiples of 62.5 Hz,
while TV sets frequencies on multiples of 62.5 kHz. Due to that, the
core needs to know if the device is in radio or TV mode, in order to
handle VIDIOC_G_FREQUENCY/VIDIOC_S_FREQUENCY. There was a code there
that used to identify, but it was buggy, and there were no safe way
fix.

So, the "common API elements" was modified to forbid to use radio to
do video stream.

Later, a coarse grain logic was added at the v4l2 core in order to
present a different set of ioctls, based on the V4L2 device type,
and the chapter was modified again.

On that time, we were lazy enough to rewrite chapter 1. So,
we just add an exception "hack" at the chapter noticing that
radio devices don't stream.

I don't see a strong reason to not add other pontual exceptions
there where pertinent, but if we start having too many exceptions,
then is time to rewrite it in a way that would make more sense.

> Under common API elements, also the first section (opening
> and closing devices) refers to the interfaces section which, as we know,
> contains sub-device documentation.

Yeah, exceptions could be added, but it means that someone should read
the entire chapter and mention what doesn't apply for subdev.

> Do you see that something else is needed than telling which common API
> elements aren't relevant for sub-devices? (I didn't find explicit
> information in other sections, by a quick glance at least, telling which
> interfaces they apply to.)

No. I didn't read the entire chapter to see what doesn't apply for
sub-devices, but I'm pretty sure that there are many things. For
example, you can't read/write/mmap/stream a video on a subdev.

> Should we make such a change, this would be an additional argument for
> supporting VIDIOC_QUERYCAP on sub-devices.

Nah. We shouldn't add ioctls with the argument that it would be easier
to document. Also, if we add a subdev QUERYCAP, it would provide a
different set of information than a V4L2 device QUERYCAP.

> Further on, section 8, "Common
> definitions for V4L2 and V4L2 subdev interfaces", should probably be merged
> with the "common API elements" section.

Well, if we go to approach (2), we'll need to shrink the common
API definitions chapter, and add another chapter for the "uncommon"
features.

As an exercise: try to rewrite just open.rst to exclude sudevs where
not pertinent. Even a single definition like this:


	The main driver always exposes one or more
	:term:`V4L2 device nodes <v4l2 device node>`
	(see :ref:`v4l2_device_naming`) with are responsible for implementing
	data streaming, if applicable.

will become a lot more complex to explain if we don't have any term
to refer to "all device node types created by the v4l2 core except
for /dev/v4l-subdev* and /dev/mediaXXX".

The "Related devices" and "Shared Data Streams" sections won't apply to
subdevs.

Most of what's written at the "Multiple Opens" section also don't
apply, as subdevs don't support streaming nor they accept the priority
mechanisms via VIDIOC_S_PRIORITY.

The notes at "Functions" section also don't apply to subdevs.

So, it is probably a lot easier to just create a new "open.rst"
for subdev API and remove all that doesn't apply - as proposed
in approach (3) (see below) - keeping the V4L2 one as-is.

In a matter of fact, most of the things explained at V4L2
part of the spec don't apply to subdevs. So, it is easier
to just tell what applies there (controls, events, format 
negotiation, crop/selection) than the opposite.

The dev-subdev.rst does a good job describing it. If we move
it from Documentation/media/uapi/v4l to Documentation/media/uapi/subdev,
all we need to do is to add chapters for the syscalls it
supports: open/close/ioctl, with can be a simplified version of what
is there at v4l, removing all things that don't apply to subdevs.

The dev-subdev.rst already has links to the pertinent sections
at v4l uAPI spec. So, I suspect that, if it require any change at
all, that would be minimal.

It would probably be worth to mention at the controls, events
and selection/crop sections that what's described there applies
to both V4L2 and subdev APIs.


> Just my thougts. Anyway... let's continue tomorrow.
> 
> > 
> > 3) "promote" subdev API to a separate part of the media spec,
> >    just like what it was done for media controller, e. g. adding
> >    a /Documentation/media/uapi/subdev directory and add there
> >    descriptions for all syscalls that apply to subdevs
> >    (open, close, ioctl). That would be weird from kAPI point of
> >    view, as splitting it from V4L2 won't make sense there. So,
> >    we'll likely need to add some notes at both kAPI and uAPI to
> >    explain that the subdev API userspace API is just a different
> >    way to expose V4L2 hardware control, but, internally, both
> >    are implemented by the same V4L2 core.

Long term, IMHO, (3) is the best solution. Also, I think it is easier
to do that than (2).

My proposal is that, for 4.15, we do (1), by adding an exception
to what we consider as V4L2 device nodes, explicitly excluding 
subdevs. Then, with time, we go to (3).

> > 
> > This patchset assumes (1). I'm ok if someone wants to do either
> > (2) or (3), but I won't have the required time to do such
> > changes.  


Thanks,
Mauro