요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
RC·CEC·media driver 선택
building.rst:119-292Remote controller, HDMI CEC, filtered/unfiltered media driver 설정을 비교합니다.
Build와 설치
building.rst:293-357전체 kernel과 `media_build` driver tree를 빌드하고 설치하는 절차를 설명합니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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.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 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 applications
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 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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Media 장치 지원용 source 준비
1-28Media 장치를 지원하도록 kernel을 빌드하는 첫 단계는 distribution이 제공하는 source package 또는 kernel main git tree에서 Linux kernel source를 받는 것입니다.
새 기능을 시험하거나 bug를 보고하거나 새 patch를 개발하려면 main media development tree의 `master` branch를 사용해야 합니다.
- Linux media development tree
https://git.linuxtv.org/media.git/ - LinuxTV wiki
https://linuxtv.org/wiki - V4L-DVB driver build guide
https://linuxtv.org/wiki/index.php/How_to_Obtain,_Build_and_Install_V4L-DVB_Device_Drivers
원문 각주에 적힌 upstream Linux kernel development tree 경로는 `https://git.kernel.org/pub/scm/li nux/kernel/git/torvalds/linux.git/`입니다. 경로 가운데의 두 공백도 원문 표기를 그대로 보존했습니다.
Linux kernel 설정
29-95Kernel build option menu는 다음 명령으로 엽니다.
$ make menuconfig
필요한 option을 모두 선택한 다음 설정을 저장하고 종료합니다. 변경 결과는 `.config`에 기록되며, media support를 module로 선택한 예는 다음과 같습니다.
...
# CONFIG_RC_CORE is not set
# CONFIG_CEC_CORE is not set
CONFIG_MEDIA_SUPPORT=m
CONFIG_MEDIA_SUPPORT_FILTER=y
...
Media subsystem의 상위 menu option은 다음 위치에 있습니다.
Device Drivers --->
<M> Remote Controller support --->
[ ] HDMI CEC RC integration
[ ] Enable CEC error injection support
[*] HDMI CEC drivers --->
<*> Multimedia support --->
Device Drivers menu에서 remote control, CEC, multimedia core로 들어가는 상위 설정 구조입니다.
| 설정 option | 역할 |
|---|---|
| `Remote Controller support` | Remote controller core를 활성화합니다. 일부 TV card driver도 이 core에 의존할 수 있습니다. |
| `HDMI CEC RC integration` | HDMI CEC로 받은 data를 machine에 직접 연결한 remote controller의 입력처럼 Linux에 전달합니다. |
| `HDMI CEC drivers` | HDMI interface에서 CEC code를 송수신하는 platform 및 USB driver를 선택합니다. |
| `Multimedia support` | Camera, audio/video grabber, TV 지원을 활성화합니다. |
Media subsystem은 kernel 본체에 built-in으로 넣거나 module로 빌드할 수 있습니다. 대부분의 사용 사례에서는 module 구성이 권장됩니다.
Menu 대신 `scripts/config`로 option을 직접 바꿀 수도 있습니다. Media support와 remote controller support를 module로 설정하는 명령은 다음과 같습니다.
$ scripts/config -m RC_CORE
$ scripts/config -m MEDIA_SUPPORT
GPU의 HDMI CEC driver는 `Device Drivers` 아래 `Graphics support` menu에서 선택합니다. GPU driver가 HDMI CEC를 지원하면 media subsystem의 CEC core support도 자동으로 활성화됩니다.
Media subsystem dependency
96-118깨끗한 config에서 앞의 상위 option만 켜는 것으로는 보통 충분하지 않습니다. Media subsystem은 동작에 필요한 여러 Linux core 기능에 의존합니다.
대부분의 media device는 주변 장치와 통신할 때 I²C(Inter-Integrated Circuit) serial bus를 사용합니다. 해당 hardware를 빌드하려면 menu 또는 다음 명령으로 I²C support를 켭니다.
./scripts/config -m I2C
Remote controller core에는 input device support가 필요합니다.
./scripts/config -m INPUT
선택한 driver에 따라 PCI 또는 USB support 같은 다른 core 기능도 필요할 수 있습니다.
Remote Controller support 활성화
119-163Remote controller menu에서는 장치별 driver와 decoder를 선택합니다.
--- 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 --->
| Option | 설명 |
|---|---|
| `Compile Remote Controller keymap modules` | 여러 대중적인 remote controller용 key map을 만듭니다. |
| `LIRC user interface` | `lirc` program이 raw remote-control data를 받을 수 있는 확장 API를 활성화합니다. |
| `Support for eBPF programs attached to lirc devices` | Application이 eBPF program으로 Linux kernel에 추가 remote-control decoding 기능을 제공할 수 있게 합니다. |
| `Remote controller decoders` | Linux kernel이 인식할 protocol을 선택합니다. 특정 decoder를 끌 목적이 아니라면 모든 하위 option을 유지하는 것이 좋습니다. |
| `Remote Controller devices` | 사용할 장치에 필요한 driver를 선택합니다. |
Intel NUC와 일부 ASUS x86 desktop에 있는 ITE remote controller driver를 지원하도록 `scripts/config`를 설정하는 예는 다음과 같습니다.
$ 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
HDMI CEC support 활성화
164-191Driver가 HDMI CEC를 요구하면 CEC support는 자동으로 설정됩니다. 따라서 이를 필요로 하는 graphics card 또는 기존 HDMI driver를 활성화하면 됩니다.
HDMI 전용 driver는 `HDMI CEC drivers` menu에서 선택합니다.
--- 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
위 목록은 예시입니다. 실제 HDMI 장치 option은 system architecture에 따라 달라지고 새 kernel에서 변경될 수 있습니다.
Media support와 driver filter
192-261Media menu를 선택하면 다음과 같은 option이 표시됩니다.
--- 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 --->
Media support에서 filter와 자동 선택을 설정한 뒤 기능별 core·driver menu로 이동합니다.
무엇을 하는지 정확히 알고 있거나 SoC platform driver를 빌드하는 경우가 아니라면 `Autoselect ancillary drivers`를 켜 두는 것이 강하게 권장됩니다. 이 option은 필요한 I²C ancillary driver를 자동 선택합니다.
`Filter media drivers`는 PC와 laptop hardware 설정을 단순화합니다. 필요한 media 기능 종류를 다음 option으로 지정합니다.
[ ] Cameras and video grabbers
[ ] Analog TV
[ ] Digital TV
[ ] AM/FM radio receivers/transmitters
[ ] Software defined radio
[ ] Platform-specific devices
[ ] Test drivers
Camera나 video grabber만 지원하려면 첫 option만 선택하면 됩니다. 여러 option을 함께 고를 수도 있고, build system이 선택한 기능에 필요한 core driver를 자동 선택합니다.
대부분의 TV card는 analog TV와 digital TV를 모두 지원하는 hybrid 장치입니다. Hybrid card라면 menu에서 `Analog TV`와 `Digital TV`를 함께 활성화해야 할 수 있습니다.
Filter를 사용할 때 media core의 기본값은 대개 기본 동작에 충분하지만, 다음 `Media support` 하위 menu에서 선택 기능을 추가로 켤 수 있습니다.
Media core support --->
Video4Linux options --->
Media controller options --->
Digital TV options --->
HDMI CEC options --->
Driver filter의 기본 선택에 더해 필요한 core 기능을 수동으로 보강하는 경로입니다.
Filter를 고르면 조건에 맞는 driver가 `Media support->Media drivers` 하위 menu에 나타납니다.
Filter 없이 core와 driver 선택
262-292`Filter media drivers`를 끄면 dependency가 충족된 system용 driver가 모두 `Media drivers` menu에 표시됩니다.
다만 먼저 `Media Core Support` menu에서 해당 driver가 요구하는 core 기능을 모두 켜야 합니다. 빠진 기능이 있으면 대응하는 device driver가 목록에 나타나지 않습니다.
`cx231xx-cardlist`에 나열된 board 하나와 media core를 module로 지원하려면 `.config`에 다음 항목이 필요합니다.
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
새 kernel 빌드와 설치
293-305`.config`에 필요한 항목이 모두 들어가면 `make`로 kernel을 빌드합니다.
$ make
그다음 새 kernel module과 kernel을 설치합니다.
$ sudo make modules_install
$ sudo make install
새 media driver와 core만 빌드
306-357Development tree의 새 kernel은 실험적 변경과 bug를 포함할 수 있어 그대로 실행하기가 위험할 수 있습니다. 대안 tree를 이용하면 새 driver만 빌드할 수 있습니다.
- Linux Kernel backports project
https://backports.wiki.kernel.org/index.php/Main_Page - LinuxTV media_build tree
https://git.linuxtv.org/media_build.git/
LinuxTV developer가 관리하는 `media_build`는 최신 kernel의 media driver를 매일 가져오는 backport tree입니다. Test에는 비교적 안전하지만 임의의 kernel에서 동작하거나 빌드된다는 보장은 없고, 시간 범위 안에서 best-effort 방식으로 유지됩니다.
문제가 있으면 Linux media subsystem mailing list `media@vger.kernel.org`로 patch를 보낼 수 있습니다. media-build patch의 e-mail subject에는 `[PATCH media-build]`를 붙입니다.
처음 사용할 때는 다음 script를 실행합니다.
$ ./build
| 주의 | 내용 |
|---|---|
| 1 | `media-build` tree가 갱신되면 `./build`를 두 번 실행해야 할 수 있습니다. |
| 2 | 과거에 현재와 다른 kernel version용으로 빌드했다면 `make distclean`이 필요할 수 있습니다. |
| 3 | 기본적으로 현재 실행 중인 kernel에 정의된 media config option을 그대로 사용합니다. |
다른 driver나 config option을 선택하려면 다음 menu를 엽니다.
$ make menuconfig
선택을 마치면 새 driver를 빌드하고 설치합니다.
$ make && sudo make install
이 설치는 현재 kernel이 사용하던 기존 media driver를 덮어씁니다.
Kernel과 media 설정
building.rst:1-118Source tree 선택, `menuconfig`, media core dependency를 정리합니다.