1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _open:
5
6***************************
7Opening and Closing Devices
8***************************
9
10.. _v4l2_hardware_control:
11
12Controlling a hardware peripheral via V4L2
13==========================================
14
15Hardware that is supported using the V4L2 uAPI often consists of multiple
16devices or peripherals, each of which have their own driver.
17
18The bridge driver exposes one or more V4L2 device nodes
19(see :ref:`v4l2_device_naming`).
20
21There are other drivers providing support for other components of
22the hardware, which may also expose device nodes, called V4L2 sub-devices.
23
24When such V4L2 sub-devices are exposed, they allow controlling those
25other hardware components - usually connected via a serial bus (like
26I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices
27can be controlled indirectly via the bridge driver or explicitly via
28the :ref:`Media Controller <media_controller>` and via the
29:ref:`V4L2 sub-devices <subdev>`.
30
31The devices that require the use of the
32:ref:`Media Controller <media_controller>` are called **MC-centric**
33devices. The devices that are fully controlled via V4L2 device nodes
34are called **video-node-centric**.
35
36Userspace can check if a V4L2 hardware peripheral is MC-centric by
37calling :ref:`VIDIOC_QUERYCAP` and checking the
38:ref:`device_caps field <device-capabilities>`.
39
40If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``,
41then it is MC-centric, otherwise, it is video-node-centric.
42
43It is required for MC-centric drivers to identify the V4L2
44sub-devices and to configure the pipelines via the
45:ref:`media controller API <media_controller>` before using the peripheral.
46Also, the sub-devices' configuration shall be controlled via the
47:ref:`sub-device API <subdev>`.
48
49.. note::
50
51   A video-node-centric may still provide media-controller and
52   sub-device interfaces as well.
53
54  However, in that case the media-controller and the sub-device
55  interfaces are read-only and just provide information about the
56  device. The actual configuration is done via the video nodes.
57
58.. _v4l2_device_naming:
59
60V4L2 Device Node Naming
61=======================
62
63V4L2 drivers are implemented as kernel modules, loaded manually by the
64system administrator or automatically when a device is first discovered.
65The driver modules plug into the ``videodev`` kernel module. It provides
66helper functions and a common application interface specified in this
67document.
68
69Each driver thus loaded registers one or more device nodes with major
70number 81. Minor numbers are allocated dynamically unless the kernel
71is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES.
72In that case minor numbers are allocated in ranges depending on the
73device node type.
74
75The device nodes supported by the Video4Linux subsystem are:
76
77======================== ====================================================
78Default device node name Usage
79======================== ====================================================
80``/dev/videoX``		 Video and metadata for capture/output devices
81``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
82``/dev/radioX``		 Radio tuners and modulators
83``/dev/swradioX``	 Software Defined Radio tuners and modulators
84``/dev/v4l-touchX``	 Touch sensors
85``/dev/v4l-subdevX``	 Video sub-devices (used by sensors and other
86			 components of the hardware peripheral)\ [#]_
87======================== ====================================================
88
89Where ``X`` is a non-negative integer.
90
91.. note::
92
93   1. The actual device node name is system-dependent, as udev rules may apply.
94   2. There is no guarantee that ``X`` will remain the same for the same
95      device, as the number depends on the device driver's probe order.
96      If you need an unique name, udev default rules produce
97      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing
98      links that can be used uniquely to identify a V4L2 device node::
99
100	$ tree /dev/v4l
101	/dev/v4l
102	├── by-id
103	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
104	└── by-path
105	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
106
107.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different
108       set of system calls, as covered at :ref:`subdev`.
109
110Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
111options to select specific video/radio/vbi node numbers. This allows the
112user to request that the device node is named e.g. /dev/video5 instead
113of leaving it to chance. When the driver supports multiple devices of
114the same type more than one device node number can be assigned,
115separated by commas:
116
117.. code-block:: none
118
119   # modprobe mydriver video_nr=0,1 radio_nr=0,1
120
121In ``/etc/modules.conf`` this may be written as:
122
123::
124
125    options mydriver video_nr=0,1 radio_nr=0,1
126
127When no device node number is given as module option the driver supplies
128a default.
129
130Normally udev will create the device nodes in /dev automatically for
131you. If udev is not installed, then you need to enable the
132CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
133correctly relate a minor number to a device node number. I.e., you need
134to be certain that minor number 5 maps to device node name video5. With
135this kernel option different device types have different minor number
136ranges. These ranges are listed in :ref:`devices`.
137
138The creation of character special files (with mknod) is a privileged
139operation and devices cannot be opened by major and minor number. That
140means applications cannot *reliably* scan for loaded or installed
141drivers. The user must enter a device name, or the application can try
142the conventional device names.
143
144.. _related:
145
146Related Devices
147===============
148
149Devices can support several functions. For example video capturing, VBI
150capturing and radio support.
151
152The V4L2 API creates different V4L2 device nodes for each of these functions.
153
154The V4L2 API was designed with the idea that one device node could
155support all functions. However, in practice this never worked: this
156'feature' was never used by applications and many drivers did not
157support it and if they did it was certainly never tested. In addition,
158switching a device node between different functions only works when
159using the streaming I/O API, not with the
160:c:func:`read()`/\ :c:func:`write()` API.
161
162Today each V4L2 device node supports just one function.
163
164Besides video input or output the hardware may also support audio
165sampling or playback. If so, these functions are implemented as ALSA PCM
166devices with optional ALSA audio mixer devices.
167
168One problem with all these devices is that the V4L2 API makes no
169provisions to find these related V4L2 device nodes. Some really complex
170hardware use the Media Controller (see :ref:`media_controller`) which can
171be used for this purpose. But several drivers do not use it, and while some
172code exists that uses sysfs to discover related V4L2 device nodes (see
173libmedia_dev in the
174`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
175repository), there is no library yet that can provide a single API
176towards both Media Controller-based devices and devices that do not use
177the Media Controller. If you want to work on this please write to the
178linux-media mailing list:
179`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
180
181Multiple Opens
182==============
183
184V4L2 devices can be opened more than once. [#f1]_ When this is supported
185by the driver, users can for example start a "panel" application to
186change controls like brightness or audio volume, while another
187application captures video and audio. In other words, panel applications
188are comparable to an ALSA audio mixer application. Just opening a V4L2
189device should not change the state of the device. [#f2]_
190
191Once an application has allocated the memory buffers needed for
192streaming data (by calling the :ref:`VIDIOC_REQBUFS`
193or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
194implicitly by calling the :c:func:`read()` or
195:c:func:`write()` functions) that application (filehandle)
196becomes the owner of the device. It is no longer allowed to make changes
197that would affect the buffer sizes (e.g. by calling the
198:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
199no longer allowed to allocate buffers or start or stop streaming. The
200EBUSY error code will be returned instead.
201
202Merely opening a V4L2 device does not grant exclusive access. [#f3]_
203Initiating data exchange however assigns the right to read or write the
204requested type of data, and to change related properties, to this file
205descriptor. Applications can request additional access privileges using
206the priority mechanism described in :ref:`app-pri`.
207
208Shared Data Streams
209===================
210
211V4L2 drivers should not support multiple applications reading or writing
212the same data stream on a device by copying buffers, time multiplexing
213or similar means. This is better handled by a proxy application in user
214space.
215
216Functions
217=========
218
219To open and close V4L2 devices applications use the
220:c:func:`open()` and :c:func:`close()` function,
221respectively. Devices are programmed using the
222:ref:`ioctl() <func-ioctl>` function as explained in the following
223sections.
224
225.. [#f1]
226   There are still some old and obscure drivers that have not been
227   updated to allow for multiple opens. This implies that for such
228   drivers :c:func:`open()` can return an ``EBUSY`` error code
229   when the device is already in use.
230
231.. [#f2]
232   Unfortunately, opening a radio device often switches the state of the
233   device to radio mode in many drivers. This behavior should be fixed
234   eventually as it violates the V4L2 specification.
235
236.. [#f3]
237   Drivers could recognize the ``O_EXCL`` open flag. Presently this is
238   not required, so applications cannot know if it really works.
239