* [PATCH 0/4] Improve media admin-guide
@ 2020-04-16 11:36 Mauro Carvalho Chehab
2020-04-16 11:36 ` [PATCH 1/4] media: admin-guide: add a card list for cx231xx boards Mauro Carvalho Chehab
` (3 more replies)
0 siblings, 4 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-04-16 11:36 UTC (permalink / raw)
To: Linux Media Mailing List; +Cc: Mauro Carvalho Chehab, Hans Verkuil
Currently, the media admin-guide is just a random set of documents.
Add an introductory chapter and a building guide at the beginning.
While here, add a cardlist for cx231xx boards and update the em28xx
cardlist.
Mauro Carvalho Chehab (4):
media: admin-guide: add a card list for cx231xx boards
media: admin-guide: update em28xx cardlist
media: admin-guide: Add an introduction chapter
media: admin-guide: add a generic building guide
Documentation/admin-guide/media/building.rst | 357 ++++++++++++++++++
Documentation/admin-guide/media/cardlist.rst | 1 +
.../admin-guide/media/cx231xx-cardlist.rst | 99 +++++
.../admin-guide/media/em28xx-cardlist.rst | 4 +
Documentation/admin-guide/media/index.rst | 3 +
Documentation/admin-guide/media/intro.rst | 25 ++
6 files changed, 489 insertions(+)
create mode 100644 Documentation/admin-guide/media/building.rst
create mode 100644 Documentation/admin-guide/media/cx231xx-cardlist.rst
create mode 100644 Documentation/admin-guide/media/intro.rst
--
2.25.2
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH 1/4] media: admin-guide: add a card list for cx231xx boards 2020-04-16 11:36 [PATCH 0/4] Improve media admin-guide Mauro Carvalho Chehab @ 2020-04-16 11:36 ` Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 2/4] media: admin-guide: update em28xx cardlist Mauro Carvalho Chehab ` (2 subsequent siblings) 3 siblings, 0 replies; 7+ messages in thread From: Mauro Carvalho Chehab @ 2020-04-16 11:36 UTC (permalink / raw) To: Linux Media Mailing List; +Cc: Mauro Carvalho Chehab It is interesting to have a card list also for cx231xx driver, as it currently supports 27 different boards. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/admin-guide/media/cardlist.rst | 1 + .../admin-guide/media/cx231xx-cardlist.rst | 99 +++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 Documentation/admin-guide/media/cx231xx-cardlist.rst diff --git a/Documentation/admin-guide/media/cardlist.rst b/Documentation/admin-guide/media/cardlist.rst index 5c9c3c97bcb2..527188ee9697 100644 --- a/Documentation/admin-guide/media/cardlist.rst +++ b/Documentation/admin-guide/media/cardlist.rst @@ -9,6 +9,7 @@ Cards List au0828-cardlist bttv-cardlist cx18-cardlist + cx231xx-cardlist cx23885-cardlist cx88-cardlist em28xx-cardlist diff --git a/Documentation/admin-guide/media/cx231xx-cardlist.rst b/Documentation/admin-guide/media/cx231xx-cardlist.rst new file mode 100644 index 000000000000..d374101be047 --- /dev/null +++ b/Documentation/admin-guide/media/cx231xx-cardlist.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 + +cx231xx cards list +================== + +.. tabularcolumns:: |p{1.4cm}|p{10.0cm}|p{6.5cm}| + +.. flat-table:: + :header-rows: 1 + :widths: 2 12 19 + :stub-columns: 0 + + * - Card number + - Card name + - USB IDs + * - 0 + - Unknown CX231xx video grabber + - 0572:5A3C + * - 1 + - Conexant Hybrid TV - CARRAERA + - 0572:58A2 + * - 2 + - Conexant Hybrid TV - SHELBY + - 0572:58A1 + * - 3 + - Conexant Hybrid TV - RDE253S + - 0572:58A4 + * - 4 + - Conexant Hybrid TV - RDU253S + - 0572:58A5 + * - 5 + - Conexant VIDEO GRABBER + - 0572:58A6, 07ca:c039 + * - 6 + - Conexant Hybrid TV - rde 250 + - 0572:589E + * - 7 + - Conexant Hybrid TV - RDU 250 + - 0572:58A0 + * - 8 + - Hauppauge EXETER + - 2040:b120, 2040:b140 + * - 9 + - Hauppauge USB Live 2 + - 2040:c200 + * - 10 + - Pixelview PlayTV USB Hybrid + - 4000:4001 + * - 11 + - Pixelview Xcapture USB + - 1D19:6109, 4000:4001 + * - 12 + - Kworld UB430 USB Hybrid + - 1b80:e424 + * - 13 + - Iconbit Analog Stick U100 FM + - 1f4d:0237 + * - 14 + - Hauppauge WinTV USB2 FM (PAL) + - 2040:b110 + * - 15 + - Hauppauge WinTV USB2 FM (NTSC) + - 2040:b111 + * - 16 + - Elgato Video Capture V2 + - 0fd9:0037 + * - 17 + - Geniatech OTG102 + - 1f4d:0102 + * - 18 + - Kworld UB445 USB Hybrid + - 1b80:e421 + * - 19 + - Hauppauge WinTV 930C-HD (1113xx) / HVR-900H (111xxx) / PCTV QuatroStick 521e + - 2040:b130, 2040:b138, 2013:0259 + * - 20 + - Hauppauge WinTV 930C-HD (1114xx) / HVR-901H (1114xx) / PCTV QuatroStick 522e + - 2040:b131, 2040:b139, 2013:025e + * - 21 + - Hauppauge WinTV-HVR-955Q (111401) + - 2040:b123, 2040:b124 + * - 22 + - Terratec Grabby + - 1f4d:0102 + * - 23 + - Evromedia USB Full Hybrid Full HD + - 1b80:d3b2 + * - 24 + - Astrometa T2hybrid + - 15f4:0135 + * - 25 + - The Imaging Source DFG/USB2pro + - 199e:8002 + * - 26 + - Hauppauge WinTV-HVR-935C + - 2040:b151 + * - 27 + - Hauppauge WinTV-HVR-975 + - 2040:b150 -- 2.25.2 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 2/4] media: admin-guide: update em28xx cardlist 2020-04-16 11:36 [PATCH 0/4] Improve media admin-guide Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 1/4] media: admin-guide: add a card list for cx231xx boards Mauro Carvalho Chehab @ 2020-04-16 11:36 ` Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 3/4] media: admin-guide: Add an introduction chapter Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 4/4] media: admin-guide: add a generic building guide Mauro Carvalho Chehab 3 siblings, 0 replies; 7+ messages in thread From: Mauro Carvalho Chehab @ 2020-04-16 11:36 UTC (permalink / raw) To: Linux Media Mailing List; +Cc: Mauro Carvalho Chehab A new em28xx card was added upstream. Update cards list accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/admin-guide/media/em28xx-cardlist.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/admin-guide/media/em28xx-cardlist.rst b/Documentation/admin-guide/media/em28xx-cardlist.rst index cb2e693a56a2..a5f0e6d22a1a 100644 --- a/Documentation/admin-guide/media/em28xx-cardlist.rst +++ b/Documentation/admin-guide/media/em28xx-cardlist.rst @@ -430,3 +430,7 @@ EM28xx cards list - Magix USB Videowandler-2 - em2861 - 1b80:e349 + * - 104 + - PCTV DVB-S2 Stick (461e v2) + - em28178 + - 2013:0461, 2013:0259 -- 2.25.2 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 3/4] media: admin-guide: Add an introduction chapter 2020-04-16 11:36 [PATCH 0/4] Improve media admin-guide Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 1/4] media: admin-guide: add a card list for cx231xx boards Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 2/4] media: admin-guide: update em28xx cardlist Mauro Carvalho Chehab @ 2020-04-16 11:36 ` Mauro Carvalho Chehab 2020-04-17 9:00 ` Hans Verkuil 2020-04-16 11:36 ` [PATCH 4/4] media: admin-guide: add a generic building guide Mauro Carvalho Chehab 3 siblings, 1 reply; 7+ messages in thread From: Mauro Carvalho Chehab @ 2020-04-16 11:36 UTC (permalink / raw) To: Linux Media Mailing List; +Cc: Mauro Carvalho Chehab, Hans Verkuil The media's admin guide is currently just a group of not-connected docs. Add an introduction chapter for it to start making sense to a random reader. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/admin-guide/media/index.rst | 2 ++ Documentation/admin-guide/media/intro.rst | 25 +++++++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 Documentation/admin-guide/media/intro.rst diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst index 6e5e6bdb6d4b..f79d4f1e05ba 100644 --- a/Documentation/admin-guide/media/index.rst +++ b/Documentation/admin-guide/media/index.rst @@ -34,6 +34,8 @@ Video4Linux (V4L) driver-specific documentation :maxdepth: 5 :numbered: + intro + cardlist v4l-with-ir diff --git a/Documentation/admin-guide/media/intro.rst b/Documentation/admin-guide/media/intro.rst new file mode 100644 index 000000000000..9b6399fd904f --- /dev/null +++ b/Documentation/admin-guide/media/intro.rst @@ -0,0 +1,25 @@ +============ +Introduction +============ + +The media subsystem consists on Linux support for several different types +of devices: + +- Audio and video grabbers; +- PC and Laptop Cameras; +- Complex cameras found on Embedded hardware; +- Analog and digital TV; +- HDMI Customer Electronics Control (CEC); +- Multi-touch input devices; +- Remote Controllers; +- Media encoders and decoders. + +Due to the diversity of devices, the subsystem provides several different +APIs: + +- Remote Controller API; +- HDMI CEC API; +- Video4Linux API; +- Media controller API; +- Video4Linux Request API (experimental); +- Digital TV API (also known as DVB API). -- 2.25.2 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH 3/4] media: admin-guide: Add an introduction chapter 2020-04-16 11:36 ` [PATCH 3/4] media: admin-guide: Add an introduction chapter Mauro Carvalho Chehab @ 2020-04-17 9:00 ` Hans Verkuil 0 siblings, 0 replies; 7+ messages in thread From: Hans Verkuil @ 2020-04-17 9:00 UTC (permalink / raw) To: Mauro Carvalho Chehab, Linux Media Mailing List On 16/04/2020 13:36, Mauro Carvalho Chehab wrote: > The media's admin guide is currently just a group of > not-connected docs. > > Add an introduction chapter for it to start making sense > to a random reader. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > --- > Documentation/admin-guide/media/index.rst | 2 ++ > Documentation/admin-guide/media/intro.rst | 25 +++++++++++++++++++++++ > 2 files changed, 27 insertions(+) > create mode 100644 Documentation/admin-guide/media/intro.rst > > diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst > index 6e5e6bdb6d4b..f79d4f1e05ba 100644 > --- a/Documentation/admin-guide/media/index.rst > +++ b/Documentation/admin-guide/media/index.rst > @@ -34,6 +34,8 @@ Video4Linux (V4L) driver-specific documentation > :maxdepth: 5 > :numbered: > > + intro > + > cardlist > > v4l-with-ir > diff --git a/Documentation/admin-guide/media/intro.rst b/Documentation/admin-guide/media/intro.rst > new file mode 100644 > index 000000000000..9b6399fd904f > --- /dev/null > +++ b/Documentation/admin-guide/media/intro.rst > @@ -0,0 +1,25 @@ > +============ > +Introduction > +============ > + > +The media subsystem consists on Linux support for several different types > +of devices: I'd rephrase this to: The media subsystem supports several different types of devices: > + > +- Audio and video grabbers; I'd say 'Video and audio grabbers' since video is the main use-case. > +- PC and Laptop Cameras; I'd replace 'PC' with 'Webcams'. > +- Complex cameras found on Embedded hardware; > +- Analog and digital TV; > +- HDMI Customer Electronics Control (CEC); Customer -> Consumer > +- Multi-touch input devices; > +- Remote Controllers; > +- Media encoders and decoders. Add: - AM/FM Radio and RDS receivers/transmitters - Software Defines Radio receivers/transmitters > + > +Due to the diversity of devices, the subsystem provides several different > +APIs: > + > +- Remote Controller API; > +- HDMI CEC API; > +- Video4Linux API; > +- Media controller API; > +- Video4Linux Request API (experimental); I think this can be dropped since it is part of the Media controller API. It's not a separate API as such. > +- Digital TV API (also known as DVB API). > Regards, Hans ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH 4/4] media: admin-guide: add a generic building guide 2020-04-16 11:36 [PATCH 0/4] Improve media admin-guide Mauro Carvalho Chehab ` (2 preceding siblings ...) 2020-04-16 11:36 ` [PATCH 3/4] media: admin-guide: Add an introduction chapter Mauro Carvalho Chehab @ 2020-04-16 11:36 ` Mauro Carvalho Chehab 2020-04-17 9:21 ` Hans Verkuil 3 siblings, 1 reply; 7+ messages in thread From: Mauro Carvalho Chehab @ 2020-04-16 11:36 UTC (permalink / raw) To: Linux Media Mailing List; +Cc: Mauro Carvalho Chehab, Hans Verkuil Several of the existing documents under the media admin-guide contain build procedures. Add an specific chapter describing it. This document was partially inspired on the modifications I made to the bttv.rst file. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/admin-guide/media/building.rst | 357 +++++++++++++++++++ Documentation/admin-guide/media/index.rst | 1 + 2 files changed, 358 insertions(+) create mode 100644 Documentation/admin-guide/media/building.rst diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst new file mode 100644 index 000000000000..c898e3a981c1 --- /dev/null +++ b/Documentation/admin-guide/media/building.rst @@ -0,0 +1,357 @@ +.. 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. diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst index f79d4f1e05ba..ecaf28effa6a 100644 --- a/Documentation/admin-guide/media/index.rst +++ b/Documentation/admin-guide/media/index.rst @@ -35,6 +35,7 @@ Video4Linux (V4L) driver-specific documentation :numbered: intro + building cardlist -- 2.25.2 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH 4/4] media: admin-guide: add a generic building guide 2020-04-16 11:36 ` [PATCH 4/4] media: admin-guide: add a generic building guide Mauro Carvalho Chehab @ 2020-04-17 9:21 ` Hans Verkuil 0 siblings, 0 replies; 7+ messages in thread From: Hans Verkuil @ 2020-04-17 9:21 UTC (permalink / raw) To: Mauro Carvalho Chehab, Linux Media Mailing List On 16/04/2020 13:36, Mauro Carvalho Chehab wrote: > Several of the existing documents under the media admin-guide > contain build procedures. > > Add an specific chapter describing it. This document was > partially inspired on the modifications I made to the bttv.rst > file. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > --- > Documentation/admin-guide/media/building.rst | 357 +++++++++++++++++++ > Documentation/admin-guide/media/index.rst | 1 + > 2 files changed, 358 insertions(+) > create mode 100644 Documentation/admin-guide/media/building.rst > > diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst > new file mode 100644 > index 000000000000..c898e3a981c1 > --- /dev/null > +++ b/Documentation/admin-guide/media/building.rst > @@ -0,0 +1,357 @@ > +.. 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: Remove comma after 'that' > + > +- 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/ Spurious spaces in the middle of 'linux'?! > + > +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. Comma after 'Then' is not needed. > + > +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:: those -> these > + > + Device Drivers ---> > + <M> Remote Controller support ---> > + [ ] HDMI CEC RC integration > + [ ] Enable CEC error injection support > + [*] HDMI CEC drivers ---> Looking at this I think it would be better if this would be just one submenu: "HDMI CEC support". And move the two CEC options above it into that submenu. > + <*> 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 Kernel -> kernel It's used like that elsewhere as well, it should just be lower-case 'kernel'. > +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 have -> has GPUs -> HDMI interfaces (CEC isn't part of a GPU, it is tied to HDMI interfaces) > + 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 GPU -> HDMI > + 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 Such -> Such a > +(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:: It's -> Its > + > + --- 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 usage -> use aplications -> 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 I wouldn't copy lists of available drivers in this document: it will quickly become outdated. Documenting high-level configs makes sense, but listing drivers doesn't IMHO. > + > +.. [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 Except if -> Unless > +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:: Drop "with those options", so 'desired,' becomes 'desired::'. > + > + [ ] 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 ---> This option is only available without filtering, but this example is with filtering on, so this menu item doesn't exist. > + Video4Linux options ---> > + Media controller options ---> > + Digital TV options ---> > + HDMI CEC options ---> This last line is outdated since HDMI CEC was moved out of this menu. > + > +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. FYI: if I disable items in this Core support menu I see all sorts of messages appearing. Also, if Video4Linux core is enabled, then I can't change the 'Media Controller API' menu item. Only if I disable Video4Linux core can I change that MC API option. That can't be right, can it? > + > +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 warranties -> guarantees > +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. > diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst > index f79d4f1e05ba..ecaf28effa6a 100644 > --- a/Documentation/admin-guide/media/index.rst > +++ b/Documentation/admin-guide/media/index.rst > @@ -35,6 +35,7 @@ Video4Linux (V4L) driver-specific documentation > :numbered: > > intro > + building > > cardlist > > Regards, Hans ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-04-17 9:21 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-04-16 11:36 [PATCH 0/4] Improve media admin-guide Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 1/4] media: admin-guide: add a card list for cx231xx boards Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 2/4] media: admin-guide: update em28xx cardlist Mauro Carvalho Chehab 2020-04-16 11:36 ` [PATCH 3/4] media: admin-guide: Add an introduction chapter Mauro Carvalho Chehab 2020-04-17 9:00 ` Hans Verkuil 2020-04-16 11:36 ` [PATCH 4/4] media: admin-guide: add a generic building guide Mauro Carvalho Chehab 2020-04-17 9:21 ` Hans Verkuil
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.