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@xxxxxxxxxx> > --- > 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@xxxxxxxxxxxxxxx. 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
