Documentation/media/uapi/v4l/open.rst

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