document types of hardware control for V4L2
Subsystems (2)
v7 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.
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
Signature · 1 line
2.13.5
PATCH v7 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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Documentation/media/uapi/v4l/glossary.rst new file +136 -0
@@ -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`.
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.5
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Hi Mauro,
Thanks for continuing the work on this!
Quoted 22 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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +6
-0@@ -0,0 +1,136 @@ +======== +Glossary +======== + +.. note:: +
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Quoted 20 lines
Documentation/media/uapi/v4l/glossary.rst new file +20
-0+ + 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. +
Documentation/media/uapi/v4l/glossary.rst line 46
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Quoted 61 lines
Documentation/media/uapi/v4l/glossary.rst new file +61
-0+ + 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
Documentation/media/uapi/v4l/glossary.rst line 117
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + V4L2 main driver + The V4L2 device driver that implements the main logic to talk with + the V4L2 hardware. + + Also known as bridge driver.
Documentation/media/uapi/v4l/glossary.rst line 133
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ + 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.
Quoted 15 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ V4L2 hardware that it is controlled via V4L2 device nodes. + + 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 · 4 lines
Regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Hi Mauro,
Quoted 3 lines · Sakari Ailus
Documentation/media/uapi/v4l/glossary.rst line 113
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ 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.
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Fri, 6 Oct 2017 14:51:06 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 11 lines
Hi Mauro,
Quoted 3 lines · Sakari Ailus
Documentation/media/uapi/v4l/glossary.rst line 113
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ 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:
Quoted 8 lines
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 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Quoted 18 lines · Mauro Carvalho Chehab
Em Fri, 6 Oct 2017 14:51:06 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 15 lines
Hi Mauro,
Quoted 3 lines · Sakari Ailus
Documentation/media/uapi/v4l/glossary.rst line 113
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ 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**.
Quoted 7 lines
Quoted 4 lines
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.
Quoted 4 lines
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.
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Tue, 10 Oct 2017 14:54:35 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 33 lines · Mauro Carvalho Chehab
Quoted 18 lines
Em Fri, 6 Oct 2017 14:51:06 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 15 lines
Hi Mauro,
Quoted 3 lines · Sakari Ailus
Documentation/media/uapi/v4l/glossary.rst line 113
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ 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**.Quoted 7 lines
Quoted 4 lines
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.
Quoted 1 line
Quoted 6 lines
Quoted 3 lines
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
Hi Mauro,
Quoted 47 lines · Mauro Carvalho Chehab
Em Tue, 10 Oct 2017 14:54:35 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 33 lines · Mauro Carvalho Chehab
Quoted 18 lines
Em Fri, 6 Oct 2017 14:51:06 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 15 lines
Hi Mauro,
Quoted 3 lines · Sakari Ailus
Documentation/media/uapi/v4l/glossary.rst line 113
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ 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**.Quoted 7 lines
Quoted 4 lines
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.
Quoted 1 line
Quoted 6 lines
Quoted 3 lines
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.
Quoted 7 lines
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.
Quoted 8 lines
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.
Quoted 15 lines
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.
Signature · 4 lines
Kind regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Wed, 11 Oct 2017 01:18:58 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 16 lines
Quoted 7 lines
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.
Quoted 6 lines
There are a couple of possible alternatives:
1) define V4L2 device nodes excluding
/dev/subdev, with is the current approach;
Quoted 6 lines
Quoted 2 lines
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.
Quoted 3 lines
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.
Quoted 4 lines
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.
Quoted 2 lines
Should we make such a change, this would be an additional argument for supporting
VIDIOC_QUERYCAPon 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.
Quoted 3 lines
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.
Quoted 13 lines
Just my thougts. Anyway... let's continue tomorrow.
Quoted 11 lines
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).
Quoted 4 lines
Quoted 4 lines
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
In reply to Sakari AilusEm Fri, 6 Oct 2017 13:22:29 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 2 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ 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
Quoted 21 lines · Mauro Carvalho Chehab
Em Fri, 6 Oct 2017 13:22:29 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 2 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ 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.
Quoted 6 lines
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.
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
In reply to Sakari AilusEm Fri, 6 Oct 2017 13:22:29 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 78 lines
Hi Mauro,
Thanks for continuing the work on this!
Quoted 22 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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +6
-0@@ -0,0 +1,136 @@ +======== +Glossary +======== + +.. note:: +Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Quoted 20 lines
Documentation/media/uapi/v4l/glossary.rst new file +20
-0+ + 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. +Documentation/media/uapi/v4l/glossary.rst line 46
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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:
Quoted 2 lines
ISP drivers often contain a receiver for image data from external source such as a sensor and act as V4L2 main driver.
OK.
Quoted 79 lines
Quoted 62 lines
Documentation/media/uapi/v4l/glossary.rst new file +61
-0+ + 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 - SoCDocumentation/media/uapi/v4l/glossary.rst line 117
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Quoted 7 lines
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.
Quoted 12 lines
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +11
-0+ + 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
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 133
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ V4L2 sub-device driver. + + See :ref:`subdev`. + + Vdevnode-centricI 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.
Quoted 17 lines
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ V4L2 hardware that it is controlled via V4L2 device nodes. + + See :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +0
-0Documentation/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
I'm enclosing the diff, against v7, that should hopefully cover all the points that both you and Hans mentioned.
Thanks,
Mauro
Documentation/media/uapi/v4l/glossary.rst +36 -22
@@ -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 1/1 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 | 150 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 151 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Documentation/media/uapi/v4l/glossary.rst new file +150 -0
@@ -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`.
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 v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
In reply to Mauro Carvalho ChehabQuoted 22 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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +6
-0@@ -0,0 +1,136 @@ +======== +Glossary +======== + +.. note:: +
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 19
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Device Node + A character device node in the file system used to control and do
and -> and/or
Documentation/media/uapi/v4l/glossary.rst line 24
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ 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.
Quoted 16 lines
Documentation/media/uapi/v4l/glossary.rst new file +16
-0+ + 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. +
Documentation/media/uapi/v4l/glossary.rst line 50
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 58
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 70
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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: '
Documentation/media/uapi/v4l/glossary.rst line 79
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 85
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 86
Quoted 1 line
Documentation/media/uapi/v4l/glossary.rst new file +1
-0+ cores and external camera sensors together make a
make a -> form the
Possible synonym for 'form': 'constitute'. I'm OK with either.
Quoted 21 lines
Documentation/media/uapi/v4l/glossary.rst new file +21
-0+ 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
Documentation/media/uapi/v4l/glossary.rst line 117
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 129
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 134
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + 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`.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ + 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
Re: [PATCH v7 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Tue, 10 Oct 2017 09:47:13 +0200
Hans Verkuil <[email protected]> escreveu:
Quoted 231 lines · Mauro Carvalho Chehab
Quoted 22 lines
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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +6
-0@@ -0,0 +1,136 @@ +======== +Glossary +======== + +.. note:: +Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 19
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Device Node + A character device node in the file system used to control and doand -> and/or
Documentation/media/uapi/v4l/glossary.rst line 24
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ 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.
Quoted 16 lines
Documentation/media/uapi/v4l/glossary.rst new file +16
-0+ + 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. +Documentation/media/uapi/v4l/glossary.rst line 50
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 58
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 70
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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: '
Documentation/media/uapi/v4l/glossary.rst line 79
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 85
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + 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 IPI'd just say "form the functional". The term 'user-facing' is out of place here.
Documentation/media/uapi/v4l/glossary.rst line 86
Quoted 1 line
Documentation/media/uapi/v4l/glossary.rst new file +1
-0+ cores and external camera sensors together make amake a -> form the
Possible synonym for 'form': 'constitute'. I'm OK with either.
Quoted 21 lines
Documentation/media/uapi/v4l/glossary.rst new file +21
-0+ 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 - SoCDocumentation/media/uapi/v4l/glossary.rst line 117
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 129
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 134
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + 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`.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ + See :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +0
-0Documentation/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 biblioRegards,
Quoted 1 line
Hans
I agree with all proposed changes. I'm folding the attached patch to it.
Thanks,
Mauro
Documentation/media/uapi/v4l/glossary.rst +25 -16
@@ -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
Quoted 322 lines · Mauro Carvalho Chehab
Em Tue, 10 Oct 2017 09:47:13 +0200
Hans Verkuil <[email protected]> escreveu:Quoted 231 lines · Mauro Carvalho Chehab
Quoted 22 lines
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 | 136 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 137 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +6
-0@@ -0,0 +1,136 @@ +======== +Glossary +======== + +.. note:: +Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 19
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Device Node + A character device node in the file system used to control and doand -> and/or
Documentation/media/uapi/v4l/glossary.rst line 24
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ 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.
Quoted 16 lines
Documentation/media/uapi/v4l/glossary.rst new file +16
-0+ + 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. +Documentation/media/uapi/v4l/glossary.rst line 50
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 58
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 70
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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: '
Documentation/media/uapi/v4l/glossary.rst line 79
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 85
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + 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 IPI'd just say "form the functional". The term 'user-facing' is out of place here.
Documentation/media/uapi/v4l/glossary.rst line 86
Quoted 1 line
Documentation/media/uapi/v4l/glossary.rst new file +1
-0+ cores and external camera sensors together make amake a -> form the
Possible synonym for 'form': 'constitute'. I'm OK with either.
Quoted 21 lines
Documentation/media/uapi/v4l/glossary.rst new file +21
-0+ 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 - SoCDocumentation/media/uapi/v4l/glossary.rst line 117
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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.
Documentation/media/uapi/v4l/glossary.rst line 129
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + 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.
Documentation/media/uapi/v4l/glossary.rst line 134
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + 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`.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ + See :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +0
-0Documentation/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 biblioRegards,
Quoted 1 line
Hans
I agree with all proposed changes. I'm folding the attached patch to it.
Thanks,
MauroDocumentation/media/uapi/v4l/glossary.rst +19
-13@@ -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
Documentation/media/uapi/v4l/glossary.rst Glossary · line 138
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst +5
-2@@ -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
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst +1
-1See :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
Em Tue, 10 Oct 2017 10:27:12 +0200
Hans Verkuil <[email protected]> escreveu:
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst Glossary · line 138
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst +3
-0+ 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
PATCH v7 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 | 44 ++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-)
Documentation/media/uapi/v4l/open.rst +41 -3
@@ -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
Signature · 1 line
2.13.5
PATCH v7 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 @@ 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:
Signature · 1 line
2.13.5
PATCH v7 4/7 media: open.rst: document devnode-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 | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)
Documentation/media/uapi/v4l/open.rst +40 -0
@@ -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
Signature · 1 line
2.13.5
Randy Dunlap
reviewerRe: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types
Quoted 11 lines · Mauro Carvalho Chehab
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 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,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...)
Quoted 37 lines
Documentation/media/uapi/v4l/open.rst +33
-0+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
Signature · 1 line
~Randy
Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types
Hi Randy,
Em Wed, 27 Sep 2017 15:32:12 -0700
Randy Dunlap <[email protected]> escreveu:
Quoted 6 lines
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 16
Quoted 4 lines
Documentation/media/uapi/v4l/open.rst +4
-0+Types of V4L2 media hardware control +==================================== + +V4L2 hardware periferal is usually complex: support for it isperipheral (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 4/7] media: open.rst: document devnode-centric and mc-centric types
In reply to Mauro Carvalho ChehabHi Mauro,
Quoted 25 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 | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)Documentation/media/uapi/v4l/open.rst +3
-0@@ -7,6 +7,46 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: + +
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 22
Quoted 10 lines
Documentation/media/uapi/v4l/open.rst +10
-0+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/
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 30
Quoted 8 lines
Documentation/media/uapi/v4l/open.rst +8
-0+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.
Quoted 22 lines
Documentation/media/uapi/v4l/open.rst +19
-0+ +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
Signature · 4 lines
Kind regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 4/7] media: open.rst: document devnode-centric and mc-centric types
Em Fri, 6 Oct 2017 15:24:27 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 31 lines
Documentation/media/uapi/v4l/open.rst Opening and Closing Devices · line 30
Quoted 3 lines
Documentation/media/uapi/v4l/open.rst +3
-0+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.
Quoted 6 lines
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
PATCH v7 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 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/media/uapi/v4l/open.rst +6 -6
@@ -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
Signature · 1 line
2.13.5
Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary
Hi Mauro,
Quoted 14 lines · Mauro Carvalho Chehab
As we now have a glossary, some terms used on
open.rstrequire adjustments.Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)Documentation/media/uapi/v4l/open.rst +0
-0
Documentation/media/uapi/v4l/open.rst Related Devices · line 146
Quoted 5 lines
Documentation/media/uapi/v4l/open.rst +1
-1@@ -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/ ?
Quoted 26 lines
Documentation/media/uapi/v4l/open.rst +5
-5The 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
Signature · 4 lines
Regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary
Em Fri, 6 Oct 2017 15:48:22 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 20 lines
Hi Mauro,
Quoted 17 lines · Mauro Carvalho Chehab
As we now have a glossary, some terms used on
open.rstrequire adjustments.Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)Documentation/media/uapi/v4l/open.rst +0
-0@@ -143,7 +143,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support.
Quoted 6 lines
Documentation/media/uapi/v4l/open.rst Related Devices · line 146
Quoted 2 lines
Documentation/media/uapi/v4l/open.rst +1
-1-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.
Quoted 2 lines
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 5/7] media: open.rst: Adjust some terms to match the glossary
Hi Mauro,
Quoted 39 lines · Mauro Carvalho Chehab
Em Fri, 6 Oct 2017 15:48:22 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 20 lines
Hi Mauro,
Quoted 17 lines · Mauro Carvalho Chehab
As we now have a glossary, some terms used on
open.rstrequire adjustments.Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)Documentation/media/uapi/v4l/open.rst +0
-0@@ -143,7 +143,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support.Quoted 6 lines
Documentation/media/uapi/v4l/open.rst Related Devices · line 146
Quoted 2 lines
Documentation/media/uapi/v4l/open.rst +1
-1-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.
Quoted 2 lines
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:
Quoted 7 lines
/dev/video0 /dev/radio0 /dev/vbi0As 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?
Signature · 4 lines
Kind regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 5/7] media: open.rst: Adjust some terms to match the glossary
Em Wed, 11 Oct 2017 01:41:00 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 46 lines
Hi Mauro,
Quoted 43 lines · Mauro Carvalho Chehab
Em Fri, 6 Oct 2017 15:48:22 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 20 lines
Hi Mauro,
Quoted 17 lines · Mauro Carvalho Chehab
As we now have a glossary, some terms used on
open.rstrequire adjustments.Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)Documentation/media/uapi/v4l/open.rst +0
-0@@ -143,7 +143,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support.Quoted 6 lines
Documentation/media/uapi/v4l/open.rst Related Devices · line 146
Quoted 2 lines
Documentation/media/uapi/v4l/open.rst +1
-1-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.
Quoted 2 lines
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
Quoted 7 lines
Quoted 3 lines
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.
Quoted 4 lines
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:
Quoted 1 line
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
PATCH v7 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
@@ -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
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.5
Re: [PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices
Quoted 5 lines · 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 <[email protected]>
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 6/7] media: videodev2: add a flag for MC-centric devices
In reply to Mauro Carvalho ChehabQuoted 17 lines · 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 <[email protected]>--- 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 +0
-0
Documentation/media/uapi/v4l/open.rst the periferal can be used. For such devices, the sub-devices' configuration · line 52
Quoted 6 lines
Documentation/media/uapi/v4l/open.rst +3
-0@@ -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:
Regards,
Hans
Quoted 49 lines
Documentation/media/uapi/v4l/open.rst +4
-0+ report a ``V4L2_MC_CENTRIC`` :c:type:`v4l2_capability` flag + (see :ref:`VIDIOC_QUERYCAP`). + + .. _v4l2_device_naming: V4L2 Device Node NamingDocumentation/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 canDocumentation/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-capabilitiesinclude/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 */ /*
PATCH v7 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
@@ -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
Signature · 1 line
2.13.5
Re: [PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric
Quoted 8 lines · 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 <[email protected]>
Thanks!
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v7 7/7] media: open.rst: add a notice about subdev-API on vdev-centric
In reply to Mauro Carvalho ChehabQuoted 6 lines · 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.
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:
Regards,
Hans
Quoted 25 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/media/uapi/v4l/open.rst +7
-0@@ -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