| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _open: |
| 5 |
|
| 6 |
*************************** |
| 7 |
Opening and Closing Devices |
| 8 |
*************************** |
| 9 |
|
| 10 |
.. _v4l2_hardware_control: |
| 11 |
|
| 12 |
Controlling a hardware peripheral via V4L2 |
| 13 |
========================================== |
| 14 |
|
| 15 |
Hardware that is supported using the V4L2 uAPI often consists of multiple |
| 16 |
devices or peripherals, each of which have their own driver. |
| 17 |
|
| 18 |
The bridge driver exposes one or more V4L2 device nodes |
| 19 |
(see :ref:`v4l2_device_naming`). |
| 20 |
|
| 21 |
There are other drivers providing support for other components of |
| 22 |
the hardware, which may also expose device nodes, called V4L2 sub-devices. |
| 23 |
|
| 24 |
When such V4L2 sub-devices are exposed, they allow controlling those |
| 25 |
other hardware components - usually connected via a serial bus (like |
| 26 |
I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices |
| 27 |
can be controlled indirectly via the bridge driver or explicitly via |
| 28 |
the :ref:`Media Controller <media_controller>` and via the |
| 29 |
:ref:`V4L2 sub-devices <subdev>`. |
| 30 |
|
| 31 |
The devices that require the use of the |
| 32 |
:ref:`Media Controller <media_controller>` are called **MC-centric** |
| 33 |
devices. The devices that are fully controlled via V4L2 device nodes |
| 34 |
are called **video-node-centric**. |
| 35 |
|
| 36 |
Userspace can check if a V4L2 hardware peripheral is MC-centric by |
| 37 |
calling :ref:`VIDIOC_QUERYCAP` and checking the |
| 38 |
:ref:`device_caps field <device-capabilities>`. |
| 39 |
|
| 40 |
If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, |
| 41 |
then it is MC-centric, otherwise, it is video-node-centric. |
| 42 |
|
| 43 |
It is required for MC-centric drivers to identify the V4L2 |
| 44 |
sub-devices and to configure the pipelines via the |
| 45 |
:ref:`media controller API <media_controller>` before using the peripheral. |
| 46 |
Also, the sub-devices' configuration shall be controlled via the |
| 47 |
:ref:`sub-device API <subdev>`. |
| 48 |
|
| 49 |
.. note:: |
| 50 |
|
| 51 |
A video-node-centric may still provide media-controller and |
| 52 |
sub-device interfaces as well. |
| 53 |
|
| 54 |
However, in that case the media-controller and the sub-device |
| 55 |
interfaces are read-only and just provide information about the |
| 56 |
device. The actual configuration is done via the video nodes. |
| 57 |
|
| 58 |
.. _v4l2_device_naming: |
| 59 |
|
| 60 |
V4L2 Device Node Naming |
| 61 |
======================= |
| 62 |
|
| 63 |
V4L2 drivers are implemented as kernel modules, loaded manually by the |
| 64 |
system administrator or automatically when a device is first discovered. |
| 65 |
The driver modules plug into the ``videodev`` kernel module. It provides |
| 66 |
helper functions and a common application interface specified in this |
| 67 |
document. |
| 68 |
|
| 69 |
Each driver thus loaded registers one or more device nodes with major |
| 70 |
number 81. Minor numbers are allocated dynamically unless the kernel |
| 71 |
is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. |
| 72 |
In that case minor numbers are allocated in ranges depending on the |
| 73 |
device node type. |
| 74 |
|
| 75 |
The device nodes supported by the Video4Linux subsystem are: |
| 76 |
|
| 77 |
======================== ==================================================== |
| 78 |
Default device node name Usage |
| 79 |
======================== ==================================================== |
| 80 |
``/dev/videoX`` Video and metadata for capture/output devices |
| 81 |
``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext) |
| 82 |
``/dev/radioX`` Radio tuners and modulators |
| 83 |
``/dev/swradioX`` Software Defined Radio tuners and modulators |
| 84 |
``/dev/v4l-touchX`` Touch sensors |
| 85 |
``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other |
| 86 |
components of the hardware peripheral)\ [#]_ |
| 87 |
======================== ==================================================== |
| 88 |
|
| 89 |
Where ``X`` is a non-negative integer. |
| 90 |
|
| 91 |
.. note:: |
| 92 |
|
| 93 |
1. The actual device node name is system-dependent, as udev rules may apply. |
| 94 |
2. There is no guarantee that ``X`` will remain the same for the same |
| 95 |
device, as the number depends on the device driver's probe order. |
| 96 |
If you need an unique name, udev default rules produce |
| 97 |
``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing |
| 98 |
links that can be used uniquely to identify a V4L2 device node:: |
| 99 |
|
| 100 |
$ tree /dev/v4l |
| 101 |
/dev/v4l |
| 102 |
├── by-id |
| 103 |
│ └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 |
| 104 |
└── by-path |
| 105 |
└── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 |
| 106 |
|
| 107 |
.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different |
| 108 |
set of system calls, as covered at :ref:`subdev`. |
| 109 |
|
| 110 |
Many drivers support "video_nr", "radio_nr" or "vbi_nr" module |
| 111 |
options to select specific video/radio/vbi node numbers. This allows the |
| 112 |
user to request that the device node is named e.g. /dev/video5 instead |
| 113 |
of leaving it to chance. When the driver supports multiple devices of |
| 114 |
the same type more than one device node number can be assigned, |
| 115 |
separated by commas: |
| 116 |
|
| 117 |
.. code-block:: none |
| 118 |
|
| 119 |
# modprobe mydriver video_nr=0,1 radio_nr=0,1 |
| 120 |
|
| 121 |
In ``/etc/modules.conf`` this may be written as: |
| 122 |
|
| 123 |
:: |
| 124 |
|
| 125 |
options mydriver video_nr=0,1 radio_nr=0,1 |
| 126 |
|
| 127 |
When no device node number is given as module option the driver supplies |
| 128 |
a default. |
| 129 |
|
| 130 |
Normally udev will create the device nodes in /dev automatically for |
| 131 |
you. If udev is not installed, then you need to enable the |
| 132 |
CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to |
| 133 |
correctly relate a minor number to a device node number. I.e., you need |
| 134 |
to be certain that minor number 5 maps to device node name video5. With |
| 135 |
this kernel option different device types have different minor number |
| 136 |
ranges. These ranges are listed in :ref:`devices`. |
| 137 |
|
| 138 |
The creation of character special files (with mknod) is a privileged |
| 139 |
operation and devices cannot be opened by major and minor number. That |
| 140 |
means applications cannot *reliably* scan for loaded or installed |
| 141 |
drivers. The user must enter a device name, or the application can try |
| 142 |
the conventional device names. |
| 143 |
|
| 144 |
.. _related: |
| 145 |
|
| 146 |
Related Devices |
| 147 |
=============== |
| 148 |
|
| 149 |
Devices can support several functions. For example video capturing, VBI |
| 150 |
capturing and radio support. |
| 151 |
|
| 152 |
The V4L2 API creates different V4L2 device nodes for each of these functions. |
| 153 |
|
| 154 |
The V4L2 API was designed with the idea that one device node could |
| 155 |
support all functions. However, in practice this never worked: this |
| 156 |
'feature' was never used by applications and many drivers did not |
| 157 |
support it and if they did it was certainly never tested. In addition, |
| 158 |
switching a device node between different functions only works when |
| 159 |
using the streaming I/O API, not with the |
| 160 |
:c:func:`read()`/\ :c:func:`write()` API. |
| 161 |
|
| 162 |
Today each V4L2 device node supports just one function. |
| 163 |
|
| 164 |
Besides video input or output the hardware may also support audio |
| 165 |
sampling or playback. If so, these functions are implemented as ALSA PCM |
| 166 |
devices with optional ALSA audio mixer devices. |
| 167 |
|
| 168 |
One problem with all these devices is that the V4L2 API makes no |
| 169 |
provisions to find these related V4L2 device nodes. Some really complex |
| 170 |
hardware use the Media Controller (see :ref:`media_controller`) which can |
| 171 |
be used for this purpose. But several drivers do not use it, and while some |
| 172 |
code exists that uses sysfs to discover related V4L2 device nodes (see |
| 173 |
libmedia_dev in the |
| 174 |
`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git |
| 175 |
repository), there is no library yet that can provide a single API |
| 176 |
towards both Media Controller-based devices and devices that do not use |
| 177 |
the Media Controller. If you want to work on this please write to the |
| 178 |
linux-media mailing list: |
| 179 |
`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. |
| 180 |
|
| 181 |
Multiple Opens |
| 182 |
============== |
| 183 |
|
| 184 |
V4L2 devices can be opened more than once. [#f1]_ When this is supported |
| 185 |
by the driver, users can for example start a "panel" application to |
| 186 |
change controls like brightness or audio volume, while another |
| 187 |
application captures video and audio. In other words, panel applications |
| 188 |
are comparable to an ALSA audio mixer application. Just opening a V4L2 |
| 189 |
device should not change the state of the device. [#f2]_ |
| 190 |
|
| 191 |
Once an application has allocated the memory buffers needed for |
| 192 |
streaming data (by calling the :ref:`VIDIOC_REQBUFS` |
| 193 |
or :ref:`VIDIOC_CREATE_BUFS` ioctls, or |
| 194 |
implicitly by calling the :c:func:`read()` or |
| 195 |
:c:func:`write()` functions) that application (filehandle) |
| 196 |
becomes the owner of the device. It is no longer allowed to make changes |
| 197 |
that would affect the buffer sizes (e.g. by calling the |
| 198 |
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are |
| 199 |
no longer allowed to allocate buffers or start or stop streaming. The |
| 200 |
EBUSY error code will be returned instead. |
| 201 |
|
| 202 |
Merely opening a V4L2 device does not grant exclusive access. [#f3]_ |
| 203 |
Initiating data exchange however assigns the right to read or write the |
| 204 |
requested type of data, and to change related properties, to this file |
| 205 |
descriptor. Applications can request additional access privileges using |
| 206 |
the priority mechanism described in :ref:`app-pri`. |
| 207 |
|
| 208 |
Shared Data Streams |
| 209 |
=================== |
| 210 |
|
| 211 |
V4L2 drivers should not support multiple applications reading or writing |
| 212 |
the same data stream on a device by copying buffers, time multiplexing |
| 213 |
or similar means. This is better handled by a proxy application in user |
| 214 |
space. |
| 215 |
|
| 216 |
Functions |
| 217 |
========= |
| 218 |
|
| 219 |
To open and close V4L2 devices applications use the |
| 220 |
:c:func:`open()` and :c:func:`close()` function, |
| 221 |
respectively. Devices are programmed using the |
| 222 |
:ref:`ioctl() <func-ioctl>` function as explained in the following |
| 223 |
sections. |
| 224 |
|
| 225 |
.. [#f1] |
| 226 |
There are still some old and obscure drivers that have not been |
| 227 |
updated to allow for multiple opens. This implies that for such |
| 228 |
drivers :c:func:`open()` can return an ``EBUSY`` error code |
| 229 |
when the device is already in use. |
| 230 |
|
| 231 |
.. [#f2] |
| 232 |
Unfortunately, opening a radio device often switches the state of the |
| 233 |
device to radio mode in many drivers. This behavior should be fixed |
| 234 |
eventually as it violates the V4L2 specification. |
| 235 |
|
| 236 |
.. [#f3] |
| 237 |
Drivers could recognize the ``O_EXCL`` open flag. Presently this is |
| 238 |
not required, so applications cannot know if it really works. |