path: root/Documentation/admin-guide/media/building.rst

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