.. 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 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 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.