document types of hardware control for V4L2
Subsystems (2)
v8 cover document types of hardware control for V4L2
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.
v8:
- Addressed Hans and Sakari's comments. Hopefully, we'll all agree with this one :-)
- Added :term:foo references at the glossary and at the first time a term appears inside a V4L2 section.
I opted to not replace all occurences for a couple of reasons:
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.
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 vdevnode-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 | 167 +++++++++++++++++++++++ Documentation/media/uapi/v4l/open.rst | 158 +++++++++++++++++---- 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, 309 insertions(+), 25 deletions(-) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Signature · 1 line
2.13.6
PATCH v8 1/7 media: add glossary.rst with a glossary of terms used at V4L2 spec
Add a glossary of terms for V4L2, as several concepts are complex enough to cause misunderstandings.
--- Documentation/media/uapi/v4l/glossary.rst | 167 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 168 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Documentation/media/uapi/v4l/glossary.rst new file +167 -0
@@ -0,0 +1,167 @@ +======== +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 :term:`media hardware`. Often, the + bridge driver is the same as :term:`V4L2 main driver`. + + Chip + :See: :term:`Integrated circuit`. + + Device Driver + Driver + The part of the Linux Kernel that implements support + for a :term:`hardware component`. + + 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 :term:`microprocessor`, with its architecture optimized + for the operational requirements of digital signal processing. + + Field-programmable Gate Array + FPGA + A field-programmable gate array (FPGA) is an :term:`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 :term:`media hardware`. For example an :term:`I²C` + or :term:`SPI` device, or an :term:`IP block` inside an + :term:`SoC` or :term:`FPGA`. + + Image Signal Processor + ISP + A specialized :term:`microprocessor` 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 :term:`V4L2 main driver`. + + Integrated circuit + IC + A set of electronic circuits on one small flat piece of + semiconductor material, normally silicon. + + Also known as :term:`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). + + Inter-Integrated Circuit + I²C + A multi-master, multi-slave, packet switched, single-ended, + serial computer bus. A :term:`V4L2 sub-device driver` usually is + controlled via this bus. + + :See: http://www.nxp.com/docs/en/user-guide/UM10204.pdf. + + IP block + :See: :term:`IP core`. + + Media controller + MC + An API designed to expose and control the relationships of the + :term:`media hardware` to applications. + + :See: :ref:`media_controller`. + + Media controller centric + MC-centric + :term:`V4L2 hardware` that requires a :term:`media controller`. + + :See: :ref:`v4l2_hardware_control`. + + Media hardware + A group of hardware components that together form the + functional media hardware. For instance the :term:`SoC` + :term:`ISP` :term:`IP cores <ip core>` and external camera + sensors together form the camera media hardware. + + Media hardware control + Type of control for a :term:`media hardware` supported a + V4L2 :term:`driver`. + + :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 :term:`integrated circuit`. + + SMBus + A subset of :term:`I²C`, with defines a stricter usage of the bus. + + Serial Peripheral Interface + SPI + Synchronous serial communication interface specification used for + short distance communication, primarily in embedded systems. + + System on a Chip + SoC + An :term:`integrated circuit` that integrates all components of a + computer or other electronic systems. + + V4L2 device node + A :term:`device node` that is associated to a + :term:`V4L2 main driver`, as specified in :ref:`v4l2_device_naming`. + + V4L2 hardware + Hardware that is controlled by a :term:`V4L2 main driver` or a + :term:`V4L2 sub-device driver`. V4L2 hardware is a subset of the + :term:`media hardware`. Often the two are the same, but + :term:`media hardware` can also contain other non-V4L2 hardware + such as Digital TV hardware. + + V4L2 main driver + The V4L2 :term:`device driver` that implements the main logic to + talk with the :term:`V4L2 hardware`. + + Often, the same as :term:`bridge driver`. + + :See: :ref:`v4l2_hardware_control`. + + V4L2 sub-device + :See: :term:`V4L2 sub-device driver`. + + V4L2 sub-device driver + A :term:`driver` for a :term:`media hardware` whose bus(es) + connects it to the hardware controlled via the + :term:`V4L2 main driver`. + + :See: :ref:`subdev`. + + Video device node centric + Vdevnode-centric + :term:`V4L2 hardware` that is controlled via + :term:`V4L2 device nodes <v4l2 device node>`. + + :See: :ref:`v4l2_hardware_control`.
Documentation/media/uapi/v4l/v4l2.rst +1 -0
@@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. videodev capture-example v4l2grab-example + glossary biblio
Signature · 1 line
2.13.6
Re: [PATCH v8 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
More (mostly) small stuff:
Quoted 112 lines · 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 <[email protected]>--- Documentation/media/uapi/v4l/glossary.rst | 167 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 168 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +96
-0@@ -0,0 +1,167 @@ +======== +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 :term:`media hardware`. Often, the + bridge driver is the same as :term:`V4L2 main driver`. + + Chip + :See: :term:`Integrated circuit`. + + Device Driver + Driver + The part of the Linux Kernel that implements support + for a :term:`hardware component`. + + 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 :term:`microprocessor`, with its architecture optimized + for the operational requirements of digital signal processing. + + Field-programmable Gate Array + FPGA + A field-programmable gate array (FPGA) is an :term:`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 :term:`media hardware`. For example an :term:`I²C` + or :term:`SPI` device, or an :term:`IP block` inside an + :term:`SoC` or :term:`FPGA`. + + Image Signal Processor + ISP + A specialized :term:`microprocessor` 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 :term:`V4L2 main driver`. + + Integrated circuit + IC + A set of electronic circuits on one small flat piece of + semiconductor material, normally silicon. + + Also known as :term:`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). + + Inter-Integrated Circuit + I²C + A multi-master, multi-slave, packet switched, single-ended, + serial computer bus. A :term:`V4L2 sub-device driver` usually is + controlled via this bus. + + :See: http://www.nxp.com/docs/en/user-guide/UM10204.pdf. + + IP block + :See: :term:`IP core`. + + Media controller + MC + An API designed to expose and control the relationships of the + :term:`media hardware` to applications. + + :See: :ref:`media_controller`. + + Media controller centric
Documentation/media/uapi/v4l/glossary.rst line 106
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ MC-centric + :term:`V4L2 hardware` that requires a :term:`media controller`. + + :See: :ref:`v4l2_hardware_control`. + + Media hardware + A group of hardware components that together form the + functional media hardware. For instance the :term:`SoC` + :term:`ISP` :term:`IP cores <ip core>` and external camera + sensors together form the camera media hardware.
Perhaps this is a bit better:
...form the media hardware for a camera.
Documentation/media/uapi/v4l/glossary.rst line 109
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Media hardware control + Type of control for a :term:`media hardware` supported a
for a -> for
supported -> supported by
Documentation/media/uapi/v4l/glossary.rst line 112
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ V4L2 :term:`driver`. + + :See: :ref:`v4l2_hardware_control`.
Do we actually need this term in the glossary? I'm not convinced. We will typically talk about 'MC-centric' or 'Video device node centric', but rarely about 'Media hardware control'. Just my opinion though.
Documentation/media/uapi/v4l/glossary.rst line 115
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Microprocessor + An electronic circuitry that carries out the instructions
It's either "Electronic circuitry" or "An electronic circuit". In this case I'd say the former, but I'm no HW engineer.
Documentation/media/uapi/v4l/glossary.rst line 121
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ of a computer program by performing the basic arithmetic, logical, + control and input/output (I/O) operations specified by the + instructions on a single :term:`integrated circuit`. + + SMBus + A subset of :term:`I²C`, with defines a stricter usage of the bus.
with -> which
Documentation/media/uapi/v4l/glossary.rst line 126
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + Serial Peripheral Interface + SPI + Synchronous serial communication interface specification used for + short distance communication, primarily in embedded systems.
...primarily used in...
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + System on a Chip + SoC + An :term:`integrated circuit` that integrates all components of a + computer or other electronic systems. + + V4L2 device node + A :term:`device node` that is associated to a + :term:`V4L2 main driver`, as specified in :ref:`v4l2_device_naming`. + + V4L2 hardware + Hardware that is controlled by a :term:`V4L2 main driver` or a
Documentation/media/uapi/v4l/glossary.rst line 148
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ :term:`V4L2 sub-device driver`. V4L2 hardware is a subset of the + :term:`media hardware`. Often the two are the same, but + :term:`media hardware` can also contain other non-V4L2 hardware + such as Digital TV hardware. + + V4L2 main driver + The V4L2 :term:`device driver` that implements the main logic to + talk with the :term:`V4L2 hardware`. + + Often, the same as :term:`bridge driver`.
Remove the comma after 'Often'.
Documentation/media/uapi/v4l/glossary.rst line 153
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + :See: :ref:`v4l2_hardware_control`. + + V4L2 sub-device + :See: :term:`V4L2 sub-device driver`.
Isn't a "V4L2 sub-device" typically an instance of a device as implemented by a "V4L2 sub-device driver"?
Documentation/media/uapi/v4l/glossary.rst line 156
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + V4L2 sub-device driver + A :term:`driver` for a :term:`media hardware` whose bus(es)
Not media hardware, but "hardware component".
Documentation/media/uapi/v4l/glossary.rst line 157
Quoted 1 line
Documentation/media/uapi/v4l/glossary.rst new file +1
-0+ connects it to the hardware controlled via the
I think 'by' is better than 'via'.
Documentation/media/uapi/v4l/glossary.rst line 164
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ :term:`V4L2 main driver`. + + :See: :ref:`subdev`. + + Video device node centric + Vdevnode-centric + :term:`V4L2 hardware` that is controlled via
Same as before: I think 'by' is better than 'via'.
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ :term:`V4L2 device nodes <v4l2 device node>`. + + :See: :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +0
-0
Documentation/media/uapi/v4l/v4l2.rst This part describes the Video for Linux API version 2 (V4L2 API) specification. · line 38
Quoted 7 lines
Documentation/media/uapi/v4l/v4l2.rst +1
-0@@ -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
PATCH v8 2/7 media: open.rst: better document device node naming
In reply to Mauro Carvalho ChehabRight 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.
--- Documentation/media/uapi/v4l/open.rst | 53 ++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 7 deletions(-)
Documentation/media/uapi/v4l/open.rst +46 -7
@@ -7,14 +7,16 @@ Opening and Closing Devices *************************** -Device Naming -============= +.. _v4l2_device_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 -helper functions and a common application interface specified in this -document. +V4L2 Device Node Naming +======================= + +V4L2 :term:`drivers <driver>` 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 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
@@ -23,6 +25,43 @@ 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 :term:`device node` types defined at V4L2 spec 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. :term:`V4L2 sub-device` nodes (e. g. ``/dev/v4l-sudevX``) provide a + different API and aren't considered as + :term:`V4L2 device nodes <v4l2 device node>`. + + 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
Signature · 1 line
2.13.6
PATCH v8 3/7 media: open.rst: remove the minor number range
In reply to Mauro Carvalho Chehabminor 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.
--- Documentation/media/uapi/v4l/open.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/media/uapi/v4l/open.rst +4 -5
@@ -19,11 +19,10 @@ module. It provides 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 :term:`device node` types defined at V4L2 spec are:
Signature · 1 line
2.13.6
PATCH v8 4/7 media: open.rst: document vdevnode-centric and mc-centric types
In reply to Mauro Carvalho ChehabWhen 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.
--- Documentation/media/uapi/v4l/open.rst | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+)
Documentation/media/uapi/v4l/open.rst +55 -0
@@ -7,6 +7,61 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: + + +Types of V4L2 media hardware control +==================================== + +A :term:`V4L2 hardware` is usually complex: support for it is +implemented via a :term:`V4L2 main driver` and often by several +additional :term:`drivers <driver>`. +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. + +The other drivers are called :term:`V4L2 sub-devices <v4l2 sub-device>` +and provide control to other +:term:`hardware components <hardware component>` are usually connected +via a serial bus (like :term:`I²C`, :term:`SMBus` or :term:`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, 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. + .. _v4l2_device_naming: V4L2 Device Node Naming
Signature · 1 line
2.13.6
Re: [PATCH v8 4/7] media: open.rst: document vdevnode-centric and mc-centric types
More word-smithing...
Quoted 19 lines · 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 <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+)Documentation/media/uapi/v4l/open.rst +0
-0
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 16
Quoted 10 lines
Documentation/media/uapi/v4l/open.rst +7
-0@@ -7,6 +7,61 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: + + +Types of V4L2 media hardware control +==================================== + +A :term:`V4L2 hardware` is usually complex: support for it is
No 'A '.
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 17
Quoted 1 line
Documentation/media/uapi/v4l/open.rst +1
-0+implemented via a :term:`V4L2 main driver` and often by several
I prefer 'by' instead of 'via'.
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 21
Quoted 4 lines
Documentation/media/uapi/v4l/open.rst +4
-0+additional :term:`drivers <driver>`. +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
with -> which
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 24
Quoted 3 lines
Documentation/media/uapi/v4l/open.rst +3
-0+data streaming, if applicable. + +The other drivers are called :term:`V4L2 sub-devices <v4l2 sub-device>`
I'd say "V4L2 sub-device drivers"
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 26
Quoted 2 lines
Documentation/media/uapi/v4l/open.rst +2
-0+and provide control to other +:term:`hardware components <hardware component>` are usually connected
:term:hardware components <hardware component>. Those component are usually controlled
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 35
Quoted 9 lines
Documentation/media/uapi/v4l/open.rst +9
-0+via a serial bus (like :term:`I²C`, :term:`SMBus` or :term:`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, 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,
Instead of 'interface-wise' I'd use 'API-wise'. That reminds me: should we add 'API' to the glossary as well? (Can be done later)
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 43
Quoted 8 lines
Documentation/media/uapi/v4l/open.rst +8
-0+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
**V4L2** -> the **V4L2**
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 50
Quoted 7 lines
Documentation/media/uapi/v4l/open.rst +7
-0+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
provide -> provides
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 56
Quoted 6 lines
Documentation/media/uapi/v4l/open.rst +6
-0+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.
I'd rephrase this:
On **MC-centric** V4L2 hardware, the **V4L2 sub-device nodes** provide control of the specific part of the V4L2 hardware represented by each node.
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 59
Quoted 3 lines
Documentation/media/uapi/v4l/open.rst +3
-0+ +Also, the additional versatility of **MC-centric** V4L2 hardware comes +with additional responsibilities, the main one of which is the requirements
...of which the main one is the requirement...
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 67
Quoted 9 lines
Documentation/media/uapi/v4l/open.rst +5
-0+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. + .. _v4l2_device_naming: V4L2 Device Node Naming
Regards,
Hans
PATCH v8 5/7 media: open.rst: Adjust some terms to match the glossary
In reply to Mauro Carvalho ChehabAs we now have a glossary, some terms used on open.rst require adjustments.
--- Documentation/media/uapi/v4l/open.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-)
Documentation/media/uapi/v4l/open.rst +13 -12
@@ -159,27 +159,28 @@ 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 :term:`V4L2 device nodes <v4l2 device node>` +types for each of these functions. -The V4L2 API was designed with the idea that one device node could +The V4L2 API was designed with the idea that one :term:`device node` could support all functions. However, in practice this never worked: this -'feature' was never used by applications and many drivers did not -support it and if they did it was certainly never tested. In addition, +'feature' was never used by applications and many :term:`drivers <driver>` +did not support it and if they did it was certainly never tested. In addition, 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. +Besides video input or output, the :term:`media 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 :term:`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
Signature · 1 line
2.13.6
PATCH v8 6/7 media: videodev2: add a flag for MC-centric devices
In reply to Mauro Carvalho ChehabAs both vdev-centric and MC-centric devices may implement the same APIs, we need a flag to allow userspace to distinguish between them.
--- 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(+)
Documentation/media/uapi/v4l/open.rst +7 -0
@@ -62,6 +62,13 @@ 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. +.. 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
Documentation/media/uapi/v4l/vidioc-querycap.rst +5 -0
@@ -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
Documentation/media/videodev2.h.rst.exceptions +1 -0
@@ -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
include/uapi/linux/videodev2.h +2 -0
@@ -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 */ /*
Signature · 1 line
2.13.6
PATCH v8 7/7 media: open.rst: add a notice about subdev-API on vdev-centric
In reply to Mauro Carvalho ChehabThe 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.
--- Documentation/media/uapi/v4l/open.rst | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/media/uapi/v4l/open.rst +7 -0
@@ -62,6 +62,13 @@ 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. +.. 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
Signature · 1 line
2.13.6