On 08/05/2020 16:25, Mauro Carvalho Chehab wrote: > Em Fri, 8 May 2020 15:40:25 +0200 > Hans Verkuil <hverkuil-cisco@xxxxxxxxx> escreveu: > >> On 08/05/2020 15:10, Mauro Carvalho Chehab wrote: >>> 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 <mchehab+huawei@xxxxxxxxxx> >>> --- >>> .../userspace-api/media/glossary.rst | 182 ++++++++++++++++++ >>> Documentation/userspace-api/media/index.rst | 3 + >>> 2 files changed, 185 insertions(+) >>> create mode 100644 Documentation/userspace-api/media/glossary.rst >>> >>> diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst >>> new file mode 100644 >>> index 000000000000..18a1ace00159 >>> --- /dev/null >>> +++ b/Documentation/userspace-api/media/glossary.rst >>> @@ -0,0 +1,182 @@ >>> +.. 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/userspace-api/media/fdl-appendix.rst. >>> + >>> +======== >>> +Glossary >>> +======== >>> + >>> +.. note:: >>> + >>> + This goal of this section is to standardize the terms used within the media >> >> This -> The >> >>> + userspace API documentation. It is written incrementally as they are >>> + standardized in the media documentation. >>> + >>> + So, it is a Work In Progress. >> >> I'd just say: >> >> userspace API documentation. This is Work in Progress. >> >>> + >>> +.. Please keep the glossary entries in alphabetical order >>> + >>> +.. glossary:: >>> + >>> + Bridge Driver >>> + A :term:`device driver` that implements the main logic to talk with >>> + media hardware. >>> + >>> + CEC API >>> + **Consumer Electronics Control API** >>> + >>> + An API designed to receive and transmit data via an HDMI >>> + CEC interface. >>> + >>> + See :ref:`cec`. >>> + >>> + Device Driver >>> + Part of the Linux Kernel that implements support for a hardware >>> + component. >>> + >>> + Device Node >>> + A character device node in the file system used to control and >>> + ransfer data in and out of a Kernel driver. >> >> ransfer -> transfer >> >>> + >>> + Digital TV API >>> + **Previously known as DVB API** >>> + >>> + An API designed to control a subset of the :term:`Media Hardware` >>> + that implements digital TV. >> >> I think it will help to provide some examples, e.g.: >> >> that implements digital TV (e.g. DVB, ATSC, etc.). > > For the above: Ok! > >> >>> + >>> + See :ref:`dvbapi`. >>> + >>> + DSP >>> + **Digital Signal Processor** >>> + >>> + A specialized :term:`Microprocessor`, with its architecture >>> + optimized for the operational needs of digital signal processing. >>> + >>> + FPGA >>> + **Field-programmable Gate Array** >>> + >>> + An :term:`IC` circuit designed to be configured by a customer or >>> + a designer after manufacturing. >>> + >>> + See https://en.wikipedia.org/wiki/Field-programmable_gate_array. >>> + >>> + I²C >>> + **Inter-Integrated Circuit** >>> + >>> + 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. >>> + >>> + IC >>> + **Integrated circuit** >>> + >>> + A set of electronic circuits on one small flat piece of >>> + semiconductor material, normally silicon. >>> + >>> + Also known as chip. >>> + >>> + IP Block >>> + **Intellectual property 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 Blocks 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). >>> + >>> + ISP >>> + **Image Signal Processor** >>> + >>> + A specialized processor that implements a set of algorithms for >>> + processing image data. ISPs may implement algorithms for lens >>> + shading correction, demosaicing, 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 the media hardware. It is >>> + composed by: >>> + >>> + - :term:`CEC API`; >>> + - :term:`Digital TV API`; >>> + - :term:`MC API`; >>> + - :term:`RC API`; and >>> + - :term:`V4L2 API`. >>> + >>> + See :doc:`v4l/v4l2`. >> >> Is that the right reference? I'd expect that v4l/v4l2 refers to the V4L2 API >> and not the whole media API. > > That's the right reference: userspace-api/media/v4l/v4l2.rst file has > just the V4L2 API. That's what I mean: This is the glossary entry for 'Media API', so why have a reference to the V4L2 API? I expect to see a reference to the top-level media API. > > The entire API file is now at userspace-api/media/index.html. > >> >>> + >>> + MC API >>> + **Media Controller API** >>> + >>> + An API designed to expose and control the relationships between >>> + devices and sub-devices. >> >> I'd say 'media devices and sub-devices'. Otherwise it would suggest that >> the MC API also supports non-media devices. > > Yeah, it sounds too generic, but MC is currently used also by audio > devices.> > Ok, "audio" is "media", but not covered by this spec. > > We might use "multimedia" or some similar word. What do you think? Multimedia is fine. Or audio/video. Regards, Hans > > Thanks, > Mauro >
