building.rst (12199B)
1.. SPDX-License-Identifier: GPL-2.0 2 3=================================== 4Building support for a media device 5=================================== 6 7The first step is to download the Kernel's source code, either via a 8distribution-specific source file or via the Kernel's main git tree\ [1]_. 9 10Please 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 16you should use the main media development tree ``master`` branch: 17 18 https://git.linuxtv.org/media_tree.git/ 19 20In 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 29Configuring the Linux Kernel 30============================ 31 32You can access a menu of Kernel building options with:: 33 34 $ make menuconfig 35 36Then, select all desired options and exit it, saving the configuration. 37 38The changed configuration will be at the ``.config`` file. It would 39look 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 48The 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 57The ``Remote Controller support`` option enables the core support for 58remote controllers\ [2]_. 59 60The ``HDMI CEC RC integration`` option enables integration of HDMI CEC 61with Linux, allowing to receive data via HDMI CEC as if it were produced 62by a remote controller directly connected to the machine. 63 64The ``HDMI CEC drivers`` option allow selecting platform and USB drivers 65that receives and/or transmits CEC codes via HDMI interfaces\ [3]_. 66 67The last option (``Multimedia support``) enables support for cameras, 68audio/video grabbers and TV. 69 70The media subsystem support can either be built together with the main 71Kernel or as a module. For most use cases, it is preferred to have it 72built 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 96Media dependencies 97------------------ 98 99It should be noticed that enabling the above from a clean config is 100usually not enough. The media subsystem depends on several other Linux 101core support in order to work. 102 103For example, most media devices use a serial communication bus in 104order to talk with some peripherals. Such bus is called I²C 105(Inter-Integrated Circuit). In order to be able to build support 106for such hardware, the I²C bus support should be enabled, either via 107menu or with:: 108 109 ./scripts/config -m I2C 110 111Another example: the remote controller core requires support for 112input devices, with can be enabled with:: 113 114 ./scripts/config -m INPUT 115 116Other core functionality may also be needed (like PCI and/or USB support), 117depending on the specific driver(s) you would like to enable. 118 119Enabling Remote Controller Support 120---------------------------------- 121 122The remote controller menu allows selecting drivers for specific devices. 123It'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 132The ``Compile Remote Controller keymap modules`` option creates key maps for 133several popular remote controllers. 134 135The ``LIRC user interface`` option adds enhanced functionality when using the 136``lirc`` program, by enabling an API that allows userspace to receive raw data 137from remote controllers. 138 139The ``Support for eBPF programs attached to lirc devices`` option allows 140the usage of special programs (called eBPF) that would allow aplications 141to add extra remote controller decoding functionality to the Linux Kernel. 142 143The ``Remote controller decoders`` option allows selecting the 144protocols that will be recognized by the Linux Kernel. Except if you 145want to disable some specific decoder, it is suggested to keep all 146sub-options enabled. 147 148The ``Remote Controller devices`` allows you to select the drivers 149that would be needed to support your device. 150 151The same configuration can also be set via the ``script/config`` 152script. So, for instance, in order to support the ITE remote controller 153driver (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 164Enabling HDMI CEC Support 165------------------------- 166 167The HDMI CEC support is set automatically when a driver requires it. So, 168all you need to do is to enable support either for a graphics card 169that needs it or by one of the existing HDMI drivers. 170 171The HDMI-specific drivers are available at the ``HDMI CEC drivers`` 172menu\ [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 192Enabling Media Support 193---------------------- 194 195The Media menu has a lot more options than the remote controller menu. 196Once 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 210Except if you know exactly what you're doing, or if you want to build 211a driver for a SoC platform, it is strongly recommended to keep the 212``Autoselect ancillary drivers`` option turned on, as it will auto-select 213the needed I²C ancillary drivers. 214 215There are now two ways to select media device drivers, as described 216below. 217 218``Filter media drivers`` menu 219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 220 221This menu is meant to easy setup for PC and Laptop hardware. It works 222by letting the user to specify what kind of media drivers are desired, 223with 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 233So, if you want to add support to a camera or video grabber only, 234select just the first option. Multiple options are allowed. 235 236Once the options on this menu are selected, the building system will 237auto-select the needed core drivers in order to support the selected 238functionality. 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 247When using this option, the defaults for the media support core 248functionality are usually good enough to provide the basic functionality 249for the driver. Yet, you could manually enable some desired extra (optional) 250functionality 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 259Once you select the desired filters, the drivers that matches the filtering 260criteria will be available at the ``Media support->Media drivers`` sub-menu. 261 262``Media Core Support`` menu without filtering 263^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 264 265If you disable the ``Filter media drivers`` menu, all drivers available 266for your system whose dependencies are met should be shown at the 267``Media drivers`` menu. 268 269Please notice, however, that you should first ensure that the 270``Media Core Support`` menu has all the core functionality your drivers 271would need, as otherwise the corresponding device drivers won't be shown. 272 273Example 274------- 275 276In 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 293Building and installing a new Kernel 294==================================== 295 296Once the ``.config`` file has everything needed, all it takes to build 297is to run the ``make`` command:: 298 299 $ make 300 301And then install the new Kernel and its modules:: 302 303 $ sudo make modules_install 304 $ sudo make install 305 306Building just the new media drivers and core 307============================================ 308 309Running a new development Kernel from the development tree is usually risky, 310because it may have experimental changes that may have bugs. So, there are 311some ways to build just the new drivers, using alternative trees. 312 313There is the `Linux Kernel backports project 314<https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains 315newer drivers meant to be compiled against stable Kernels. 316 317The LinuxTV developers, with are responsible for maintaining the media 318subsystem also maintains a backport tree, with just the media drivers 319daily updated from the newest kernel. Such tree is available at: 320 321https://git.linuxtv.org/media_build.git/ 322 323It 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 325it would work (or even build) on a random Kernel. This tree is maintained 326using a "best-efforts" principle, as time permits us to fix issues there. 327 328If you notice anything wrong on it, feel free to submit patches at the 329Linux media subsystem's mailing list: media@vger.kernel.org. Please 330add ``[PATCH media-build]`` at the e-mail's subject if you submit a new 331patch for the media-build. 332 333Before 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 347In order to select different drivers or different config options, 348use:: 349 350 $ make menuconfig 351 352Then, you can build and install the new drivers:: 353 354 $ make && sudo make install 355 356This will override the previous media drivers that your Kernel were 357using.