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 applications 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.