diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 0936dd24ed3d..71f6bf9e735e 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -38,70 +38,41 @@ the basic concepts applicable to all devices. V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is -first opened. The driver modules plug into the "videodev" kernel +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. Assigning -minor numbers to V4L2 devices is entirely up to the system administrator, -this is primarily intended to solve conflicts between devices. - Access permissions are associated with character -device special files, hence we must ensure device numbers cannot -change with the module load order. To this end minor numbers are no -longer automatically assigned by the "videodev" module as in V4L but -requested by the driver. The defaults will suffice for most people -unless two drivers compete for the same minor numbers. - The module options to select minor numbers are named -after the device special file with a "_nr" suffix. For example "video_nr" -for /dev/video video capture devices. The number is -an offset to the base minor number associated with the device type. - - In earlier versions of the V4L2 API the module options -where named after the device special file with a "unit_" prefix, expressing -the minor number itself, not an offset. Rationale for this change is unknown. -Lastly the naming and semantics are just a convention among driver writers, -the point to note is that minor numbers are not supposed to be hardcoded -into drivers. - When the driver supports multiple devices of the same -type more than one minor number can be assigned, separated by commas: - +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: + -> insmod mydriver.o video_nr=0,1 radio_nr=0,1 +> modprobe mydriver video_nr=0,1 radio_nr=0,1 In /etc/modules.conf this may be written as: -alias char-major-81-0 mydriver -alias char-major-81-1 mydriver -alias char-major-81-64 mydriver -options mydriver video_nr=0,1 radio_nr=0,1 +options mydriver video_nr=0,1 radio_nr=0,1 - - - When an application attempts to open a device -special file with major number 81 and minor number 0, 1, or 64, load -"mydriver" (and the "videodev" module it depends upon). - - - Register the first two video capture devices with -minor number 0 and 1 (base number is 0), the first two radio device -with minor number 64 and 65 (base 64). - - - When no minor number is given as module -option the driver supplies a default. -recommends the base minor numbers to be used for the various device -types. Obviously minor numbers must be unique. When the number is -already in use the offending device will not be -registered. + When no device node number is given as module +option the driver supplies a default. - By convention system administrators create various -character device special files with these major and minor numbers in -the /dev directory. The names recommended for the -different V4L2 device types are listed in . + 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 . The creation of character special files (with @@ -110,85 +81,66 @@ 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. - - Under the device filesystem (devfs) the minor number -options are ignored. V4L2 drivers (or by proxy the "videodev" module) -automatically create the required device files in the -/dev/v4l directory using the conventional device -names above.
Multiple Opens - In general, V4L2 devices can be opened more than once. + V4L2 devices can be opened more than once. +There are still some old and obscure drivers that have not been updated to +allow for multiple opens. This implies that for such drivers &func-open; can +return an &EBUSY; when the device is already in use. 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 OSS or ALSA audio mixer application. -When a device supports multiple functions like capturing and overlay -simultaneously, multiple opens allow concurrent -use of the device by forked processes or specialized applications. +applications are comparable to an ALSA audio mixer application. +Just opening a V4L2 device should not change the state of the device. +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. - Multiple opens are optional, although drivers should -permit at least concurrent accesses without data exchange, &ie; panel -applications. This implies &func-open; can return an &EBUSY; when the -device is already in use, as well as &func-ioctl; functions initiating -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read; -and &func-write; functions. + Once an application has allocated the memory buffers needed for +streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls, +or implicitly by calling the &func-read; or &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 &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate +buffers or start or stop streaming. The &EBUSY; will be returned instead. - Mere opening a V4L2 device does not grant exclusive + Merely opening a V4L2 device does not grant exclusive access. Drivers could recognize the O_EXCL open flag. Presently this is not required, @@ -206,12 +158,7 @@ additional access privileges using the priority mechanism described in 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. When the driver supports stream -sharing anyway it must be implemented transparently. The V4L2 API does -not specify how conflicts are solved. +a proxy application in user space.
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 087e8465e09a..6bf35328dcbf 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -145,7 +145,7 @@ applications. --> 3.15 2014-02-03 hv - Update several sections of "Common API Elements": + Update several sections of "Common API Elements": "Opening and Closing Devices" "Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings".