diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/open.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/open.rst | 120 |
1 files changed, 98 insertions, 22 deletions
diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 38046ef20141..4e8fd216a1b0 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -1,11 +1,4 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/userspace-api/media/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later .. _open: @@ -13,22 +6,105 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: -Device Naming -============= +Controlling a hardware peripheral via V4L2 +========================================== + +Hardware that is supported using the V4L2 uAPI often consists of multiple +devices or peripherals, each of which have their own driver. + +The bridge driver exposes one or more V4L2 device nodes +(see :ref:`v4l2_device_naming`). + +There are other drivers providing support for other components of +the hardware, which may also expose device nodes, called V4L2 sub-devices. + +When such V4L2 sub-devices are exposed, they allow controlling those +other hardware components - usually connected via a serial bus (like +I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices +can be controlled indirectly via the bridge driver or explicitly via +the :ref:`Media Controller <media_controller>` and via the +:ref:`V4L2 sub-devices <subdev>`. + +The devices that require the use of the +:ref:`Media Controller <media_controller>` are called **MC-centric** +devices. The devices that are fully controlled via V4L2 device nodes +are called **video-node-centric**. + +Userspace can check if a V4L2 hardware peripheral is MC-centric by +calling :ref:`VIDIOC_QUERYCAP` and checking the +:ref:`device_caps field <device-capabilities>`. + +If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, +then it is MC-centric, otherwise, it is video-node-centric. + +It is required for MC-centric drivers to identify the V4L2 +sub-devices and to configure the pipelines via the +:ref:`media controller API <media_controller>` before using the peripheral. +Also, the sub-devices' configuration shall be controlled via the +:ref:`sub-device API <subdev>`. + +.. note:: + + A video-node-centric may still provide media-controller and + sub-device interfaces as well. + + However, in that case the media-controller and the sub-device + interfaces are read-only and just provide information about the + device. The actual configuration is done via the video nodes. + +.. _v4l2_device_naming: + +V4L2 Device Node Naming +======================= V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. -The driver modules plug into the "videodev" kernel module. It provides +The driver modules plug into the ``videodev`` kernel module. It provides helper functions and a common application interface specified in this document. Each driver thus loaded registers one or more device nodes with major -number 81 and a minor number between 0 and 255. Minor numbers are -allocated dynamically unless the kernel is compiled with the kernel -option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers -are allocated in ranges depending on the device node type (video, radio, -etc.). +number 81. Minor numbers are allocated dynamically unless the kernel +is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. +In that case minor numbers are allocated in ranges depending on the +device node type. + +The device nodes supported by the Video4Linux subsystem are: + +======================== ==================================================== +Default device node name Usage +======================== ==================================================== +``/dev/videoX`` Video and metadata for capture/output devices +``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext) +``/dev/radioX`` Radio tuners and modulators +``/dev/swradioX`` Software Defined Radio tuners and modulators +``/dev/v4l-touchX`` Touch sensors +``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other + components of the hardware peripheral)\ [#]_ +======================== ==================================================== + +Where ``X`` is a non-negative integer. + +.. note:: + + 1. The actual device node name is system-dependent, as udev rules may apply. + 2. There is no guarantee that ``X`` will remain the same for the same + device, as the number depends on the device driver's probe order. + If you need an unique name, udev default rules produce + ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing + links that can be used uniquely to identify a V4L2 device node:: + + $ tree /dev/v4l + /dev/v4l + ├── by-id + │ └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 + └── by-path + └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 + +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different + set of system calls, as covered at :ref:`subdev`. Many drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the @@ -73,7 +149,7 @@ Related Devices Devices can support several functions. For example video capturing, VBI capturing and radio support. -The V4L2 API creates different nodes for each of these functions. +The V4L2 API creates different V4L2 device nodes for each of these functions. The V4L2 API was designed with the idea that one device node could support all functions. However, in practice this never worked: this @@ -83,17 +159,17 @@ switching a device node between different functions only works when using the streaming I/O API, not with the :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. -Today each device node supports just one function. +Today each V4L2 device node supports just one function. Besides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as ALSA PCM devices with optional ALSA audio mixer devices. One problem with all these devices is that the V4L2 API makes no -provisions to find these related devices. Some really complex devices -use the Media Controller (see :ref:`media_controller`) which can be -used for this purpose. But most drivers do not use it, and while some -code exists that uses sysfs to discover related devices (see +provisions to find these related V4L2 device nodes. Some really complex +hardware use the Media Controller (see :ref:`media_controller`) which can +be used for this purpose. But several drivers do not use it, and while some +code exists that uses sysfs to discover related V4L2 device nodes (see libmedia_dev in the `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git repository), there is no library yet that can provide a single API |