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