diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2020-06-03 20:59:38 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2020-06-03 20:59:38 -0700 |
commit | a98f670e41a99f53acb1fb33cee9c6abbb2e6f23 (patch) | |
tree | f8ae10a4cb91758ad7f9422053753a8c5d0f04dc /Documentation/userspace-api/media/v4l/open.rst | |
parent | ee01c4d72adffb7d424535adf630f2955748fa8b (diff) | |
parent | 938b29db3aa9c293c7c1366b16e55e308f1a1ddd (diff) |
Merge tag 'media/v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
- Media documentation is now split into admin-guide, driver-api and
userspace-api books (a longstanding request from Jon);
- The media Kconfig was reorganized, in order to make easier to select
drivers and their dependencies;
- The testing drivers now has a separate directory;
- added a new driver for Rockchip Video Decoder IP;
- The atomisp staging driver was resurrected. It is meant to work with
4 generations of cameras on Atom-based laptops, tablets and cell
phones. So, it seems worth investing time to cleanup this driver and
making it in good shape.
- Added some V4L2 core ancillary routines to help with h264 codecs;
- Added an ov2740 image sensor driver;
- The si2157 gained support for Analog TV, which, in turn, added
support for some cx231xx and cx23885 boards to also support analog
standards;
- Added some V4L2 controls (V4L2_CID_CAMERA_ORIENTATION and
V4L2_CID_CAMERA_SENSOR_ROTATION) to help identifying where the camera
is located at the device;
- VIDIOC_ENUM_FMT was extended to support MC-centric devices;
- Lots of drivers improvements and cleanups.
* tag 'media/v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (503 commits)
media: Documentation: media: Refer to mbus format documentation from CSI-2 docs
media: s5k5baf: Replace zero-length array with flexible-array
media: i2c: imx219: Drop <linux/clk-provider.h> and <linux/clkdev.h>
media: i2c: Add ov2740 image sensor driver
media: ov8856: Implement sensor module revision identification
media: ov8856: Add devicetree support
media: dt-bindings: ov8856: Document YAML bindings
media: dvb-usb: Add Cinergy S2 PCIe Dual Port support
media: dvbdev: Fix tuner->demod media controller link
media: dt-bindings: phy: phy-rockchip-dphy-rx0: move rockchip dphy rx0 bindings out of staging
media: staging: dt-bindings: phy-rockchip-dphy-rx0: remove non-used reg property
media: atomisp: unify the version for isp2401 a0 and b0 versions
media: atomisp: update TODO with the current data
media: atomisp: adjust some code at sh_css that could be broken
media: atomisp: don't produce errs for ignored IRQs
media: atomisp: print IRQ when debugging
media: atomisp: isp_mmu: don't use kmem_cache
media: atomisp: add a notice about possible leak resources
media: atomisp: disable the dynamic and reserved pools
media: atomisp: turn on camera before setting it
...
Diffstat (limited to 'Documentation/userspace-api/media/v4l/open.rst')
-rw-r--r-- | Documentation/userspace-api/media/v4l/open.rst | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst new file mode 100644 index 000000000000..38046ef20141 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -0,0 +1,165 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _open: + +*************************** +Opening and Closing Devices +*************************** + + +Device Naming +============= + +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. + +Each driver thus loaded registers one or more device nodes with major +number 81 and a minor number between 0 and 255. 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 (video, radio, +etc.). + +Many 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: + +.. code-block:: none + + # modprobe mydriver video_nr=0,1 radio_nr=0,1 + +In ``/etc/modules.conf`` this may be written as: + +:: + + options mydriver video_nr=0,1 radio_nr=0,1 + +When no device node number is given as module option the driver supplies +a default. + +Normally 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`. + +The 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. + + +.. _related: + +Related Devices +=============== + +Devices can support several functions. For example video capturing, VBI +capturing and radio support. + +The V4L2 API creates different nodes for each of these functions. + +The 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 +:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API. + +Today each device node supports just one function. + +Besides 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. + +One problem with all these devices is that the V4L2 API makes no +provisions to find these related devices. Some really complex devices +use the Media Controller (see :ref:`media_controller`) which can be +used for this purpose. But most drivers do not use it, and while some +code exists that uses sysfs to discover related devices (see +libmedia_dev in the +`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ 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 <https://linuxtv.org/lists.php>`__. + + +Multiple Opens +============== + +V4L2 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]_ + +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 :ref:`read() <func-read>` or +:ref:`write() <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 <VIDIOC_G_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. + +Merely 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`. + + +Shared Data Streams +=================== + +V4L2 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. + + +Functions +========= + +To open and close V4L2 devices applications use the +:ref:`open() <func-open>` and :ref:`close() <func-close>` function, +respectively. Devices are programmed using the +:ref:`ioctl() <func-ioctl>` function as explained in the following +sections. + +.. [#f1] + There are still some old and obscure drivers that have not been + updated to allow for multiple opens. This implies that for such + drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code + when the device is already in use. + +.. [#f2] + Unfortunately, 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. + +.. [#f3] + Drivers could recognize the ``O_EXCL`` open flag. Presently this is + not required, so applications cannot know if it really works. |