Documentation/admin-guide/media/building.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================================
   4 Building support for a media device
   5 ===================================
   6
   7 The first step is to download the Kernel's source code, either via a
   8 distribution-specific source file or via the Kernel's main git tree\ [1]_.
   9
  10 Please notice, however, that, if:
  11
  12 - you're a braveheart and want to experiment with new stuff;
  13 - if you want to report a bug;
  14 - if you're developing new patches
  15
  16 you should use the main media development tree ``master`` branch:
  17
  18     https://git.linuxtv.org/media_tree.git/
  19
  20 In this case, you may find some useful information at the
  21 `LinuxTv wiki pages <https://linuxtv.org/wiki>`_:
  22
  23     https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers
  24
  25 .. [1] The upstream Linux Kernel development tree is located at
  26
  27        https://git.kernel.org/pub/scm/li  nux/kernel/git/torvalds/linux.git/
  28
  29 Configuring the Linux Kernel
  30 ============================
  31
  32 You can access a menu of Kernel building options with::
  33
  34     $ make menuconfig
  35
  36 Then, select all desired options and exit it, saving the configuration.
  37
  38 The changed configuration will be at the ``.config`` file. It would
  39 look like::
  40
  41     ...
  42     # CONFIG_RC_CORE is not set
  43     # CONFIG_CEC_CORE is not set
  44     CONFIG_MEDIA_SUPPORT=m
  45     CONFIG_MEDIA_SUPPORT_FILTER=y
  46     ...
  47
  48 The media subsystem is controlled by those menu configuration options::
  49
  50     Device Drivers --->
  51         <M> Remote Controller support  --->
  52         [ ] HDMI CEC RC integration
  53         [ ] Enable CEC error injection support
  54         [*] HDMI CEC drivers  --->
  55         <*> Multimedia support  --->
  56
  57 The ``Remote Controller support`` option enables the core support for
  58 remote controllers\ [2]_.
  59
  60 The ``HDMI CEC RC integration`` option enables integration of HDMI CEC
  61 with Linux, allowing to receive data via HDMI CEC as if it were produced
  62 by a remote controller directly connected to the machine.
  63
  64 The ``HDMI CEC drivers`` option allow selecting platform and USB drivers
  65 that receives and/or transmits CEC codes via HDMI interfaces\ [3]_.
  66
  67 The last option (``Multimedia support``) enables support for cameras,
  68 audio/video grabbers and TV.
  69
  70 The media subsystem support can either be built together with the main
  71 Kernel or as a module. For most use cases, it is preferred to have it
  72 built as modules.
  73
  74 .. note::
  75
  76    Instead of using a menu, the Kernel provides a script with allows
  77    enabling configuration options directly. To enable media support
  78    and remote controller support using Kernel modules, you could use::
  79
  80         $ scripts/config -m RC_CORE
  81         $ scripts/config -m MEDIA_SUPPORT
  82
  83 .. [2] ``Remote Controller support`` should also be enabled if you
  84        want to use some TV card drivers that may depend on the remote
  85        controller core support.
  86
  87 .. [3] Please notice that the DRM subsystem also have drivers for GPUs
  88        that use the media HDMI CEC support.
  89
  90        Those GPU-specific drivers are selected via the ``Graphics support``
  91        menu, under ``Device Drivers``.
  92
  93        When a GPU driver supports HDMI CEC, it will automatically
  94        enable the CEC core support at the media subsystem.
  95
  96 Media dependencies
  97 ------------------
  98
  99 It should be noticed that enabling the above from a clean config is
 100 usually not enough. The media subsystem depends on several other Linux
 101 core support in order to work.
 102
 103 For example, most media devices use a serial communication bus in
 104 order to talk with some peripherals. Such bus is called I²C
 105 (Inter-Integrated Circuit). In order to be able to build support
 106 for such hardware, the I²C bus support should be enabled, either via
 107 menu or with::
 108
 109     ./scripts/config -m I2C
 110
 111 Another example: the remote controller core requires support for
 112 input devices, with can be enabled with::
 113
 114     ./scripts/config -m INPUT
 115
 116 Other core functionality may also be needed (like PCI and/or USB support),
 117 depending on the specific driver(s) you would like to enable.
 118
 119 Enabling Remote Controller Support
 120 ----------------------------------
 121
 122 The remote controller menu allows selecting drivers for specific devices.
 123 It's menu looks like this::
 124
 125          --- Remote Controller support
 126          <M>   Compile Remote Controller keymap modules
 127          [*]   LIRC user interface
 128          [*]     Support for eBPF programs attached to lirc devices
 129          [*]   Remote controller decoders  --->
 130          [*]   Remote Controller devices  --->
 131
 132 The ``Compile Remote Controller keymap modules`` option creates key maps for
 133 several popular remote controllers.
 134
 135 The ``LIRC user interface`` option adds enhanced functionality when using the
 136 ``lirc`` program, by enabling an API that allows userspace to receive raw data
 137 from remote controllers.
 138
 139 The ``Support for eBPF programs attached to lirc devices`` option allows
 140 the usage of special programs (called eBPF) that would allow aplications
 141 to add extra remote controller decoding functionality to the Linux Kernel.
 142
 143 The ``Remote controller decoders`` option allows selecting the
 144 protocols that will be recognized by the Linux Kernel. Except if you
 145 want to disable some specific decoder, it is suggested to keep all
 146 sub-options enabled.
 147
 148 The ``Remote Controller devices`` allows you to select the drivers
 149 that would be needed to support your device.
 150
 151 The same configuration can also be set via the ``script/config``
 152 script. So, for instance, in order to support the ITE remote controller
 153 driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::
 154
 155         $ scripts/config -e INPUT
 156         $ scripts/config -e ACPI
 157         $ scripts/config -e MODULES
 158         $ scripts/config -m RC_CORE
 159         $ scripts/config -e RC_DEVICES
 160         $ scripts/config -e RC_DECODERS
 161         $ scripts/config -m IR_RC5_DECODER
 162         $ scripts/config -m IR_ITE_CIR
 163
 164 Enabling HDMI CEC Support
 165 -------------------------
 166
 167 The HDMI CEC support is set automatically when a driver requires it. So,
 168 all you need to do is to enable support either for a graphics card
 169 that needs it or by one of the existing HDMI drivers.
 170
 171 The HDMI-specific drivers are available at the ``HDMI CEC drivers``
 172 menu\ [4]_::
 173
 174         --- HDMI CEC drivers
 175         < >   ChromeOS EC CEC driver
 176         < >   Amlogic Meson AO CEC driver
 177         < >   Amlogic Meson G12A AO CEC driver
 178         < >   Generic GPIO-based CEC driver
 179         < >   Samsung S5P CEC driver
 180         < >   STMicroelectronics STiH4xx HDMI CEC driver
 181         < >   STMicroelectronics STM32 HDMI CEC driver
 182         < >   Tegra HDMI CEC driver
 183         < >   SECO Boards HDMI CEC driver
 184         [ ]     SECO Boards IR RC5 support
 185         < >   Pulse Eight HDMI CEC
 186         < >   RainShadow Tech HDMI CEC
 187
 188 .. [4] The above contents is just an example. The actual options for
 189        HDMI devices depends on the system's architecture and may vary
 190        on new Kernels.
 191
 192 Enabling Media Support
 193 ----------------------
 194
 195 The Media menu has a lot more options than the remote controller menu.
 196 Once selected, you should see the following options::
 197
 198         --- Media support
 199         [ ] Filter media drivers
 200         [*] Autoselect ancillary drivers
 201             Media device types --->
 202             Media core support --->
 203             Video4Linux options --->
 204             Media controller options --->
 205             Digital TV options --->
 206             HDMI CEC options --->
 207             Media drivers --->
 208             Media ancillary drivers --->
 209
 210 Except if you know exactly what you're doing, or if you want to build
 211 a driver for a SoC platform, it is strongly recommended to keep the
 212 ``Autoselect ancillary drivers`` option turned on, as it will auto-select
 213 the needed I²C ancillary drivers.
 214
 215 There are now two ways to select media device drivers, as described
 216 below.
 217
 218 ``Filter media drivers`` menu
 219 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 220
 221 This menu is meant to easy setup for PC and Laptop hardware. It works
 222 by letting the user to specify what kind of media drivers are desired,
 223 with those options::
 224
 225         [ ] Cameras and video grabbers
 226         [ ] Analog TV
 227         [ ] Digital TV
 228         [ ] AM/FM radio receivers/transmitters
 229         [ ] Software defined radio
 230         [ ] Platform-specific devices
 231         [ ] Test drivers
 232
 233 So, if you want to add support to a camera or video grabber only,
 234 select just the first option. Multiple options are allowed.
 235
 236 Once the options on this menu are selected, the building system will
 237 auto-select the needed core drivers in order to support the selected
 238 functionality.
 239
 240 .. note::
 241
 242    Most TV cards are hybrid: they support both Analog TV and Digital TV.
 243
 244    If you have an hybrid card, you may need to enable both ``Analog TV``
 245    and ``Digital TV`` at the menu.
 246
 247 When using this option, the defaults for the media support core
 248 functionality are usually good enough to provide the basic functionality
 249 for the driver. Yet, you could manually enable some desired extra (optional)
 250 functionality using the settings under each of the following
 251 ``Media support`` sub-menus::
 252
 253             Media core support --->
 254             Video4Linux options --->
 255             Media controller options --->
 256             Digital TV options --->
 257             HDMI CEC options --->
 258
 259 Once you select the desired filters, the drivers that matches the filtering
 260 criteria will be available at the ``Media support->Media drivers`` sub-menu.
 261
 262 ``Media Core Support`` menu without filtering
 263 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 264
 265 If you disable the ``Filter media drivers`` menu, all drivers available
 266 for your system whose dependencies are met should be shown at the
 267 ``Media drivers`` menu.
 268
 269 Please notice, however, that you should first ensure that the
 270 ``Media Core Support`` menu has all the core functionality your drivers
 271 would need, as otherwise the corresponding device drivers won't be shown.
 272
 273 Example
 274 -------
 275
 276 In order to enable modular support for one of the boards listed on
 277 :doc:`this table <cx231xx-cardlist>`, with modular media core modules, the
 278 ``.config`` file should contain those lines::
 279
 280     CONFIG_MODULES=y
 281     CONFIG_USB=y
 282     CONFIG_I2C=y
 283     CONFIG_INPUT=y
 284     CONFIG_RC_CORE=m
 285     CONFIG_MEDIA_SUPPORT=m
 286     CONFIG_MEDIA_SUPPORT_FILTER=y
 287     CONFIG_MEDIA_ANALOG_TV_SUPPORT=y
 288     CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y
 289     CONFIG_MEDIA_USB_SUPPORT=y
 290     CONFIG_VIDEO_CX231XX=y
 291     CONFIG_VIDEO_CX231XX_DVB=y
 292
 293 Building and installing a new Kernel
 294 ====================================
 295
 296 Once the ``.config`` file has everything needed, all it takes to build
 297 is to run the ``make`` command::
 298
 299     $ make
 300
 301 And then install the new Kernel and its modules::
 302
 303     $ sudo make modules_install
 304     $ sudo make install
 305
 306 Building just the new media drivers and core
 307 ============================================
 308
 309 Running a new development Kernel from the development tree is usually risky,
 310 because it may have experimental changes that may have bugs. So, there are
 311 some ways to build just the new drivers, using alternative trees.
 312
 313 There is the `Linux Kernel backports project
 314 <https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains
 315 newer drivers meant to be compiled against stable Kernels.
 316
 317 The LinuxTV developers, with are responsible for maintaining the media
 318 subsystem also maintains a backport tree, with just the media drivers
 319 daily updated from the newest kernel. Such tree is available at:
 320
 321 https://git.linuxtv.org/media_build.git/
 322
 323 It should be noticed that, while it should be relatively safe to use the
 324 ``media_build`` tree for testing purposes, there are not warranties that
 325 it would work (or even build) on a random Kernel. This tree is maintained
 326 using a "best-efforts" principle, as time permits us to fix issues there.
 327
 328 If you notice anything wrong on it, feel free to submit patches at the
 329 Linux media subsystem's mailing list: media@vger.kernel.org. Please
 330 add ``[PATCH media-build]`` at the e-mail's subject if you submit a new
 331 patch for the media-build.
 332
 333 Before using it, you should run::
 334
 335     $ ./build
 336
 337 .. note::
 338
 339     1) you may need to run it twice if the ``media-build`` tree gets
 340        updated;
 341     2) you may need to do a ``make distclean`` if you had built it
 342        in the past for a different Kernel version than the one you're
 343        currently using;
 344     3) by default, it will use the same config options for media as
 345        the ones defined on the Kernel you're running.
 346
 347 In order to select different drivers or different config options,
 348 use::
 349
 350     $ make menuconfig
 351
 352 Then, you can build and install the new drivers::
 353
 354     $ make && sudo make install
 355
 356 This will override the previous media drivers that your Kernel were
 357 using.