Documentation/userspace-api/media/v4l/open.rst

   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.