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