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