Documentation/media/uapi/v4l/open.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _open:
  11
  12 ***************************
  13 Opening and Closing Devices
  14 ***************************
  15
  16
  17 Device Naming
  18 =============
  19
  20 V4L2 drivers are implemented as kernel modules, loaded manually by the
  21 system administrator or automatically when a device is first discovered.
  22 The driver modules plug into the "videodev" kernel module. It provides
  23 helper functions and a common application interface specified in this
  24 document.
  25
  26 Each driver thus loaded registers one or more device nodes with major
  27 number 81 and a minor number between 0 and 255. Minor numbers are
  28 allocated dynamically unless the kernel is compiled with the kernel
  29 option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
  30 are allocated in ranges depending on the device node type (video, radio,
  31 etc.).
  32
  33 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
  34 options to select specific video/radio/vbi node numbers. This allows the
  35 user to request that the device node is named e.g. /dev/video5 instead
  36 of leaving it to chance. When the driver supports multiple devices of
  37 the same type more than one device node number can be assigned,
  38 separated by commas:
  39
  40 .. code-block:: none
  41
  42    # modprobe mydriver video_nr=0,1 radio_nr=0,1
  43
  44 In ``/etc/modules.conf`` this may be written as:
  45
  46 ::
  47
  48     options mydriver video_nr=0,1 radio_nr=0,1
  49
  50 When no device node number is given as module option the driver supplies
  51 a default.
  52
  53 Normally udev will create the device nodes in /dev automatically for
  54 you. If udev is not installed, then you need to enable the
  55 CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
  56 correctly relate a minor number to a device node number. I.e., you need
  57 to be certain that minor number 5 maps to device node name video5. With
  58 this kernel option different device types have different minor number
  59 ranges. These ranges are listed in :ref:`devices`.
  60
  61 The creation of character special files (with mknod) is a privileged
  62 operation and devices cannot be opened by major and minor number. That
  63 means applications cannot *reliably* scan for loaded or installed
  64 drivers. The user must enter a device name, or the application can try
  65 the conventional device names.
  66
  67
  68 .. _related:
  69
  70 Related Devices
  71 ===============
  72
  73 Devices can support several functions. For example video capturing, VBI
  74 capturing and radio support.
  75
  76 The V4L2 API creates different nodes for each of these functions.
  77
  78 The V4L2 API was designed with the idea that one device node could
  79 support all functions. However, in practice this never worked: this
  80 'feature' was never used by applications and many drivers did not
  81 support it and if they did it was certainly never tested. In addition,
  82 switching a device node between different functions only works when
  83 using the streaming I/O API, not with the
  84 :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
  85
  86 Today each device node supports just one function.
  87
  88 Besides video input or output the hardware may also support audio
  89 sampling or playback. If so, these functions are implemented as ALSA PCM
  90 devices with optional ALSA audio mixer devices.
  91
  92 One problem with all these devices is that the V4L2 API makes no
  93 provisions to find these related devices. Some really complex devices
  94 use the Media Controller (see :ref:`media_controller`) which can be
  95 used for this purpose. But most drivers do not use it, and while some
  96 code exists that uses sysfs to discover related devices (see
  97 libmedia_dev in the
  98 `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
  99 repository), there is no library yet that can provide a single API
 100 towards both Media Controller-based devices and devices that do not use
 101 the Media Controller. If you want to work on this please write to the
 102 linux-media mailing list:
 103 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
 104
 105
 106 Multiple Opens
 107 ==============
 108
 109 V4L2 devices can be opened more than once. [#f1]_ When this is supported
 110 by the driver, users can for example start a "panel" application to
 111 change controls like brightness or audio volume, while another
 112 application captures video and audio. In other words, panel applications
 113 are comparable to an ALSA audio mixer application. Just opening a V4L2
 114 device should not change the state of the device. [#f2]_
 115
 116 Once an application has allocated the memory buffers needed for
 117 streaming data (by calling the :ref:`VIDIOC_REQBUFS`
 118 or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
 119 implicitly by calling the :ref:`read() <func-read>` or
 120 :ref:`write() <func-write>` functions) that application (filehandle)
 121 becomes the owner of the device. It is no longer allowed to make changes
 122 that would affect the buffer sizes (e.g. by calling the
 123 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
 124 no longer allowed to allocate buffers or start or stop streaming. The
 125 EBUSY error code will be returned instead.
 126
 127 Merely opening a V4L2 device does not grant exclusive access. [#f3]_
 128 Initiating data exchange however assigns the right to read or write the
 129 requested type of data, and to change related properties, to this file
 130 descriptor. Applications can request additional access privileges using
 131 the priority mechanism described in :ref:`app-pri`.
 132
 133
 134 Shared Data Streams
 135 ===================
 136
 137 V4L2 drivers should not support multiple applications reading or writing
 138 the same data stream on a device by copying buffers, time multiplexing
 139 or similar means. This is better handled by a proxy application in user
 140 space.
 141
 142
 143 Functions
 144 =========
 145
 146 To open and close V4L2 devices applications use the
 147 :ref:`open() <func-open>` and :ref:`close() <func-close>` function,
 148 respectively. Devices are programmed using the
 149 :ref:`ioctl() <func-ioctl>` function as explained in the following
 150 sections.
 151
 152 .. [#f1]
 153    There are still some old and obscure drivers that have not been
 154    updated to allow for multiple opens. This implies that for such
 155    drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code
 156    when the device is already in use.
 157
 158 .. [#f2]
 159    Unfortunately, opening a radio device often switches the state of the
 160    device to radio mode in many drivers. This behavior should be fixed
 161    eventually as it violates the V4L2 specification.
 162
 163 .. [#f3]
 164    Drivers could recognize the ``O_EXCL`` open flag. Presently this is
 165    not required, so applications cannot know if it really works.