0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _open:
0005
0006 ***************************
0007 Opening and Closing Devices
0008 ***************************
0009
0010 .. _v4l2_hardware_control:
0011
0012 Controlling a hardware peripheral via V4L2
0013 ==========================================
0014
0015 Hardware that is supported using the V4L2 uAPI often consists of multiple
0016 devices or peripherals, each of which have their own driver.
0017
0018 The bridge driver exposes one or more V4L2 device nodes
0019 (see :ref:`v4l2_device_naming`).
0020
0021 There are other drivers providing support for other components of
0022 the hardware, which may also expose device nodes, called V4L2 sub-devices.
0023
0024 When such V4L2 sub-devices are exposed, they allow controlling those
0025 other hardware components - usually connected via a serial bus (like
0026 I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices
0027 can be controlled indirectly via the bridge driver or explicitly via
0028 the :ref:`Media Controller <media_controller>` and via the
0029 :ref:`V4L2 sub-devices <subdev>`.
0030
0031 The devices that require the use of the
0032 :ref:`Media Controller <media_controller>` are called **MC-centric**
0033 devices. The devices that are fully controlled via V4L2 device nodes
0034 are called **video-node-centric**.
0035
0036 Userspace can check if a V4L2 hardware peripheral is MC-centric by
0037 calling :ref:`VIDIOC_QUERYCAP` and checking the
0038 :ref:`device_caps field <device-capabilities>`.
0039
0040 If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``,
0041 then it is MC-centric, otherwise, it is video-node-centric.
0042
0043 It is required for MC-centric drivers to identify the V4L2
0044 sub-devices and to configure the pipelines via the
0045 :ref:`media controller API <media_controller>` before using the peripheral.
0046 Also, the sub-devices' configuration shall be controlled via the
0047 :ref:`sub-device API <subdev>`.
0048
0049 .. note::
0050
0051 A video-node-centric may still provide media-controller and
0052 sub-device interfaces as well.
0053
0054 However, in that case the media-controller and the sub-device
0055 interfaces are read-only and just provide information about the
0056 device. The actual configuration is done via the video nodes.
0057
0058 .. _v4l2_device_naming:
0059
0060 V4L2 Device Node Naming
0061 =======================
0062
0063 V4L2 drivers are implemented as kernel modules, loaded manually by the
0064 system administrator or automatically when a device is first discovered.
0065 The driver modules plug into the ``videodev`` kernel module. It provides
0066 helper functions and a common application interface specified in this
0067 document.
0068
0069 Each driver thus loaded registers one or more device nodes with major
0070 number 81. Minor numbers are allocated dynamically unless the kernel
0071 is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES.
0072 In that case minor numbers are allocated in ranges depending on the
0073 device node type.
0074
0075 The device nodes supported by the Video4Linux subsystem are:
0076
0077 ======================== ====================================================
0078 Default device node name Usage
0079 ======================== ====================================================
0080 ``/dev/videoX`` Video and metadata for capture/output devices
0081 ``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext)
0082 ``/dev/radioX`` Radio tuners and modulators
0083 ``/dev/swradioX`` Software Defined Radio tuners and modulators
0084 ``/dev/v4l-touchX`` Touch sensors
0085 ``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other
0086 components of the hardware peripheral)\ [#]_
0087 ======================== ====================================================
0088
0089 Where ``X`` is a non-negative integer.
0090
0091 .. note::
0092
0093 1. The actual device node name is system-dependent, as udev rules may apply.
0094 2. There is no guarantee that ``X`` will remain the same for the same
0095 device, as the number depends on the device driver's probe order.
0096 If you need an unique name, udev default rules produce
0097 ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing
0098 links that can be used uniquely to identify a V4L2 device node::
0099
0100 $ tree /dev/v4l
0101 /dev/v4l
0102 ├── by-id
0103 │ └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
0104 └── by-path
0105 └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
0106
0107 .. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different
0108 set of system calls, as covered at :ref:`subdev`.
0109
0110 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
0111 options to select specific video/radio/vbi node numbers. This allows the
0112 user to request that the device node is named e.g. /dev/video5 instead
0113 of leaving it to chance. When the driver supports multiple devices of
0114 the same type more than one device node number can be assigned,
0115 separated by commas:
0116
0117 .. code-block:: none
0118
0119 # modprobe mydriver video_nr=0,1 radio_nr=0,1
0120
0121 In ``/etc/modules.conf`` this may be written as:
0122
0123 ::
0124
0125 options mydriver video_nr=0,1 radio_nr=0,1
0126
0127 When no device node number is given as module option the driver supplies
0128 a default.
0129
0130 Normally udev will create the device nodes in /dev automatically for
0131 you. If udev is not installed, then you need to enable the
0132 CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
0133 correctly relate a minor number to a device node number. I.e., you need
0134 to be certain that minor number 5 maps to device node name video5. With
0135 this kernel option different device types have different minor number
0136 ranges. These ranges are listed in :ref:`devices`.
0137
0138 The creation of character special files (with mknod) is a privileged
0139 operation and devices cannot be opened by major and minor number. That
0140 means applications cannot *reliably* scan for loaded or installed
0141 drivers. The user must enter a device name, or the application can try
0142 the conventional device names.
0143
0144 .. _related:
0145
0146 Related Devices
0147 ===============
0148
0149 Devices can support several functions. For example video capturing, VBI
0150 capturing and radio support.
0151
0152 The V4L2 API creates different V4L2 device nodes for each of these functions.
0153
0154 The V4L2 API was designed with the idea that one device node could
0155 support all functions. However, in practice this never worked: this
0156 'feature' was never used by applications and many drivers did not
0157 support it and if they did it was certainly never tested. In addition,
0158 switching a device node between different functions only works when
0159 using the streaming I/O API, not with the
0160 :c:func:`read()`/\ :c:func:`write()` API.
0161
0162 Today each V4L2 device node supports just one function.
0163
0164 Besides video input or output the hardware may also support audio
0165 sampling or playback. If so, these functions are implemented as ALSA PCM
0166 devices with optional ALSA audio mixer devices.
0167
0168 One problem with all these devices is that the V4L2 API makes no
0169 provisions to find these related V4L2 device nodes. Some really complex
0170 hardware use the Media Controller (see :ref:`media_controller`) which can
0171 be used for this purpose. But several drivers do not use it, and while some
0172 code exists that uses sysfs to discover related V4L2 device nodes (see
0173 libmedia_dev in the
0174 `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
0175 repository), there is no library yet that can provide a single API
0176 towards both Media Controller-based devices and devices that do not use
0177 the Media Controller. If you want to work on this please write to the
0178 linux-media mailing list:
0179 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
0180
0181 Multiple Opens
0182 ==============
0183
0184 V4L2 devices can be opened more than once. [#f1]_ When this is supported
0185 by the driver, users can for example start a "panel" application to
0186 change controls like brightness or audio volume, while another
0187 application captures video and audio. In other words, panel applications
0188 are comparable to an ALSA audio mixer application. Just opening a V4L2
0189 device should not change the state of the device. [#f2]_
0190
0191 Once an application has allocated the memory buffers needed for
0192 streaming data (by calling the :ref:`VIDIOC_REQBUFS`
0193 or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
0194 implicitly by calling the :c:func:`read()` or
0195 :c:func:`write()` functions) that application (filehandle)
0196 becomes the owner of the device. It is no longer allowed to make changes
0197 that would affect the buffer sizes (e.g. by calling the
0198 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
0199 no longer allowed to allocate buffers or start or stop streaming. The
0200 EBUSY error code will be returned instead.
0201
0202 Merely opening a V4L2 device does not grant exclusive access. [#f3]_
0203 Initiating data exchange however assigns the right to read or write the
0204 requested type of data, and to change related properties, to this file
0205 descriptor. Applications can request additional access privileges using
0206 the priority mechanism described in :ref:`app-pri`.
0207
0208 Shared Data Streams
0209 ===================
0210
0211 V4L2 drivers should not support multiple applications reading or writing
0212 the same data stream on a device by copying buffers, time multiplexing
0213 or similar means. This is better handled by a proxy application in user
0214 space.
0215
0216 Functions
0217 =========
0218
0219 To open and close V4L2 devices applications use the
0220 :c:func:`open()` and :c:func:`close()` function,
0221 respectively. Devices are programmed using the
0222 :ref:`ioctl() <func-ioctl>` function as explained in the following
0223 sections.
0224
0225 .. [#f1]
0226 There are still some old and obscure drivers that have not been
0227 updated to allow for multiple opens. This implies that for such
0228 drivers :c:func:`open()` can return an ``EBUSY`` error code
0229 when the device is already in use.
0230
0231 .. [#f2]
0232 Unfortunately, opening a radio device often switches the state of the
0233 device to radio mode in many drivers. This behavior should be fixed
0234 eventually as it violates the V4L2 specification.
0235
0236 .. [#f3]
0237 Drivers could recognize the ``O_EXCL`` open flag. Presently this is
0238 not required, so applications cannot know if it really works.
