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

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. c:namespace:: MC

.. _media-func-close:

media-close - Close a media device

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

===========

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

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. c:namespace:: MC

.. _media-func-ioctl:

media-ioctl - Control a media device

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

``argp``

    Pointer to a request-specific structure.

Description

===========

requests, their respective function and parameters are specified in

:ref:`media-user-func`.

Return Value

============

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. c:namespace:: MC

.. _media-func-open:

media-open - Open a media device

Synopsis

========

    #include <fcntl.h>

.. c:function:: int open( const char *device_name, int flags )

    :name: mc-open

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.

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:

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. c:namespace:: MC

.. _media_ioc_device_info:

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

===========

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}|

    :stub-columns: 0

    :widths:       1 1 2

    *  -  char

       -  ``driver``\ [16]

       -  Name of the driver implementing the media API as a NUL-terminated

       -  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.

used instead. The ``bus_info`` field is guaranteed to be unique, but can

vary across reboots or device unplug/replug.

Return Value

============

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. c:namespace:: MC

.. _media_ioc_enum_entities:

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

===========

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}|

    *  - }

       -

Return Value

============