ȸsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget0/translations/zh_CN/userspace-api/media/v4l/openmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/zh_TW/userspace-api/media/v4l/openmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/it_IT/userspace-api/media/v4l/openmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ja_JP/userspace-api/media/v4l/openmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ko_KR/userspace-api/media/v4l/openmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/sp_SP/userspace-api/media/v4l/openmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h8SPDX-License-Identifier: GFDL-1.1-no-invariants-or-laterh]h8SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhJ/var/lib/git/docbuild/linux/Documentation/userspace-api/media/v4l/open.rsthKubhtarget)}(h .. _open:h]h}(h]h ]h"]h$]h&]refidopenuh1hhKhhhhhhubhsection)}(hhh](htitle)}(hOpening and Closing Devicesh]hOpening and Closing Devices}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(h.. _v4l2_hardware_control:h]h}(h]h ]h"]h$]h&]hv4l2-hardware-controluh1hhK hhhhhhubh)}(hhh](h)}(h*Controlling a hardware peripheral via V4L2h]h*Controlling a hardware peripheral via V4L2}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh paragraph)}(hHardware that is supported using the V4L2 uAPI often consists of multiple devices or peripherals, each of which have their own driver.h]hHardware that is supported using the V4L2 uAPI often consists of multiple devices or peripherals, each of which have their own driver.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXThe bridge driver exposes one or more V4L2 device nodes (see :ref:`v4l2_device_naming`).h](h=The bridge driver exposes one or more V4L2 device nodes (see }(hjhhhNhNubh)}(h:ref:`v4l2_device_naming`h]hinline)}(hj h]hv4l2_device_naming}(hjhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]refdocuserspace-api/media/v4l/open refdomainjreftyperef refexplicitrefwarn reftargetv4l2_device_naminguh1hhhhKhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThere are other drivers providing support for other components of the hardware, which may also expose device nodes, called V4L2 sub-devices.h]hThere are other drivers providing support for other components of the hardware, which may also expose device nodes, called V4L2 sub-devices.}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXrWhen such V4L2 sub-devices are exposed, they allow controlling those other hardware components - usually connected via a serial bus (like I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices can be controlled indirectly via the bridge driver or explicitly via the :ref:`Media Controller ` and via the :ref:`V4L2 sub-devices `.h](hXWhen such V4L2 sub-devices are exposed, they allow controlling those other hardware components - usually connected via a serial bus (like I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices can be controlled indirectly via the bridge driver or explicitly via the }(hjHhhhNhNubh)}(h*:ref:`Media Controller `h]j)}(hjRh]hMedia Controller}(hjThhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjPubah}(h]h ]h"]h$]h&]refdocj( refdomainj^reftyperef refexplicitrefwarnj.media_controlleruh1hhhhKhjHubh and via the }(hjHhhhNhNubh)}(h :ref:`V4L2 sub-devices `h]j)}(hjvh]hV4L2 sub-devices}(hjxhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjtubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.subdevuh1hhhhKhjHubh.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hThe devices that require the use of the :ref:`Media Controller ` are called **MC-centric** devices. The devices that are fully controlled via V4L2 device nodes are called **video-node-centric**.h](h(The devices that require the use of the }(hjhhhNhNubh)}(h*:ref:`Media Controller `h]j)}(hjh]hMedia Controller}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.media_controlleruh1hhhhKhjubh are called }(hjhhhNhNubhstrong)}(h**MC-centric**h]h MC-centric}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhQ devices. The devices that are fully controlled via V4L2 device nodes are called }(hjhhhNhNubj)}(h**video-node-centric**h]hvideo-node-centric}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hUserspace can check if a V4L2 hardware peripheral is MC-centric by calling :ref:`VIDIOC_QUERYCAP` and checking the :ref:`device_caps field `.h](hKUserspace can check if a V4L2 hardware peripheral is MC-centric by calling }(hjhhhNhNubh)}(h:ref:`VIDIOC_QUERYCAP`h]j)}(hjh]hVIDIOC_QUERYCAP}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainj reftyperef refexplicitrefwarnj.vidioc_querycapuh1hhhhK$hjubh and checking the }(hjhhhNhNubh)}(h.:ref:`device_caps field `h]j)}(hj$h]hdevice_caps field}(hj&hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhj"ubah}(h]h ]h"]h$]h&]refdocj( refdomainj0reftyperef refexplicitrefwarnj.device-capabilitiesuh1hhhhK$hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK$hhhhubh)}(h}If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, then it is MC-centric, otherwise, it is video-node-centric.h](hIf the device returns }(hjLhhhNhNubhliteral)}(h``V4L2_CAP_IO_MC``h]hV4L2_CAP_IO_MC}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjLubh flag at }(hjLhhhNhNubjU)}(h``device_caps``h]h device_caps}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjLubh=, then it is MC-centric, otherwise, it is video-node-centric.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK(hhhhubh)}(hXIt is required for MC-centric drivers to identify the V4L2 sub-devices and to configure the pipelines via the :ref:`media controller API ` before using the peripheral. Also, the sub-devices' configuration shall be controlled via the :ref:`sub-device API `.h](hnIt is required for MC-centric drivers to identify the V4L2 sub-devices and to configure the pipelines via the }(hjhhhNhNubh)}(h.:ref:`media controller API `h]j)}(hjh]hmedia controller API}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.media_controlleruh1hhhhK+hjubha before using the peripheral. Also, the sub-devices’ configuration shall be controlled via the }(hjhhhNhNubh)}(h:ref:`sub-device API `h]j)}(hjh]hsub-device API}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.subdevuh1hhhhK+hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK+hhhhubhnote)}(hX A video-node-centric may still provide media-controller and sub-device interfaces as well. However, in that case the media-controller and the sub-device interfaces are read-only and just provide information about the device. The actual configuration is done via the video nodes.h](h block_quote)}(h[A video-node-centric may still provide media-controller and sub-device interfaces as well. h]h)}(hZA video-node-centric may still provide media-controller and sub-device interfaces as well.h]hZA video-node-centric may still provide media-controller and sub-device interfaces as well.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK3hjubah}(h]h ]h"]h$]h&]uh1jhhhK3hjubh)}(hHowever, in that case the media-controller and the sub-device interfaces are read-only and just provide information about the device. The actual configuration is done via the video nodes.h]hHowever, in that case the media-controller and the sub-device interfaces are read-only and just provide information about the device. The actual configuration is done via the video nodes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK6hjubeh}(h]h ]h"]h$]h&]uh1jhhhhhhhNubh)}(h.. _v4l2_device_naming:h]h}(h]h ]h"]h$]h&]hv4l2-device-naminguh1hhK:hhhhhhubeh}(h](*controlling-a-hardware-peripheral-via-v4l2heh ]h"](*controlling a hardware peripheral via v4l2v4l2_hardware_controleh$]h&]uh1hhhhhhhhK expect_referenced_by_name}jhsexpect_referenced_by_id}hhsubh)}(hhh](h)}(hV4L2 Device Node Namingh]hV4L2 Device Node Naming}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"hhhhhK=ubh)}(hX(V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. The driver modules plug into the ``videodev`` kernel module. It provides helper functions and a common application interface specified in this document.h](hV4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. The driver modules plug into the }(hj3hhhNhNubjU)}(h ``videodev``h]hvideodev}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jThj3ubhk kernel module. It provides helper functions and a common application interface specified in this document.}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hj"hhubh)}(hX$Each driver thus loaded registers one or more device nodes with major number 81. Minor numbers are allocated dynamically unless the kernel is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are allocated in ranges depending on the device node type.h]hX$Each driver thus loaded registers one or more device nodes with major number 81. Minor numbers are allocated dynamically unless the kernel is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are allocated in ranges depending on the device node type.}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKEhj"hhubh)}(h ../../video0 └── by-path └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0h]henumerated_list)}(hhh](h list_item)}(hIThe actual device node name is system-dependent, as udev rules may apply.h]h)}(hjh]hIThe actual device node name is system-dependent, as udev rules may apply.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hX&There is no guarantee that ``X`` will remain the same for the same device, as the number depends on the device driver's probe order. If you need an unique name, udev default rules produce ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing links that can be used uniquely to identify a V4L2 device node:: $ tree /dev/v4l /dev/v4l ├── by-id │   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 └── by-path └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0h](h)}(hXAThere is no guarantee that ``X`` will remain the same for the same device, as the number depends on the device driver's probe order. If you need an unique name, udev default rules produce ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing links that can be used uniquely to identify a V4L2 device node::h](hThere is no guarantee that }(hjhhhNhNubjU)}(h``X``h]hX}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjubh will remain the same for the same device, as the number depends on the device driver’s probe order. If you need an unique name, udev default rules produce }(hjhhhNhNubjU)}(h``/dev/v4l/by-id/``h]h/dev/v4l/by-id/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjubh and }(hjhhhNhNubjU)}(h``/dev/v4l/by-path/``h]h/dev/v4l/by-path/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjubhW directories containing links that can be used uniquely to identify a V4L2 device node:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK^hjubh literal_block)}(h$ tree /dev/v4l /dev/v4l ├── by-id │   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 └── by-path └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0h]h$ tree /dev/v4l /dev/v4l ├── by-id │   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 └── by-path └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0}hjsbah}(h]h ]h"]h$]h&]hhuh1j hhhKdhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjubah}(h]h ]h"]h$]h&]uh1jhj"hhhNhNubhfootnote)}(hy**V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different set of system calls, as covered at :ref:`subdev`. h](hlabel)}(hhh]h1}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj5hhhNhNubh)}(hx**V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different set of system calls, as covered at :ref:`subdev`.h](j)}(h**V4L2 sub-device nodes**h]hV4L2 sub-device nodes}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjHubh (e. g. }(hjHhhhNhNubjU)}(h``/dev/v4l-subdevX``h]h/dev/v4l-subdevX}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1jThjHubh5) use a different set of system calls, as covered at }(hjHhhhNhNubh)}(h :ref:`subdev`h]j)}(hjrh]hsubdev}(hjthhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjpubah}(h]h ]h"]h$]h&]refdocj( refdomainj~reftyperef refexplicitrefwarnj.subdevuh1hhhhKkhjHubh.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKkhj5ubeh}(h]jZah ]h"]1ah$]h&]jTajYKj[j(uh1j3hhhKkhj"hhubh)}(hXiMany drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the user to request that the device node is named e.g. /dev/video5 instead of leaving it to chance. When the driver supports multiple devices of the same type more than one device node number can be assigned, separated by commas:h]hXuMany drivers support “video_nr”, “radio_nr” or “vbi_nr” module options to select specific video/radio/vbi node numbers. This allows the user to request that the device node is named e.g. /dev/video5 instead of leaving it to chance. When the driver supports multiple devices of the same type more than one device node number can be assigned, separated by commas:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhj"hhubj )}(h-# modprobe mydriver video_nr=0,1 radio_nr=0,1h]h-# modprobe mydriver video_nr=0,1 radio_nr=0,1}hjsbah}(h]h ]h"]h$]h&]hhforcelanguagenonehighlight_args}uh1j hhhKuhj"hhubh)}(h0In ``/etc/modules.conf`` this may be written as:h](hIn }(hjhhhNhNubjU)}(h``/etc/modules.conf``h]h/etc/modules.conf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jThjubh this may be written as:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKyhj"hhubj )}(h*options mydriver video_nr=0,1 radio_nr=0,1h]h*options mydriver video_nr=0,1 radio_nr=0,1}hjsbah}(h]h ]h"]h$]h&]hhuh1j hhhK}hj"hhubh)}(hSWhen no device node number is given as module option the driver supplies a default.h]hSWhen no device node number is given as module option the driver supplies a default.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj"hhubh)}(hXNormally udev will create the device nodes in /dev automatically for you. If udev is not installed, then you need to enable the CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly relate a minor number to a device node number. I.e., you need to be certain that minor number 5 maps to device node name video5. With this kernel option different device types have different minor number ranges. These ranges are listed in :ref:`devices`.h](hXNormally udev will create the device nodes in /dev automatically for you. If udev is not installed, then you need to enable the CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly relate a minor number to a device node number. I.e., you need to be certain that minor number 5 maps to device node name video5. With this kernel option different device types have different minor number ranges. These ranges are listed in }(hjhhhNhNubh)}(h:ref:`devices`h]j)}(hjh]hdevices}(hj hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.devicesuh1hhhhKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj"hhubh)}(hX3The creation of character special files (with mknod) is a privileged operation and devices cannot be opened by major and minor number. That means applications cannot *reliably* scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names.h](hThe creation of character special files (with mknod) is a privileged operation and devices cannot be opened by major and minor number. That means applications cannot }(hj0hhhNhNubhemphasis)}(h *reliably*h]hreliably}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1j8hj0ubh scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names.}(hj0hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj"hhubh)}(h .. _related:h]h}(h]h ]h"]h$]h&]hrelateduh1hhKhj"hhhhubeh}(h](v4l2-device-node-namingjeh ]h"](v4l2 device node namingv4l2_device_namingeh$]h&]uh1hhhhhhhhK=j}jcj sj }jj subh)}(hhh](h)}(hRelated Devicesh]hRelated Devices}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhhKubh)}(hdDevices can support several functions. For example video capturing, VBI capturing and radio support.h]hdDevices can support several functions. For example video capturing, VBI capturing and radio support.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hMThe V4L2 API creates different V4L2 device nodes for each of these functions.h]hMThe V4L2 API creates different V4L2 device nodes for each of these functions.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hXThe V4L2 API was designed with the idea that one device node could support all functions. However, in practice this never worked: this 'feature' was never used by applications and many drivers did not support it and if they did it was certainly never tested. In addition, switching a device node between different functions only works when using the streaming I/O API, not with the :c:func:`read()`/\ :c:func:`write()` API.h](hXThe V4L2 API was designed with the idea that one device node could support all functions. However, in practice this never worked: this ‘feature’ was never used by applications and many drivers did not support it and if they did it was certainly never tested. In addition, switching a device node between different functions only works when using the streaming I/O API, not with the }(hjhhhNhNubh)}(h:c:func:`read()`h]jU)}(hjh]hread()}(hjhhhNhNubah}(h]h ](jcc-funceh"]h$]h&]uh1jThjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarn c:parent_keysphinx.domains.c LookupKey)}data]j ASTIdentifier)} identifierV4LsbNasbj.readuh1hhhhKhjubh/ }(hjhhhNhNubh)}(h:c:func:`write()`h]jU)}(hjh]hwrite()}(hjhhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.writeuh1hhhhKhjubh API.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(h7Today each V4L2 device node supports just one function.h]h7Today each V4L2 device node supports just one function.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hBesides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as ALSA PCM devices with optional ALSA audio mixer devices.h]hBesides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as ALSA PCM devices with optional ALSA audio mixer devices.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubh)}(hXOne problem with all these devices is that the V4L2 API makes no provisions to find these related V4L2 device nodes. Some really complex hardware use the Media Controller (see :ref:`media_controller`) which can be used for this purpose. But several drivers do not use it, and while some code exists that uses sysfs to discover related V4L2 device nodes (see libmedia_dev in the `v4l-utils `__ git repository), there is no library yet that can provide a single API towards both Media Controller-based devices and devices that do not use the Media Controller. If you want to work on this please write to the linux-media mailing list: `https://linuxtv.org/lists.php `__.h](hOne problem with all these devices is that the V4L2 API makes no provisions to find these related V4L2 device nodes. Some really complex hardware use the Media Controller (see }(hjhhhNhNubh)}(h:ref:`media_controller`h]j)}(hjh]hmedia_controller}(hj!hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainj+reftyperef refexplicitrefwarnj.media_controlleruh1hhhhKhjubh) which can be used for this purpose. But several drivers do not use it, and while some code exists that uses sysfs to discover related V4L2 device nodes (see libmedia_dev in the }(hjhhhNhNubh reference)}(h>`v4l-utils `__h]h v4l-utils}(hjChhhNhNubah}(h]h ]h"]h$]h&]name v4l-utilsrefuri.http://git.linuxtv.org/cgit.cgi/v4l-utils.git/uh1jAhjubh git repository), there is no library yet that can provide a single API towards both Media Controller-based devices and devices that do not use the Media Controller. If you want to work on this please write to the linux-media mailing list: }(hjhhhNhNubjB)}(hA`https://linuxtv.org/lists.php `__h]hhttps://linuxtv.org/lists.php}(hjYhhhNhNubah}(h]h ]h"]h$]h&]namehttps://linuxtv.org/lists.phpjShttps://linuxtv.org/lists.phpuh1jAhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhhubeh}(h](related-devicesj\eh ]h"](related devicesrelatedeh$]h&]uh1hhhhhhhhKj}jzjRsj }j\jRsubh)}(hhh](h)}(hMultiple Opensh]hMultiple Opens}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXV4L2 devices can be opened more than once. [#f1]_ When this is supported by the driver, users can for example start a "panel" application to change controls like brightness or audio volume, while another application captures video and audio. In other words, panel applications are comparable to an ALSA audio mixer application. Just opening a V4L2 device should not change the state of the device. [#f2]_h](h+V4L2 devices can be opened more than once. }(hjhhhNhNubjI)}(h[#f1]_h]h2}(hjhhhNhNubah}(h]id3ah ]h"]h$]h&]jYKhf1j[j(uh1jHhjj\KubhXa When this is supported by the driver, users can for example start a “panel” application to change controls like brightness or audio volume, while another application captures video and audio. In other words, panel applications are comparable to an ALSA audio mixer application. Just opening a V4L2 device should not change the state of the device. }(hjhhhNhNubjI)}(h[#f2]_h]h3}(hjhhhNhNubah}(h]id4ah ]h"]h$]h&]jYKhf2j[j(uh1jHhjj\Kubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX<Once an application has allocated the memory buffers needed for streaming data (by calling the :ref:`VIDIOC_REQBUFS` or :ref:`VIDIOC_CREATE_BUFS` ioctls, or implicitly by calling the :c:func:`read()` or :c:func:`write()` functions) that application (filehandle) becomes the owner of the device. It is no longer allowed to make changes that would affect the buffer sizes (e.g. by calling the :ref:`VIDIOC_S_FMT ` ioctl) and other applications are no longer allowed to allocate buffers or start or stop streaming. The EBUSY error code will be returned instead.h](h_Once an application has allocated the memory buffers needed for streaming data (by calling the }(hjhhhNhNubh)}(h:ref:`VIDIOC_REQBUFS`h]j)}(hjh]hVIDIOC_REQBUFS}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.vidioc_reqbufsuh1hhhhKhjubh or }(hjhhhNhNubh)}(h:ref:`VIDIOC_CREATE_BUFS`h]j)}(hjh]hVIDIOC_CREATE_BUFS}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftyperef refexplicitrefwarnj.vidioc_create_bufsuh1hhhhKhjubh& ioctls, or implicitly by calling the }(hjhhhNhNubh)}(h:c:func:`read()`h]jU)}(hj h]hread()}(hj hhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThj ubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.readuh1hhhhKhjubh or }(hjhhhNhNubh)}(h:c:func:`write()`h]jU)}(hj7 h]hwrite()}(hj9 hhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThj5 ubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.writeuh1hhhhKhjubh functions) that application (filehandle) becomes the owner of the device. It is no longer allowed to make changes that would affect the buffer sizes (e.g. by calling the }(hjhhhNhNubh)}(h":ref:`VIDIOC_S_FMT `h]j)}(hjZ h]h VIDIOC_S_FMT}(hj\ hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjX ubah}(h]h ]h"]h$]h&]refdocj( refdomainjf reftyperef refexplicitrefwarnj. vidioc_g_fmtuh1hhhhKhjubh ioctl) and other applications are no longer allowed to allocate buffers or start or stop streaming. The EBUSY error code will be returned instead.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOMerely opening a V4L2 device does not grant exclusive access. [#f3]_ Initiating data exchange however assigns the right to read or write the requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in :ref:`app-pri`.h](h>Merely opening a V4L2 device does not grant exclusive access. }(hj hhhNhNubjI)}(h[#f3]_h]h4}(hj hhhNhNubah}(h]id5ah ]h"]h$]h&]jYKhf3j[j(uh1jHhj j\Kubh Initiating data exchange however assigns the right to read or write the requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in }(hj hhhNhNubh)}(h:ref:`app-pri`h]j)}(hj h]happ-pri}(hj hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]refdocj( refdomainj reftyperef refexplicitrefwarnj.app-priuh1hhhhKhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]multiple-opensah ]h"]multiple opensah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hShared Data Streamsh]hShared Data Streams}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hV4L2 drivers should not support multiple applications reading or writing the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space.h]hV4L2 drivers should not support multiple applications reading or writing the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]shared-data-streamsah ]h"]shared data streamsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Functionsh]h Functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hTo open and close V4L2 devices applications use the :c:func:`open()` and :c:func:`close()` function, respectively. Devices are programmed using the :ref:`ioctl() ` function as explained in the following sections.h](h4To open and close V4L2 devices applications use the }(hj hhhNhNubh)}(h:c:func:`open()`h]jU)}(hj h]hopen()}(hj hhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThj ubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.openuh1hhhhKhj ubh and }(hj hhhNhNubh)}(h:c:func:`close()`h]jU)}(hj5 h]hclose()}(hj7 hhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThj3 ubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.closeuh1hhhhKhj ubh: function, respectively. Devices are programmed using the }(hj hhhNhNubh)}(h:ref:`ioctl() `h]j)}(hjX h]hioctl()}(hjZ hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjV ubah}(h]h ]h"]h$]h&]refdocj( refdomainjd reftyperef refexplicitrefwarnj. func-ioctluh1hhhhKhj ubh1 function as explained in the following sections.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj4)}(hThere are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such drivers :c:func:`open()` can return an ``EBUSY`` error code when the device is already in use. h](j:)}(hhh]h2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj hhhNhNubh)}(hThere are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such drivers :c:func:`open()` can return an ``EBUSY`` error code when the device is already in use.h](hThere are still some old and obscure drivers that have not been updated to allow for multiple opens. This implies that for such drivers }(hj hhhNhNubh)}(h:c:func:`open()`h]jU)}(hj h]hopen()}(hj hhhNhNubah}(h]h ](jjc-funceh"]h$]h&]uh1jThj ubah}(h]h ]h"]h$]h&]refdocj( refdomainjreftypefunc refexplicitrefwarnjjj.openuh1hhhhKhj ubh can return an }(hj hhhNhNubjU)}(h ``EBUSY``h]hEBUSY}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jThj ubh. error code when the device is already in use.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubeh}(h]jah ]h"]f1ah$]h&]jajYKj[j(uh1j3hhhKhj hhubj4)}(hUnfortunately, opening a radio device often switches the state of the device to radio mode in many drivers. This behavior should be fixed eventually as it violates the V4L2 specification. h](j:)}(hhh]h3}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj hhhNhNubh)}(hUnfortunately, opening a radio device often switches the state of the device to radio mode in many drivers. This behavior should be fixed eventually as it violates the V4L2 specification.h]hUnfortunately, opening a radio device often switches the state of the device to radio mode in many drivers. This behavior should be fixed eventually as it violates the V4L2 specification.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubeh}(h]jah ]h"]f2ah$]h&]jajYKj[j(uh1j3hhhKhj hhubj4)}(hDrivers could recognize the ``O_EXCL`` open flag. Presently this is not required, so applications cannot know if it really works.h](j:)}(hhh]h4}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj hhhNhNubh)}(hDrivers could recognize the ``O_EXCL`` open flag. Presently this is not required, so applications cannot know if it really works.h](hDrivers could recognize the }(hj hhhNhNubjU)}(h ``O_EXCL``h]hO_EXCL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jThj ubh[ open flag. Presently this is not required, so applications cannot know if it really works.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubeh}(h]j ah ]h"]f3ah$]h&]j ajYKj[j(uh1j3hhhKhj hhubeh}(h] functionsah ]h"] functionsah$]h&]uh1hhhhhhhhKubeh}(h](opening-and-closing-devicesheh ]h"](opening and closing devicesopeneh$]h&]uh1hhhhhhhhKj}jG hsj }hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksjfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjn error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(f1]jaf2]jaf3]j aurefids}(h]hah]haj]j aj\]jRaj]jaj]jaj ]j ajZ]jJaunameids}(jG hjF jC jhjjjcjjbj_jzj\jyjvj j j j j> j; j jj jj6 j jjZu nametypes}(jG jF jjjcjbjzjyj j j> j j j6 juh}(hhjC hhhjhjj"j_j"jTjJjZj5j\jhjvjhj jjjjjj j j j j; j jj jj j j u footnote_refs}(j ]jaj ]jaj ]j au citation_refs} autofootnotes](j5j j j eautofootnote_refs](jJjjj esymbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j| KsRparse_messages]transform_messages](hsystem_message)}(hhh]h)}(hhh]h*Hyperlink target "open" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1j ubj )}(hhh]h)}(hhh]h;Hyperlink target "v4l2-hardware-control" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehlineK uh1j ubj )}(hhh]h)}(hhh]h8Hyperlink target "v4l2-device-naming" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehlineK:uh1j ubj )}(hhh]h)}(hhh]h-Hyperlink target "related" is not referenced.}hj7 sbah}(h]h ]h"]h$]h&]uh1hhj4 ubah}(h]h ]h"]h$]h&]levelKtypej sourcehlineKuh1j ube transformerN include_log] decorationNhhub.