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 applications
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.
358