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