openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

media: docs: make MC documents more compatible with Sphinx 3.1+ 

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab 2020-09-24 16:57:41 +02:00
parent f9b2e8aa32
commit 937e68053d
15 changed files with 52 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Documentation/userspace-api/media/mediactl/media-func-close.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media-func-close:
@ -11,7 +12,6 @@ Name
media-close - Close a media device
Synopsis
========
@ -19,16 +19,13 @@ Synopsis
#include <unistd.h>
.. c:function:: int close( int fd )
:name: mc-close
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <mc-open>`.
File descriptor returned by :c:func:`open()`.
Description
===========
@ -36,11 +33,10 @@ Description
Closes the media device. Resources associated with the file descriptor
are freed. The device configuration remain unchanged.
Return Value
============
:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
:c:func:`close()` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
EBADF

10
Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media-func-ioctl:
@ -11,7 +12,6 @@ Name
media-ioctl - Control a media device
Synopsis
========
@ -19,15 +19,13 @@ Synopsis
#include <sys/ioctl.h>
.. c:function:: int ioctl( int fd, int request, void *argp )
:name: mc-ioctl
``int ioctl(int fd, int request, void *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open() <mc-open>`.
File descriptor returned by :c:func:`open()`.
``request``
Media ioctl request code as defined in the media.h header file, for
@ -36,7 +34,6 @@ Arguments
``argp``
Pointer to a request-specific structure.
Description
===========
@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl
requests, their respective function and parameters are specified in
:ref:`media-user-func`.
Return Value
============

10
Documentation/userspace-api/media/mediactl/media-func-open.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media-func-open:
@ -11,7 +12,6 @@ Name
media-open - Open a media device
Synopsis
========
@ -19,9 +19,7 @@ Synopsis
#include <fcntl.h>
.. c:function:: int open( const char *device_name, int flags )
:name: mc-open
Arguments
=========
@ -33,11 +31,10 @@ Arguments
Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
Other flags have no effect.
Description
===========
To open a media device applications call :ref:`open() <media-func-open>` with the
To open a media device applications call :c:func:`open()` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
@ -45,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
Return Value
============
:ref:`open() <func-open>` returns the new file descriptor on success. On error,
:c:func:`open()` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
are:

13
Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_device_info:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_DEVICE_INFO - Query device information
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
:name: MEDIA_IOC_DEVICE_INFO
.. c:macro:: MEDIA_IOC_DEVICE_INFO
``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_device_info`.
Description
===========
@ -38,7 +37,6 @@ a struct :c:type:`media_device_info`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.
.. c:type:: media_device_info
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@ -48,7 +46,6 @@ ioctl never fails.
:stub-columns: 0
:widths: 1 1 2
* - char
- ``driver``\ [16]
- Name of the driver implementing the media API as a NUL-terminated
@ -94,7 +91,6 @@ ioctl never fails.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
@ -102,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.
Return Value
============

11
Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_enum_entities:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp )
:name: MEDIA_IOC_ENUM_ENTITIES
.. c:macro:: MEDIA_IOC_ENUM_ENTITIES
``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_entity_desc`.
Description
===========
@ -49,7 +48,6 @@ Entity IDs can be non-contiguous. Applications must *not* try to
enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
id's until they get an error.
.. c:type:: media_entity_desc
.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}|
@ -136,7 +134,6 @@ id's until they get an error.
* - }
-
Return Value
============

13
Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_enum_links:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
:name: MEDIA_IOC_ENUM_LINKS
.. c:macro:: MEDIA_IOC_ENUM_LINKS
``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_links_enum`.
Description
===========
@ -53,7 +52,6 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
Only forward links that originate at one of the entity's source pads are
returned during the enumeration process.
.. c:type:: media_links_enum
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@ -82,7 +80,6 @@ returned during the enumeration process.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
.. c:type:: media_pad_desc
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@ -110,7 +107,6 @@ returned during the enumeration process.
the array to zero.
.. c:type:: media_link_desc
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@ -137,7 +133,6 @@ returned during the enumeration process.
- Reserved for future extensions. Drivers and applications must set
the array to zero.
Return Value
============

14
Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_g_topology:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
:name: MEDIA_IOC_G_TOPOLOGY
.. c:macro:: MEDIA_IOC_G_TOPOLOGY
``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_v2_topology`.
Description
===========
@ -120,7 +119,6 @@ desired arrays with the media graph elements.
converted to a 64-bits integer. It can be zero. if zero, the ioctl
won't store the links. It will just update ``num_links``
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_entity
@ -158,7 +156,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_interface
@ -192,7 +189,6 @@ desired arrays with the media graph elements.
- Used only for device node interfaces. See
:c:type:`media_v2_intf_devnode` for details.
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_intf_devnode
@ -245,7 +241,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
.. c:type:: media_v2_link
@ -282,7 +277,6 @@ desired arrays with the media graph elements.
- Reserved for future extensions. Drivers and applications must set
this array to zero.
Return Value
============

11
Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_request_alloc:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_REQUEST_ALLOC - Allocate a request
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
:name: MEDIA_IOC_REQUEST_ALLOC
.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to an integer.
Description
===========
@ -51,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
for the request to complete.
The request will remain allocated until all the file descriptors associated
with it are closed by :ref:`close() <request-func-close>` and the driver no
with it are closed by :c:func:`close()` and the driver no
longer uses the request internally. See also
:ref:`here <media-request-life-time>` for more information.

10
Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_ioc_setup_link:
@ -11,24 +12,22 @@ Name
MEDIA_IOC_SETUP_LINK - Modify the properties of a link
Synopsis
========
.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
:name: MEDIA_IOC_SETUP_LINK
.. c:macro:: MEDIA_IOC_SETUP_LINK
``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <media-func-open>`.
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`media_link_desc`.
Description
===========
@ -53,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code.
If the specified link can't be found the driver returns with an ``EINVAL``
error code.
Return Value
============

7
Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_request_ioc_queue:
@ -11,13 +12,12 @@ Name
MEDIA_REQUEST_IOC_QUEUE - Queue a request
Synopsis
========
.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
:name: MEDIA_REQUEST_IOC_QUEUE
.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
Arguments
=========
@ -25,7 +25,6 @@ Arguments
``request_fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
Description
===========

8
Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media_request_ioc_reinit:
@ -11,13 +12,12 @@ Name
MEDIA_REQUEST_IOC_REINIT - Re-initialize a request
Synopsis
========
.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT )
:name: MEDIA_REQUEST_IOC_REINIT
.. c:macro:: MEDIA_REQUEST_IOC_REINIT
``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)``
Arguments
=========
@ -33,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated
request.
Re-initializing a request will clear any existing data from the request.
This avoids having to :ref:`close() <request-func-close>` a completed
This avoids having to :c:func:`close()` a completed
request and allocate a new request. Instead the completed request can just
be re-initialized and it is ready to be used again.

5
Documentation/userspace-api/media/mediactl/request-api.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _media-request-api:
@ -93,7 +94,7 @@ regardless of whether a request is in use or not.
Setting the same control through a request and also directly can lead to
undefined behavior!
User-space can :ref:`poll() <request-func-poll>` a request file descriptor in
User-space can :c:func:`poll()` a request file descriptor in
order to wait until the request completes. A request is considered complete
once all its associated buffers are available for dequeuing and all the
associated controls have been updated with the values at the time of completion.
@ -115,7 +116,7 @@ Recycling and Destruction
-------------------------
Finally, a completed request can either be discarded or be reused. Calling
:ref:`close() <request-func-close>` on a request file descriptor will make
:c:func:`close()` on a request file descriptor will make
that file descriptor unusable and the request will be freed once it is no
longer in use by the kernel. That is, if the request is queued and then the
file descriptor is closed, then it won't be freed until the driver completed

8
Documentation/userspace-api/media/mediactl/request-func-close.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC.request
.. _request-func-close:
@ -11,7 +12,6 @@ Name
request-close - Close a request file descriptor
Synopsis
========
@ -19,9 +19,7 @@ Synopsis
#include <unistd.h>
.. c:function:: int close( int fd )
:name: req-close
Arguments
=========
@ -29,7 +27,6 @@ Arguments
``fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
Description
===========
@ -38,11 +35,10 @@ are freed once all file descriptors associated with the request are closed
and the driver has completed the request.
See :ref:`here <media-request-life-time>` for more information.
Return Value
============
:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is
:c:func:`close()` returns 0 on success. On error, -1 is
returned, and ``errno`` is set appropriately. Possible error codes are:
EBADF

8
Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _request-func-ioctl:
@ -11,7 +12,6 @@ Name
request-ioctl - Control a request file descriptor
Synopsis
========
@ -19,9 +19,7 @@ Synopsis
#include <sys/ioctl.h>
.. c:function:: int ioctl( int fd, int cmd, void *argp )
:name: req-ioctl
``int ioctl(int fd, int cmd, void *argp)``
Arguments
=========
@ -36,7 +34,6 @@ Arguments
``argp``
Pointer to a request-specific structure.
Description
===========
@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl
commands, their respective function and parameters are specified in
:ref:`media-user-func`.
Return Value
============

12
Documentation/userspace-api/media/mediactl/request-func-poll.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _request-func-poll:
@ -11,7 +12,6 @@ Name
request-poll - Wait for some event on a file descriptor
Synopsis
========
@ -19,9 +19,7 @@ Synopsis
#include <sys/poll.h>
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
:name: request-poll
Arguments
=========
@ -35,14 +33,13 @@ Arguments
``timeout``
Timeout to wait for events
Description
===========
With the :c:func:`poll() <request-func-poll>` function applications can wait
With the :c:func:`poll()` function applications can wait
for a request to complete.
On success :c:func:`poll() <request-func-poll>` returns the number of file
On success :c:func:`poll()` returns the number of file
descriptors that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
@ -53,11 +50,10 @@ set appropriately.
Attempting to poll for a request that is not yet queued will
set the ``POLLERR`` flag in ``revents``.
Return Value
============
On success, :c:func:`poll() <request-func-poll>` returns the number of
On success, :c:func:`poll()` returns the number of
structures which have non-zero ``revents`` fields, or zero if the call
timed out. On error -1 is returned, and the ``errno`` variable is set
appropriately: