diff --git a/Documentation/linux_tv/media/v4l/dev-capture.rst b/Documentation/linux_tv/media/v4l/dev-capture.rst index eb5c1522905d69de1f833be5d32ffe4b7d6e9594..c970a1fd143944e74a1f7d42d5e9e18688992299 100644 --- a/Documentation/linux_tv/media/v4l/dev-capture.rst +++ b/Documentation/linux_tv/media/v4l/dev-capture.rst @@ -75,23 +75,23 @@ To request different parameters applications set the ``type`` field of a struct :ref:`v4l2_format ` as above and initialize all fields of the struct :ref:`v4l2_pix_format ` ``vbi`` member of the ``fmt`` union, or better just modify the results -of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT ` +of :ref:`VIDIOC_G_FMT`, and call the :ref:`VIDIOC_S_FMT ` ioctl with a pointer to this structure. Drivers may adjust the -parameters and finally return the actual parameters as ``VIDIOC_G_FMT`` +parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT` does. -Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT ` ioctl +Like :ref:`VIDIOC_S_FMT ` the :ref:`VIDIOC_TRY_FMT ` ioctl can be used to learn about hardware limitations without disabling I/O or possibly time consuming hardware preparations. The contents of struct :ref:`v4l2_pix_format ` and struct :ref:`v4l2_pix_format_mplane ` are discussed in :ref:`pixfmt`. See also the specification of the -``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for -details. Video capture devices must implement both the ``VIDIOC_G_FMT`` -and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all -requests and always returns default parameters as ``VIDIOC_G_FMT`` does. -``VIDIOC_TRY_FMT`` is optional. +:ref:`VIDIOC_G_FMT`, :ref:`VIDIOC_S_FMT ` and :ref:`VIDIOC_TRY_FMT ` ioctls for +details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT` +and :ref:`VIDIOC_S_FMT ` ioctl, even if :ref:`VIDIOC_S_FMT ` ignores all +requests and always returns default parameters as :ref:`VIDIOC_G_FMT` does. +:ref:`VIDIOC_TRY_FMT ` is optional. Reading Images diff --git a/Documentation/linux_tv/media/v4l/dev-osd.rst b/Documentation/linux_tv/media/v4l/dev-osd.rst index 27d2cfbf3d9cd773f2cd63ffed12bfd72607859f..4b668a3544b8367416f2557794a24f7f2b3f1e15 100644 --- a/Documentation/linux_tv/media/v4l/dev-osd.rst +++ b/Documentation/linux_tv/media/v4l/dev-osd.rst @@ -124,10 +124,10 @@ struct :ref:`v4l2_format ` to ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win`` substructure and call the :ref:`VIDIOC_S_FMT ` ioctl. The driver adjusts the parameters against hardware limits and returns -the actual parameters as ``VIDIOC_G_FMT`` does. Like ``VIDIOC_S_FMT``, +the actual parameters as :ref:`VIDIOC_G_FMT` does. Like :ref:`VIDIOC_S_FMT `, the :ref:`VIDIOC_TRY_FMT ` ioctl can be used to learn about driver capabilities without actually changing driver state. Unlike -``VIDIOC_S_FMT`` this also works after the overlay has been enabled. +:ref:`VIDIOC_S_FMT ` this also works after the overlay has been enabled. A struct :ref:`v4l2_crop ` defines the size and position of the target rectangle. The scaling factor of the overlay is implied by diff --git a/Documentation/linux_tv/media/v4l/dev-output.rst b/Documentation/linux_tv/media/v4l/dev-output.rst index 1ca0e5873a866479c1e859d98bf7f7c66e4bcd93..ee62d1a0fb871bea4e5cbcd833e7a0930acc192e 100644 --- a/Documentation/linux_tv/media/v4l/dev-output.rst +++ b/Documentation/linux_tv/media/v4l/dev-output.rst @@ -72,23 +72,23 @@ To request different parameters applications set the ``type`` field of a struct :ref:`v4l2_format ` as above and initialize all fields of the struct :ref:`v4l2_pix_format ` ``vbi`` member of the ``fmt`` union, or better just modify the results -of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT ` +of :ref:`VIDIOC_G_FMT`, and call the :ref:`VIDIOC_S_FMT ` ioctl with a pointer to this structure. Drivers may adjust the -parameters and finally return the actual parameters as ``VIDIOC_G_FMT`` +parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT` does. -Like ``VIDIOC_S_FMT`` the :ref:`VIDIOC_TRY_FMT ` ioctl +Like :ref:`VIDIOC_S_FMT ` the :ref:`VIDIOC_TRY_FMT ` ioctl can be used to learn about hardware limitations without disabling I/O or possibly time consuming hardware preparations. The contents of struct :ref:`v4l2_pix_format ` and struct :ref:`v4l2_pix_format_mplane ` are discussed in :ref:`pixfmt`. See also the specification of the -``VIDIOC_G_FMT``, ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT`` ioctls for -details. Video output devices must implement both the ``VIDIOC_G_FMT`` -and ``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all -requests and always returns default parameters as ``VIDIOC_G_FMT`` does. -``VIDIOC_TRY_FMT`` is optional. +:ref:`VIDIOC_G_FMT`, :ref:`VIDIOC_S_FMT ` and :ref:`VIDIOC_TRY_FMT ` ioctls for +details. Video output devices must implement both the :ref:`VIDIOC_G_FMT` +and :ref:`VIDIOC_S_FMT ` ioctl, even if :ref:`VIDIOC_S_FMT ` ignores all +requests and always returns default parameters as :ref:`VIDIOC_G_FMT` does. +:ref:`VIDIOC_TRY_FMT ` is optional. Writing Images diff --git a/Documentation/linux_tv/media/v4l/dev-overlay.rst b/Documentation/linux_tv/media/v4l/dev-overlay.rst index acbcfb4cbe57fd9c1611c3fd70b2603cf23857c6..26bd4a15a125e4e2f0e091000d42f932c1b56624 100644 --- a/Documentation/linux_tv/media/v4l/dev-overlay.rst +++ b/Documentation/linux_tv/media/v4l/dev-overlay.rst @@ -65,7 +65,7 @@ frame buffer parameters, namely the address and size of the frame buffer and the image format, for example RGB 5:6:5. The :ref:`VIDIOC_G_FBUF` and :ref:`VIDIOC_S_FBUF ` ioctls are available to get and -set these parameters, respectively. The ``VIDIOC_S_FBUF`` ioctl is +set these parameters, respectively. The :ref:`VIDIOC_S_FBUF ` ioctl is privileged because it allows to set up DMA into physical memory, bypassing the memory protection mechanisms of the kernel. Only the superuser can change the frame buffer address and size. Users are not @@ -76,8 +76,8 @@ system and program the V4L2 driver at the appropriate time. Some devices add the video overlay to the output signal of the graphics card. In this case the frame buffer is not modified by the video device, and the frame buffer address and pixel format are not needed by the -driver. The ``VIDIOC_S_FBUF`` ioctl is not privileged. An application -can check for this type of device by calling the ``VIDIOC_G_FBUF`` +driver. The :ref:`VIDIOC_S_FBUF ` ioctl is not privileged. An application +can check for this type of device by calling the :ref:`VIDIOC_G_FBUF` ioctl. A driver may support any (or none) of five clipping/blending methods: @@ -130,10 +130,10 @@ struct :ref:`v4l2_format ` to ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and call the :ref:`VIDIOC_S_FMT ` ioctl. The driver adjusts the parameters against hardware limits and returns the actual -parameters as ``VIDIOC_G_FMT`` does. Like ``VIDIOC_S_FMT``, the +parameters as :ref:`VIDIOC_G_FMT` does. Like :ref:`VIDIOC_S_FMT `, the :ref:`VIDIOC_TRY_FMT ` ioctl can be used to learn about driver capabilities without actually changing driver state. Unlike -``VIDIOC_S_FMT`` this also works after the overlay has been enabled. +:ref:`VIDIOC_S_FMT ` this also works after the overlay has been enabled. The scaling factor of the overlaid image is implied by the width and height given in struct :ref:`v4l2_window ` and the size @@ -199,7 +199,7 @@ are undefined. When the application set the ``clips`` field, this field must contain the number of clipping rectangles in the list. When clip lists are not supported the driver ignores this field, its contents - after calling ``VIDIOC_S_FMT`` are undefined. When clip lists are + after calling :ref:`VIDIOC_S_FMT ` are undefined. When clip lists are supported but no clipping is desired this field must be set to zero. ``void * bitmap`` diff --git a/Documentation/linux_tv/media/v4l/dev-raw-vbi.rst b/Documentation/linux_tv/media/v4l/dev-raw-vbi.rst index ca61dde3ad3801f1a6af27c26287df2035d0cf63..2cd813a5b4e44da6d31c0ab93df6859eb70f79e3 100644 --- a/Documentation/linux_tv/media/v4l/dev-raw-vbi.rst +++ b/Documentation/linux_tv/media/v4l/dev-raw-vbi.rst @@ -80,7 +80,7 @@ To request different parameters applications set the ``type`` field of a struct :ref:`v4l2_format ` as above and initialize all fields of the struct :ref:`v4l2_vbi_format ` ``vbi`` member of the ``fmt`` union, or better just modify the results -of ``VIDIOC_G_FMT``, and call the :ref:`VIDIOC_S_FMT ` +of :ref:`VIDIOC_G_FMT`, and call the :ref:`VIDIOC_S_FMT ` ioctl with a pointer to this structure. Drivers return an EINVAL error code only when the given parameters are ambiguous, otherwise they modify the parameters according to the hardware capabilities and return the @@ -94,10 +94,10 @@ expect other resource allocation points which may return EBUSY, at the :ref:`VIDIOC_STREAMON` ioctl and the first read(), write() and select() call. -VBI devices must implement both the ``VIDIOC_G_FMT`` and -``VIDIOC_S_FMT`` ioctl, even if ``VIDIOC_S_FMT`` ignores all requests -and always returns default parameters as ``VIDIOC_G_FMT`` does. -``VIDIOC_TRY_FMT`` is optional. +VBI devices must implement both the :ref:`VIDIOC_G_FMT` and +:ref:`VIDIOC_S_FMT ` ioctl, even if :ref:`VIDIOC_S_FMT ` ignores all requests +and always returns default parameters as :ref:`VIDIOC_G_FMT` does. +:ref:`VIDIOC_TRY_FMT ` is optional. .. _v4l2-vbi-format: diff --git a/Documentation/linux_tv/media/v4l/format.rst b/Documentation/linux_tv/media/v4l/format.rst index 46f740a0092ec2c85c55ed30fbbd244c3fcd0751..0184b5931709451768b27541be95297189367bd6 100644 --- a/Documentation/linux_tv/media/v4l/format.rst +++ b/Documentation/linux_tv/media/v4l/format.rst @@ -31,10 +31,10 @@ format. The data formats supported by the V4L2 API are covered in the respective device section in :ref:`devices`. For a closer look at image formats see :ref:`pixfmt`. -The ``VIDIOC_S_FMT`` ioctl is a major turning-point in the +The :ref:`VIDIOC_S_FMT ` ioctl is a major turning-point in the initialization sequence. Prior to this point multiple panel applications can access the same device concurrently to select the current input, -change controls or modify other properties. The first ``VIDIOC_S_FMT`` +change controls or modify other properties. The first :ref:`VIDIOC_S_FMT ` assigns a logical stream (video data, VBI data etc.) exclusively to one file descriptor. @@ -50,7 +50,7 @@ example video overlay is about to start or already in progress, simultaneous video capturing may be restricted to the same cropping and image size. -When applications omit the ``VIDIOC_S_FMT`` ioctl its locking side +When applications omit the :ref:`VIDIOC_S_FMT ` ioctl its locking side effects are implied by the next step, the selection of an I/O method with the :ref:`VIDIOC_REQBUFS` ioctl or implicit with the first :ref:`read() ` or @@ -61,11 +61,11 @@ the exception being drivers permitting simultaneous video capturing and overlay using the same file descriptor for compatibility with V4L and earlier versions of V4L2. Switching the logical stream or returning into "panel mode" is possible by closing and reopening the device. Drivers -*may* support a switch using ``VIDIOC_S_FMT``. +*may* support a switch using :ref:`VIDIOC_S_FMT `. All drivers exchanging data with applications must support the -``VIDIOC_G_FMT`` and ``VIDIOC_S_FMT`` ioctl. Implementation of the -``VIDIOC_TRY_FMT`` is highly recommended but optional. +:ref:`VIDIOC_G_FMT` and :ref:`VIDIOC_S_FMT ` ioctl. Implementation of the +:ref:`VIDIOC_TRY_FMT ` is highly recommended but optional. Image Format Enumeration diff --git a/Documentation/linux_tv/media/v4l/io.rst b/Documentation/linux_tv/media/v4l/io.rst index 651d4530c703cc23a75e16c888e50ef3bdb79ad1..77d13fdd1c280d7f563d4c41f26bf41917e79ef3 100644 --- a/Documentation/linux_tv/media/v4l/io.rst +++ b/Documentation/linux_tv/media/v4l/io.rst @@ -31,7 +31,7 @@ and drivers permitting simultaneous video capturing and overlay using the same file descriptor, for compatibility with V4L and earlier versions of V4L2. -``VIDIOC_S_FMT`` and ``VIDIOC_REQBUFS`` would permit this to some +:ref:`VIDIOC_S_FMT ` and :ref:`VIDIOC_REQBUFS` would permit this to some degree, but for simplicity drivers need not support switching the I/O method (after first switching away from read/write) other than by closing and reopening the device. diff --git a/Documentation/linux_tv/media/v4l/selection-api-004.rst b/Documentation/linux_tv/media/v4l/selection-api-004.rst index 4890815e268e41e89b744078c492f00c267067bc..1a8f4d09bff189680e8c708d43fb7adb7392b3f1 100644 --- a/Documentation/linux_tv/media/v4l/selection-api-004.rst +++ b/Documentation/linux_tv/media/v4l/selection-api-004.rst @@ -50,7 +50,7 @@ The composing targets refer to a memory buffer. The limits of composing coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All coordinates are expressed in pixels. The rectangle's top/left corner must be located at position ``(0,0)``. The width and height are equal to -the image size set by ``VIDIOC_S_FMT``. +the image size set by :ref:`VIDIOC_S_FMT `. The part of a buffer into which the image is inserted by the hardware is controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's @@ -90,7 +90,7 @@ to be inserted into a video signal or graphical screen. The limits of cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``. All coordinates are expressed in pixels. The top/left corner is always point ``(0,0)``. The width and height is equal to the image size -specified using ``VIDIOC_S_FMT`` ioctl. +specified using :ref:`VIDIOC_S_FMT ` ioctl. The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given diff --git a/Documentation/linux_tv/media/v4l/selection-api-005.rst b/Documentation/linux_tv/media/v4l/selection-api-005.rst index aefab87788db3dbc7fbae36c95298217f3b93773..6fdb0af2b13da12416fe591ed0771fb3cfdf5096 100644 --- a/Documentation/linux_tv/media/v4l/selection-api-005.rst +++ b/Documentation/linux_tv/media/v4l/selection-api-005.rst @@ -19,7 +19,7 @@ setting the field struct :ref:`v4l2_pix_format ```::bytesperline``. Introducing an image offsets could be done by modifying field struct :ref:`v4l2_buffer ```::m_userptr`` before calling -``VIDIOC_QBUF``. Those operations should be avoided because they are not +:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers. The selection API deals with configuration of buffer cropping/composing in a clear, intuitive and portable way. Next, with diff --git a/Documentation/linux_tv/media/v4l/standard.rst b/Documentation/linux_tv/media/v4l/standard.rst index 3c0f6cb97f134ccee0a791d6496d63a824756c87..ec39b2b39e67f2d08f774e6b9a198c4dca212ed7 100644 --- a/Documentation/linux_tv/media/v4l/standard.rst +++ b/Documentation/linux_tv/media/v4l/standard.rst @@ -56,8 +56,8 @@ output device which is: Here the driver shall set the ``std`` field of struct :ref:`v4l2_input ` and struct -:ref:`v4l2_output ` to zero and the ``VIDIOC_G_STD``, -``VIDIOC_S_STD``, ``VIDIOC_QUERYSTD`` and ``VIDIOC_ENUMSTD`` ioctls +:ref:`v4l2_output ` to zero and the :ref:`VIDIOC_G_STD`, +:ref:`VIDIOC_S_STD `, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls shall return the ENOTTY error code or the EINVAL error code. Applications can make use of the :ref:`input-capabilities` and diff --git a/Documentation/linux_tv/media/v4l/tuner.rst b/Documentation/linux_tv/media/v4l/tuner.rst index b1be27bd297efaec951c8d285db9d3e71be7b51c..67f4e24709b5edcc1a09cc692fd173f06398f6ef 100644 --- a/Documentation/linux_tv/media/v4l/tuner.rst +++ b/Documentation/linux_tv/media/v4l/tuner.rst @@ -24,9 +24,9 @@ inputs. To query and change tuner properties applications use the :ref:`VIDIOC_G_TUNER` and :ref:`VIDIOC_S_TUNER ` ioctls, respectively. The -struct :ref:`v4l2_tuner ` returned by ``VIDIOC_G_TUNER`` +struct :ref:`v4l2_tuner ` returned by :ref:`VIDIOC_G_TUNER` also contains signal status information applicable when the tuner of the -current video or radio input is queried. Note that ``VIDIOC_S_TUNER`` +current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER ` does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct @@ -61,7 +61,7 @@ cannot specify whether the frequency is for a tuner or a modulator. To query and change modulator properties applications use the :ref:`VIDIOC_G_MODULATOR` and :ref:`VIDIOC_S_MODULATOR ` ioctl. Note that -``VIDIOC_S_MODULATOR`` does not switch the current modulator, when there +:ref:`VIDIOC_S_MODULATOR ` does not switch the current modulator, when there is more than one at all. The modulator is solely determined by the current video output. Drivers must support both ioctls and set the ``V4L2_CAP_MODULATOR`` flag in the struct diff --git a/Documentation/linux_tv/media/v4l/vidioc-create-bufs.rst b/Documentation/linux_tv/media/v4l/vidioc-create-bufs.rst index 9220bcea1259af1e9ecd2c3b8a9f2c3600a38cdb..d269eab4d2b65c649117cb0eb58ce2fe8cbc8c36 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-create-bufs.rst @@ -94,10 +94,10 @@ than the number requested. - ``count`` - The number of buffers requested or granted. If count == 0, then - ``VIDIOC_CREATE_BUFS`` will set ``index`` to the current number of + :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of created buffers, and it will check the validity of ``memory`` and ``format.type``. If those are invalid -1 is returned and errno is - set to EINVAL error code, otherwise ``VIDIOC_CREATE_BUFS`` returns + set to EINVAL error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns 0. It will never set errno to EBUSY error code in this particular case. diff --git a/Documentation/linux_tv/media/v4l/vidioc-cropcap.rst b/Documentation/linux_tv/media/v4l/vidioc-cropcap.rst index 22b5efe1d2e4fce65f08fd6da8d856f0f4645edb..25ad9b29b1601c9cc590e25da6d0dbefefc9ac36 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-cropcap.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-cropcap.rst @@ -34,7 +34,7 @@ Description Applications use this function to query the cropping limits, the pixel aspect of images and to calculate scale factors. They set the ``type`` field of a v4l2_cropcap structure to the respective buffer (stream) -type and call the ``VIDIOC_CROPCAP`` ioctl with a pointer to this +type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this structure. Drivers fill the rest of the structure. The results are constant except when switching the video standard. Remember this switch can occur implicit when switching the video input or output. diff --git a/Documentation/linux_tv/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/linux_tv/media/v4l/vidioc-dbg-g-chip-info.rst index 12c2e5df48ace1b98647a25a98fc44817512cbd6..a1534a326bb3e236189023504e44d09c70393be9 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-dbg-g-chip-info.rst @@ -49,14 +49,14 @@ Additionally the Linux kernel must be compiled with the To query the driver applications must initialize the ``match.type`` and ``match.addr`` or ``match.name`` fields of a struct :ref:`v4l2_dbg_chip_info ` and call -``VIDIOC_DBG_G_CHIP_INFO`` with a pointer to this structure. On success +:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success the driver stores information about the selected chip in the ``name`` and ``flags`` fields. When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr`` selects the nth bridge 'chip' on the TV card. You can enumerate all chips by starting at zero and incrementing ``match.addr`` by one until -``VIDIOC_DBG_G_CHIP_INFO`` fails with an EINVAL error code. The number +:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an EINVAL error code. The number zero always selects the bridge chip itself, e. g. the chip connected to the PCI or USB bus. Non-zero numbers identify specific parts of the bridge chip such as an AC97 register block. diff --git a/Documentation/linux_tv/media/v4l/vidioc-enum-fmt.rst b/Documentation/linux_tv/media/v4l/vidioc-enum-fmt.rst index f4fc2723f01ec09738efe1ebb25927c20c7f8cf1..c838f3dbb8080a46993267310f1c4c306c397c49 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enum-fmt.rst @@ -33,7 +33,7 @@ Description To enumerate image formats applications initialize the ``type`` and ``index`` field of struct :ref:`v4l2_fmtdesc ` and call -the ``VIDIOC_ENUM_FMT`` ioctl with a pointer to this structure. Drivers +the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code. All formats are enumerable by beginning at index zero and incrementing by one until EINVAL is returned. diff --git a/Documentation/linux_tv/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/linux_tv/media/v4l/vidioc-enum-freq-bands.rst index 2f5dbe0583b47931de688865236ad19e11d50511..3999c419589a82524ee5f9d6f50c9e9c70bfecb5 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enum-freq-bands.rst @@ -35,7 +35,7 @@ Enumerates the frequency bands that a tuner or modulator supports. To do this applications initialize the ``tuner``, ``type`` and ``index`` fields, and zero out the ``reserved`` array of a struct :ref:`v4l2_frequency_band ` and call the -``VIDIOC_ENUM_FREQ_BANDS`` ioctl with a pointer to this structure. +:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure. This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. diff --git a/Documentation/linux_tv/media/v4l/vidioc-enumaudio.rst b/Documentation/linux_tv/media/v4l/vidioc-enumaudio.rst index dcca0591864ee5cd6e961c48335625e813d945df..0fc0c3eeae5f71d603a2d3d1ea6d8bdb57ff5769 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enumaudio.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enumaudio.rst @@ -33,7 +33,7 @@ Description To query the attributes of an audio input applications initialize the ``index`` field and zero out the ``reserved`` array of a struct -:ref:`v4l2_audio ` and call the ``VIDIOC_ENUMAUDIO`` +:ref:`v4l2_audio ` and call the :ref:`VIDIOC_ENUMAUDIO` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the index is out of bounds. To enumerate all audio inputs applications shall begin at index diff --git a/Documentation/linux_tv/media/v4l/vidioc-enuminput.rst b/Documentation/linux_tv/media/v4l/vidioc-enuminput.rst index 644d50679aa2bbd0f0c4a6607cdb98c7a2eadad6..131f331462b13a24948b467e5aa68b9cec81c740 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enuminput.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enuminput.rst @@ -33,7 +33,7 @@ Description To query the attributes of a video input applications initialize the ``index`` field of struct :ref:`v4l2_input ` and call the -``VIDIOC_ENUMINPUT`` ioctl with a pointer to this structure. Drivers +:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns EINVAL. diff --git a/Documentation/linux_tv/media/v4l/vidioc-enumoutput.rst b/Documentation/linux_tv/media/v4l/vidioc-enumoutput.rst index 6ccb3d094dc881e8e2bd949d6f859138c997f7b8..cb0107b9c03b80b7da0764e1602044b2f76b73da 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enumoutput.rst @@ -33,7 +33,7 @@ Description To query the attributes of a video outputs applications initialize the ``index`` field of struct :ref:`v4l2_output ` and call -the ``VIDIOC_ENUMOUTPUT`` ioctl with a pointer to this structure. +the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns diff --git a/Documentation/linux_tv/media/v4l/vidioc-enumstd.rst b/Documentation/linux_tv/media/v4l/vidioc-enumstd.rst index d16a9494d03b8347edb2c9ec56670f2f2b37d8dd..e292b7d50cc37d6e311883a0368437d7a66fc8a5 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-enumstd.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-enumstd.rst @@ -33,7 +33,7 @@ Description To query the attributes of a video standard, especially a custom (driver defined) one, applications initialize the ``index`` field of struct -:ref:`v4l2_standard ` and call the ``VIDIOC_ENUMSTD`` +:ref:`v4l2_standard ` and call the :ref:`VIDIOC_ENUMSTD` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the index is out of bounds. To enumerate all standards applications shall begin at index @@ -401,7 +401,7 @@ ENODATA .. [1] The supported standards may overlap and we need an unambiguous set to - find the current standard returned by ``VIDIOC_G_STD``. + find the current standard returned by :ref:`VIDIOC_G_STD`. .. [2] Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP). diff --git a/Documentation/linux_tv/media/v4l/vidioc-expbuf.rst b/Documentation/linux_tv/media/v4l/vidioc-expbuf.rst index e71925f3f13e4ceb1b3386913e55d3e1de56d9be..2933640e8c4e9916154961a390877cd577ba1514 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-expbuf.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-expbuf.rst @@ -53,9 +53,9 @@ Additional flags may be posted in the ``flags`` field. Refer to a manual for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All other fields must be set to zero. In the case of multi-planar API, every plane is exported separately using -multiple ``VIDIOC_EXPBUF`` calls. +multiple :ref:`VIDIOC_EXPBUF` calls. -After calling ``VIDIOC_EXPBUF`` the ``fd`` field will be set by a +After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a driver. This is a DMABUF file descriptor. The application may pass it to other DMABUF-aware devices. Refer to :ref:`DMABUF importing ` for details about importing DMABUF files into V4L2 nodes. It is diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-audio.rst b/Documentation/linux_tv/media/v4l/vidioc-g-audio.rst index 2a81d01a1c00d032f93d4555c3cf4af76c314d98..be8899d87e33a3b35b9ddf4bddd9424058c4ff2c 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-audio.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-audio.rst @@ -36,14 +36,14 @@ Description To query the current audio input applications zero out the ``reserved`` array of a struct :ref:`v4l2_audio ` and call the -``VIDIOC_G_AUDIO`` ioctl with a pointer to this structure. Drivers fill +:ref:`VIDIOC_G_AUDIO` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the device has no audio inputs, or none which combine with the current video input. Audio inputs have one writable property, the audio mode. To select the current audio input *and* change the audio mode, applications initialize the ``index`` and ``mode`` fields, and the ``reserved`` array of a -:c:type:`struct v4l2_audio` structure and call the ``VIDIOC_S_AUDIO`` +:c:type:`struct v4l2_audio` structure and call the :ref:`VIDIOC_S_AUDIO ` ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. @@ -90,7 +90,7 @@ return the actual new audio mode. - ``mode`` - Audio mode flags set by drivers and applications (on - ``VIDIOC_S_AUDIO`` ioctl), see :ref:`audio-mode`. + :ref:`VIDIOC_S_AUDIO ` ioctl), see :ref:`audio-mode`. - .. row 5 diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-crop.rst b/Documentation/linux_tv/media/v4l/vidioc-g-crop.rst index e66f8c2135355199594dde076a41640a37787d2d..0a9ede92bc9fb84afcddbddac3cbec0b77d7383d 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-crop.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-crop.rst @@ -36,13 +36,13 @@ Description To query the cropping rectangle size and position applications set the ``type`` field of a :c:type:`struct v4l2_crop` structure to the -respective buffer (stream) type and call the ``VIDIOC_G_CROP`` ioctl +respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP` ioctl with a pointer to this structure. The driver fills the rest of the structure or returns the EINVAL error code if cropping is not supported. To change the cropping rectangle applications initialize the ``type`` and struct :ref:`v4l2_rect ` substructure named ``c`` of a -v4l2_crop structure and call the ``VIDIOC_S_CROP`` ioctl with a pointer +v4l2_crop structure and call the :ref:`VIDIOC_S_CROP ` ioctl with a pointer to this structure. Do not use the multiplanar buffer types. Use @@ -64,15 +64,15 @@ the closest size possible while maintaining the current horizontal and vertical scaling factor. Finally the driver programs the hardware with the actual cropping and -image parameters. ``VIDIOC_S_CROP`` is a write-only ioctl, it does not +image parameters. :ref:`VIDIOC_S_CROP ` is a write-only ioctl, it does not return the actual parameters. To query them applications must call -``VIDIOC_G_CROP`` and :ref:`VIDIOC_G_FMT`. When the +:ref:`VIDIOC_G_CROP` and :ref:`VIDIOC_G_FMT`. When the parameters are unsuitable the application may modify the cropping or image parameters and repeat the cycle until satisfactory parameters have been negotiated. When cropping is not supported then no parameters are changed and -``VIDIOC_S_CROP`` returns the EINVAL error code. +:ref:`VIDIOC_S_CROP ` returns the EINVAL error code. .. _v4l2-crop: diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-ctrl.rst b/Documentation/linux_tv/media/v4l/vidioc-g-ctrl.rst index 2c2677a764626b213096cee93357a751aca9b3d6..41561c5e444d91c0cbb891f2890f1797b1971a18 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-ctrl.rst @@ -34,15 +34,15 @@ Description To get the current value of a control applications initialize the ``id`` field of a struct :c:type:`struct v4l2_control` and call the -``VIDIOC_G_CTRL`` ioctl with a pointer to this structure. To change the +:ref:`VIDIOC_G_CTRL` ioctl with a pointer to this structure. To change the value of a control applications initialize the ``id`` and ``value`` fields of a struct :c:type:`struct v4l2_control` and call the -``VIDIOC_S_CTRL`` ioctl. +:ref:`VIDIOC_S_CTRL ` ioctl. When the ``id`` is invalid drivers return an EINVAL error code. When the ``value`` is out of bounds drivers can choose to take the closest valid value or return an ERANGE error code, whatever seems more appropriate. -However, ``VIDIOC_S_CTRL`` is a write-only ioctl, it does not return the +However, :ref:`VIDIOC_S_CTRL ` is a write-only ioctl, it does not return the actual new value. If the ``value`` is inappropriate for the control (e.g. if it refers to an unsupported menu index of a menu control), then EINVAL error code is returned as well. diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-dv-timings.rst b/Documentation/linux_tv/media/v4l/vidioc-g-dv-timings.rst index 8a7fa1c0facfc7eb1ad1a6715a71e0b477fbb61b..cc7cf06e74ee2ad62acf498d997d28b30acff7c6 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-dv-timings.rst @@ -36,8 +36,8 @@ Description =========== To set DV timings for the input or output, applications use the -``VIDIOC_S_DV_TIMINGS`` ioctl and to get the current timings, -applications use the ``VIDIOC_G_DV_TIMINGS`` ioctl. The detailed timing +:ref:`VIDIOC_S_DV_TIMINGS ` ioctl and to get the current timings, +applications use the :ref:`VIDIOC_G_DV_TIMINGS` ioctl. The detailed timing information is filled in using the structure struct :ref:`v4l2_dv_timings `. These ioctls take a pointer to the struct :ref:`v4l2_dv_timings ` @@ -59,7 +59,7 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes ` chapter. EINVAL - This ioctl is not supported, or the ``VIDIOC_S_DV_TIMINGS`` + This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS ` parameter was unsuitable. ENODATA diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-edid.rst b/Documentation/linux_tv/media/v4l/vidioc-g-edid.rst index 0bd8f1ba84d25366902d99603960969576a10334..a1311a52b8fabfa9f3459c151f7199728e0c44bb 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-edid.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-edid.rst @@ -52,7 +52,7 @@ value, then the EINVAL error code will be returned. To get the EDID data the application has to fill in the ``pad``, ``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved`` -array and call ``VIDIOC_G_EDID``. The current EDID from block +array and call :ref:`VIDIOC_G_EDID`. The current EDID from block ``start_block`` and of size ``blocks`` will be placed in the memory ``edid`` points to. The ``edid`` pointer must point to memory at least ``blocks`` * 128 bytes large (the size of one block is 128 bytes). @@ -65,7 +65,7 @@ If blocks have to be retrieved from the sink, then this call will block until they have been read. If ``start_block`` and ``blocks`` are both set to 0 when -``VIDIOC_G_EDID`` is called, then the driver will set ``blocks`` to the +:ref:`VIDIOC_G_EDID` is called, then the driver will set ``blocks`` to the total number of available EDID blocks and it will return 0 without copying any data. This is an easy way to discover how many EDID blocks there are. Note that if there are no EDID blocks available at all, then diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-enc-index.rst b/Documentation/linux_tv/media/v4l/vidioc-g-enc-index.rst index 68af83d964f63f10b134a2cec1b150bc67db88d1..77c7eff9732d00e5ab1e76685989650f733bece1 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-enc-index.rst @@ -31,19 +31,19 @@ Arguments Description =========== -The ``VIDIOC_G_ENC_INDEX`` ioctl provides meta data about a compressed +The :ref:`VIDIOC_G_ENC_INDEX` ioctl provides meta data about a compressed video stream the same or another application currently reads from the driver, which is useful for random access into the stream without decoding it. -To read the data applications must call ``VIDIOC_G_ENC_INDEX`` with a +To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX` with a pointer to a struct :ref:`v4l2_enc_idx `. On success the driver fills the ``entry`` array, stores the number of elements written in the ``entries`` field, and initializes the ``entries_cap`` field. Each element of the ``entry`` array contains meta data about one -picture. A ``VIDIOC_G_ENC_INDEX`` call reads up to +picture. A :ref:`VIDIOC_G_ENC_INDEX` call reads up to ``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up to ``entries_cap`` entries. This number can be lower or higher than ``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/linux_tv/media/v4l/vidioc-g-ext-ctrls.rst index cebaa6ea1ba9d5fe0c9edbe28645f4ab52c9d4ee..fb62cd0a991cdc9f335947d8aab418ad5e54f6d9 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-ext-ctrls.rst @@ -48,7 +48,7 @@ by the ``controls`` fields. To get the current value of a set of controls applications initialize the ``id``, ``size`` and ``reserved2`` fields of each struct :ref:`v4l2_ext_control ` and call the -``VIDIOC_G_EXT_CTRLS`` ioctl. String controls controls must also set the +:ref:`VIDIOC_G_EXT_CTRLS` ioctl. String controls controls must also set the ``string`` field. Controls of compound types (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field. @@ -70,14 +70,14 @@ by calling :ref:`VIDIOC_QUERY_EXT_CTRL `. To change the value of a set of controls applications initialize the ``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields of each struct :ref:`v4l2_ext_control ` and call -the ``VIDIOC_S_EXT_CTRLS`` ioctl. The controls will only be set if *all* +the :ref:`VIDIOC_S_EXT_CTRLS ` ioctl. The controls will only be set if *all* control values are valid. To check if a set of controls have correct values applications initialize the ``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields of each struct :ref:`v4l2_ext_control ` and call the -``VIDIOC_TRY_EXT_CTRLS`` ioctl. It is up to the driver whether wrong +:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned. @@ -122,7 +122,7 @@ still cause this situation. - The total size in bytes of the payload of this control. This is normally 0, but for pointer controls this should be set to the size of the memory containing the payload, or that will receive - the payload. If ``VIDIOC_G_EXT_CTRLS`` finds that this value is + the payload. If :ref:`VIDIOC_G_EXT_CTRLS` finds that this value is less than is required to store the payload result, then it is set to a value large enough to store the payload result and ENOSPC is returned. Note that for string controls this ``size`` field should @@ -248,7 +248,7 @@ still cause this situation. handling controls will also accept a value of 0 here, meaning that the controls can belong to any control class. Whether drivers support this can be tested by setting ``ctrl_class`` to 0 and - calling ``VIDIOC_TRY_EXT_CTRLS`` with a ``count`` of 0. If that + calling :ref:`VIDIOC_TRY_EXT_CTRLS ` with a ``count`` of 0. If that succeeds, then the driver supports this feature. - .. row 3 @@ -321,14 +321,14 @@ still cause this situation. ``error_idx-1`` were read or written correctly, and the state of the remaining controls is undefined. - Since ``VIDIOC_TRY_EXT_CTRLS`` does not access hardware there is + Since :ref:`VIDIOC_TRY_EXT_CTRLS ` does not access hardware there is also no need to handle the validation step in this special way, so ``error_idx`` will just be set to the control that failed the validation step instead of to ``count``. This means that if - ``VIDIOC_S_EXT_CTRLS`` fails with ``error_idx`` set to ``count``, - then you can call ``VIDIOC_TRY_EXT_CTRLS`` to try to discover the + :ref:`VIDIOC_S_EXT_CTRLS ` fails with ``error_idx`` set to ``count``, + then you can call :ref:`VIDIOC_TRY_EXT_CTRLS ` to try to discover the actual control that failed the validation step. Unfortunately, - there is no ``TRY`` equivalent for ``VIDIOC_G_EXT_CTRLS``. + there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS`. - .. row 6 @@ -467,7 +467,7 @@ EINVAL :ref:`v4l2_ext_control ` ``value`` was inappropriate (e.g. the given menu index is not supported by the driver). This error code is also returned by the - ``VIDIOC_S_EXT_CTRLS`` and ``VIDIOC_TRY_EXT_CTRLS`` ioctls if two or + :ref:`VIDIOC_S_EXT_CTRLS ` and :ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls if two or more control values are in conflict. ERANGE diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-fbuf.rst b/Documentation/linux_tv/media/v4l/vidioc-g-fbuf.rst index 0d9b6972bc449c10ea8948b81422ef5512d37e04..e622e2f2435c3f1fb49a93d4342c9b24425620ad 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-fbuf.rst @@ -34,7 +34,7 @@ Arguments Description =========== -Applications can use the ``VIDIOC_G_FBUF`` and ``VIDIOC_S_FBUF`` ioctl +Applications can use the :ref:`VIDIOC_G_FBUF` and :ref:`VIDIOC_S_FBUF ` ioctl to get and set the framebuffer parameters for a :ref:`Video Overlay ` or :ref:`Video Output Overlay ` (OSD). The type of overlay is implied by the device type (capture or @@ -48,7 +48,7 @@ of a graphics card. A non-destructive overlay blends video images into a VGA signal or graphics into a video signal. *Video Output Overlays* are always non-destructive. -To get the current parameters applications call the ``VIDIOC_G_FBUF`` +To get the current parameters applications call the :ref:`VIDIOC_G_FBUF` ioctl with a pointer to a :c:type:`struct v4l2_framebuffer` structure. The driver fills all fields of the structure or returns an EINVAL error code when overlays are not supported. @@ -57,15 +57,15 @@ To set the parameters for a *Video Output Overlay*, applications must initialize the ``flags`` field of a struct :c:type:`struct v4l2_framebuffer`. Since the framebuffer is implemented on the TV card all other parameters are determined by the -driver. When an application calls ``VIDIOC_S_FBUF`` with a pointer to +driver. When an application calls :ref:`VIDIOC_S_FBUF ` with a pointer to this structure, the driver prepares for the overlay and returns the -framebuffer parameters as ``VIDIOC_G_FBUF`` does, or it returns an error +framebuffer parameters as :ref:`VIDIOC_G_FBUF` does, or it returns an error code. To set the parameters for a *non-destructive Video Overlay*, applications must initialize the ``flags`` field, the ``fmt`` -substructure, and call ``VIDIOC_S_FBUF``. Again the driver prepares for -the overlay and returns the framebuffer parameters as ``VIDIOC_G_FBUF`` +substructure, and call :ref:`VIDIOC_S_FBUF `. Again the driver prepares for +the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF` does, or it returns an error code. For a *destructive Video Overlay* applications must additionally provide @@ -486,11 +486,11 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes ` chapter. EPERM - ``VIDIOC_S_FBUF`` can only be called by a privileged user to + :ref:`VIDIOC_S_FBUF ` can only be called by a privileged user to negotiate the parameters for a destructive overlay. EINVAL - The ``VIDIOC_S_FBUF`` parameters are unsuitable. + The :ref:`VIDIOC_S_FBUF ` parameters are unsuitable. .. [1] A physical base address may not suit all platforms. GK notes in diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-fmt.rst b/Documentation/linux_tv/media/v4l/vidioc-g-fmt.rst index 1d392e6c538d1c2ce932187ab1f489ab59442ea3..8c07fe2454e2106425db998e7c68e01b3400fdaa 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-fmt.rst @@ -41,7 +41,7 @@ struct :c:type:`struct v4l2_format` to the respective buffer (stream) type. For example video capture devices use ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the -``VIDIOC_G_FMT`` ioctl with a pointer to this structure the driver fills +:ref:`VIDIOC_G_FMT` ioctl with a pointer to this structure the driver fills the respective member of the ``fmt`` union. In case of video capture devices that is either the struct :ref:`v4l2_pix_format ` ``pix`` or the struct @@ -54,32 +54,32 @@ To change the current format parameters applications initialize the For details see the documentation of the various devices types in :ref:`devices`. Good practice is to query the current parameters first, and to modify only those parameters not suitable for the -application. When the application calls the ``VIDIOC_S_FMT`` ioctl with +application. When the application calls the :ref:`VIDIOC_S_FMT ` ioctl with a pointer to a :c:type:`struct v4l2_format` structure the driver checks and adjusts the parameters against hardware abilities. Drivers should not return an error code unless the ``type`` field is invalid, this is a mechanism to fathom device capabilities and to approach parameters acceptable for both the application and driver. On success the driver may program the hardware, allocate resources and generally -prepare for data exchange. Finally the ``VIDIOC_S_FMT`` ioctl returns -the current format parameters as ``VIDIOC_G_FMT`` does. Very simple, +prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT ` ioctl returns +the current format parameters as :ref:`VIDIOC_G_FMT` does. Very simple, inflexible devices may even ignore all input and always return the default parameters. However all V4L2 devices exchanging data with the -application must implement the ``VIDIOC_G_FMT`` and ``VIDIOC_S_FMT`` +application must implement the :ref:`VIDIOC_G_FMT` and :ref:`VIDIOC_S_FMT ` ioctl. When the requested buffer type is not supported drivers return an -EINVAL error code on a ``VIDIOC_S_FMT`` attempt. When I/O is already in +EINVAL error code on a :ref:`VIDIOC_S_FMT ` attempt. When I/O is already in progress or the resource is not available for other reasons drivers return the EBUSY error code. -The ``VIDIOC_TRY_FMT`` ioctl is equivalent to ``VIDIOC_S_FMT`` with one +The :ref:`VIDIOC_TRY_FMT ` ioctl is equivalent to :ref:`VIDIOC_S_FMT ` with one exception: it does not change driver state. It can also be called at any time, never returning EBUSY. This function is provided to negotiate parameters, to learn about hardware limitations, without disabling I/O or possibly time consuming hardware preparations. Although strongly recommended drivers are not required to implement this ioctl. -The format as returned by ``VIDIOC_TRY_FMT`` must be identical to what -``VIDIOC_S_FMT`` returns for the same input or output. +The format as returned by :ref:`VIDIOC_TRY_FMT ` must be identical to what +:ref:`VIDIOC_S_FMT ` returns for the same input or output. .. _v4l2-format: diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-frequency.rst b/Documentation/linux_tv/media/v4l/vidioc-g-frequency.rst index ce247577c3a0fab42d7c32c1e0a08bfe9a5a1304..19a5ae9c4bcd19f51f396b82e0fb36832d98d676 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-frequency.rst @@ -39,15 +39,15 @@ the ``tuner`` field of a struct :ref:`v4l2_frequency ` to the respective tuner or modulator number (only input devices have tuners, only output devices have modulators), zero out the ``reserved`` array and call the -``VIDIOC_G_FREQUENCY`` ioctl with a pointer to this structure. The +:ref:`VIDIOC_G_FREQUENCY` ioctl with a pointer to this structure. The driver stores the current frequency in the ``frequency`` field. To change the current tuner or modulator radio frequency applications initialize the ``tuner``, ``type`` and ``frequency`` fields, and the ``reserved`` array of a struct :ref:`v4l2_frequency ` -and call the ``VIDIOC_S_FREQUENCY`` ioctl with a pointer to this +and call the :ref:`VIDIOC_S_FREQUENCY ` ioctl with a pointer to this structure. When the requested frequency is not possible the driver -assumes the closest possible value. However ``VIDIOC_S_FREQUENCY`` is a +assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY ` is a write-only ioctl, it does not return the actual new frequency. diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-input.rst b/Documentation/linux_tv/media/v4l/vidioc-g-input.rst index d0abf6231b7d8ae26d8c5eb41a4d461336d6ced5..2bcaa324aa3311008c7da0743d4ddeaf308e0b46 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-input.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-input.rst @@ -33,13 +33,13 @@ Description =========== To query the current video input applications call the -``VIDIOC_G_INPUT`` ioctl with a pointer to an integer where the driver +:ref:`VIDIOC_G_INPUT` ioctl with a pointer to an integer where the driver stores the number of the input, as in the struct :ref:`v4l2_input ` ``index`` field. This ioctl will fail only when there are no video inputs, returning EINVAL. To select a video input applications store the number of the desired -input in an integer and call the ``VIDIOC_S_INPUT`` ioctl with a pointer +input in an integer and call the :ref:`VIDIOC_S_INPUT ` ioctl with a pointer to this integer. Side effects are possible. For example inputs may support different video standards, so the driver may implicitly switch the current standard. Because of these possible side effects diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-modulator.rst b/Documentation/linux_tv/media/v4l/vidioc-g-modulator.rst index 4399a13f94c1e8f19273da1ce52227592d77bddb..83e761eaef2bfe25c139e1cb55faab8a813417cf 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-modulator.rst @@ -37,7 +37,7 @@ Description To query the attributes of a modulator applications initialize the ``index`` field and zero out the ``reserved`` array of a struct :ref:`v4l2_modulator ` and call the -``VIDIOC_G_MODULATOR`` ioctl with a pointer to this structure. Drivers +:ref:`VIDIOC_G_MODULATOR` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code when the index is out of bounds. To enumerate all modulators applications shall begin at index zero, incrementing by one until the driver returns @@ -46,7 +46,7 @@ EINVAL. Modulators have two writable properties, an audio modulation set and the radio frequency. To change the modulated audio subprograms, applications initialize the ``index`` and ``txsubchans`` fields and the ``reserved`` -array and call the ``VIDIOC_S_MODULATOR`` ioctl. Drivers may choose a +array and call the :ref:`VIDIOC_S_MODULATOR ` ioctl. Drivers may choose a different audio modulation if the request cannot be satisfied. However this is a write-only ioctl, it does not return the actual audio modulation selected. @@ -198,7 +198,7 @@ To change the radio frequency the ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the respective audio matrix, or the current video standard does not - permit bilingual audio the ``VIDIOC_S_MODULATOR`` ioctl shall + permit bilingual audio the :ref:`VIDIOC_S_MODULATOR ` ioctl shall return an EINVAL error code and the driver shall fall back to mono or stereo mode. @@ -230,7 +230,7 @@ To change the radio frequency the ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the hardware does not support the respective audio matrix, or the current video standard does not permit SAP the - ``VIDIOC_S_MODULATOR`` ioctl shall return an EINVAL error code and + :ref:`VIDIOC_S_MODULATOR ` ioctl shall return an EINVAL error code and driver shall fall back to mono or stereo mode. - .. row 6 diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-output.rst b/Documentation/linux_tv/media/v4l/vidioc-g-output.rst index a38d6a118cf486479c6fe3443d09c596cf330a82..ebed04ae48daa50758ad68707c7aa3f77739f5ad 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-output.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-output.rst @@ -33,14 +33,14 @@ Description =========== To query the current video output applications call the -``VIDIOC_G_OUTPUT`` ioctl with a pointer to an integer where the driver +:ref:`VIDIOC_G_OUTPUT` ioctl with a pointer to an integer where the driver stores the number of the output, as in the struct :ref:`v4l2_output ` ``index`` field. This ioctl will fail only when there are no video outputs, returning the EINVAL error code. To select a video output applications store the number of the desired -output in an integer and call the ``VIDIOC_S_OUTPUT`` ioctl with a +output in an integer and call the :ref:`VIDIOC_S_OUTPUT ` ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly switch the current standard. standard. Because of these possible side diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-parm.rst b/Documentation/linux_tv/media/v4l/vidioc-g-parm.rst index 07432d386356d89ee4e21897d719f5a7644781d3..906faaa85bfad4ee966d069c9891718943ae0c0d 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-parm.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-parm.rst @@ -44,7 +44,7 @@ internally by a driver in read/write mode. For implications see the section discussing the :ref:`read() ` function. To get and set the streaming parameters applications call the -``VIDIOC_G_PARM`` and ``VIDIOC_S_PARM`` ioctl, respectively. They take a +:ref:`VIDIOC_G_PARM` and :ref:`VIDIOC_S_PARM ` ioctl, respectively. They take a pointer to a struct :c:type:`struct v4l2_streamparm` which contains a union holding separate parameters for input and output devices. diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-priority.rst b/Documentation/linux_tv/media/v4l/vidioc-g-priority.rst index ee80c9e0c7d476d19133069a9841b1f7f0760324..db95647d3a80283e7e35a738e0e874a0d236d06c 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-priority.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-priority.rst @@ -36,11 +36,11 @@ Description =========== To query the current access priority applications call the -``VIDIOC_G_PRIORITY`` ioctl with a pointer to an enum v4l2_priority +:ref:`VIDIOC_G_PRIORITY` ioctl with a pointer to an enum v4l2_priority variable where the driver stores the current priority. To request an access priority applications store the desired priority in -an enum v4l2_priority variable and call ``VIDIOC_S_PRIORITY`` ioctl +an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY ` ioctl with a pointer to this variable. diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst index 8c86d2b41a5bb638dfc08cc39607620c72a21a15..635cb9b2c250d7d9d5e400265ae8fc4ca2522cbc 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -34,7 +34,7 @@ Description To find out which data services are supported by a sliced VBI capture or output device, applications initialize the ``type`` field of a struct :ref:`v4l2_sliced_vbi_cap `, clear the -``reserved`` array and call the ``VIDIOC_G_SLICED_VBI_CAP`` ioctl. The +``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP` ioctl. The driver fills in the remaining fields or returns an EINVAL error code if the sliced VBI API is unsupported or ``type`` is invalid. diff --git a/Documentation/linux_tv/media/v4l/vidioc-g-std.rst b/Documentation/linux_tv/media/v4l/vidioc-g-std.rst index fa9da29e06574ce9efdf340c70ba58ac8c5f3d92..bc8e071401b021a1bae339c04232da8db119d44c 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-g-std.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-g-std.rst @@ -35,15 +35,15 @@ Description =========== To query and select the current video standard applications use the -``VIDIOC_G_STD`` and ``VIDIOC_S_STD`` ioctls which take a pointer to a -:ref:`v4l2_std_id ` type as argument. ``VIDIOC_G_STD`` +:ref:`VIDIOC_G_STD` and :ref:`VIDIOC_S_STD ` ioctls which take a pointer to a +:ref:`v4l2_std_id ` type as argument. :ref:`VIDIOC_G_STD` can return a single flag or a set of flags as in struct :ref:`v4l2_standard ` field ``id``. The flags must be unambiguous such that they appear in only one enumerated :c:type:`struct v4l2_standard` structure. -``VIDIOC_S_STD`` accepts one or more flags, being a write-only ioctl it -does not return the actual new standard as ``VIDIOC_G_STD`` does. When +:ref:`VIDIOC_S_STD ` accepts one or more flags, being a write-only ioctl it +does not return the actual new standard as :ref:`VIDIOC_G_STD` does. When no flags are given or the current input does not support the requested standard the driver returns an EINVAL error code. When the standard set is ambiguous drivers may return EINVAL or choose any of the requested @@ -61,7 +61,7 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes ` chapter. EINVAL - The ``VIDIOC_S_STD`` parameter was unsuitable. + The :ref:`VIDIOC_S_STD ` parameter was unsuitable. ENODATA Standard video timings are not supported for this input or output. diff --git a/Documentation/linux_tv/media/v4l/vidioc-overlay.rst b/Documentation/linux_tv/media/v4l/vidioc-overlay.rst index fe9084147b93ed424f17a302905c71674f2f563a..10faf25173921f480795f2e04c8b7651c1954c8a 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-overlay.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-overlay.rst @@ -32,7 +32,7 @@ Description =========== This ioctl is part of the :ref:`video overlay ` I/O method. -Applications call ``VIDIOC_OVERLAY`` to start or stop the overlay. It +Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It takes a pointer to an integer which must be set to zero by the application to stop overlay, to one to start. diff --git a/Documentation/linux_tv/media/v4l/vidioc-prepare-buf.rst b/Documentation/linux_tv/media/v4l/vidioc-prepare-buf.rst index fb3ac38b3db207d25ac9965d67a481e2541128e9..0b51c587701bab62aa62c97c6864d75f8db240ed 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-prepare-buf.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-prepare-buf.rst @@ -31,9 +31,9 @@ Arguments Description =========== -Applications can optionally call the ``VIDIOC_PREPARE_BUF`` ioctl to +Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to pass ownership of the buffer to the driver before actually enqueuing it, -using the ``VIDIOC_QBUF`` ioctl, and to prepare it for future I/O. Such +using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such preparations may include cache invalidation or cleaning. Performing them in advance saves time during the actual I/O. In case such cache operations are not required, the application can use one of diff --git a/Documentation/linux_tv/media/v4l/vidioc-query-dv-timings.rst b/Documentation/linux_tv/media/v4l/vidioc-query-dv-timings.rst index ba78f7e5bbe8adf47580a003d7b8e7171180a82c..0120432de9896ec6ec2eef8f3dfddd49d8b948ec 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-query-dv-timings.rst @@ -34,18 +34,18 @@ Description The hardware may be able to detect the current DV timings automatically, similar to sensing the video standard. To do so, applications call -``VIDIOC_QUERY_DV_TIMINGS`` with a pointer to a struct +:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct :ref:`v4l2_dv_timings `. Once the hardware detects the timings, it will fill in the timings structure. Please note that drivers shall *not* switch timings automatically if new timings are detected. Instead, drivers should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect -that userspace will take action by calling ``VIDIOC_QUERY_DV_TIMINGS``. +that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`. The reason is that new timings usually mean different buffer sizes as well, and you cannot change buffer sizes on the fly. In general, applications that receive the Source Change event will have to call -``VIDIOC_QUERY_DV_TIMINGS``, and if the detected timings are valid they +:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they will have to stop streaming, set the new timings, allocate new buffers and start streaming again. diff --git a/Documentation/linux_tv/media/v4l/vidioc-querybuf.rst b/Documentation/linux_tv/media/v4l/vidioc-querybuf.rst index 744cd9da45a3552f1a7a179adb12ad67069a5c06..280fb795c0b9d6cf4cacd14dc3d67f4d74db761c 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-querybuf.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-querybuf.rst @@ -48,7 +48,7 @@ using the :ref:`multi-planar API `, the ``m.planes`` field must contain a userspace pointer to an array of struct :ref:`v4l2_plane ` and the ``length`` field has to be set to the number of elements in that array. After calling -``VIDIOC_QUERYBUF`` with a pointer to this structure drivers return an +:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an error code or fill the rest of the structure. In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, diff --git a/Documentation/linux_tv/media/v4l/vidioc-querystd.rst b/Documentation/linux_tv/media/v4l/vidioc-querystd.rst index 1d825fff9d156aa522ec36c7f5383aef62841e06..29ce879a708b60725d47e4dc530bbaafc124e2ce 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-querystd.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-querystd.rst @@ -32,7 +32,7 @@ Description =========== The hardware may be able to detect the current video standard -automatically. To do so, applications call ``VIDIOC_QUERYSTD`` with a +automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a pointer to a :ref:`v4l2_std_id ` type. The driver stores here a set of candidates, this can be a single flag or a set of supported standards if for example the hardware can only distinguish @@ -45,10 +45,10 @@ Please note that drivers shall *not* switch the video standard automatically if a new video standard is detected. Instead, drivers should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect that userspace will take action by calling -``VIDIOC_QUERYSTD``. The reason is that a new video standard can mean +:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean different buffer sizes as well, and you cannot change buffer sizes on the fly. In general, applications that receive the Source Change event -will have to call ``VIDIOC_QUERYSTD``, and if the detected video +will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video standard is valid they will have to stop streaming, set the new standard, allocate new buffers and start streaming again. diff --git a/Documentation/linux_tv/media/v4l/vidioc-reqbufs.rst b/Documentation/linux_tv/media/v4l/vidioc-reqbufs.rst index c17d3b0465d60aaef039d95e1faa6818529cc958..451cf7b11c3db959860b12419b3fc4024016683f 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-reqbufs.rst @@ -58,7 +58,7 @@ buffers, one displayed and one filled by the application. When the I/O method is not supported the ioctl returns an EINVAL error code. -Applications can call ``VIDIOC_REQBUFS`` again to change the number of +Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of buffers, however this cannot succeed when any buffers are still mapped. A ``count`` value of zero frees all buffers, after aborting or finishing any DMA in progress, an implicit diff --git a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-interval.rst index ab136878603881eb762ca461ba1eb90576c43279..07ad0a98ead26e89105f2e3ea3aeee6f6ee3680f 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -44,7 +44,7 @@ when enumerating frame intervals. To enumerate frame intervals applications initialize the ``index``, ``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct :ref:`v4l2_subdev_frame_interval_enum ` -and call the ``VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL`` ioctl with a pointer +and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code if one of the input fields is invalid. All frame intervals are enumerable by beginning at index zero and incrementing by diff --git a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-size.rst index e08de60407574eba1db3c3a7b4e929b60bcca949..39393ef11590cc819fc059a967c5b27316b37bff 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -40,7 +40,7 @@ ioctl. To enumerate frame sizes applications initialize the ``pad``, ``which`` , ``code`` and ``index`` fields of the struct :ref:`v4l2_subdev_mbus_code_enum ` and -call the ``VIDIOC_SUBDEV_ENUM_FRAME_SIZE`` ioctl with a pointer to the +call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the structure. Drivers fill the minimum and maximum frame sizes or return an EINVAL error code if one of the input parameters is invalid. diff --git a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-mbus-code.rst index 0daf410c154641f2d20e24423aac82f48df738fa..f50a1f1c68d586a7118f8ce4e8c150afb5e8bf8a 100644 --- a/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/linux_tv/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -35,7 +35,7 @@ To enumerate media bus formats available at a given sub-device pad applications initialize the ``pad``, ``which`` and ``index`` fields of struct :ref:`v4l2_subdev_mbus_code_enum ` and -call the ``VIDIOC_SUBDEV_ENUM_MBUS_CODE`` ioctl with a pointer to this +call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an EINVAL error code if either the ``pad`` or ``index`` are invalid. All media bus formats are enumerable by beginning at index zero and incrementing by