diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-27 23:58:31 +0200 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-27 23:58:31 +0200 |
commit | ff9a082fda424257976f08fce942609f358015e0 (patch) | |
tree | 478e6b449b19baaf842369a13923499ce83ef895 /Documentation/media/uapi/v4l/open.rst | |
parent | Merge tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi (diff) | |
parent | Merge branch 'topic/docs-next' into v4l_for_linus (diff) | |
download | linux-ff9a082fda424257976f08fce942609f358015e0.tar.xz linux-ff9a082fda424257976f08fce942609f358015e0.zip |
Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media documentation updates from Mauro Carvalho Chehab:
"This patch series does the conversion of all media documentation stuff
to Restrutured Text markup format and add them to the
Documentation/index.rst file.
The media documentation was grouped into 4 books:
- media uAPI
- media kAPI
- V4L driver-specific documentation
- DVB driver-specific documentation
It also contains several documentation improvements and one fixup
patch for a core issue with cropcap.
PS. After this patch series, the media DocBook is deprecated and
should be removed. I'll add such patch on a future pull request"
* tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits)
[media] cx23885-cardlist.rst: add a new card
[media] doc-rst: add some needed escape codes
[media] doc-rst: kapi: use :c:func: instead of :cpp:func
doc-rst: kernel-doc: fix a change introduced by mistake
[media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops
[media] dvb_ringbuffer.h: some documentation improvements
[media] v4l2-ctrls.h: fully document the header file
[media] doc-rst: Fix some typedef ugly warnings
[media] doc-rst: reorganize the kAPI v4l2 chapters
[media] rename v4l2-framework.rst to v4l2-intro.rst
[media] move V4L2 clocks to a separate .rst file
[media] v4l2-fh.rst: add cross references and markups
[media] v4l2-fh.rst: add fh contents from v4l2-framework.rst
[media] v4l2-fh.h: add documentation for it
[media] v4l2-event.rst: add cross-references and markups
[media] v4l2-event.h: document all functions
[media] v4l2-event.rst: add text from v4l2-framework.rst
[media] v4l2-framework.rst: remove videobuf quick chapter
[media] v4l2-dev: add cross-references and improve markup
[media] doc-rst: move v4l2-dev doc to a separate file
...
Diffstat (limited to 'Documentation/media/uapi/v4l/open.rst')
-rw-r--r-- | Documentation/media/uapi/v4l/open.rst | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst new file mode 100644 index 000000000000..afd116edb40d --- /dev/null +++ b/Documentation/media/uapi/v4l/open.rst @@ -0,0 +1,158 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 *reliable* 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. |