Documentation/admin-guide/media/building.rst - linux/kernel/git/gregkh/driver-core - Git at Google

 .. SPDX-License-Identifier: GPL-2.0

 ===================================
 Building support for a media device
 ===================================

 The first step is to download the Kernel's source code, either via a
 distribution-specific source file or via the Kernel's main git tree\ [1]_.

 Please notice, however, that, if:

 - you're a braveheart and want to experiment with new stuff;
 - if you want to report a bug;
 - if you're developing new patches

 you should use the main media development tree ``master`` branch:

     https://git.linuxtv.org/media_tree.git/

 In this case, you may find some useful information at the
 `LinuxTv wiki pages <https://linuxtv.org/wiki>`_:

     https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers

 .. [1] The upstream Linux Kernel development tree is located at

        https://git.kernel.org/pub/scm/li  nux/kernel/git/torvalds/linux.git/

 Configuring the Linux Kernel
 ============================

 You can access a menu of Kernel building options with::

     $ make menuconfig

 Then, select all desired options and exit it, saving the configuration.

 The changed configuration will be at the ``.config`` file. It would
 look like::

     ...
     # CONFIG_RC_CORE is not set
     # CONFIG_CEC_CORE is not set
     CONFIG_MEDIA_SUPPORT=m
     CONFIG_MEDIA_SUPPORT_FILTER=y
     ...

 The media subsystem is controlled by those menu configuration options::

     Device Drivers --->
 	<M> Remote Controller support  --->
 	[ ] HDMI CEC RC integration
 	[ ] Enable CEC error injection support
 	[*] HDMI CEC drivers  --->
 	<*> Multimedia support  --->

 The ``Remote Controller support`` option enables the core support for
 remote controllers\ [2]_.

 The ``HDMI CEC RC integration`` option enables integration of HDMI CEC
 with Linux, allowing to receive data via HDMI CEC as if it were produced
 by a remote controller directly connected to the machine.

 The ``HDMI CEC drivers`` option allow selecting platform and USB drivers
 that receives and/or transmits CEC codes via HDMI interfaces\ [3]_.

 The last option (``Multimedia support``) enables support for cameras,
 audio/video grabbers and TV.

 The media subsystem support can either be built together with the main
 Kernel or as a module. For most use cases, it is preferred to have it
 built as modules.

 .. note::

    Instead of using a menu, the Kernel provides a script with allows
    enabling configuration options directly. To enable media support
    and remote controller support using Kernel modules, you could use::

 	$ scripts/config -m RC_CORE
 	$ scripts/config -m MEDIA_SUPPORT

 .. [2] ``Remote Controller support`` should also be enabled if you
        want to use some TV card drivers that may depend on the remote
        controller core support.

 .. [3] Please notice that the DRM subsystem also have drivers for GPUs
        that use the media HDMI CEC support.

        Those GPU-specific drivers are selected via the ``Graphics support``
        menu, under ``Device Drivers``.

        When a GPU driver supports supports HDMI CEC, it will automatically
        enable the CEC core support at the media subsystem.

 Media dependencies
 ------------------

 It should be noticed that enabling the above from a clean config is
 usually not enough. The media subsystem depends on several other Linux
 core support in order to work.

 For example, most media devices use a serial communication bus in
 order to talk with some peripherals. Such bus is called I²C
 (Inter-Integrated Circuit). In order to be able to build support
 for such hardware, the I²C bus support should be enabled, either via
 menu or with::

     ./scripts/config -m I2C

 Another example: the remote controller core requires support for
 input devices, with can be enabled with::

     ./scripts/config -m INPUT

 Other core functionality may also be needed (like PCI and/or USB support),
 depending on the specific driver(s) you would like to enable.

 Enabling Remote Controller Support
 ----------------------------------

 The remote controller menu allows selecting drivers for specific devices.
 It's menu looks like this::

          --- Remote Controller support
          <M>   Compile Remote Controller keymap modules
          [*]   LIRC user interface
          [*]     Support for eBPF programs attached to lirc devices
          [*]   Remote controller decoders  --->
          [*]   Remote Controller devices  --->

 The ``Compile Remote Controller keymap modules`` option creates key maps for
 several popular remote controllers.

 The ``LIRC user interface`` option adds enhanced functionality when using the
 ``lirc`` program, by enabling an API that allows userspace to receive raw data
 from remote controllers.

 The ``Support for eBPF programs attached to lirc devices`` option allows
 the usage of special programs (called eBPF) that would allow aplications
 to add extra remote controller decoding functionality to the Linux Kernel.

 The ``Remote controller decoders`` option allows selecting the
 protocols that will be recognized by the Linux Kernel. Except if you
 want to disable some specific decoder, it is suggested to keep all
 sub-options enabled.

 The ``Remote Controller devices`` allows you to select the drivers
 that would be needed to support your device.

 The same configuration can also be set via the ``script/config``
 script. So, for instance, in order to support the ITE remote controller
 driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::

 	$ scripts/config -e INPUT
 	$ scripts/config -e ACPI
 	$ scripts/config -e MODULES
 	$ scripts/config -m RC_CORE
 	$ scripts/config -e RC_DEVICES
 	$ scripts/config -e RC_DECODERS
 	$ scripts/config -m IR_RC5_DECODER
 	$ scripts/config -m IR_ITE_CIR

 Enabling HDMI CEC Support
 -------------------------

 The HDMI CEC support is set automatically when a driver requires it. So,
 all you need to do is to enable support either for a graphics card
 that needs it or by one of the existing HDMI drivers.

 The HDMI-specific drivers are available at the ``HDMI CEC drivers``
 menu\ [4]_::

 	--- HDMI CEC drivers
 	< >   ChromeOS EC CEC driver
 	< >   Amlogic Meson AO CEC driver
 	< >   Amlogic Meson G12A AO CEC driver
 	< >   Generic GPIO-based CEC driver
 	< >   Samsung S5P CEC driver
 	< >   STMicroelectronics STiH4xx HDMI CEC driver
 	< >   STMicroelectronics STM32 HDMI CEC driver
 	< >   Tegra HDMI CEC driver
 	< >   SECO Boards HDMI CEC driver
 	[ ]     SECO Boards IR RC5 support
 	< >   Pulse Eight HDMI CEC
 	< >   RainShadow Tech HDMI CEC

 .. [4] The above contents is just an example. The actual options for
        HDMI devices depends on the system's architecture and may vary
        on new Kernels.

 Enabling Media Support
 ----------------------

 The Media menu has a lot more options than the remote controller menu.
 Once selected, you should see the following options::

 	--- Media support
 	[ ] Filter media drivers
 	[*] Autoselect ancillary drivers
 	    Media device types --->
 	    Media core support --->
 	    Video4Linux options --->
 	    Media controller options --->
 	    Digital TV options --->
 	    HDMI CEC options --->
 	    Media drivers --->
 	    Media ancillary drivers --->

 Except if you know exactly what you're doing, or if you want to build
 a driver for a SoC platform, it is strongly recommended to keep the
 ``Autoselect ancillary drivers`` option turned on, as it will auto-select
 the needed I²C ancillary drivers.

 There are now two ways to select media device drivers, as described
 below.

 ``Filter media drivers`` menu
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 This menu is meant to easy setup for PC and Laptop hardware. It works
 by letting the user to specify what kind of media drivers are desired,
 with those options::

 	[ ] Cameras and video grabbers
 	[ ] Analog TV
 	[ ] Digital TV
 	[ ] AM/FM radio receivers/transmitters
 	[ ] Software defined radio
 	[ ] Platform-specific devices
 	[ ] Test drivers

 So, if you want to add support to a camera or video grabber only,
 select just the first option. Multiple options are allowed.

 Once the options on this menu are selected, the building system will
 auto-select the needed core drivers in order to support the selected
 functionality.

 .. note::

    Most TV cards are hybrid: they support both Analog TV and Digital TV.

    If you have an hybrid card, you may need to enable both ``Analog TV``
    and ``Digital TV`` at the menu.

 When using this option, the defaults for the the media support core
 functionality are usually good enough to provide the basic functionality
 for the driver. Yet, you could manually enable some desired extra (optional)
 functionality using the settings under each of the following
 ``Media support`` sub-menus::

 	    Media core support --->
 	    Video4Linux options --->
 	    Media controller options --->
 	    Digital TV options --->
 	    HDMI CEC options --->

 Once you select the desired filters, the drivers that matches the filtering
 criteria will be available at the ``Media support->Media drivers`` sub-menu.

 ``Media Core Support`` menu without filtering
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 If you disable the ``Filter media drivers`` menu, all drivers available
 for your system whose dependencies are met should be shown at the
 ``Media drivers`` menu.

 Please notice, however, that you should first ensure that the
 ``Media Core Support`` menu has all the core functionality your drivers
 would need, as otherwise the corresponding device drivers won't be shown.

 Example
 -------

 In order to enable modular support for one of the boards listed on
 :doc:`this table <cx231xx-cardlist>`, with modular media core modules, the
 ``.config`` file should contain those lines::

     CONFIG_MODULES=y
     CONFIG_USB=y
     CONFIG_I2C=y
     CONFIG_INPUT=y
     CONFIG_RC_CORE=m
     CONFIG_MEDIA_SUPPORT=m
     CONFIG_MEDIA_SUPPORT_FILTER=y
     CONFIG_MEDIA_ANALOG_TV_SUPPORT=y
     CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y
     CONFIG_MEDIA_USB_SUPPORT=y
     CONFIG_VIDEO_CX231XX=y
     CONFIG_VIDEO_CX231XX_DVB=y

 Building and installing a new Kernel
 ====================================

 Once the ``.config`` file has everything needed, all it takes to build
 is to run the ``make`` command::

     $ make

 And then install the new Kernel and its modules::

     $ sudo make modules_install
     $ sudo make install

 Building just the new media drivers and core
 ============================================

 Running a new development Kernel from the development tree is usually risky,
 because it may have experimental changes that may have bugs. So, there are
 some ways to build just the new drivers, using alternative trees.

 There is the `Linux Kernel backports project
 <https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains
 newer drivers meant to be compiled against stable Kernels.

 The LinuxTV developers, with are responsible for maintaining the media
 subsystem also maintains a backport tree, with just the media drivers
 daily updated from the newest kernel. Such tree is available at:

 https://git.linuxtv.org/media_build.git/

 It should be noticed that, while it should be relatively safe to use the
 ``media_build`` tree for testing purposes, there are not warranties that
 it would work (or even build) on a random Kernel. This tree is maintained
 using a "best-efforts" principle, as time permits us to fix issues there.

 If you notice anything wrong on it, feel free to submit patches at the
 Linux media subsystem's mailing list: media@vger.kernel.org. Please
 add ``[PATCH media-build]`` at the e-mail's subject if you submit a new
 patch for the media-build.

 Before using it, you should run::

     $ ./build

 .. note::

     1) you may need to run it twice if the ``media-build`` tree gets
        updated;
     2) you may need to do a ``make distclean`` if you had built it
        in the past for a different Kernel version than the one you're
        currently using;
     3) by default, it will use the same config options for media as
        the ones defined on the Kernel you're running.

 In order to select different drivers or different config options,
 use::

     $ make menuconfig

 Then, you can build and install the new drivers::

     $ make && sudo make install

 This will override the previous media drivers that your Kernel were
 using.
	.. SPDX-License-Identifier: GPL-2.0

	===================================
	Building support for a media device
	===================================

	The first step is to download the Kernel's source code, either via a
	distribution-specific source file or via the Kernel's main git tree\ [1]_.

	Please notice, however, that, if:

	- you're a braveheart and want to experiment with new stuff;
	- if you want to report a bug;
	- if you're developing new patches

	you should use the main media development tree ``master`` branch:

	https://git.linuxtv.org/media_tree.git/

	In this case, you may find some useful information at the
	`LinuxTv wiki pages <https://linuxtv.org/wiki>`_:

	https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers

	.. [1] The upstream Linux Kernel development tree is located at

	https://git.kernel.org/pub/scm/li nux/kernel/git/torvalds/linux.git/

	Configuring the Linux Kernel
	============================

	You can access a menu of Kernel building options with::

	$ make menuconfig

	Then, select all desired options and exit it, saving the configuration.

	The changed configuration will be at the ``.config`` file. It would
	look like::

	...
	# CONFIG_RC_CORE is not set
	# CONFIG_CEC_CORE is not set
	CONFIG_MEDIA_SUPPORT=m
	CONFIG_MEDIA_SUPPORT_FILTER=y
	...

	The media subsystem is controlled by those menu configuration options::

	Device Drivers --->
	<M> Remote Controller support --->
	[ ] HDMI CEC RC integration
	[ ] Enable CEC error injection support
	[*] HDMI CEC drivers --->
	<*> Multimedia support --->

	The ``Remote Controller support`` option enables the core support for
	remote controllers\ [2]_.

	The ``HDMI CEC RC integration`` option enables integration of HDMI CEC
	with Linux, allowing to receive data via HDMI CEC as if it were produced
	by a remote controller directly connected to the machine.

	The ``HDMI CEC drivers`` option allow selecting platform and USB drivers
	that receives and/or transmits CEC codes via HDMI interfaces\ [3]_.

	The last option (``Multimedia support``) enables support for cameras,
	audio/video grabbers and TV.

	The media subsystem support can either be built together with the main
	Kernel or as a module. For most use cases, it is preferred to have it
	built as modules.

	.. note::

	Instead of using a menu, the Kernel provides a script with allows
	enabling configuration options directly. To enable media support
	and remote controller support using Kernel modules, you could use::

	$ scripts/config -m RC_CORE
	$ scripts/config -m MEDIA_SUPPORT

	.. [2] ``Remote Controller support`` should also be enabled if you
	want to use some TV card drivers that may depend on the remote
	controller core support.

	.. [3] Please notice that the DRM subsystem also have drivers for GPUs
	that use the media HDMI CEC support.

	Those GPU-specific drivers are selected via the ``Graphics support``
	menu, under ``Device Drivers``.

	When a GPU driver supports supports HDMI CEC, it will automatically
	enable the CEC core support at the media subsystem.

	Media dependencies
	------------------

	It should be noticed that enabling the above from a clean config is
	usually not enough. The media subsystem depends on several other Linux
	core support in order to work.

	For example, most media devices use a serial communication bus in
	order to talk with some peripherals. Such bus is called I²C
	(Inter-Integrated Circuit). In order to be able to build support
	for such hardware, the I²C bus support should be enabled, either via
	menu or with::

	./scripts/config -m I2C

	Another example: the remote controller core requires support for
	input devices, with can be enabled with::

	./scripts/config -m INPUT

	Other core functionality may also be needed (like PCI and/or USB support),
	depending on the specific driver(s) you would like to enable.

	Enabling Remote Controller Support
	----------------------------------

	The remote controller menu allows selecting drivers for specific devices.
	It's menu looks like this::

	--- Remote Controller support
	<M> Compile Remote Controller keymap modules
	[*] LIRC user interface
	[*] Support for eBPF programs attached to lirc devices
	[*] Remote controller decoders --->
	[*] Remote Controller devices --->

	The ``Compile Remote Controller keymap modules`` option creates key maps for
	several popular remote controllers.

	The ``LIRC user interface`` option adds enhanced functionality when using the
	``lirc`` program, by enabling an API that allows userspace to receive raw data
	from remote controllers.

	The ``Support for eBPF programs attached to lirc devices`` option allows
	the usage of special programs (called eBPF) that would allow aplications
	to add extra remote controller decoding functionality to the Linux Kernel.

	The ``Remote controller decoders`` option allows selecting the
	protocols that will be recognized by the Linux Kernel. Except if you
	want to disable some specific decoder, it is suggested to keep all
	sub-options enabled.

	The ``Remote Controller devices`` allows you to select the drivers
	that would be needed to support your device.

	The same configuration can also be set via the ``script/config``
	script. So, for instance, in order to support the ITE remote controller
	driver (found on Intel NUCs and on some ASUS x86 desktops), you could do::

	$ scripts/config -e INPUT
	$ scripts/config -e ACPI
	$ scripts/config -e MODULES
	$ scripts/config -m RC_CORE
	$ scripts/config -e RC_DEVICES
	$ scripts/config -e RC_DECODERS
	$ scripts/config -m IR_RC5_DECODER
	$ scripts/config -m IR_ITE_CIR

	Enabling HDMI CEC Support
	-------------------------

	The HDMI CEC support is set automatically when a driver requires it. So,
	all you need to do is to enable support either for a graphics card
	that needs it or by one of the existing HDMI drivers.

	The HDMI-specific drivers are available at the ``HDMI CEC drivers``
	menu\ [4]_::

	--- HDMI CEC drivers
	< > ChromeOS EC CEC driver
	< > Amlogic Meson AO CEC driver
	< > Amlogic Meson G12A AO CEC driver
	< > Generic GPIO-based CEC driver
	< > Samsung S5P CEC driver
	< > STMicroelectronics STiH4xx HDMI CEC driver
	< > STMicroelectronics STM32 HDMI CEC driver
	< > Tegra HDMI CEC driver
	< > SECO Boards HDMI CEC driver
	[ ] SECO Boards IR RC5 support
	< > Pulse Eight HDMI CEC
	< > RainShadow Tech HDMI CEC

	.. [4] The above contents is just an example. The actual options for
	HDMI devices depends on the system's architecture and may vary
	on new Kernels.

	Enabling Media Support
	----------------------

	The Media menu has a lot more options than the remote controller menu.
	Once selected, you should see the following options::

	--- Media support
	[ ] Filter media drivers
	[*] Autoselect ancillary drivers
	Media device types --->
	Media core support --->
	Video4Linux options --->
	Media controller options --->
	Digital TV options --->
	HDMI CEC options --->
	Media drivers --->
	Media ancillary drivers --->

	Except if you know exactly what you're doing, or if you want to build
	a driver for a SoC platform, it is strongly recommended to keep the
	``Autoselect ancillary drivers`` option turned on, as it will auto-select
	the needed I²C ancillary drivers.

	There are now two ways to select media device drivers, as described
	below.

	``Filter media drivers`` menu
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	This menu is meant to easy setup for PC and Laptop hardware. It works
	by letting the user to specify what kind of media drivers are desired,
	with those options::

	[ ] Cameras and video grabbers
	[ ] Analog TV
	[ ] Digital TV
	[ ] AM/FM radio receivers/transmitters
	[ ] Software defined radio
	[ ] Platform-specific devices
	[ ] Test drivers

	So, if you want to add support to a camera or video grabber only,
	select just the first option. Multiple options are allowed.

	Once the options on this menu are selected, the building system will
	auto-select the needed core drivers in order to support the selected
	functionality.

	.. note::

	Most TV cards are hybrid: they support both Analog TV and Digital TV.

	If you have an hybrid card, you may need to enable both ``Analog TV``
	and ``Digital TV`` at the menu.

	When using this option, the defaults for the the media support core
	functionality are usually good enough to provide the basic functionality
	for the driver. Yet, you could manually enable some desired extra (optional)
	functionality using the settings under each of the following
	``Media support`` sub-menus::

	Media core support --->
	Video4Linux options --->
	Media controller options --->
	Digital TV options --->
	HDMI CEC options --->

	Once you select the desired filters, the drivers that matches the filtering
	criteria will be available at the ``Media support->Media drivers`` sub-menu.

	``Media Core Support`` menu without filtering
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	If you disable the ``Filter media drivers`` menu, all drivers available
	for your system whose dependencies are met should be shown at the
	``Media drivers`` menu.

	Please notice, however, that you should first ensure that the
	``Media Core Support`` menu has all the core functionality your drivers
	would need, as otherwise the corresponding device drivers won't be shown.

	Example
	-------

	In order to enable modular support for one of the boards listed on
	:doc:`this table <cx231xx-cardlist>`, with modular media core modules, the
	``.config`` file should contain those lines::

	CONFIG_MODULES=y
	CONFIG_USB=y
	CONFIG_I2C=y
	CONFIG_INPUT=y
	CONFIG_RC_CORE=m
	CONFIG_MEDIA_SUPPORT=m
	CONFIG_MEDIA_SUPPORT_FILTER=y
	CONFIG_MEDIA_ANALOG_TV_SUPPORT=y
	CONFIG_MEDIA_DIGITAL_TV_SUPPORT=y
	CONFIG_MEDIA_USB_SUPPORT=y
	CONFIG_VIDEO_CX231XX=y
	CONFIG_VIDEO_CX231XX_DVB=y

	Building and installing a new Kernel
	====================================

	Once the ``.config`` file has everything needed, all it takes to build
	is to run the ``make`` command::

	$ make

	And then install the new Kernel and its modules::

	$ sudo make modules_install
	$ sudo make install

	Building just the new media drivers and core
	============================================

	Running a new development Kernel from the development tree is usually risky,
	because it may have experimental changes that may have bugs. So, there are
	some ways to build just the new drivers, using alternative trees.

	There is the `Linux Kernel backports project
	<https://backports.wiki.kernel.org/index.php/Main_Page>`_, with contains
	newer drivers meant to be compiled against stable Kernels.

	The LinuxTV developers, with are responsible for maintaining the media
	subsystem also maintains a backport tree, with just the media drivers
	daily updated from the newest kernel. Such tree is available at:

	https://git.linuxtv.org/media_build.git/

	It should be noticed that, while it should be relatively safe to use the
	``media_build`` tree for testing purposes, there are not warranties that
	it would work (or even build) on a random Kernel. This tree is maintained
	using a "best-efforts" principle, as time permits us to fix issues there.

	If you notice anything wrong on it, feel free to submit patches at the
	Linux media subsystem's mailing list: media@vger.kernel.org. Please
	add ``[PATCH media-build]`` at the e-mail's subject if you submit a new
	patch for the media-build.

	Before using it, you should run::

	$ ./build

	.. note::

	1) you may need to run it twice if the ``media-build`` tree gets
	updated;
	2) you may need to do a ``make distclean`` if you had built it
	in the past for a different Kernel version than the one you're
	currently using;
	3) by default, it will use the same config options for media as
	the ones defined on the Kernel you're running.

	In order to select different drivers or different config options,
	use::

	$ make menuconfig

	Then, you can build and install the new drivers::

	$ make && sudo make install

	This will override the previous media drivers that your Kernel were
	using.