358 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===================================4Building support for a media device5===================================6 7The first step is to download the Kernel's source code, either via a8distribution-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 patches15 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 the21`LinuxTv wiki pages <https://linuxtv.org/wiki>`_:22 23 https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers24 25.. [1] The upstream Linux Kernel development tree is located at26 27 https://git.kernel.org/pub/scm/li nux/kernel/git/torvalds/linux.git/28 29Configuring the Linux Kernel30============================31 32You can access a menu of Kernel building options with::33 34 $ make menuconfig35 36Then, select all desired options and exit it, saving the configuration.37 38The changed configuration will be at the ``.config`` file. It would39look like::40 41 ...42 # CONFIG_RC_CORE is not set43 # CONFIG_CEC_CORE is not set44 CONFIG_MEDIA_SUPPORT=m45 CONFIG_MEDIA_SUPPORT_FILTER=y46 ...47 48The media subsystem is controlled by those menu configuration options::49 50 Device Drivers --->51 <M> Remote Controller support --->52 [ ] HDMI CEC RC integration53 [ ] Enable CEC error injection support54 [*] HDMI CEC drivers --->55 <*> Multimedia support --->56 57The ``Remote Controller support`` option enables the core support for58remote controllers\ [2]_.59 60The ``HDMI CEC RC integration`` option enables integration of HDMI CEC61with Linux, allowing to receive data via HDMI CEC as if it were produced62by a remote controller directly connected to the machine.63 64The ``HDMI CEC drivers`` option allow selecting platform and USB drivers65that 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 main71Kernel or as a module. For most use cases, it is preferred to have it72built as modules.73 74.. note::75 76 Instead of using a menu, the Kernel provides a script with allows77 enabling configuration options directly. To enable media support78 and remote controller support using Kernel modules, you could use::79 80 $ scripts/config -m RC_CORE81 $ scripts/config -m MEDIA_SUPPORT82 83.. [2] ``Remote Controller support`` should also be enabled if you84 want to use some TV card drivers that may depend on the remote85 controller core support.86 87.. [3] Please notice that the DRM subsystem also have drivers for GPUs88 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 automatically94 enable the CEC core support at the media subsystem.95 96Media dependencies97------------------98 99It should be noticed that enabling the above from a clean config is100usually not enough. The media subsystem depends on several other Linux101core support in order to work.102 103For example, most media devices use a serial communication bus in104order to talk with some peripherals. Such bus is called I²C105(Inter-Integrated Circuit). In order to be able to build support106for such hardware, the I²C bus support should be enabled, either via107menu or with::108 109 ./scripts/config -m I2C110 111Another example: the remote controller core requires support for112input devices, with can be enabled with::113 114 ./scripts/config -m INPUT115 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 Support120----------------------------------121 122The remote controller menu allows selecting drivers for specific devices.123It's menu looks like this::124 125 --- Remote Controller support126 <M> Compile Remote Controller keymap modules127 [*] LIRC user interface128 [*] Support for eBPF programs attached to lirc devices129 [*] Remote controller decoders --->130 [*] Remote Controller devices --->131 132The ``Compile Remote Controller keymap modules`` option creates key maps for133several popular remote controllers.134 135The ``LIRC user interface`` option adds enhanced functionality when using the136``lirc`` program, by enabling an API that allows userspace to receive raw data137from remote controllers.138 139The ``Support for eBPF programs attached to lirc devices`` option allows140the usage of special programs (called eBPF) that would allow applications141to add extra remote controller decoding functionality to the Linux Kernel.142 143The ``Remote controller decoders`` option allows selecting the144protocols that will be recognized by the Linux Kernel. Except if you145want to disable some specific decoder, it is suggested to keep all146sub-options enabled.147 148The ``Remote Controller devices`` allows you to select the drivers149that 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 controller153driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::154 155 $ scripts/config -e INPUT156 $ scripts/config -e ACPI157 $ scripts/config -e MODULES158 $ scripts/config -m RC_CORE159 $ scripts/config -e RC_DEVICES160 $ scripts/config -e RC_DECODERS161 $ scripts/config -m IR_RC5_DECODER162 $ scripts/config -m IR_ITE_CIR163 164Enabling HDMI CEC Support165-------------------------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 card169that 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 drivers175 < > ChromeOS EC CEC driver176 < > Amlogic Meson AO CEC driver177 < > Amlogic Meson G12A AO CEC driver178 < > Generic GPIO-based CEC driver179 < > Samsung S5P CEC driver180 < > STMicroelectronics STiH4xx HDMI CEC driver181 < > STMicroelectronics STM32 HDMI CEC driver182 < > Tegra HDMI CEC driver183 < > SECO Boards HDMI CEC driver184 [ ] SECO Boards IR RC5 support185 < > Pulse Eight HDMI CEC186 < > RainShadow Tech HDMI CEC187 188.. [4] The above contents is just an example. The actual options for189 HDMI devices depends on the system's architecture and may vary190 on new Kernels.191 192Enabling Media Support193----------------------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 support199 [ ] Filter media drivers200 [*] Autoselect ancillary drivers201 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 build211a driver for a SoC platform, it is strongly recommended to keep the212``Autoselect ancillary drivers`` option turned on, as it will auto-select213the needed I²C ancillary drivers.214 215There are now two ways to select media device drivers, as described216below.217 218``Filter media drivers`` menu219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^220 221This menu is meant to easy setup for PC and Laptop hardware. It works222by letting the user to specify what kind of media drivers are desired,223with those options::224 225 [ ] Cameras and video grabbers226 [ ] Analog TV227 [ ] Digital TV228 [ ] AM/FM radio receivers/transmitters229 [ ] Software defined radio230 [ ] Platform-specific devices231 [ ] Test drivers232 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 will237auto-select the needed core drivers in order to support the selected238functionality.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 core248functionality are usually good enough to provide the basic functionality249for the driver. Yet, you could manually enable some desired extra (optional)250functionality using the settings under each of the following251``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 filtering260criteria will be available at the ``Media support->Media drivers`` sub-menu.261 262``Media Core Support`` menu without filtering263^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^264 265If you disable the ``Filter media drivers`` menu, all drivers available266for your system whose dependencies are met should be shown at the267``Media drivers`` menu.268 269Please notice, however, that you should first ensure that the270``Media Core Support`` menu has all the core functionality your drivers271would need, as otherwise the corresponding device drivers won't be shown.272 273Example274-------275 276In order to enable modular support for one of the boards listed on277:doc:`this table <cx231xx-cardlist>`, with modular media core modules, the278``.config`` file should contain those lines::279 280 CONFIG_MODULES=y281 CONFIG_USB=y282 CONFIG_I2C=y283 CONFIG_INPUT=y284 CONFIG_RC_CORE=m285 CONFIG_MEDIA_SUPPORT=m286 CONFIG_MEDIA_SUPPORT_FILTER=y287 CONFIG_MEDIA_ANALOG_TV_SUPPORT=y288 CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y289 CONFIG_MEDIA_USB_SUPPORT=y290 CONFIG_VIDEO_CX231XX=y291 CONFIG_VIDEO_CX231XX_DVB=y292 293Building and installing a new Kernel294====================================295 296Once the ``.config`` file has everything needed, all it takes to build297is to run the ``make`` command::298 299 $ make300 301And then install the new Kernel and its modules::302 303 $ sudo make modules_install304 $ sudo make install305 306Building just the new media drivers and core307============================================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 are311some ways to build just the new drivers, using alternative trees.312 313There is the `Linux Kernel backports project314<https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains315newer drivers meant to be compiled against stable Kernels.316 317The LinuxTV developers, with are responsible for maintaining the media318subsystem also maintains a backport tree, with just the media drivers319daily 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 the324``media_build`` tree for testing purposes, there are not warranties that325it would work (or even build) on a random Kernel. This tree is maintained326using 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 the329Linux media subsystem's mailing list: media@vger.kernel.org. Please330add ``[PATCH media-build]`` at the e-mail's subject if you submit a new331patch for the media-build.332 333Before using it, you should run::334 335 $ ./build336 337.. note::338 339 1) you may need to run it twice if the ``media-build`` tree gets340 updated;341 2) you may need to do a ``make distclean`` if you had built it342 in the past for a different Kernel version than the one you're343 currently using;344 3) by default, it will use the same config options for media as345 the ones defined on the Kernel you're running.346 347In order to select different drivers or different config options,348use::349 350 $ make menuconfig351 352Then, you can build and install the new drivers::353 354 $ make && sudo make install355 356This will override the previous media drivers that your Kernel were357using.358