[PATCH 0/4] Improve media admin-guide

[PATCH 0/4] Improve media admin-guide

[Mauro Carvalho Chehab]

Currently, the media admin-guide is just a random set of documents.

Add an introductory chapter and a building guide at the beginning.
While here, add a cardlist for cx231xx boards and update the em28xx
cardlist.

Mauro Carvalho Chehab (4):
  media: admin-guide: add a card list for cx231xx boards
  media: admin-guide: update em28xx cardlist
  media: admin-guide: Add an introduction chapter
  media: admin-guide: add a generic building guide

 Documentation/admin-guide/media/building.rst  | 357 ++++++++++++++++++
 Documentation/admin-guide/media/cardlist.rst  |   1 +
 .../admin-guide/media/cx231xx-cardlist.rst    |  99 +++++
 .../admin-guide/media/em28xx-cardlist.rst     |   4 +
 Documentation/admin-guide/media/index.rst     |   3 +
 Documentation/admin-guide/media/intro.rst     |  25 ++
 6 files changed, 489 insertions(+)
 create mode 100644 Documentation/admin-guide/media/building.rst
 create mode 100644 Documentation/admin-guide/media/cx231xx-cardlist.rst
 create mode 100644 Documentation/admin-guide/media/intro.rst

-- 
2.25.2

[PATCH 1/4] media: admin-guide: add a card list for cx231xx boards

[Mauro Carvalho Chehab]

It is interesting to have a card list also for cx231xx
driver, as it currently supports 27 different boards.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/media/cardlist.rst  |  1 +
 .../admin-guide/media/cx231xx-cardlist.rst    | 99 +++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 Documentation/admin-guide/media/cx231xx-cardlist.rst

diff --git a/Documentation/admin-guide/media/cardlist.rst b/Documentation/admin-guide/media/cardlist.rst
index 5c9c3c97bcb2..527188ee9697 100644
--- a/Documentation/admin-guide/media/cardlist.rst
+++ b/Documentation/admin-guide/media/cardlist.rst
@@ -9,6 +9,7 @@ Cards List
 	au0828-cardlist
 	bttv-cardlist
 	cx18-cardlist
+	cx231xx-cardlist
 	cx23885-cardlist
 	cx88-cardlist
 	em28xx-cardlist
diff --git a/Documentation/admin-guide/media/cx231xx-cardlist.rst b/Documentation/admin-guide/media/cx231xx-cardlist.rst
new file mode 100644
index 000000000000..d374101be047
--- /dev/null
+++ b/Documentation/admin-guide/media/cx231xx-cardlist.rst
@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+cx231xx cards list
+==================
+
+.. tabularcolumns:: |p{1.4cm}|p{10.0cm}|p{6.5cm}|
+
+.. flat-table::
+   :header-rows: 1
+   :widths: 2 12 19
+   :stub-columns: 0
+
+   * - Card number
+     - Card name
+     - USB IDs
+   * - 0
+     - Unknown CX231xx video grabber
+     - 0572:5A3C
+   * - 1
+     - Conexant Hybrid TV - CARRAERA
+     - 0572:58A2
+   * - 2
+     - Conexant Hybrid TV - SHELBY
+     - 0572:58A1
+   * - 3
+     - Conexant Hybrid TV - RDE253S
+     - 0572:58A4
+   * - 4
+     - Conexant Hybrid TV - RDU253S
+     - 0572:58A5
+   * - 5
+     - Conexant VIDEO GRABBER
+     - 0572:58A6, 07ca:c039
+   * - 6
+     - Conexant Hybrid TV - rde 250
+     - 0572:589E
+   * - 7
+     - Conexant Hybrid TV - RDU 250
+     - 0572:58A0
+   * - 8
+     - Hauppauge EXETER
+     - 2040:b120, 2040:b140
+   * - 9
+     - Hauppauge USB Live 2
+     - 2040:c200
+   * - 10
+     - Pixelview PlayTV USB Hybrid
+     - 4000:4001
+   * - 11
+     - Pixelview Xcapture USB
+     - 1D19:6109, 4000:4001
+   * - 12
+     - Kworld UB430 USB Hybrid
+     - 1b80:e424
+   * - 13
+     - Iconbit Analog Stick U100 FM
+     - 1f4d:0237
+   * - 14
+     - Hauppauge WinTV USB2 FM (PAL)
+     - 2040:b110
+   * - 15
+     - Hauppauge WinTV USB2 FM (NTSC)
+     - 2040:b111
+   * - 16
+     - Elgato Video Capture V2
+     - 0fd9:0037
+   * - 17
+     - Geniatech OTG102
+     - 1f4d:0102
+   * - 18
+     - Kworld UB445 USB Hybrid
+     - 1b80:e421
+   * - 19
+     - Hauppauge WinTV 930C-HD (1113xx) / HVR-900H (111xxx) / PCTV QuatroStick 521e
+     - 2040:b130, 2040:b138, 2013:0259
+   * - 20
+     - Hauppauge WinTV 930C-HD (1114xx) / HVR-901H (1114xx) / PCTV QuatroStick 522e
+     - 2040:b131, 2040:b139, 2013:025e
+   * - 21
+     - Hauppauge WinTV-HVR-955Q (111401)
+     - 2040:b123, 2040:b124
+   * - 22
+     - Terratec Grabby
+     - 1f4d:0102
+   * - 23
+     - Evromedia USB Full Hybrid Full HD
+     - 1b80:d3b2
+   * - 24
+     - Astrometa T2hybrid
+     - 15f4:0135
+   * - 25
+     - The Imaging Source DFG/USB2pro
+     - 199e:8002
+   * - 26
+     - Hauppauge WinTV-HVR-935C
+     - 2040:b151
+   * - 27
+     - Hauppauge WinTV-HVR-975
+     - 2040:b150
-- 
2.25.2

[PATCH 2/4] media: admin-guide: update em28xx cardlist

[Mauro Carvalho Chehab]

A new em28xx card was added upstream. Update cards list
accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/media/em28xx-cardlist.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/admin-guide/media/em28xx-cardlist.rst b/Documentation/admin-guide/media/em28xx-cardlist.rst
index cb2e693a56a2..a5f0e6d22a1a 100644
--- a/Documentation/admin-guide/media/em28xx-cardlist.rst
+++ b/Documentation/admin-guide/media/em28xx-cardlist.rst
@@ -430,3 +430,7 @@ EM28xx cards list
      - Magix USB Videowandler-2
      - em2861
      - 1b80:e349
+   * - 104
+     - PCTV DVB-S2 Stick (461e v2)
+     - em28178
+     - 2013:0461, 2013:0259
-- 
2.25.2

[PATCH 3/4] media: admin-guide: Add an introduction chapter

[Mauro Carvalho Chehab]

The media's admin guide is currently just a group of
not-connected docs.

Add an introduction chapter for it to start making sense
to a random reader.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/media/index.rst |  2 ++
 Documentation/admin-guide/media/intro.rst | 25 +++++++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 Documentation/admin-guide/media/intro.rst

diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index 6e5e6bdb6d4b..f79d4f1e05ba 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -34,6 +34,8 @@ Video4Linux (V4L)  driver-specific documentation
 	:maxdepth: 5
 	:numbered:
 
+	intro
+
 	cardlist
 
 	v4l-with-ir
diff --git a/Documentation/admin-guide/media/intro.rst b/Documentation/admin-guide/media/intro.rst
new file mode 100644
index 000000000000..9b6399fd904f
--- /dev/null
+++ b/Documentation/admin-guide/media/intro.rst
@@ -0,0 +1,25 @@
+============
+Introduction
+============
+
+The media subsystem consists on Linux support for several different types
+of devices:
+
+- Audio and video grabbers;
+- PC and Laptop Cameras;
+- Complex cameras found on Embedded hardware;
+- Analog and digital TV;
+- HDMI Customer Electronics Control (CEC);
+- Multi-touch input devices;
+- Remote Controllers;
+- Media encoders and decoders.
+
+Due to the diversity of devices, the subsystem provides several different
+APIs:
+
+- Remote Controller API;
+- HDMI CEC API;
+- Video4Linux API;
+- Media controller API;
+- Video4Linux Request API (experimental);
+- Digital TV API (also known as DVB API).
-- 
2.25.2

[PATCH 4/4] media: admin-guide: add a generic building guide

[Mauro Carvalho Chehab]

Several of the existing documents under the media admin-guide
contain build procedures.

Add an specific chapter describing it. This document was
partially inspired on the modifications I made to the bttv.rst
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/media/building.rst | 357 +++++++++++++++++++
 Documentation/admin-guide/media/index.rst    |   1 +
 2 files changed, 358 insertions(+)
 create mode 100644 Documentation/admin-guide/media/building.rst

diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst
new file mode 100644
index 000000000000..c898e3a981c1
--- /dev/null
+++ b/Documentation/admin-guide/media/building.rst
@@ -0,0 +1,357 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+Building support for a media device
+===================================
+
+The first step is to download the Kernel's source code, either via a
+distribution-specific source file or via the Kernel's main git tree\ [1]_.
+
+Please notice, however, that, if:
+
+- you're a braveheart and want to experiment with new stuff;
+- if you want to report a bug;
+- if you're developing new patches
+
+you should use the main media development tree ``master`` branch:
+
+    https://git.linuxtv.org/media_tree.git/
+
+In this case, you may find some useful information at the
+`LinuxTv wiki pages <https://linuxtv.org/wiki>`_:
+
+    https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers
+
+.. [1] The upstream Linux Kernel development tree is located at
+
+       https://git.kernel.org/pub/scm/li  nux/kernel/git/torvalds/linux.git/
+
+Configuring the Linux Kernel
+============================
+
+You can access a menu of Kernel building options with::
+
+    $ make menuconfig
+
+Then, select all desired options and exit it, saving the configuration.
+
+The changed configuration will be at the ``.config`` file. It would
+look like::
+
+    ...
+    # CONFIG_RC_CORE is not set
+    # CONFIG_CEC_CORE is not set
+    CONFIG_MEDIA_SUPPORT=m
+    CONFIG_MEDIA_SUPPORT_FILTER=y
+    ...
+
+The media subsystem is controlled by those menu configuration options::
+
+    Device Drivers --->
+	<M> Remote Controller support  --->
+	[ ] HDMI CEC RC integration
+	[ ] Enable CEC error injection support
+	[*] HDMI CEC drivers  --->
+	<*> Multimedia support  --->
+
+The ``Remote Controller support`` option enables the core support for
+remote controllers\ [2]_.
+
+The ``HDMI CEC RC integration`` option enables integration of HDMI CEC
+with Linux, allowing to receive data via HDMI CEC as if it were produced
+by a remote controller directly connected to the machine.
+
+The ``HDMI CEC drivers`` option allow selecting platform and USB drivers
+that receives and/or transmits CEC codes via HDMI interfaces\ [3]_.
+
+The last option (``Multimedia support``) enables support for cameras,
+audio/video grabbers and TV.
+
+The media subsystem support can either be built together with the main
+Kernel or as a module. For most use cases, it is preferred to have it
+built as modules.
+
+.. note::
+
+   Instead of using a menu, the Kernel provides a script with allows
+   enabling configuration options directly. To enable media support
+   and remote controller support using Kernel modules, you could use::
+
+	$ scripts/config -m RC_CORE
+	$ scripts/config -m MEDIA_SUPPORT
+
+.. [2] ``Remote Controller support`` should also be enabled if you
+       want to use some TV card drivers that may depend on the remote
+       controller core support.
+
+.. [3] Please notice that the DRM subsystem also have drivers for GPUs
+       that use the media HDMI CEC support.
+
+       Those GPU-specific drivers are selected via the ``Graphics support``
+       menu, under ``Device Drivers``.
+
+       When a GPU driver supports supports HDMI CEC, it will automatically
+       enable the CEC core support at the media subsystem.
+
+Media dependencies
+------------------
+
+It should be noticed that enabling the above from a clean config is
+usually not enough. The media subsystem depends on several other Linux
+core support in order to work.
+
+For example, most media devices use a serial communication bus in
+order to talk with some peripherals. Such bus is called I²C
+(Inter-Integrated Circuit). In order to be able to build support
+for such hardware, the I²C bus support should be enabled, either via
+menu or with::
+
+    ./scripts/config -m I2C
+
+Another example: the remote controller core requires support for
+input devices, with can be enabled with::
+
+    ./scripts/config -m INPUT
+
+Other core functionality may also be needed (like PCI and/or USB support),
+depending on the specific driver(s) you would like to enable.
+
+Enabling Remote Controller Support
+----------------------------------
+
+The remote controller menu allows selecting drivers for specific devices.
+It's menu looks like this::
+
+         --- Remote Controller support
+         <M>   Compile Remote Controller keymap modules
+         [*]   LIRC user interface
+         [*]     Support for eBPF programs attached to lirc devices
+         [*]   Remote controller decoders  --->
+         [*]   Remote Controller devices  --->
+
+The ``Compile Remote Controller keymap modules`` option creates key maps for
+several popular remote controllers.
+
+The ``LIRC user interface`` option adds enhanced functionality when using the
+``lirc`` program, by enabling an API that allows userspace to receive raw data
+from remote controllers.
+
+The ``Support for eBPF programs attached to lirc devices`` option allows
+the usage of special programs (called eBPF) that would allow aplications
+to add extra remote controller decoding functionality to the Linux Kernel.
+
+The ``Remote controller decoders`` option allows selecting the
+protocols that will be recognized by the Linux Kernel. Except if you
+want to disable some specific decoder, it is suggested to keep all
+sub-options enabled.
+
+The ``Remote Controller devices`` allows you to select the drivers
+that would be needed to support your device.
+
+The same configuration can also be set via the ``script/config``
+script. So, for instance, in order to support the ITE remote controller
+driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::
+
+	$ scripts/config -e INPUT
+	$ scripts/config -e ACPI
+	$ scripts/config -e MODULES
+	$ scripts/config -m RC_CORE
+	$ scripts/config -e RC_DEVICES
+	$ scripts/config -e RC_DECODERS
+	$ scripts/config -m IR_RC5_DECODER
+	$ scripts/config -m IR_ITE_CIR
+
+Enabling HDMI CEC Support
+-------------------------
+
+The HDMI CEC support is set automatically when a driver requires it. So,
+all you need to do is to enable support either for a graphics card
+that needs it or by one of the existing HDMI drivers.
+
+The HDMI-specific drivers are available at the ``HDMI CEC drivers``
+menu\ [4]_::
+
+	--- HDMI CEC drivers
+	< >   ChromeOS EC CEC driver
+	< >   Amlogic Meson AO CEC driver
+	< >   Amlogic Meson G12A AO CEC driver
+	< >   Generic GPIO-based CEC driver
+	< >   Samsung S5P CEC driver
+	< >   STMicroelectronics STiH4xx HDMI CEC driver
+	< >   STMicroelectronics STM32 HDMI CEC driver
+	< >   Tegra HDMI CEC driver
+	< >   SECO Boards HDMI CEC driver
+	[ ]     SECO Boards IR RC5 support
+	< >   Pulse Eight HDMI CEC
+	< >   RainShadow Tech HDMI CEC
+
+.. [4] The above contents is just an example. The actual options for
+       HDMI devices depends on the system's architecture and may vary
+       on new Kernels.
+
+Enabling Media Support
+----------------------
+
+The Media menu has a lot more options than the remote controller menu.
+Once selected, you should see the following options::
+
+	--- Media support
+	[ ] Filter media drivers
+	[*] Autoselect ancillary drivers
+	    Media device types --->
+	    Media core support --->
+	    Video4Linux options --->
+	    Media controller options --->
+	    Digital TV options --->
+	    HDMI CEC options --->
+	    Media drivers --->
+	    Media ancillary drivers --->
+
+Except if you know exactly what you're doing, or if you want to build
+a driver for a SoC platform, it is strongly recommended to keep the
+``Autoselect ancillary drivers`` option turned on, as it will auto-select
+the needed I²C ancillary drivers.
+
+There are now two ways to select media device drivers, as described
+below.
+
+``Filter media drivers`` menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This menu is meant to easy setup for PC and Laptop hardware. It works
+by letting the user to specify what kind of media drivers are desired,
+with those options::
+
+	[ ] Cameras and video grabbers
+	[ ] Analog TV
+	[ ] Digital TV
+	[ ] AM/FM radio receivers/transmitters
+	[ ] Software defined radio
+	[ ] Platform-specific devices
+	[ ] Test drivers
+
+So, if you want to add support to a camera or video grabber only,
+select just the first option. Multiple options are allowed.
+
+Once the options on this menu are selected, the building system will
+auto-select the needed core drivers in order to support the selected
+functionality.
+
+.. note::
+
+   Most TV cards are hybrid: they support both Analog TV and Digital TV.
+
+   If you have an hybrid card, you may need to enable both ``Analog TV``
+   and ``Digital TV`` at the menu.
+
+When using this option, the defaults for the the media support core
+functionality are usually good enough to provide the basic functionality
+for the driver. Yet, you could manually enable some desired extra (optional)
+functionality using the settings under each of the following
+``Media support`` sub-menus::
+
+	    Media core support --->
+	    Video4Linux options --->
+	    Media controller options --->
+	    Digital TV options --->
+	    HDMI CEC options --->
+
+Once you select the desired filters, the drivers that matches the filtering
+criteria will be available at the ``Media support->Media drivers`` sub-menu.
+
+``Media Core Support`` menu without filtering
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you disable the ``Filter media drivers`` menu, all drivers available
+for your system whose dependencies are met should be shown at the
+``Media drivers`` menu.
+
+Please notice, however, that you should first ensure that the
+``Media Core Support`` menu has all the core functionality your drivers
+would need, as otherwise the corresponding device drivers won't be shown.
+
+Example
+-------
+
+In order to enable modular support for one of the boards listed on
+:doc:`this table <cx231xx-cardlist>`, with modular media core modules, the
+``.config`` file should contain those lines::
+
+    CONFIG_MODULES=y
+    CONFIG_USB=y
+    CONFIG_I2C=y
+    CONFIG_INPUT=y
+    CONFIG_RC_CORE=m
+    CONFIG_MEDIA_SUPPORT=m
+    CONFIG_MEDIA_SUPPORT_FILTER=y
+    CONFIG_MEDIA_ANALOG_TV_SUPPORT=y
+    CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y
+    CONFIG_MEDIA_USB_SUPPORT=y
+    CONFIG_VIDEO_CX231XX=y
+    CONFIG_VIDEO_CX231XX_DVB=y
+
+Building and installing a new Kernel
+====================================
+
+Once the ``.config`` file has everything needed, all it takes to build
+is to run the ``make`` command::
+
+    $ make
+
+And then install the new Kernel and its modules::
+
+    $ sudo make modules_install
+    $ sudo make install
+
+Building just the new media drivers and core
+============================================
+
+Running a new development Kernel from the development tree is usually risky,
+because it may have experimental changes that may have bugs. So, there are
+some ways to build just the new drivers, using alternative trees.
+
+There is the `Linux Kernel backports project
+<https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains
+newer drivers meant to be compiled against stable Kernels.
+
+The LinuxTV developers, with are responsible for maintaining the media
+subsystem also maintains a backport tree, with just the media drivers
+daily updated from the newest kernel. Such tree is available at:
+
+https://git.linuxtv.org/media_build.git/
+
+It should be noticed that, while it should be relatively safe to use the
+``media_build`` tree for testing purposes, there are not warranties that
+it would work (or even build) on a random Kernel. This tree is maintained
+using a "best-efforts" principle, as time permits us to fix issues there.
+
+If you notice anything wrong on it, feel free to submit patches at the
+Linux media subsystem's mailing list: media@vger.kernel.org. Please
+add ``[PATCH media-build]`` at the e-mail's subject if you submit a new
+patch for the media-build.
+
+Before using it, you should run::
+
+    $ ./build
+
+.. note::
+
+    1) you may need to run it twice if the ``media-build`` tree gets
+       updated;
+    2) you may need to do a ``make distclean`` if you had built it
+       in the past for a different Kernel version than the one you're
+       currently using;
+    3) by default, it will use the same config options for media as
+       the ones defined on the Kernel you're running.
+
+In order to select different drivers or different config options,
+use::
+
+    $ make menuconfig
+
+Then, you can build and install the new drivers::
+
+    $ make && sudo make install
+
+This will override the previous media drivers that your Kernel were
+using.
diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index f79d4f1e05ba..ecaf28effa6a 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -35,6 +35,7 @@ Video4Linux (V4L)  driver-specific documentation
 	:numbered:
 
 	intro
+	building
 
 	cardlist
 
-- 
2.25.2

Re: [PATCH 3/4] media: admin-guide: Add an introduction chapter

[Hans Verkuil]

On 16/04/2020 13:36, Mauro Carvalho Chehab wrote:
> The media's admin guide is currently just a group of
> not-connected docs.
> 
> Add an introduction chapter for it to start making sense
> to a random reader.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/admin-guide/media/index.rst |  2 ++
>  Documentation/admin-guide/media/intro.rst | 25 +++++++++++++++++++++++
>  2 files changed, 27 insertions(+)
>  create mode 100644 Documentation/admin-guide/media/intro.rst
> 
> diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
> index 6e5e6bdb6d4b..f79d4f1e05ba 100644
> --- a/Documentation/admin-guide/media/index.rst
> +++ b/Documentation/admin-guide/media/index.rst
> @@ -34,6 +34,8 @@ Video4Linux (V4L)  driver-specific documentation
>  	:maxdepth: 5
>  	:numbered:
>  
> +	intro
> +
>  	cardlist
>  
>  	v4l-with-ir
> diff --git a/Documentation/admin-guide/media/intro.rst b/Documentation/admin-guide/media/intro.rst
> new file mode 100644
> index 000000000000..9b6399fd904f
> --- /dev/null
> +++ b/Documentation/admin-guide/media/intro.rst
> @@ -0,0 +1,25 @@
> +============
> +Introduction
> +============
> +
> +The media subsystem consists on Linux support for several different types
> +of devices:

I'd rephrase this to:

The media subsystem supports several different types of devices:

> +
> +- Audio and video grabbers;

I'd say 'Video and audio grabbers' since video is the main use-case.

> +- PC and Laptop Cameras;

I'd replace 'PC' with 'Webcams'.

> +- Complex cameras found on Embedded hardware;
> +- Analog and digital TV;
> +- HDMI Customer Electronics Control (CEC);

Customer -> Consumer

> +- Multi-touch input devices;
> +- Remote Controllers;
> +- Media encoders and decoders.

Add:

- AM/FM Radio and RDS receivers/transmitters
- Software Defines Radio receivers/transmitters

> +
> +Due to the diversity of devices, the subsystem provides several different
> +APIs:
> +
> +- Remote Controller API;
> +- HDMI CEC API;
> +- Video4Linux API;
> +- Media controller API;
> +- Video4Linux Request API (experimental);

I think this can be dropped since it is part of the Media controller API. It's
not a separate API as such.

> +- Digital TV API (also known as DVB API).
> 

Regards,

	Hans

Re: [PATCH 4/4] media: admin-guide: add a generic building guide

[Hans Verkuil]

On 16/04/2020 13:36, Mauro Carvalho Chehab wrote:
> Several of the existing documents under the media admin-guide
> contain build procedures.
> 
> Add an specific chapter describing it. This document was
> partially inspired on the modifications I made to the bttv.rst
> file.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/admin-guide/media/building.rst | 357 +++++++++++++++++++
>  Documentation/admin-guide/media/index.rst    |   1 +
>  2 files changed, 358 insertions(+)
>  create mode 100644 Documentation/admin-guide/media/building.rst
> 
> diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst
> new file mode 100644
> index 000000000000..c898e3a981c1
> --- /dev/null
> +++ b/Documentation/admin-guide/media/building.rst
> @@ -0,0 +1,357 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===================================
> +Building support for a media device
> +===================================
> +
> +The first step is to download the Kernel's source code, either via a
> +distribution-specific source file or via the Kernel's main git tree\ [1]_.
> +
> +Please notice, however, that, if:

Remove comma after 'that'

> +
> +- you're a braveheart and want to experiment with new stuff;
> +- if you want to report a bug;
> +- if you're developing new patches
> +
> +you should use the main media development tree ``master`` branch:
> +
> +    https://git.linuxtv.org/media_tree.git/
> +
> +In this case, you may find some useful information at the
> +`LinuxTv wiki pages <https://linuxtv.org/wiki>`_:
> +
> +    https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers
> +
> +.. [1] The upstream Linux Kernel development tree is located at
> +
> +       https://git.kernel.org/pub/scm/li  nux/kernel/git/torvalds/linux.git/

Spurious spaces in the middle of 'linux'?!

> +
> +Configuring the Linux Kernel
> +============================
> +
> +You can access a menu of Kernel building options with::
> +
> +    $ make menuconfig
> +
> +Then, select all desired options and exit it, saving the configuration.

Comma after 'Then' is not needed.

> +
> +The changed configuration will be at the ``.config`` file. It would
> +look like::
> +
> +    ...
> +    # CONFIG_RC_CORE is not set
> +    # CONFIG_CEC_CORE is not set
> +    CONFIG_MEDIA_SUPPORT=m
> +    CONFIG_MEDIA_SUPPORT_FILTER=y
> +    ...
> +
> +The media subsystem is controlled by those menu configuration options::

those -> these

> +
> +    Device Drivers --->
> +	<M> Remote Controller support  --->
> +	[ ] HDMI CEC RC integration
> +	[ ] Enable CEC error injection support
> +	[*] HDMI CEC drivers  --->

Looking at this I think it would be better if this would be just one
submenu: "HDMI CEC support". And move the two CEC options above it into
that submenu.

> +	<*> Multimedia support  --->
> +
> +The ``Remote Controller support`` option enables the core support for
> +remote controllers\ [2]_.
> +
> +The ``HDMI CEC RC integration`` option enables integration of HDMI CEC
> +with Linux, allowing to receive data via HDMI CEC as if it were produced
> +by a remote controller directly connected to the machine.
> +
> +The ``HDMI CEC drivers`` option allow selecting platform and USB drivers
> +that receives and/or transmits CEC codes via HDMI interfaces\ [3]_.
> +
> +The last option (``Multimedia support``) enables support for cameras,
> +audio/video grabbers and TV.
> +
> +The media subsystem support can either be built together with the main
> +Kernel or as a module. For most use cases, it is preferred to have it

Kernel -> kernel

It's used like that elsewhere as well, it should just be lower-case 'kernel'.

> +built as modules.
> +
> +.. note::
> +
> +   Instead of using a menu, the Kernel provides a script with allows
> +   enabling configuration options directly. To enable media support
> +   and remote controller support using Kernel modules, you could use::
> +
> +	$ scripts/config -m RC_CORE
> +	$ scripts/config -m MEDIA_SUPPORT
> +
> +.. [2] ``Remote Controller support`` should also be enabled if you
> +       want to use some TV card drivers that may depend on the remote
> +       controller core support.
> +
> +.. [3] Please notice that the DRM subsystem also have drivers for GPUs

have -> has

GPUs -> HDMI interfaces

(CEC isn't part of a GPU, it is tied to HDMI interfaces)

> +       that use the media HDMI CEC support.
> +
> +       Those GPU-specific drivers are selected via the ``Graphics support``
> +       menu, under ``Device Drivers``.
> +
> +       When a GPU driver supports supports HDMI CEC, it will automatically

GPU -> HDMI

> +       enable the CEC core support at the media subsystem.
> +
> +Media dependencies
> +------------------
> +
> +It should be noticed that enabling the above from a clean config is
> +usually not enough. The media subsystem depends on several other Linux
> +core support in order to work.
> +
> +For example, most media devices use a serial communication bus in
> +order to talk with some peripherals. Such bus is called I²C

Such -> Such a

> +(Inter-Integrated Circuit). In order to be able to build support
> +for such hardware, the I²C bus support should be enabled, either via
> +menu or with::
> +
> +    ./scripts/config -m I2C
> +
> +Another example: the remote controller core requires support for
> +input devices, with can be enabled with::
> +
> +    ./scripts/config -m INPUT
> +
> +Other core functionality may also be needed (like PCI and/or USB support),
> +depending on the specific driver(s) you would like to enable.
> +
> +Enabling Remote Controller Support
> +----------------------------------
> +
> +The remote controller menu allows selecting drivers for specific devices.
> +It's menu looks like this::

It's -> Its

> +
> +         --- Remote Controller support
> +         <M>   Compile Remote Controller keymap modules
> +         [*]   LIRC user interface
> +         [*]     Support for eBPF programs attached to lirc devices
> +         [*]   Remote controller decoders  --->
> +         [*]   Remote Controller devices  --->
> +
> +The ``Compile Remote Controller keymap modules`` option creates key maps for
> +several popular remote controllers.
> +
> +The ``LIRC user interface`` option adds enhanced functionality when using the
> +``lirc`` program, by enabling an API that allows userspace to receive raw data
> +from remote controllers.
> +
> +The ``Support for eBPF programs attached to lirc devices`` option allows
> +the usage of special programs (called eBPF) that would allow aplications

usage -> use

aplications -> applications

> +to add extra remote controller decoding functionality to the Linux Kernel.
> +
> +The ``Remote controller decoders`` option allows selecting the
> +protocols that will be recognized by the Linux Kernel. Except if you
> +want to disable some specific decoder, it is suggested to keep all
> +sub-options enabled.
> +
> +The ``Remote Controller devices`` allows you to select the drivers
> +that would be needed to support your device.
> +
> +The same configuration can also be set via the ``script/config``
> +script. So, for instance, in order to support the ITE remote controller
> +driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::
> +
> +	$ scripts/config -e INPUT
> +	$ scripts/config -e ACPI
> +	$ scripts/config -e MODULES
> +	$ scripts/config -m RC_CORE
> +	$ scripts/config -e RC_DEVICES
> +	$ scripts/config -e RC_DECODERS
> +	$ scripts/config -m IR_RC5_DECODER
> +	$ scripts/config -m IR_ITE_CIR
> +
> +Enabling HDMI CEC Support
> +-------------------------
> +
> +The HDMI CEC support is set automatically when a driver requires it. So,
> +all you need to do is to enable support either for a graphics card
> +that needs it or by one of the existing HDMI drivers.
> +
> +The HDMI-specific drivers are available at the ``HDMI CEC drivers``
> +menu\ [4]_::
> +
> +	--- HDMI CEC drivers
> +	< >   ChromeOS EC CEC driver
> +	< >   Amlogic Meson AO CEC driver
> +	< >   Amlogic Meson G12A AO CEC driver
> +	< >   Generic GPIO-based CEC driver
> +	< >   Samsung S5P CEC driver
> +	< >   STMicroelectronics STiH4xx HDMI CEC driver
> +	< >   STMicroelectronics STM32 HDMI CEC driver
> +	< >   Tegra HDMI CEC driver
> +	< >   SECO Boards HDMI CEC driver
> +	[ ]     SECO Boards IR RC5 support
> +	< >   Pulse Eight HDMI CEC
> +	< >   RainShadow Tech HDMI CEC

I wouldn't copy lists of available drivers in this document: it will
quickly become outdated. Documenting high-level configs makes sense,
but listing drivers doesn't IMHO.

> +
> +.. [4] The above contents is just an example. The actual options for
> +       HDMI devices depends on the system's architecture and may vary
> +       on new Kernels.
> +
> +Enabling Media Support
> +----------------------
> +
> +The Media menu has a lot more options than the remote controller menu.
> +Once selected, you should see the following options::
> +
> +	--- Media support
> +	[ ] Filter media drivers
> +	[*] Autoselect ancillary drivers
> +	    Media device types --->
> +	    Media core support --->
> +	    Video4Linux options --->
> +	    Media controller options --->
> +	    Digital TV options --->
> +	    HDMI CEC options --->
> +	    Media drivers --->
> +	    Media ancillary drivers --->
> +
> +Except if you know exactly what you're doing, or if you want to build

Except if -> Unless

> +a driver for a SoC platform, it is strongly recommended to keep the
> +``Autoselect ancillary drivers`` option turned on, as it will auto-select
> +the needed I²C ancillary drivers.
> +
> +There are now two ways to select media device drivers, as described
> +below.
> +
> +``Filter media drivers`` menu
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +This menu is meant to easy setup for PC and Laptop hardware. It works
> +by letting the user to specify what kind of media drivers are desired,
> +with those options::

Drop "with those options", so 'desired,' becomes 'desired::'.

> +
> +	[ ] Cameras and video grabbers
> +	[ ] Analog TV
> +	[ ] Digital TV
> +	[ ] AM/FM radio receivers/transmitters
> +	[ ] Software defined radio
> +	[ ] Platform-specific devices
> +	[ ] Test drivers
> +
> +So, if you want to add support to a camera or video grabber only,
> +select just the first option. Multiple options are allowed.
> +
> +Once the options on this menu are selected, the building system will
> +auto-select the needed core drivers in order to support the selected
> +functionality.
> +
> +.. note::
> +
> +   Most TV cards are hybrid: they support both Analog TV and Digital TV.
> +
> +   If you have an hybrid card, you may need to enable both ``Analog TV``
> +   and ``Digital TV`` at the menu.
> +
> +When using this option, the defaults for the the media support core
> +functionality are usually good enough to provide the basic functionality
> +for the driver. Yet, you could manually enable some desired extra (optional)
> +functionality using the settings under each of the following
> +``Media support`` sub-menus::
> +
> +	    Media core support --->

This option is only available without filtering, but this example is with filtering
on, so this menu item doesn't exist.

> +	    Video4Linux options --->
> +	    Media controller options --->
> +	    Digital TV options --->
> +	    HDMI CEC options --->

This last line is outdated since HDMI CEC was moved out of this menu.

> +
> +Once you select the desired filters, the drivers that matches the filtering
> +criteria will be available at the ``Media support->Media drivers`` sub-menu.
> +
> +``Media Core Support`` menu without filtering
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If you disable the ``Filter media drivers`` menu, all drivers available
> +for your system whose dependencies are met should be shown at the
> +``Media drivers`` menu.
> +
> +Please notice, however, that you should first ensure that the
> +``Media Core Support`` menu has all the core functionality your drivers
> +would need, as otherwise the corresponding device drivers won't be shown.

FYI: if I disable items in this Core support menu I see all sorts of messages
appearing. Also, if Video4Linux core is enabled, then I can't change the
'Media Controller API' menu item. Only if I disable Video4Linux core can I change
that MC API option. That can't be right, can it?

> +
> +Example
> +-------
> +
> +In order to enable modular support for one of the boards listed on
> +:doc:`this table <cx231xx-cardlist>`, with modular media core modules, the
> +``.config`` file should contain those lines::
> +
> +    CONFIG_MODULES=y
> +    CONFIG_USB=y
> +    CONFIG_I2C=y
> +    CONFIG_INPUT=y
> +    CONFIG_RC_CORE=m
> +    CONFIG_MEDIA_SUPPORT=m
> +    CONFIG_MEDIA_SUPPORT_FILTER=y
> +    CONFIG_MEDIA_ANALOG_TV_SUPPORT=y
> +    CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y
> +    CONFIG_MEDIA_USB_SUPPORT=y
> +    CONFIG_VIDEO_CX231XX=y
> +    CONFIG_VIDEO_CX231XX_DVB=y
> +
> +Building and installing a new Kernel
> +====================================
> +
> +Once the ``.config`` file has everything needed, all it takes to build
> +is to run the ``make`` command::
> +
> +    $ make
> +
> +And then install the new Kernel and its modules::
> +
> +    $ sudo make modules_install
> +    $ sudo make install
> +
> +Building just the new media drivers and core
> +============================================
> +
> +Running a new development Kernel from the development tree is usually risky,
> +because it may have experimental changes that may have bugs. So, there are
> +some ways to build just the new drivers, using alternative trees.
> +
> +There is the `Linux Kernel backports project
> +<https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains
> +newer drivers meant to be compiled against stable Kernels.
> +
> +The LinuxTV developers, with are responsible for maintaining the media
> +subsystem also maintains a backport tree, with just the media drivers
> +daily updated from the newest kernel. Such tree is available at:
> +
> +https://git.linuxtv.org/media_build.git/
> +
> +It should be noticed that, while it should be relatively safe to use the
> +``media_build`` tree for testing purposes, there are not warranties that

warranties -> guarantees

> +it would work (or even build) on a random Kernel. This tree is maintained
> +using a "best-efforts" principle, as time permits us to fix issues there.
> +
> +If you notice anything wrong on it, feel free to submit patches at the
> +Linux media subsystem's mailing list: media@vger.kernel.org. Please
> +add ``[PATCH media-build]`` at the e-mail's subject if you submit a new
> +patch for the media-build.
> +
> +Before using it, you should run::
> +
> +    $ ./build
> +
> +.. note::
> +
> +    1) you may need to run it twice if the ``media-build`` tree gets
> +       updated;
> +    2) you may need to do a ``make distclean`` if you had built it
> +       in the past for a different Kernel version than the one you're
> +       currently using;
> +    3) by default, it will use the same config options for media as
> +       the ones defined on the Kernel you're running.
> +
> +In order to select different drivers or different config options,
> +use::
> +
> +    $ make menuconfig
> +
> +Then, you can build and install the new drivers::
> +
> +    $ make && sudo make install
> +
> +This will override the previous media drivers that your Kernel were
> +using.
> diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
> index f79d4f1e05ba..ecaf28effa6a 100644
> --- a/Documentation/admin-guide/media/index.rst
> +++ b/Documentation/admin-guide/media/index.rst
> @@ -35,6 +35,7 @@ Video4Linux (V4L)  driver-specific documentation
>  	:numbered:
>  
>  	intro
> +	building
>  
>  	cardlist
>  
> 

Regards,

	Hans