| 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.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: [email protected]. 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. |