media/v4l/open.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
18 The bridge driver exposes one or more V4L2 device nodes
22 the hardware, which may also expose device nodes, called V4L2 sub-devices.
24 When such V4L2 sub-devices are exposed, they allow controlling those
25 other hardware components - usually connected via a serial bus (like
26 I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices
29 :ref:`V4L2 sub-devices <subdev>`.
32 :ref:`Media Controller <media_controller>` are called **MC-centric**
33 devices. The devices that are fully controlled via V4L2 device nodes
34 are called **video-node-centric**.
36 Userspace can check if a V4L2 hardware peripheral is MC-centric by
38 :ref:`device_caps field <device-capabilities>`.
40 If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``,
41 then it is MC-centric, otherwise, it is video-node-centric.
43 It is required for MC-centric drivers to identify the V4L2
44 sub-devices and to configure the pipelines via the
46 Also, the sub-devices' configuration shall be controlled via the
47 :ref:`sub-device API <subdev>`.
51    A video-node-centric may still provide media-controller and
52    sub-device interfaces as well.
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.
60 V4L2 Device Node Naming
64 system administrator or automatically when a device is first discovered.
69 Each driver thus loaded registers one or more device nodes with major
73 device node type.
75 The device nodes supported by the Video4Linux subsystem are:
78 Default device node name Usage
84 ``/dev/v4l-touchX``	 Touch sensors
85 ``/dev/v4l-subdevX``	 Video sub-devices (used by sensors and other
89 Where ``X`` is a non-negative integer.
93    1. The actual device node name is system-dependent, as udev rules may apply.
95       device, as the number depends on the device driver's probe order.
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::
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
107 .. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different
112 user to request that the device node is named e.g. /dev/video5 instead
114 the same type more than one device node number can be assigned,
117 .. code-block:: none
127 When no device node number is given as module option the driver supplies
130 Normally udev will create the device nodes in /dev automatically for
133 correctly relate a minor number to a device node number. I.e., you need
134 to be certain that minor number 5 maps to device node name video5. With
135 this kernel option different device types have different minor number
141 drivers. The user must enter a device name, or the application can try
142 the conventional device names.
152 The V4L2 API creates different V4L2 device nodes for each of these functions.
154 The V4L2 API was designed with the idea that one device node could
158 switching a device node between different functions only works when
162 Today each V4L2 device node supports just one function.
169 provisions to find these related V4L2 device nodes. Some really complex
172 code exists that uses sysfs to discover related V4L2 device nodes (see
174 `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
176 towards both Media Controller-based devices and devices that do not use
178 linux-media mailing list:
189 device should not change the state of the device. [#f2]_
196 becomes the owner of the device. It is no longer allowed to make changes
202 Merely opening a V4L2 device does not grant exclusive access. [#f3]_
206 the priority mechanism described in :ref:`app-pri`.
212 the same data stream on a device by copying buffers, time multiplexing
222 :ref:`ioctl() <func-ioctl>` function as explained in the following
229    when the device is already in use.
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