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