GNU Linux-libre 4.14.295-gnu1
[releases.git] / 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.