~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/userspace-api/media/v4l/open.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/userspace-api/media/v4l/open.rst (Architecture sparc64) and /Documentation/userspace-api/media/v4l/open.rst (Architecture m68k)


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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php