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