[media] docs-rst: simplify c:type: cross references

Media device

^^^^^^^^^^^^

A media device is represented by a :c:type:`struct media_device <media_device>`

A media device is represented by a struct :c:type:`media_device`

instance, defined in ``include/media/media-device.h``.

Allocation of the structure is handled by the media device driver, usually by

embedding the :c:type:`media_device` instance in a larger driver-specific

Entities

^^^^^^^^

Entities are represented by a :c:type:`struct media_entity <media_entity>`

Entities are represented by a struct :c:type:`media_entity`

instance, defined in ``include/media/media-entity.h``. The structure is usually

embedded into a higher-level structure, such as

:c:type:`v4l2_subdev` or :c:type:`video_device`

^^^^^^^^^^

Interfaces are represented by a

:c:type:`struct media_interface <media_interface>` instance, defined in

struct :c:type:`media_interface` instance, defined in

``include/media/media-entity.h``. Currently, only one type of interface is

defined: a device node. Such interfaces are represented by a

:c:type:`struct media_intf_devnode <media_intf_devnode>`.

struct :c:type:`media_intf_devnode`.

Drivers initialize and create device node interfaces by calling

:c:func:`media_devnode_create()`

Pads

^^^^

Pads are represented by a :c:type:`struct media_pad <media_pad>` instance,

Pads are represented by a struct :c:type:`media_pad` instance,

defined in ``include/media/media-entity.h``. Each entity stores its pads in

a pads array managed by the entity driver. Drivers usually embed the array in

a driver-specific structure.

Pads are identified by their entity and their 0-based index in the pads

array.

Both information are stored in the :c:type:`struct media_pad <media_pad>`,

making the :c:type:`struct media_pad <media_pad>` pointer the canonical way

Both information are stored in the struct :c:type:`media_pad`,

making the struct :c:type:`media_pad` pointer the canonical way

to store and pass link references.

Pads have flags that describe the pad capabilities and state.

Links

^^^^^

Links are represented by a :c:type:`struct media_link <media_link>` instance,

Links are represented by a struct :c:type:`media_link` instance,

defined in ``include/media/media-entity.h``. There are two types of links:

**1. pad to pad links**:

Due to the wide differences between drivers regarding power management

needs, the media controller does not implement power management. However,

the :c:type:`struct media_entity <media_entity>` includes a ``use_count``

the struct :c:type:`media_entity` includes a ``use_count``

field that media drivers

can use to track the number of users of every entity for power management

needs.

The function will mark all entities connected to the given entity through

enabled links, either directly or indirectly, as streaming.

The :c:type:`struct media_pipeline <media_pipeline>` instance pointed to by

The struct :c:type:`media_pipeline` instance pointed to by

the pipe argument will be stored in every entity in the pipeline.

Drivers should embed the :c:type:`struct media_pipeline <media_pipeline>`

Drivers should embed the struct :c:type:`media_pipeline`

in higher-level pipeline structures and can then access the

pipeline through the :c:type:`struct media_entity <media_entity>`

pipeline through the struct :c:type:`media_entity`

pipe field.

Calls to :c:func:`media_entity_pipeline_start()` can be nested.

.. note::

   On Linux DVB API version 3, setting a frontend were done via

   :c:type:`struct dvb_frontend_parameters <dvb_frontend_parameters>`.

   struct :c:type:`dvb_frontend_parameters`.

   This got replaced on version 5 (also called "S2API", as this API were

   added originally_enabled to provide support for DVB-S2), because the

   old API has a very limited support to new standards and new hardware.

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 <v4l2_buffer>`,

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

argument to the :ref:`VIDIOC_QUERYBUF`,

:ref:`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 <v4l2_buffer>`,

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

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

:c:type:`struct v4l2_plane <v4l2_plane>` instead. In that case, struct

:c:type:`struct v4l2_buffer <v4l2_buffer>` contains an array of plane structures.

struct :c:type:`v4l2_plane` instead. In that case, struct

struct :c:type:`v4l2_buffer` contains an array of plane structures.

Dequeued video buffers come with timestamps. The driver decides at which

part of the frame and with which clock the timestamp is taken. Please

       -  When using the multi-planar API, contains a userspace pointer to

	  an array of struct :c:type:`v4l2_plane`. The size of

	  the array should be put in the ``length`` field of this

	  :c:type:`struct v4l2_buffer <v4l2_buffer>` structure.

	  struct :c:type:`v4l2_buffer` structure.

    -  .. row 15

Timecodes

=========

The :c:type:`struct v4l2_timecode <v4l2_timecode>` structure is designed to hold a

The struct :c:type:`v4l2_timecode` structure is designed to hold a

:ref:`smpte12m` or similar timecode. (struct

:c:type:`struct timeval` timestamps are stored in struct

:c:type:`v4l2_buffer` field ``timestamp``.)

:c:type:`v4l2_format` to

``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the

:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the

:c:type:`struct v4l2_window <v4l2_window>` substructure named ``win``. It is not

struct :c:type:`v4l2_window` substructure named ``win``. It is not

possible to retrieve a previously programmed clipping list or bitmap.

To program the source rectangle applications set the ``type`` field of a

struct :c:type:`v4l2_format` to

``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the

:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the

:c:type:`struct v4l2_window <v4l2_window>` substructure named ``win``. It is not

struct :c:type:`v4l2_window` substructure named ``win``. It is not

possible to retrieve a previously programmed clipping list or bitmap.

To program the overlay window applications set the ``type`` field of a