document types of hardware control for V4L2
Subsystems (2)
v5 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.
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 | 147 +++++++++++++++++++++++ Documentation/media/uapi/v4l/open.rst | 114 +++++++++++++++--- 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, 256 insertions(+), 14 deletions(-) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Signature · 1 line
2.13.5
PATCH v5 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rst
Documentation/media/uapi/v4l/glossary.rst new file +147 -0
@@ -0,0 +1,147 @@ +======== +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. + + Hardware peripheral + A group of hardware components that together make a larger + user-facing functional peripheral. For instance the SoC ISP IP + cores and external camera sensors together make a + camera hardware peripheral. + + Also known as peripheral. + + Hardware peripheral control + Type of control for a hardware peripheral supported by V4L2 drivers. + + See :ref:`v4l2_hardware_control`. + + 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. + + IP block + The same as IP core. + + Intelectual 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). + + Image processor - ISP + A specialized digital signal processor used for image processing + in digital cameras, mobile phones or other devices. + + Peripheral + The same as hardware peripheral. + + Media Controller + An API used to identify the hardware components and (optionally) + change the links between hardware components. + + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + 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. + + Sub-device hardware components + Hardware components that aren't controlled by the + V4L2 main driver. + + 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 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`. + + 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 it is implemented by a device + driver that is not part of the main V4L2 driver. + + See :ref:`subdev`. + + Vdev-centric + V4L2 hardware that it is controlled via V4L2 device nodes. + + See :ref:`v4l2_hardware_control`.
Documentation/media/uapi/v4l/v4l2.rst +1 -0
@@ -31,6 +31,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 v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 16 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +0
-0
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0@@ -0,0 +1,147 @@ +======== +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.
I'd leave the WiP part out.
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.
I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
Quoted 21 lines
Documentation/media/uapi/v4l/glossary.rst new file +21
-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. + + Hardware component
Documentation/media/uapi/v4l/glossary.rst line 47
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ A subset of the media hardware. For example an I²C or SPI device, + or an IP block inside an SoC or FPGA. + + Hardware peripheral + A group of hardware components that together make a larger + user-facing functional peripheral. For instance the SoC ISP IP + cores and external camera sensors together make a + camera hardware peripheral. + + Also known as peripheral.
Aren't peripherals usually understood to be devices that you can plug into a computer? Such as a printer, or a... floppy drive?
I certainly wouldn't call this a peripheral. How about "aggregate device"? We haven't used that before, but I think it relatively well catches the meaning without being excessively elaborate.
Quoted 21 lines
Documentation/media/uapi/v4l/glossary.rst new file +21
-0+ + Hardware peripheral control + Type of control for a hardware peripheral supported by V4L2 drivers. + + See :ref:`v4l2_hardware_control`. + + 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. + + IP block + The same as IP core. +
Documentation/media/uapi/v4l/glossary.rst line 78
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ Intelectual 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). + + Image processor - ISP
"Image signal processor"
Documentation/media/uapi/v4l/glossary.rst line 80
Quoted 2 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ A specialized digital signal processor used for image processing + in digital cameras, mobile phones or other devices.
Traditional ISPs aren't programmable in the sense that you could execute code in them. Instead, they implement a set of image processing algorithms the parameters of which you can specify. How about:
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).
Documentation/media/uapi/v4l/glossary.rst line 83
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Peripheral + The same as hardware peripheral.
Peripheral generally is a very seldom used term nowadays, perhaps because mostly you don't need to explicitly refer to external devices. I'd just leave it out.
Documentation/media/uapi/v4l/glossary.rst line 87
Quoted 4 lines
Documentation/media/uapi/v4l/glossary.rst new file +4
-0+ + Media Controller + An API used to identify the hardware components and (optionally) + change the links between hardware components.
IMO glossary is not where optional and mandatory parts of APIs should be discussed. Just the scope. I.e. I'd leave "(optionally)" out. Change -> configure.
The links are also between media entities, not hardware components. It is not uncommon that a driver for a hardware component exposes several sub-devices for the same component.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + See :ref:`v4l2_hardware_control`. +
Documentation/media/uapi/v4l/glossary.rst line 105
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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
We don't have "Bus" in I²C, I'd leave it out here, too.
Quoted 4 lines
Documentation/media/uapi/v4l/glossary.rst new file +4
-0+ 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 119
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. + + Sub-device hardware components + Hardware components that aren't controlled by the + V4L2 main driver. + + V4L2 device node + A device node that is associated to a V4L2 main driver, + as specified in :ref:`v4l2_device_naming`.
This will be confusing. Many sub-device nodes are exposed by so-called main drivers.
I'd understand this as any device node type that is exposed by V4L2. In general there should not be limitation on this, although video device nodes are effectively only exposed by main drivers.
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ + V4L2 hardware + A hardware used to on a media device supported by the V4L2 + subsystem. +
Documentation/media/uapi/v4l/glossary.rst line 134
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ V4L2 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`. + + V4L2 main driver + The V4L2 device driver that implements the main logic to talk with + the V4L2 hardware. + + Also known as bridge driver.
Is UVC driver a bridge driver? How about instead:
Bridge and ISP drivers typically are V4L2 main drivers.
Documentation/media/uapi/v4l/glossary.rst line 140
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + See :ref:`v4l2_hardware_control`. + + V4L2 sub-device + Part of the media hardware that it is implemented by a device + driver that is not part of the main V4L2 driver.
How about:
V4L2 abstraction for a hardware component which is functionally or physically separate from the DMA engine.
Quoted 19 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ + See :ref:`subdev`. + + Vdev-centric + V4L2 hardware that it is controlled via V4L2 device nodes. + + See :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +1
-0@@ -31,6 +31,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. videodev capture-example v4l2grab-example + glossary biblio
Signature · 4 lines
Kind regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 24 lines
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 19 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +3
-0@@ -0,0 +1,147 @@ +======== +Glossary +========
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ +.. 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.I'd leave the WiP part out.
IMO, it is important to mention it, as the glossary, right now, covers only what's used on the first two sections of the API book. There are a lot more to be covered.
Quoted 12 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
Quoted 2 lines
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
No, only on some drivers the bridge driver has DMA. A vast amount of drivers (USB ones) don't implement any DMA inside the driver, as it is up to the USB host driver to implement support for DMA.
There are even some USB host drivers that don't always use DMA for I/O transfers, using direct I/O if the message is smaller than a threshold or not multiple of the bus word. This is pretty common on SoC USB host drivers.
In any case, for the effect of this spec, and for all discussions we ever had about it, bridge driver == V4L2 main driver. I don't see any reason why to distinguish between them.
Quoted 27 lines
Quoted 27 lines
Documentation/media/uapi/v4l/glossary.rst new file +26
-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. + + 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. + + Hardware peripheral + A group of hardware components that together make a larger
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 47
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ user-facing functional peripheral. For instance the SoC ISP IP + cores and external camera sensors together make a + camera hardware peripheral. + + Also known as peripheral.Aren't peripherals usually understood to be devices that you can plug into a computer? Such as a printer, or a... floppy drive?
That is the common sense, although, technically, peripherals are any I/O component. It is "peripheral" in the sense that it is not part of the CPU's internal circuits. Instead, it is a data that should be sent in or out the CPU.
On such concept, even an I/O hardware integrated inside a SoC is a peripheral.
Yet, Hans argued already against using it. I opened a separate thread for us to discuss about it.
Quoted 3 lines
I certainly wouldn't call this a peripheral. How about "aggregate device"? We haven't used that before, but I think it relatively well catches the meaning without being excessively elaborate.
"aggregate device" means nothing to me ;-) I propose "media hardware" instead.
Quoted 26 lines
Quoted 26 lines
Documentation/media/uapi/v4l/glossary.rst new file +25
-0+ + Hardware peripheral control + Type of control for a hardware peripheral supported by V4L2 drivers. + + See :ref:`v4l2_hardware_control`. + + 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. + + IP block + The same as IP core. + + Intelectual 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.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 78
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ 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). + + Image processor - ISP"Image signal processor"
OK.
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst line 80
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ A specialized digital signal processor used for image processing + in digital cameras, mobile phones or other devices.Traditional ISPs aren't programmable in the sense that you could execute code in them. Instead, they implement a set of image processing algorithms the parameters of which you can specify.
That definition came directly from Wikipedia :-)
Quoted 7 lines
How about:
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).
Works for me.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 83
Quoted 4 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Peripheral + The same as hardware peripheral.Peripheral generally is a very seldom used term nowadays, perhaps because mostly you don't need to explicitly refer to external devices. I'd just leave it out.
Let's discuss the usage of "peripheral" x "V4L2 hardware" x "media hardware".
Once we reach a consensus, I'll replace for whatever term we agree.
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst line 87
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +4
-0+ + Media Controller + An API used to identify the hardware components and (optionally) + change the links between hardware components.IMO glossary is not where optional and mandatory parts of APIs should be discussed. Just the scope. I.e. I'd leave "(optionally)" out. Change -> configure.
IMO, glossary should provide a summary of all terms used, specially the ones that are defined at the API itself.
Quoted 3 lines
The links are also between media entities, not hardware components. It is not uncommon that a driver for a hardware component exposes several sub-devices for the same component.
The concept of entities, links, interfaces, etc should be added at the glossary, but IMHO it is out of the current scope: this glossary is only at the V4L2 part of the spec, with doesn't cover MC.
I'm OK if you want to expand it to cover the entire uAPI book, but I don't have any time for doing it myself.
So, I would prefer to keep the definition here as simple as possible. What about:
An API designed to expose and control devices and sub-devices relationships to applications.
(that's basically a quick summary of what's written at media-controller-intro.rst)
Quoted 13 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + 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
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 105
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ instructions on a single integrated circuit. + + SMBus + A subset of I²C, with defines a stricter usage of the bus. + + Serial Peripheral Interface Bus - SPIWe don't have "Bus" in I²C, I'd leave it out here, too.
I2C is a serial bus (and it is implemented as a bus inside the Kernel). Take a look at Documentation/i2c/summary.
Quoted 9 lines
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ 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. + + Sub-device hardware components + Hardware components that aren't controlled by the
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 119
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ V4L2 main driver. + + V4L2 device node + A device node that is associated to a V4L2 main driver, + as specified in :ref:`v4l2_device_naming`.This will be confusing. Many sub-device nodes are exposed by so-called main drivers.
The sub-device nodes are not listed at v4l2_device_naming chapter. Also, as I mentioned, I'm adding a notice there explicitly excluding them from "V4L2 device node".
Btw, I don't know why (and where) a main driver would also be exporting a sub-device. That seems to be a violation of the subdev API.
Quoted 3 lines
I'd understand this as any device node type that is exposed by V4L2. In general there should not be limitation on this, although video device nodes are effectively only exposed by main drivers.
The goal of the glossary (and other changes in this series) is to differentiate what is:
- V4L2 device node - e. g. /dev/video, /dev/radio, /dev/swradio, /dev/vbi, /dev/v4l-touch (and only those)
- V4L2 sub-device node - e. g. /dev/v4l-subdev.
If you think this is not enough, we could repeat the above info, although, IMHO, it is better to add refs to the right chapters, in order to avoid the need of touching the glossary every time we add a new V4L2 device node.
Quoted 10 lines
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + V4L2 hardware + A hardware used to on a media device supported by the V4L2 + subsystem. + + V4L2 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 134
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.Is UVC driver a bridge driver? How about instead:
Yes, sure: UVC driver is a bridge driver/main driver. It is the UVC driver that sends/receives data from the USB bus and send to the sensors. It also sends data via URB to the USB host driver, with, in turn send it to send to CPU (usually via DMA - although some USB drivers actually implement direct I/O for short messages).
Quoted 1 line
Bridge and ISP drivers typically are V4L2 main drivers.
We don't have a concept of an "ISP driver". Adding it sounds very confusing, as an ISP hardware may actually implement different functions - so it ends by being supported by multiple drivers.
Quoted 11 lines
Documentation/media/uapi/v4l/glossary.rst line 140
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + See :ref:`v4l2_hardware_control`. + + V4L2 sub-device + Part of the media hardware that it is implemented by a device + driver that is not part of the main V4L2 driver.How about:
V4L2 abstraction for a hardware component which is functionally or physically separate from the DMA engine.
That's actually not true. On vdev-centric devices, common ISP controls (bright, color, saturation, etc) are actually implemented by the main V4L2 driver.
Also, on USB drivers, the DMA engine is actually not implemented by the main driver, but by the USB host driver.
Quoted 11 lines
Quoted 11 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ + See :ref:`subdev`. + + Vdev-centric + V4L2 hardware that it is controlled via V4L2 device nodes. + + See :ref:`v4l2_hardware_control`.Documentation/media/uapi/v4l/v4l2.rst +0
-0
Quoted 9 lines
Documentation/media/uapi/v4l/v4l2.rst This part describes the Video for Linux API version 2 (V4L2 API) specification. · line 37
Quoted 8 lines
Documentation/media/uapi/v4l/v4l2.rst +1
-0@@ -31,6 +31,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. videodev capture-example v4l2grab-example + glossary biblio
Thanks,
Mauro
Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Hi Mauro,
My apologies for the late reply.
Quoted 36 lines · Mauro Carvalho Chehab
Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 24 lines
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 19 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +3
-0@@ -0,0 +1,147 @@ +======== +Glossary +========Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ +.. 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.I'd leave the WiP part out.
Quoted 3 lines
IMO, it is important to mention it, as the glossary, right now, covers only what's used on the first two sections of the API book. There are a lot more to be covered.
Works for me.
Quoted 20 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
Quoted 2 lines
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
No, only on some drivers the bridge driver has DMA. A vast amount of drivers (USB ones) don't implement any DMA inside the driver, as it is up to the USB host driver to implement support for DMA.
Quoted 8 lines
There are even some USB host drivers that don't always use DMA for I/O transfers, using direct I/O if the message is smaller than a threshold or not multiple of the bus word. This is pretty common on SoC USB host drivers.
In any case, for the effect of this spec, and for all discussions we ever had about it, bridge driver == V4L2 main driver. I don't see any reason why to distinguish between them.
I think you should precisely define what a bridge driver means. Generally ISP drivers aren't referred to as bridge drivers albeit they, too, function as V4L2 main drivers.
Quoted 45 lines
Quoted 28 lines
Quoted 28 lines
Documentation/media/uapi/v4l/glossary.rst new file +26
-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. + + 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. + + Hardware peripheral + A group of hardware components that together make a largerQuoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 47
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ user-facing functional peripheral. For instance the SoC ISP IP + cores and external camera sensors together make a + camera hardware peripheral. + + Also known as peripheral.Aren't peripherals usually understood to be devices that you can plug into a computer? Such as a printer, or a... floppy drive?
That is the common sense, although, technically, peripherals are any I/O component. It is "peripheral" in the sense that it is not part of the CPU's internal circuits. Instead, it is a data that should be sent in or out the CPU.
On such concept, even an I/O hardware integrated inside a SoC is a peripheral.
Quoted 8 lines
Yet, Hans argued already against using it. I opened a separate thread for us to discuss about it.
Quoted 3 lines
I certainly wouldn't call this a peripheral. How about "aggregate device"? We haven't used that before, but I think it relatively well catches the meaning without being excessively elaborate.
"aggregate device" means nothing to me ;-) I propose "media hardware" instead.
Hardware is substance such as milk. You can't say "a milk".
Media hardware as such does not include suggestion that the components have something common that defines them. Aggregate device would. We don't use the term now because we haven't had one that refers to the entire device that consists of, well, devices. It'd explicitly refer a device consists of several devices rather than adding one more term used somewhat vaguely.
I wonder what Hans / Laurent think. (Cc Laurent.)
Quoted 39 lines
Quoted 27 lines
Quoted 27 lines
Documentation/media/uapi/v4l/glossary.rst new file +25
-0+ + Hardware peripheral control + Type of control for a hardware peripheral supported by V4L2 drivers. + + See :ref:`v4l2_hardware_control`. + + 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. + + IP block + The same as IP core. + + Intelectual 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.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 78
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ 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). + + Image processor - ISP"Image signal processor"
OK.
Quoted 1 line
Quoted 8 lines
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst line 80
Quoted 2 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ A specialized digital signal processor used for image processing + in digital cameras, mobile phones or other devices.Traditional ISPs aren't programmable in the sense that you could execute code in them. Instead, they implement a set of image processing algorithms the parameters of which you can specify.
That definition came directly from Wikipedia :-)
I wonder whether the person (or persons) who wrote the article have worked on such hardware that is typically supported in V4L2. :-)
Quoted 34 lines
Quoted 8 lines
How about:
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).
Works for me.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 83
Quoted 4 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Peripheral + The same as hardware peripheral.Peripheral generally is a very seldom used term nowadays, perhaps because mostly you don't need to explicitly refer to external devices. I'd just leave it out.
Let's discuss the usage of "peripheral" x "V4L2 hardware" x "media hardware".
Once we reach a consensus, I'll replace for whatever term we agree.
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst line 87
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +4
-0+ + Media Controller + An API used to identify the hardware components and (optionally) + change the links between hardware components.IMO glossary is not where optional and mandatory parts of APIs should be discussed. Just the scope. I.e. I'd leave "(optionally)" out. Change -> configure.
Quoted 2 lines
IMO, glossary should provide a summary of all terms used, specially the ones that are defined at the API itself.
Yes, but that's orthogonal to what I wrote above.
Quoted 12 lines
Quoted 4 lines
The links are also between media entities, not hardware components. It is not uncommon that a driver for a hardware component exposes several sub-devices for the same component.
The concept of entities, links, interfaces, etc should be added at the glossary, but IMHO it is out of the current scope: this glossary is only at the V4L2 part of the spec, with doesn't cover MC.
I'm OK if you want to expand it to cover the entire uAPI book, but I don't have any time for doing it myself.
Quoted 8 lines
So, I would prefer to keep the definition here as simple as possible. What about:
An API designed to expose and control devices and sub-devices relationships to applications.
(that's basically a quick summary of what's written at
media-controller-intro.rst)
Works for me. I think it'd be useful to improve that in the future, but I think the glossary will be quite useful to define the terms used. During the review of the set it's become apparent that different people understand the terms we use regularly a bit differently.
Quoted 23 lines
Quoted 14 lines
Quoted 14 lines
Documentation/media/uapi/v4l/glossary.rst new file +12
-0+ + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + 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 theQuoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 105
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ instructions on a single integrated circuit. + + SMBus + A subset of I²C, with defines a stricter usage of the bus. + + Serial Peripheral Interface Bus - SPIWe don't have "Bus" in I²C, I'd leave it out here, too.
Quoted 2 lines
I2C is a serial bus (and it is implemented as a bus inside the Kernel). Take a look at
Documentation/i2c/summary.
I don't disagree with that, but at the same time this is not related to my suggestion.
"Bus" is not part of the abbreviation SPI, therefore we should not suggest that here.
Quoted 33 lines
Quoted 10 lines
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ 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. + + Sub-device hardware components + Hardware components that aren't controlled by theQuoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 119
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ V4L2 main driver. + + V4L2 device node + A device node that is associated to a V4L2 main driver, + as specified in :ref:`v4l2_device_naming`.This will be confusing. Many sub-device nodes are exposed by so-called main drivers.
The sub-device nodes are not listed at
v4l2_device_namingchapter. Also, as I mentioned, I'm adding a notice there explicitly excluding them from "V4L2 device node".Btw, I don't know why (and where) a main driver would also be exporting a sub-device. That seems to be a violation of the subdev API.
Quoted 3 lines
I'd understand this as any device node type that is exposed by V4L2. In general there should not be limitation on this, although video device nodes are effectively only exposed by main drivers.
The goal of the glossary (and other changes in this series) is to differentiate what is:
Quoted 8 lines
- V4L2 device node - e. g.
/dev/video,/dev/radio,/dev/swradio,/dev/vbi,/dev/v4l-touch(and only those)
- V4L2 sub-device node - e. g./dev/v4l-subdev.If you think this is not enough, we could repeat the above info, although, IMHO, it is better to add refs to the right chapters, in order to avoid the need of touching the glossary every time we add a new V4L2 device node.
Yes, it'd easily become quite long. Yes, I think the reference is good for now.
Quoted 26 lines
Quoted 11 lines
Quoted 11 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + V4L2 hardware + A hardware used to on a media device supported by the V4L2 + subsystem. + + V4L2 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 134
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.Is UVC driver a bridge driver? How about instead:
Yes, sure: UVC driver is a bridge driver/main driver. It is the UVC driver that sends/receives data from the USB bus and send to the sensors. It also sends data via URB to the USB host driver, with, in turn send it to send to CPU (usually via DMA - although some USB drivers actually implement direct I/O for short messages).
Quoted 3 lines
Quoted 1 line
Bridge and ISP drivers typically are V4L2 main drivers.
We don't have a concept of an "ISP driver". Adding it sounds very
I think we do have that roughly as much as we do have bridge driver. We definitely also support devices that are called ISPs, therefore we do have ISP drivers.
Quoted 2 lines
confusing, as an ISP hardware may actually implement different functions - so it ends by being supported by multiple drivers.
Typically ISPs are controlled by a single driver as the sub-blocks in an ISP usually can only be found in that very ISP.
Quoted 13 lines
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst line 140
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + See :ref:`v4l2_hardware_control`. + + V4L2 sub-device + Part of the media hardware that it is implemented by a device + driver that is not part of the main V4L2 driver.How about:
Quoted 2 lines
V4L2 abstraction for a hardware component which is functionally or physically separate from the DMA engine.
Quoted 6 lines
That's actually not true. On vdev-centric devices, common ISP controls (bright, color, saturation, etc) are actually implemented by the main V4L2 driver.
Also, on USB drivers, the DMA engine is actually not implemented by the main driver, but by the USB host driver.
Right, that's true indeed.
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Em Thu, 5 Oct 2017 11:21:07 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 72 lines
Hi Mauro,
My apologies for the late reply.
Quoted 36 lines · Mauro Carvalho Chehab
Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 24 lines
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 19 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +3
-0@@ -0,0 +1,147 @@ +======== +Glossary +========Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ +.. 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.I'd leave the WiP part out.
Quoted 3 lines
IMO, it is important to mention it, as the glossary, right now, covers only what's used on the first two sections of the API book. There are a lot more to be covered.
Works for me.
Quoted 25 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
Quoted 2 lines
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
No, only on some drivers the bridge driver has DMA. A vast amount of drivers (USB ones) don't implement any DMA inside the driver, as it is up to the USB host driver to implement support for DMA.
There are even some USB host drivers that don't always use DMA for I/O transfers, using direct I/O if the message is smaller than a threshold or not multiple of the bus word. This is pretty common on SoC USB host drivers.
Quoted 7 lines
Quoted 3 lines
In any case, for the effect of this spec, and for all discussions we ever had about it, bridge driver == V4L2 main driver. I don't see any reason why to distinguish between them.
I think you should precisely define what a bridge driver means. Generally ISP drivers aren't referred to as bridge drivers albeit they, too, function as V4L2 main drivers.
It would be more productive if you could reply to the v7 of this patch series with your suggestion for such definition.
IMHO, a bridge driver is a driver for a piece of hardware that allows sending/receiving I2C control messages to a media hardware component, but I'm likely ok with any other definition you have in mind.
Quoted 57 lines
Quoted 46 lines
Quoted 29 lines
Quoted 29 lines
Documentation/media/uapi/v4l/glossary.rst new file +26
-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. + + 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. + + Hardware peripheral + A group of hardware components that together make a largerQuoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 47
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ user-facing functional peripheral. For instance the SoC ISP IP + cores and external camera sensors together make a + camera hardware peripheral. + + Also known as peripheral.Aren't peripherals usually understood to be devices that you can plug into a computer? Such as a printer, or a... floppy drive?
That is the common sense, although, technically, peripherals are any I/O component. It is "peripheral" in the sense that it is not part of the CPU's internal circuits. Instead, it is a data that should be sent in or out the CPU.
On such concept, even an I/O hardware integrated inside a SoC is a peripheral.
Quoted 8 lines
Yet, Hans argued already against using it. I opened a separate thread for us to discuss about it.
Quoted 3 lines
I certainly wouldn't call this a peripheral. How about "aggregate device"? We haven't used that before, but I think it relatively well catches the meaning without being excessively elaborate.
"aggregate device" means nothing to me ;-) I propose "media hardware" instead.
Hardware is substance such as milk. You can't say "a milk".
Quoted 7 lines
Media hardware as such does not include suggestion that the components have something common that defines them. Aggregate device would. We don't use the term now because we haven't had one that refers to the entire device that consists of, well, devices. It'd explicitly refer a device consists of several devices rather than adding one more term used somewhat vaguely.
I wonder what Hans / Laurent think. (Cc Laurent.)
Hans was OK with "media hardware".
Quoted 47 lines
Quoted 47 lines
Quoted 28 lines
Quoted 28 lines
Documentation/media/uapi/v4l/glossary.rst new file +25
-0+ + Hardware peripheral control + Type of control for a hardware peripheral supported by V4L2 drivers. + + See :ref:`v4l2_hardware_control`. + + 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. + + IP block + The same as IP core. + + Intelectual 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.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 78
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ 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). + + Image processor - ISP"Image signal processor"
OK.
Quoted 7 lines
Documentation/media/uapi/v4l/glossary.rst line 80
Quoted 3 lines
Documentation/media/uapi/v4l/glossary.rst new file +2
-0+ A specialized digital signal processor used for image processing + in digital cameras, mobile phones or other devices.Traditional ISPs aren't programmable in the sense that you could execute code in them. Instead, they implement a set of image processing algorithms the parameters of which you can specify.
Quoted 4 lines
Quoted 1 line
That definition came directly from Wikipedia :-)
I wonder whether the person (or persons) who wrote the article have worked on such hardware that is typically supported in V4L2. :-)
:-)
Quoted 87 lines
Quoted 33 lines
Quoted 7 lines
How about:
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).
Works for me.
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 83
Quoted 4 lines
Documentation/media/uapi/v4l/glossary.rst new file +3
-0+ + Peripheral + The same as hardware peripheral.Peripheral generally is a very seldom used term nowadays, perhaps because mostly you don't need to explicitly refer to external devices. I'd just leave it out.
Let's discuss the usage of "peripheral" x "V4L2 hardware" x "media hardware".
Once we reach a consensus, I'll replace for whatever term we agree.
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst line 87
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +4
-0+ + Media Controller + An API used to identify the hardware components and (optionally) + change the links between hardware components.IMO glossary is not where optional and mandatory parts of APIs should be discussed. Just the scope. I.e. I'd leave "(optionally)" out. Change -> configure.
Quoted 2 lines
IMO, glossary should provide a summary of all terms used, specially the ones that are defined at the API itself.
Yes, but that's orthogonal to what I wrote above.
Quoted 12 lines
Quoted 4 lines
The links are also between media entities, not hardware components. It is not uncommon that a driver for a hardware component exposes several sub-devices for the same component.
The concept of entities, links, interfaces, etc should be added at the glossary, but IMHO it is out of the current scope: this glossary is only at the V4L2 part of the spec, with doesn't cover MC.
I'm OK if you want to expand it to cover the entire uAPI book, but I don't have any time for doing it myself.
Quoted 8 lines
So, I would prefer to keep the definition here as simple as possible. What about:
An API designed to expose and control devices and sub-devices relationships to applications.
(that's basically a quick summary of what's written at
media-controller-intro.rst)Works for me. I think it'd be useful to improve that in the future, but I think the glossary will be quite useful to define the terms used. During the review of the set it's become apparent that different people understand the terms we use regularly a bit differently.
Quoted 23 lines
Quoted 22 lines
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + See :ref:`v4l2_hardware_control`. +Documentation/media/uapi/v4l/glossary.rst line 105
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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 - SPIWe don't have "Bus" in I²C, I'd leave it out here, too.
Quoted 8 lines
Quoted 2 lines
I2C is a serial bus (and it is implemented as a bus inside the Kernel). Take a look at
Documentation/i2c/summary.I don't disagree with that, but at the same time this is not related to my suggestion.
"Bus" is not part of the abbreviation SPI, therefore we should not suggest that here.
Ah, so you proposal here is just to replace:
Serial Peripheral Interface Bus - SPI
To
Serial Peripheral Interface - SPI
Right? If so, it sounds OK.
Quoted 72 lines
Quoted 34 lines
Quoted 11 lines
Quoted 11 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ 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. + + Sub-device hardware components + Hardware components that aren't controlled by theQuoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 119
Quoted 5 lines
Documentation/media/uapi/v4l/glossary.rst new file +5
-0+ V4L2 main driver. + + V4L2 device node + A device node that is associated to a V4L2 main driver, + as specified in :ref:`v4l2_device_naming`.This will be confusing. Many sub-device nodes are exposed by so-called main drivers.
The sub-device nodes are not listed at
v4l2_device_namingchapter. Also, as I mentioned, I'm adding a notice there explicitly excluding them from "V4L2 device node".Btw, I don't know why (and where) a main driver would also be exporting a sub-device. That seems to be a violation of the subdev API.
Quoted 3 lines
I'd understand this as any device node type that is exposed by V4L2. In general there should not be limitation on this, although video device nodes are effectively only exposed by main drivers.
The goal of the glossary (and other changes in this series) is to differentiate what is:
Quoted 8 lines
- V4L2 device node - e. g.
/dev/video,/dev/radio,/dev/swradio,/dev/vbi,/dev/v4l-touch(and only those)
- V4L2 sub-device node - e. g./dev/v4l-subdev.If you think this is not enough, we could repeat the above info, although, IMHO, it is better to add refs to the right chapters, in order to avoid the need of touching the glossary every time we add a new V4L2 device node.
Yes, it'd easily become quite long. Yes, I think the reference is good for now.
Quoted 26 lines
Quoted 11 lines
Quoted 11 lines
Documentation/media/uapi/v4l/glossary.rst new file +9
-0+ + V4L2 hardware + A hardware used to on a media device supported by the V4L2 + subsystem. + + V4L2 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 134
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.Is UVC driver a bridge driver? How about instead:
Yes, sure: UVC driver is a bridge driver/main driver. It is the UVC driver that sends/receives data from the USB bus and send to the sensors. It also sends data via URB to the USB host driver, with, in turn send it to send to CPU (usually via DMA - although some USB drivers actually implement direct I/O for short messages).
Quoted 7 lines
Quoted 3 lines
Quoted 1 line
Bridge and ISP drivers typically are V4L2 main drivers.
We don't have a concept of an "ISP driver". Adding it sounds very
I think we do have that roughly as much as we do have bridge driver. We definitely also support devices that are called ISPs, therefore we do have ISP drivers.
We have drivers for things implemented via ISP. However, right now, there's no distinction at the driver if the functionality is implemented on software (ISP) or in hardware.
Quoted 6 lines
Quoted 3 lines
confusing, as an ISP hardware may actually implement different functions - so it ends by being supported by multiple drivers.
Typically ISPs are controlled by a single driver as the sub-blocks in an ISP usually can only be found in that very ISP.
I'm almost sure that this is not true for Exynos drivers. There are m2m drivers and normal drivers for the same ISP (doing different things, like format conversion, scaling, etc).
Quoted 14 lines
Quoted 14 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst line 140
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ + See :ref:`v4l2_hardware_control`. + + V4L2 sub-device + Part of the media hardware that it is implemented by a device + driver that is not part of the main V4L2 driver.How about:
V4L2 abstraction for a hardware component which is functionally or physically separate from the DMA engine.
Quoted 9 lines
Quoted 6 lines
That's actually not true. On vdev-centric devices, common ISP controls (bright, color, saturation, etc) are actually implemented by the main V4L2 driver.
Also, on USB drivers, the DMA engine is actually not implemented by the main driver, but by the USB host driver.
Right, that's true indeed.
Thanks,
Mauro
Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Hi Mauro,
Quoted 30 lines · Mauro Carvalho Chehab
Quoted 21 lines
Quoted 21 lines
Quoted 20 lines
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ + See :ref:`media_controller`. + + MC-centric + V4L2 hardware that requires a Media controller. + + See :ref:`v4l2_hardware_control`. +Documentation/media/uapi/v4l/glossary.rst line 105
Quoted 10 lines
Documentation/media/uapi/v4l/glossary.rst new file +10
-0+ 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 - SPIWe don't have "Bus" in I²C, I'd leave it out here, too.
Quoted 8 lines
Quoted 2 lines
I2C is a serial bus (and it is implemented as a bus inside the Kernel). Take a look at
Documentation/i2c/summary.I don't disagree with that, but at the same time this is not related to my suggestion.
"Bus" is not part of the abbreviation SPI, therefore we should not suggest that here.
Quoted 8 lines
Ah, so you proposal here is just to replace:
Serial Peripheral Interface Bus - SPI
To
Serial Peripheral Interface - SPIRight? If so, it sounds OK.
Yes, please. That's exactly what I had in mind.
...
Quoted 39 lines
Quoted 23 lines
Quoted 23 lines
Quoted 8 lines
Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst new file +8
-0+ V4L2 hardware + A hardware used to on a media device supported by the V4L2 + subsystem. + + V4L2 hardware control + The type of hardware control that a device supports. + + See :ref:`v4l2_hardware_control`.Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 134
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.Is UVC driver a bridge driver? How about instead:
Yes, sure: UVC driver is a bridge driver/main driver. It is the UVC driver that sends/receives data from the USB bus and send to the sensors. It also sends data via URB to the USB host driver, with, in turn send it to send to CPU (usually via DMA - although some USB drivers actually implement direct I/O for short messages).
Quoted 7 lines
Quoted 3 lines
Quoted 1 line
Bridge and ISP drivers typically are V4L2 main drivers.
We don't have a concept of an "ISP driver". Adding it sounds very
I think we do have that roughly as much as we do have bridge driver. We definitely also support devices that are called ISPs, therefore we do have ISP drivers.
We have drivers for things implemented via ISP. However, right now, there's no distinction at the driver if the functionality is implemented on software (ISP) or in hardware.
Quoted 4 lines
Quoted 3 lines
confusing, as an ISP hardware may actually implement different functions - so it ends by being supported by multiple drivers.
Quoted 6 lines
Quoted 2 lines
Typically ISPs are controlled by a single driver as the sub-blocks in an ISP usually can only be found in that very ISP.
I'm almost sure that this is not true for Exynos drivers. There are m2m drivers and normal drivers for the same ISP (doing different things, like format conversion, scaling, etc).
I don't know the Exynos hardware. There are exceptions but they tend to be increasingly rare as extra memory hops hurt performance and increase power consumption in common use cases.
If there is a split to multiple devices, then usually the first device is CSI-2 receiver plus DMA (bridge) and the second is the ISP (i.e. where the processing happens).
Signature · 4 lines
Regards, Sakari Ailus e-mail: [email protected]
Mauro Carvalho Chehab
Reviewed-by Laurent Pinchart Reviewed-by Guennadi Liakhovetski Reviewed-by Andy Walls Reviewed-by David BrownellRe: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
In reply to Sakari AilusEm Thu, 5 Oct 2017 11:21:07 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 72 lines
Hi Mauro,
My apologies for the late reply.
Quoted 36 lines · Mauro Carvalho Chehab
Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 24 lines
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 19 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +3
-0@@ -0,0 +1,147 @@ +======== +Glossary +========Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ +.. 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.I'd leave the WiP part out.
Quoted 3 lines
IMO, it is important to mention it, as the glossary, right now, covers only what's used on the first two sections of the API book. There are a lot more to be covered.
Works for me.
Quoted 25 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
Quoted 2 lines
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
No, only on some drivers the bridge driver has DMA. A vast amount of drivers (USB ones) don't implement any DMA inside the driver, as it is up to the USB host driver to implement support for DMA.
There are even some USB host drivers that don't always use DMA for I/O transfers, using direct I/O if the message is smaller than a threshold or not multiple of the bus word. This is pretty common on SoC USB host drivers.
Quoted 7 lines
Quoted 3 lines
In any case, for the effect of this spec, and for all discussions we ever had about it, bridge driver == V4L2 main driver. I don't see any reason why to distinguish between them.
I think you should precisely define what a bridge driver means. Generally ISP drivers aren't referred to as bridge drivers albeit they, too, function as V4L2 main drivers.
Btw, this is already defined, currently, at v4l2-subdev.h:
* Sub-devices are devices that are connected somehow to the main bridge
* device. These devices are usually audio/video muxers/encoders/decoders or
* sensors and webcam controllers.
*
* Usually these devices are controlled through an i2c bus, but other busses
* may also be used.
Please notice that there it says: "main bridge" :-)
Such definition was added since the beginning of the subdev concept, back in 2008 and was reviewed by several V4L core developers:
commit 2a1fcdf08230522bd5024f91da24aaa6e8d81f59
Author: Hans Verkuil <[email protected]> Date: Sat Nov 29 21:36:58 2008 -0300
V4L/DVB (9820): v4l2: add v4l2_device and v4l2_subdev structs to the v4l2 framework.
Start implementing a proper v4l2 framework as discussed during the Linux Plumbers Conference 2008.
Introduces v4l2_device (for device instances) and v4l2_subdev (representing sub-device instances).
Thanks,
Mauro
Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec
Quoted 92 lines · Mauro Carvalho Chehab
Em Thu, 5 Oct 2017 11:21:07 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 72 lines
Hi Mauro,
My apologies for the late reply.
Quoted 36 lines · Mauro Carvalho Chehab
Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 24 lines
Hi Mauro,
Thanks for the update. A few comments below.
Quoted 19 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 | 147 ++++++++++++++++++++++++++++++ Documentation/media/uapi/v4l/v4l2.rst | 1 + 2 files changed, 148 insertions(+) create mode 100644 Documentation/media/uapi/v4l/glossary.rstDocumentation/media/uapi/v4l/glossary.rst new file +3
-0@@ -0,0 +1,147 @@ +======== +Glossary +========Quoted 8 lines
Documentation/media/uapi/v4l/glossary.rst line 9
Quoted 6 lines
Documentation/media/uapi/v4l/glossary.rst new file +6
-0+ +.. 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.I'd leave the WiP part out.
Quoted 3 lines
IMO, it is important to mention it, as the glossary, right now, covers only what's used on the first two sections of the API book. There are a lot more to be covered.
Works for me.
Quoted 25 lines
Quoted 13 lines
Documentation/media/uapi/v4l/glossary.rst line 16
Quoted 9 lines
Documentation/media/uapi/v4l/glossary.rst new file +7
-0+ +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge driver + The same as V4L2 main driver.I've understood bridges being essentially a bus receiver + DMA. Most ISPs contain both but have more than that. How about:
Quoted 2 lines
A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers typically act as V4L2 main drivers.
No, only on some drivers the bridge driver has DMA. A vast amount of drivers (USB ones) don't implement any DMA inside the driver, as it is up to the USB host driver to implement support for DMA.
There are even some USB host drivers that don't always use DMA for I/O transfers, using direct I/O if the message is smaller than a threshold or not multiple of the bus word. This is pretty common on SoC USB host drivers.
Quoted 7 lines
Quoted 3 lines
In any case, for the effect of this spec, and for all discussions we ever had about it, bridge driver == V4L2 main driver. I don't see any reason why to distinguish between them.
I think you should precisely define what a bridge driver means. Generally ISP drivers aren't referred to as bridge drivers albeit they, too, function as V4L2 main drivers.
Btw, this is already defined, currently, at
v4l2-subdev.h:* Sub-devices are devices that are connected somehow to the main bridge
* device. These devices are usually audio/video muxers/encoders/decoders or
* sensors and webcam controllers.
*
* Usually these devices are controlled through an i2c bus, but other busses
* may also be used.
Quoted 4 lines
Please notice that there it says: "main bridge" :-)
Such definition was added since the beginning of the subdev concept, back in 2008 and was reviewed by several V4L core developers:
A lot has happened since 2008. :-)
Anyway, I'll review the latest set.
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
PATCH v5 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 | 39 ++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-)
Documentation/media/uapi/v4l/open.rst +36 -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,37 @@ 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 warranty that ``X`` will remain the same for the same + device, as the number depends on the device driver's probe order. + If you need an unique name, udev default rules produce + ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directoiries 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 + + 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
Re: [PATCH v5 2/7] media: open.rst: better document device node naming
Hi Mauro,
Quoted 36 lines · Mauro Carvalho Chehab
Right now, only kAPI documentation describes the device naming. However, such description is needed at the uAPI too. Add it, and describe how to get an unique identify for a given device.
Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 39 ++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-)Documentation/media/uapi/v4l/open.rst +5
-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,37 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are allocated in ranges depending on the device node type (video, radio, etc.).
Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 37
Quoted 10 lines
Documentation/media/uapi/v4l/open.rst +10
-0+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
Should we document V4L2 sub-device nodes here as well? They are implemented by the V4L2 core as well as the other device node types.
Their purpose is somewhat different, though, and I think we'll need to make that explicit somehow.
Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 45
Quoted 8 lines
Documentation/media/uapi/v4l/open.rst +8
-0+======================== ====================================================== + +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 warranty that ``X`` will remain the same for the same
s/warranty/guarantee/
Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 48
Quoted 3 lines
Documentation/media/uapi/v4l/open.rst +3
-0+ 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/`` directoiries containing
"directories"
Quoted 13 lines
Documentation/media/uapi/v4l/open.rst +10
-0+ 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 + + 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 · 4 lines
Kind regards, Sakari Ailus e-mail: [email protected]
Re: [PATCH v5 2/7] media: open.rst: better document device node naming
Hi Sakari,
Em Tue, 29 Aug 2017 11:34:06 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 53 lines
Hi Mauro,
Quoted 36 lines · Mauro Carvalho Chehab
Right now, only kAPI documentation describes the device naming. However, such description is needed at the uAPI too. Add it, and describe how to get an unique identify for a given device.
Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/media/uapi/v4l/open.rst | 39 ++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-)Documentation/media/uapi/v4l/open.rst +5
-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,37 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are allocated in ranges depending on the device node type (video, radio, etc.).Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 37
Quoted 10 lines
Documentation/media/uapi/v4l/open.rst +10
-0+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 sensorsShould we document V4L2 sub-device nodes here as well? They are implemented by the V4L2 core as well as the other device node types.
Quoted 2 lines
Their purpose is somewhat different, though, and I think we'll need to make that explicit somehow.
Actually, what we're calling as "V4L2 Device node" are the vdev-centric device nodes. That should not include /dev/v4l-subdevX.
What we can do here is to explicitly rule out the subdev interfaces, with something like:
.. note::
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.
Quoted 11 lines
Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 45
Quoted 9 lines
Documentation/media/uapi/v4l/open.rst +8
-0+======================== ====================================================== + +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 warranty that ``X`` will remain the same for the sames/warranty/guarantee/
OK.
Quoted 6 lines
Documentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 48
Quoted 4 lines
Documentation/media/uapi/v4l/open.rst +3
-0+ 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/`` directoiries containing"directories"
OK.
Quoted 15 lines
Quoted 4 lines
Documentation/media/uapi/v4l/open.rst +3
-0+ links that can be used uniquely to identify a V4L2 device node:: + + $ tree /dev/v4lDocumentation/media/uapi/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 61
Quoted 10 lines
Documentation/media/uapi/v4l/open.rst +7
-0+ /dev/v4l + ├── by-id + │ └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 + └── by-path + └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 + + Many drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the user to request that the device node is named e.g. /dev/video5 instead
Thanks,
Mauro
PATCH v5 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
Re: [PATCH v5 3/7] media: open.rst: remove the minor number range
Quoted 10 lines · Mauro Carvalho Chehab
minor numbers use to range between 0 to 255, but that was changed a long time ago. While it still applies when
CONFIG_VIDEO_FIXED_MINOR_RANGES, when the minor number is dynamically allocated, this may not be true. In any case, this is not relevant, as udev will take care of it.So, remove this useless misinformation.
Acked-by Hans Verkuil <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>
Signature · 2 lines
Sakari Ailus e-mail: [email protected]
PATCH v5 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 hardware peripheral 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 +peripheral control: via the **V4L2 device nodes**. We refer to this kind +of control as **V4L2 device node centric** (or, simply, "**vdev-centric**"). + +Later (kernel 2.6.39), a new type of periferal control was +added in order to support complex peripherals 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 **vdev-centric** hardware peripheral control, the peripheral 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** hardware peripheral 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
PATCH v5 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
@@ -138,7 +138,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
@@ -148,17 +148,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
PATCH v5 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** hardware peripheral 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
@@ -252,6 +252,11 @@ specification the ioctl returns an ``EINVAL`` error code. * - ``V4L2_CAP_TOUCH`` - 0x10000000 - This is a touch device. + * - ``V4L2_MC_CENTRIC`` + - 0x20000000 + - Indicates that the device require **MC-centric** hardware + control, and thus can't be used by **vdev-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
PATCH v5 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 **vdev-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** hardware peripheral control should
Signature · 1 line
2.13.5