Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit af4a4d0d authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

doc-rst: linux_tv: Replace reference names to match ioctls 



Due to a limitation at the DocBook language, the references
were using lowercase and slashes, instead of the name of the
ioctls. On ReST, make them identical. This will hopefully
help to cleanup the code a little bit.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 78981884

Documentation/linux_tv/media/dvb/audio_function_calls.rst

+1 −1
Original line number Diff line number Diff line
@@ -456,7 +456,7 @@ AUDIO_SET_MUTE 
DESCRIPTION



This ioctl is for DVB devices only. To control a V4L2 decoder use the

V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` with the

V4L2 :ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` with the

``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.



This ioctl call asks the audio device to mute the stream that is

Documentation/linux_tv/media/dvb/video_function_calls.rst

+9 −9
Original line number Diff line number Diff line
@@ -239,7 +239,7 @@ VIDEO_STOP 
DESCRIPTION



This ioctl is for DVB devices only. To control a V4L2 decoder use the

V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` instead.

V4L2 :ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` instead.



This ioctl call asks the Video Device to stop playing the current

stream. Depending on the input parameter, the screen can be blanked out
@@ -302,7 +302,7 @@ VIDEO_PLAY 
DESCRIPTION



This ioctl is for DVB devices only. To control a V4L2 decoder use the

V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` instead.

V4L2 :ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` instead.



This ioctl call asks the Video Device to start playing a video stream

from the selected source.
@@ -348,7 +348,7 @@ VIDEO_FREEZE 
DESCRIPTION



This ioctl is for DVB devices only. To control a V4L2 decoder use the

V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` instead.

V4L2 :ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` instead.



This ioctl call suspends the live video stream being played. Decoding

and playing are frozen. It is then possible to restart the decoding and
@@ -398,7 +398,7 @@ VIDEO_CONTINUE 
DESCRIPTION



This ioctl is for DVB devices only. To control a V4L2 decoder use the

V4L2 :ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` instead.

V4L2 :ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` instead.



This ioctl call restarts decoding and playing processes of the video

stream which was played before a call to VIDEO_FREEZE was made.
@@ -763,7 +763,7 @@ VIDEO_GET_EVENT 
DESCRIPTION



This ioctl is for DVB devices only. To get events from a V4L2 decoder

use the V4L2 :ref:`VIDIOC_DQEVENT <vidioc-dqevent>` ioctl instead.

use the V4L2 :ref:`VIDIOC_DQEVENT <VIDIOC_DQEVENT>` ioctl instead.



This ioctl call returns an event of type video_event if available. If

an event is not available, the behavior depends on whether the device is
@@ -844,11 +844,11 @@ DESCRIPTION 


This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders

this ioctl has been replaced by the

:ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` ioctl.

:ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.



This ioctl commands the decoder. The ``video_command`` struct is a

subset of the ``v4l2_decoder_cmd`` struct, so refer to the

:ref:`VIDIOC_DECODER_CMD <vidioc-decoder-cmd>` documentation for

:ref:`VIDIOC_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation for

more information.



SYNOPSIS
@@ -900,11 +900,11 @@ DESCRIPTION 


This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders

this ioctl has been replaced by the

:ref:`VIDIOC_TRY_DECODER_CMD <vidioc-decoder-cmd>` ioctl.

:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.



This ioctl tries a decoder command. The ``video_command`` struct is a

subset of the ``v4l2_decoder_cmd`` struct, so refer to the

:ref:`VIDIOC_TRY_DECODER_CMD <vidioc-decoder-cmd>` documentation

:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation

for more information.



SYNOPSIS

Documentation/linux_tv/media/v4l/app-pri.rst

+5 −5
Original line number Diff line number Diff line
@@ -16,17 +16,17 @@ 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

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 <vidioc-querycap>` ioctl.

<VIDIOC_G_PRIORITY>` after verifying the device with the

:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl.



Ioctls changing driver properties, such as

:ref:`VIDIOC_S_INPUT <vidioc-g-input>`, return an EBUSY error code

:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an EBUSY error code

after another application obtained higher priority.

Documentation/linux_tv/media/v4l/audio.rst

+12 −12
Original line number Diff line number Diff line
@@ -27,31 +27,31 @@ number, starting at zero, of one audio input or output. 


To learn about the number and attributes of the available inputs and

outputs applications can enumerate them with the

:ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` and

:ref:`VIDIOC_ENUMAUDOUT <vidioc-enumaudioout>` ioctl, respectively.

:ref:`VIDIOC_ENUMAUDIO <VIDIOC_ENUMAUDIO>` and

:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDIOout>` ioctl, respectively.

The struct :ref:`v4l2_audio <v4l2-audio>` returned by the

:ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` ioctl also contains signal

:ref:`VIDIOC_ENUMAUDIO <VIDIOC_ENUMAUDIO>` ioctl also contains signal

:status information applicable when the current audio input is queried.



The :ref:`VIDIOC_G_AUDIO <vidioc-g-audio>` and

:ref:`VIDIOC_G_AUDOUT <vidioc-g-audioout>` ioctls report the current

The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and

:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDIOout>` ioctls report the current

audio input and output, respectively. Note that, unlike

:ref:`VIDIOC_G_INPUT <vidioc-g-input>` and

:ref:`VIDIOC_G_OUTPUT <vidioc-g-output>` these ioctls return a

structure as :ref:`VIDIOC_ENUMAUDIO <vidioc-enumaudio>` and

:ref:`VIDIOC_ENUMAUDOUT <vidioc-enumaudioout>` do, not just an index.

:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and

:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a

structure as :ref:`VIDIOC_ENUMAUDIO <VIDIOC_ENUMAUDIO>` and

:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDIOout>` do, not just an index.



To select an audio input and change its properties applications call the

:ref:`VIDIOC_S_AUDIO <vidioc-g-audio>` ioctl. To select an audio

:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio

output (which presently has no changeable properties) applications call

the :ref:`VIDIOC_S_AUDOUT <vidioc-g-audioout>` ioctl.

the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDIOout>` ioctl.



Drivers must implement all audio input ioctls when the device has

multiple selectable audio inputs, all audio output ioctls when the

device has multiple selectable audio outputs. When the device has any

audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag

in the struct :ref:`v4l2_capability <v4l2-capability>` returned by

the :ref:`VIDIOC_QUERYCAP <vidioc-querycap>` ioctl.

the :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl.





.. code-block:: c

Documentation/linux_tv/media/v4l/buffer.rst

+22 −22
Original line number Diff line number Diff line
@@ -12,9 +12,9 @@ planes, while the buffer structure acts as a container for the planes. 
Only pointers to buffers (planes) are exchanged, the data itself is not

copied. These pointers, together with meta-information like timestamps

or field parity, are stored in a struct :c:type:`struct v4l2_buffer`,

argument to the :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,

:ref:`VIDIOC_QBUF <vidioc-qbuf>` and

:ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. In the multi-planar API,

argument to the :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`,

:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and

:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,

some plane-specific members of struct :c:type:`struct v4l2_buffer`,

such as pointers and sizes for each plane, are stored in struct

:c:type:`struct v4l2_plane` instead. In that case, struct
@@ -26,8 +26,8 @@ see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and 
``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags

are always valid and constant across all buffers during the whole video

stream. Changes in these flags may take place as a side effect of

:ref:`VIDIOC_S_INPUT <vidioc-g-input>` or

:ref:`VIDIOC_S_OUTPUT <vidioc-g-output>` however. The

:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or

:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The

``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on

mem-to-mem devices is an exception to the rule: the timestamp source

flags are copied from the OUTPUT video buffer to the CAPTURE video
@@ -50,12 +50,12 @@ buffer. 


       -  

       -  Number of the buffer, set by the application except when calling

          :ref:`VIDIOC_DQBUF <vidioc-qbuf>`, then it is set by the

          :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the

          driver. This field can range from zero to the number of buffers

          allocated with the :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` ioctl

          allocated with the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` ioctl

          (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`

          ``count``), plus any buffers allocated with

          :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>` minus one.

          :ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` minus one.



    -  .. row 2
@@ -243,8 +243,8 @@ buffer. 
       -  

       -  Size of the buffer (not the payload) in bytes for the

          single-planar API. This is set by the driver based on the calls to

          :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or

          :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`. For the

          :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` and/or

          :ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>`. For the

          multi-planar API the application sets this to the number of

          elements in the ``planes`` array. The driver will fill in the

          actual number of valid elements in that array.
@@ -303,8 +303,8 @@ buffer. 
       -  

       -  Size in bytes of the plane (not its payload). This is set by the

          driver based on the calls to

          :ref:`VIDIOC_REQBUFS <vidioc-reqbufs>` and/or

          :ref:`VIDIOC_CREATE_BUFS <vidioc-create-bufs>`.

          :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` and/or

          :ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>`.



    -  .. row 3
@@ -506,9 +506,9 @@ buffer. 
       -  The buffer resides in device memory and has been mapped into the

          application's address space, see :ref:`mmap` for details.

          Drivers set or clear this flag when the

          :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,

          :ref:`VIDIOC_QBUF <vidioc-qbuf>` or

          :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called. Set by the

          :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`,

          :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or

          :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the

          driver.



    -  .. row 2
@@ -609,10 +609,10 @@ buffer. 


       -  The buffer has been prepared for I/O and can be queued by the

          application. Drivers set or clear this flag when the

          :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>`,

          :ref:`VIDIOC_PREPARE_BUF <vidioc-qbuf>`,

          :ref:`VIDIOC_QBUF <vidioc-qbuf>` or

          :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called.

          :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`,

          :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,

          :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or

          :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.



    -  .. row 10
@@ -645,12 +645,12 @@ buffer. 


       -  Last buffer produced by the hardware. mem2mem codec drivers set

          this flag on the capture queue for the last buffer when the

          :ref:`VIDIOC_QUERYBUF <vidioc-querybuf>` or

          :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl is called. Due to

          :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` or

          :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to

          hardware limitations, the last buffer may be empty. In this case

          the driver will set the ``bytesused`` field to 0, regardless of

          the format. Any Any subsequent call to the

          :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl will not block anymore,

          :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,

          but return an EPIPE error code.



    -  .. row 13