Re: [PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
Em Thu, 4 Oct 2018 10:27:06 -0300 Mauro Carvalho Chehab escreveu: > > > + For V4L2 hardware, this is also known as V4L2 main driver. > > > > Do we use the term V4L2 main driver in the V4L2 spec ? > > Right now, I don't think we use, but this is something that we'll > need to, in order to define hardware controls. > > Anyway, I'll remove the reference for a V4L2 hardware from this patch, > moving to the one that talks about vdev-centric/mc-centric. In time: I'll remove the reference for *V4L2 main driver*, with is what you asked for Thanks, Mauro
Re: [PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
Em Thu, 04 Oct 2018 14:41:30 +0300 Laurent Pinchart escreveu: > Hi Mauro, > > (CC'ing Kieran) > > Thank you for the patch. > > On Tuesday, 25 September 2018 22:14:51 EEST Mauro Carvalho Chehab wrote: > > From: Mauro Carvalho Chehab > > > > Add a glossary of terms used within the media userspace API > > documentation, as several concepts are complex enough to cause > > misunderstandings. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > > > v3: > > - Add SPDX header and dual-license the glossary > > - Make glossary generic enough to be used for all media uAPI > > documentation; - Add a few new items to the glossary, to imply that it > > covers not only V4L2; - Move it to the uAPI document as a hole. > > > > v2: Did some changes based on Sakari's feedback. > > > > Documentation/media/media_uapi.rst| 3 + > > Documentation/media/uapi/glossary.rst | 162 ++ > > 2 files changed, 165 insertions(+) > > create mode 100644 Documentation/media/uapi/glossary.rst > > > > diff --git a/Documentation/media/media_uapi.rst > > b/Documentation/media/media_uapi.rst index 28eb35a1f965..41f091a26003 > > 100644 > > --- a/Documentation/media/media_uapi.rst > > +++ b/Documentation/media/media_uapi.rst > > @@ -2,6 +2,8 @@ > > > > .. include:: > > > > +.. _media_uapi: > > + > > > > Linux Media Infrastructure userspace API > > > > @@ -31,3 +33,4 @@ License". > > uapi/cec/cec-api > > uapi/gen-errors > > uapi/fdl-appendix > > +uapi/glossary > > Is there an easy way to cross-reference to the glossary when terms are used ? According with Sphinx documentation, there is: :term:`some glossary term` But, on the tests I did here, it didn't really work with Sphinx 1.4. It is actually on my TODO list to seek for a good way to address it (and to find/replace occurrences of the terms at the documentation to add cross-refs). > > > diff --git a/Documentation/media/uapi/glossary.rst > > b/Documentation/media/uapi/glossary.rst new file mode 100644 > > index ..9e2a2b29e8b2 > > --- /dev/null > > +++ b/Documentation/media/uapi/glossary.rst > > @@ -0,0 +1,162 @@ > > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later > > + > > +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0 > > +.. > > +.. For GFDL-1.1-or-later, see: > > +.. > > +.. Permission is granted to copy, distribute and/or modify this document > > +.. under the terms of the GNU Free Documentation License, Version 1.1 or > > +.. any later version published by the Free Software Foundation, with no > > +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. > > +.. A copy of the license is included at > > +.. Documentation/media/uapi/fdl-appendix.rst. > > + > > + > > +Glossary > > + > > + > > +.. note:: > > + > > + This goal of section is to standardize the terms used within the media > > + userspace API documentation. It is written incrementally as they are > > + standardized in the media documentation. > > + > > + So, it is a Work In Progress. > > + > > +.. Please keep the glossary entries in alphabetical order > > + > > +.. glossary:: > > + > > +Bridge driver > > Shouldn't all words start with a capital letter ? I guess it is a matter of preference. Right now, I'm capitalizing stuff only when they have acronyms (like Digital Signal Processor - DSP), but I'm ok of doing it to the other terms as well. > > > + A device driver that implements the main logic to talk with > > + a media hardware. > > Terms that are part of the glossary should also be capitalized (and cross- > referenced within the glossary). For now, it doesn't matter much. When we add cross references, it will use either :ref: or :term:, so the actual text will be inserted by Sphinx. > > Hardware is still uncountable in English. I know we've discussed this > previously, but if we want to write a glossary, it should be in English. > Maybe > we need to involve a native English speaker here. Kieran ? :-) I'll replace: a media hardware -> media hardware > > Additionally, I don't think the definition is correct. Bridges, as defined in > V4L2, are opposed to subdevs, while "media hardware" in your definition > includes everything. This needs to be clarified. Please notice that the goal of this glossary is to be generic, and not specific to V4L2. Extra care should be taken if we want to talk about "subdevs" here, as such concept doesn't exist on DVB, CEC or RC (but "main driver" does). Also, I don't think that a subdev driver would fit into "implements the main logic to talk with media hardware." Anyway, if you have a better definition, feel free to suggest. > > > + For V4L2 hardware, this is also known as V4L2 main driver. > > Do we use the term V4L2 main driver in the V4L2 spec ? Right now, I don't think we use, but this is something that we'll need to, in
Re: [PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
Hi Mauro, (CC'ing Kieran) Thank you for the patch. On Tuesday, 25 September 2018 22:14:51 EEST Mauro Carvalho Chehab wrote: > From: Mauro Carvalho Chehab > > Add a glossary of terms used within the media userspace API > documentation, as several concepts are complex enough to cause > misunderstandings. > > Signed-off-by: Mauro Carvalho Chehab > --- > > v3: > - Add SPDX header and dual-license the glossary > - Make glossary generic enough to be used for all media uAPI > documentation; - Add a few new items to the glossary, to imply that it > covers not only V4L2; - Move it to the uAPI document as a hole. > > v2: Did some changes based on Sakari's feedback. > > Documentation/media/media_uapi.rst| 3 + > Documentation/media/uapi/glossary.rst | 162 ++ > 2 files changed, 165 insertions(+) > create mode 100644 Documentation/media/uapi/glossary.rst > > diff --git a/Documentation/media/media_uapi.rst > b/Documentation/media/media_uapi.rst index 28eb35a1f965..41f091a26003 > 100644 > --- a/Documentation/media/media_uapi.rst > +++ b/Documentation/media/media_uapi.rst > @@ -2,6 +2,8 @@ > > .. include:: > > +.. _media_uapi: > + > > Linux Media Infrastructure userspace API > > @@ -31,3 +33,4 @@ License". > uapi/cec/cec-api > uapi/gen-errors > uapi/fdl-appendix > +uapi/glossary Is there an easy way to cross-reference to the glossary when terms are used ? > diff --git a/Documentation/media/uapi/glossary.rst > b/Documentation/media/uapi/glossary.rst new file mode 100644 > index ..9e2a2b29e8b2 > --- /dev/null > +++ b/Documentation/media/uapi/glossary.rst > @@ -0,0 +1,162 @@ > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later > + > +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0 > +.. > +.. For GFDL-1.1-or-later, see: > +.. > +.. Permission is granted to copy, distribute and/or modify this document > +.. under the terms of the GNU Free Documentation License, Version 1.1 or > +.. any later version published by the Free Software Foundation, with no > +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. > +.. A copy of the license is included at > +.. Documentation/media/uapi/fdl-appendix.rst. > + > + > +Glossary > + > + > +.. note:: > + > + This goal of section is to standardize the terms used within the media > + userspace API documentation. It is written incrementally as they are > + standardized in the media documentation. > + > + So, it is a Work In Progress. > + > +.. Please keep the glossary entries in alphabetical order > + > +.. glossary:: > + > +Bridge driver Shouldn't all words start with a capital letter ? > + A device driver that implements the main logic to talk with > + a media hardware. Terms that are part of the glossary should also be capitalized (and cross- referenced within the glossary). Hardware is still uncountable in English. I know we've discussed this previously, but if we want to write a glossary, it should be in English. Maybe we need to involve a native English speaker here. Kieran ? :-) Additionally, I don't think the definition is correct. Bridges, as defined in V4L2, are opposed to subdevs, while "media hardware" in your definition includes everything. This needs to be clarified. > + For V4L2 hardware, this is also known as V4L2 main driver. Do we use the term V4L2 main driver in the V4L2 spec ? > +Consumer Electronics Control API > + An API designed to receive and transmit data via a HDMI > + CEC interface. So the definition of "Consumer Electronics Control" is CEC ? :-) It would be more useful to do it the other way around, define CEC as Consumer Electronics Control, and explain what it is. > + See :ref:`cec`. > + > +Device Node > + A character device node in the file system used to control and do > + input/output data transfers from/to a Kernel driver. Maybe "and transfer data in and out of a kernel driver" ? > + > +Digital TV API - DVB API Is DVB the same as Digital TV ? The digital video API (https://linuxtv.org/ downloads/v4l-dvb-apis-new/uapi/v4l/dv-timings.html) is sometimes referred to digital TV too. How about standardizing on DVB and avoiding digital TV completely in the specification ? > + An API designed to control the media device components related to > + digital TV, including frontends, demuxes, streaming, conditional > + access, etc. > + > + See :ref:`dvbapi`. > + > +Digital Signal Processor - DSP Here and below I would put the abbreviation first. If someone looks up a term in the glossary because they don't know what it means, they're more likely to search for the abbreviation, not the full term. > + A specialized microprocessor, with its architecture optimized for > + the operational needs of digital signal processing. Stupid question, do we need this entry in
Re: [PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
Em Mon, 1 Oct 2018 17:20:26 +0200 Hans Verkuil escreveu: > On 09/25/2018 09:14 PM, Mauro Carvalho Chehab wrote: > > From: Mauro Carvalho Chehab > > > > Add a glossary of terms used within the media userspace API > > documentation, as several concepts are complex enough to cause > > misunderstandings. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > > > v3: > > - Add SPDX header and dual-license the glossary > > - Make glossary generic enough to be used for all media uAPI > > documentation; > > - Add a few new items to the glossary, to imply that it covers not only > > V4L2; > > - Move it to the uAPI document as a hole. > > > > v2: Did some changes based on Sakari's feedback. > > > > Documentation/media/media_uapi.rst| 3 + > > Documentation/media/uapi/glossary.rst | 162 ++ > > 2 files changed, 165 insertions(+) > > create mode 100644 Documentation/media/uapi/glossary.rst > > > > diff --git a/Documentation/media/media_uapi.rst > > b/Documentation/media/media_uapi.rst > > index 28eb35a1f965..41f091a26003 100644 > > --- a/Documentation/media/media_uapi.rst > > +++ b/Documentation/media/media_uapi.rst > > @@ -2,6 +2,8 @@ > > > > .. include:: > > > > +.. _media_uapi: > > + > > > > Linux Media Infrastructure userspace API > > > > @@ -31,3 +33,4 @@ License". > > uapi/cec/cec-api > > uapi/gen-errors > > uapi/fdl-appendix > > +uapi/glossary > > diff --git a/Documentation/media/uapi/glossary.rst > > b/Documentation/media/uapi/glossary.rst > > new file mode 100644 > > index ..9e2a2b29e8b2 > > --- /dev/null > > +++ b/Documentation/media/uapi/glossary.rst > > @@ -0,0 +1,162 @@ > > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later > > + > > +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0 > > +.. > > +.. For GFDL-1.1-or-later, see: > > +.. > > +.. Permission is granted to copy, distribute and/or modify this document > > +.. under the terms of the GNU Free Documentation License, Version 1.1 or > > +.. any later version published by the Free Software Foundation, with no > > +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. > > +.. A copy of the license is included at > > +.. Documentation/media/uapi/fdl-appendix.rst. > > + > > + > > +Glossary > > + > > + > > +.. note:: > > + > > + This goal of section is to standardize the terms used within the media > > + userspace API documentation. It is written incrementally as they are > > + standardized in the media documentation. > > + > > + So, it is a Work In Progress. > > + > > +.. Please keep the glossary entries in alphabetical order > > + > > +.. glossary:: > > + > > +Bridge driver > > + A device driver that implements the main logic to talk with > > + a media hardware. > > s/a // > > > + > > + For V4L2 hardware, this is also known as V4L2 main driver. > > s/as/as the/ > > > + > > +Consumer Electronics Control API > > + An API designed to receive and transmit data via a HDMI > > + CEC interface. > > + > > + See :ref:`cec`. > > + > > +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 TV API - DVB API > > + An API designed to control the media device components related to > > + digital TV, including frontends, demuxes, streaming, conditional > > + access, etc. > > To be added to this glossary in the future: > > - Frontend > - Demux > - Conditional Access Yeah. The idea here is just to place a boilerplate for it. We should in the future add more terms to the glossary. After having the glossary added, it should be reviewed along the other documents. Then, I'll add digital TV specific terms. > > > + > > + See :ref:`dvbapi`. > > + > > +Digital Signal Processor - DSP > > + A specialized microprocessor, with its architecture optimized for > > + the operational needs of digital signal processing. > > + > > +Driver > > + 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. > > + > > +Inter-Integrated Circuit - I²C > > + A multi-master, multi-slave, packet switched, single-ended, > > + serial computer bus used to control some hardware components > > + like sub-device hardware components. > > + > > + 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. > > + >
Re: [PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
On 09/25/2018 09:14 PM, Mauro Carvalho Chehab wrote: > From: Mauro Carvalho Chehab > > Add a glossary of terms used within the media userspace API > documentation, as several concepts are complex enough to cause > misunderstandings. > > Signed-off-by: Mauro Carvalho Chehab > --- > > v3: > - Add SPDX header and dual-license the glossary > - Make glossary generic enough to be used for all media uAPI documentation; > - Add a few new items to the glossary, to imply that it covers not only > V4L2; > - Move it to the uAPI document as a hole. > > v2: Did some changes based on Sakari's feedback. > > Documentation/media/media_uapi.rst| 3 + > Documentation/media/uapi/glossary.rst | 162 ++ > 2 files changed, 165 insertions(+) > create mode 100644 Documentation/media/uapi/glossary.rst > > diff --git a/Documentation/media/media_uapi.rst > b/Documentation/media/media_uapi.rst > index 28eb35a1f965..41f091a26003 100644 > --- a/Documentation/media/media_uapi.rst > +++ b/Documentation/media/media_uapi.rst > @@ -2,6 +2,8 @@ > > .. include:: > > +.. _media_uapi: > + > > Linux Media Infrastructure userspace API > > @@ -31,3 +33,4 @@ License". > uapi/cec/cec-api > uapi/gen-errors > uapi/fdl-appendix > +uapi/glossary > diff --git a/Documentation/media/uapi/glossary.rst > b/Documentation/media/uapi/glossary.rst > new file mode 100644 > index ..9e2a2b29e8b2 > --- /dev/null > +++ b/Documentation/media/uapi/glossary.rst > @@ -0,0 +1,162 @@ > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later > + > +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0 > +.. > +.. For GFDL-1.1-or-later, see: > +.. > +.. Permission is granted to copy, distribute and/or modify this document > +.. under the terms of the GNU Free Documentation License, Version 1.1 or > +.. any later version published by the Free Software Foundation, with no > +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. > +.. A copy of the license is included at > +.. Documentation/media/uapi/fdl-appendix.rst. > + > + > +Glossary > + > + > +.. note:: > + > + This goal of section is to standardize the terms used within the media > + userspace API documentation. It is written incrementally as they are > + standardized in the media documentation. > + > + So, it is a Work In Progress. > + > +.. Please keep the glossary entries in alphabetical order > + > +.. glossary:: > + > +Bridge driver > + A device driver that implements the main logic to talk with > + a media hardware. s/a // > + > + For V4L2 hardware, this is also known as V4L2 main driver. s/as/as the/ > + > +Consumer Electronics Control API > + An API designed to receive and transmit data via a HDMI > + CEC interface. > + > + See :ref:`cec`. > + > +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 TV API - DVB API > + An API designed to control the media device components related to > + digital TV, including frontends, demuxes, streaming, conditional > + access, etc. To be added to this glossary in the future: - Frontend - Demux - Conditional Access > + > + See :ref:`dvbapi`. > + > +Digital Signal Processor - DSP > + A specialized microprocessor, with its architecture optimized for > + the operational needs of digital signal processing. > + > +Driver > + 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. > + > +Inter-Integrated Circuit - I²C > + A multi-master, multi-slave, packet switched, single-ended, > + serial computer bus used to control some hardware components > + like sub-device hardware components. > + > + 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. > + > +Intelectual property core - IP block Intelectual -> Intellectual > + 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 Signal Processor - ISP > + A specialised
[PATCH v3] media: docs: add glossary.rst with common terms used at V4L2 spec
From: Mauro Carvalho Chehab Add a glossary of terms used within the media userspace API documentation, as several concepts are complex enough to cause misunderstandings. Signed-off-by: Mauro Carvalho Chehab --- v3: - Add SPDX header and dual-license the glossary - Make glossary generic enough to be used for all media uAPI documentation; - Add a few new items to the glossary, to imply that it covers not only V4L2; - Move it to the uAPI document as a hole. v2: Did some changes based on Sakari's feedback. Documentation/media/media_uapi.rst| 3 + Documentation/media/uapi/glossary.rst | 162 ++ 2 files changed, 165 insertions(+) create mode 100644 Documentation/media/uapi/glossary.rst diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst index 28eb35a1f965..41f091a26003 100644 --- a/Documentation/media/media_uapi.rst +++ b/Documentation/media/media_uapi.rst @@ -2,6 +2,8 @@ .. include:: +.. _media_uapi: + Linux Media Infrastructure userspace API @@ -31,3 +33,4 @@ License". uapi/cec/cec-api uapi/gen-errors uapi/fdl-appendix +uapi/glossary diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst new file mode 100644 index ..9e2a2b29e8b2 --- /dev/null +++ b/Documentation/media/uapi/glossary.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later + +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0 +.. +.. For GFDL-1.1-or-later, see: +.. +.. Permission is granted to copy, distribute and/or modify this document +.. under the terms of the GNU Free Documentation License, Version 1.1 or +.. any later version published by the Free Software Foundation, with no +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. +.. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. + + +Glossary + + +.. note:: + + This goal of section is to standardize the terms used within the media + userspace API documentation. It is written incrementally as they are + standardized in the media documentation. + + So, it is a Work In Progress. + +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + +Bridge driver + A device driver that implements the main logic to talk with + a media hardware. + + For V4L2 hardware, this is also known as V4L2 main driver. + +Consumer Electronics Control API + An API designed to receive and transmit data via a HDMI + CEC interface. + + See :ref:`cec`. + +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 TV API - DVB API + An API designed to control the media device components related to + digital TV, including frontends, demuxes, streaming, conditional + access, etc. + + See :ref:`dvbapi`. + +Digital Signal Processor - DSP + A specialized microprocessor, with its architecture optimized for + the operational needs of digital signal processing. + +Driver + 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. + +Inter-Integrated Circuit - I²C + A multi-master, multi-slave, packet switched, single-ended, + serial computer bus used to control some hardware components + like sub-device hardware components. + + 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. + +Intelectual property core - IP block + 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 Signal Processor - ISP + A specialised processor that implements a set of algorithms for + processing image data. ISPs may implement algorithms for lens + shading correction, demosaic, scaling and pixel format conversion + as well as produce statistics for the use of the control + algorithms (e.g. automatic exposure, white balance and focus). + +Media API + A set of userspace APIs used to control a media