[deliverable/linux.git] / Documentation / linux_tv / media / v4l / app-pri.rst

.. -*- coding: utf-8; mode: rst -*-

.. _app-pri:

********************
Application Priority
********************

When multiple applications share a device it may be desirable to assign
them different priorities. Contrary to the traditional "rm -rf /" school
of thought a video recording application could for example block other
applications from changing video controls or switching the current TV
channel. Another objective is to permit low priority applications
working in background, which can be preempted by user controlled
applications and automatically regain control of the device at a later
time.

Since these features cannot be implemented entirely in user space V4L2
defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and
:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and
query the access priority associate with a file descriptor. Opening a
device assigns a medium priority, compatible with earlier versions of
V4L2 and drivers not supporting these ioctls. Applications requiring a
different priority will usually call :ref:`VIDIOC_S_PRIORITY
<VIDIOC_G_PRIORITY>` after verifying the device with the
:ref:`VIDIOC_QUERYCAP` ioctl.

Ioctls changing driver properties, such as
:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an EBUSY error code
after another application obtained higher priority.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _app-pri:
	4
	5	********************
	6	Application Priority
	7	********************
	8
	9	When multiple applications share a device it may be desirable to assign
	10	them different priorities. Contrary to the traditional "rm -rf /" school
	11	of thought a video recording application could for example block other
	12	applications from changing video controls or switching the current TV
	13	channel. Another objective is to permit low priority applications
	14	working in background, which can be preempted by user controlled
	15	applications and automatically regain control of the device at a later
	16	time.
	17
	18	Since these features cannot be implemented entirely in user space V4L2
4e03cb76	19	defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and
af4a4d0d	20	:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and
5377d91f MH	21	query the access priority associate with a file descriptor. Opening a
	22	device assigns a medium priority, compatible with earlier versions of
	23	V4L2 and drivers not supporting these ioctls. Applications requiring a
e6702ee1	24	different priority will usually call :ref:`VIDIOC_S_PRIORITY
af4a4d0d	25	<VIDIOC_G_PRIORITY>` after verifying the device with the
7347081e	26	:ref:`VIDIOC_QUERYCAP` ioctl.
5377d91f MH	27
5377d91f MH	28	Ioctls changing driver properties, such as
af4a4d0d	29	:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an EBUSY error code
5377d91f MH	30	after another application obtained higher priority.
	31
	32
	33	.. ------------------------------------------------------------------------------
	34	.. This file was automatically converted from DocBook-XML with the dbxml
	35	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
	36	.. from the linux kernel, refer to:
	37	..
	38	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
	39	.. ------------------------------------------------------------------------------