[media] doc-rst: add media.h header to media contrller

Adding the header file is interesting for several reasons:

1) It makes MC documentation consistend with other parts;
2) The header file can be used as a quick index to all API
elements;
3) The cross-reference check helps to identify symbols that
aren't documented.

Signed-off-by: Mauro Carvalho Chehab <[e-mail]>

Documentation/media/Makefile

···
 SRC_DIR=$(srctree)/Documentation/media
 
 FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
-	  videodev2.h.rst
+	  videodev2.h.rst media.h.rst
 
 TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
···
 	@$($(quiet)gen_rst)
 
 $(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions
+	@$($(quiet)gen_rst)
+
+$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions
 	@$($(quiet)gen_rst)
 
 cleandocs:

Documentation/media/media.h.rst.exceptions

···
+# Ignore header name
+ignore define __LINUX_MEDIA_H
+
+# Ignore macros
+ignore define MEDIA_API_VERSION
+ignore define MEDIA_ENT_F_BASE
+ignore define MEDIA_ENT_F_OLD_BASE
+ignore define MEDIA_ENT_F_OLD_SUBDEV_BASE
+ignore define MEDIA_INTF_T_DVB_BASE
+ignore define MEDIA_INTF_T_V4L_BASE
+ignore define MEDIA_INTF_T_ALSA_BASE
+
+#ignore legacy entity type macros
+ignore define MEDIA_ENT_TYPE_SHIFT
+ignore define MEDIA_ENT_TYPE_MASK
+ignore define MEDIA_ENT_SUBTYPE_MASK
+ignore define MEDIA_ENT_T_DEVNODE_UNKNOWN
+ignore define MEDIA_ENT_T_DEVNODE
+ignore define MEDIA_ENT_T_DEVNODE_V4L
+ignore define MEDIA_ENT_T_DEVNODE_FB
+ignore define MEDIA_ENT_T_DEVNODE_ALSA
+ignore define MEDIA_ENT_T_DEVNODE_DVB
+ignore define MEDIA_ENT_T_UNKNOWN
+ignore define MEDIA_ENT_T_V4L2_VIDEO
+ignore define MEDIA_ENT_T_V4L2_SUBDEV
+ignore define MEDIA_ENT_T_V4L2_SUBDEV_SENSOR
+ignore define MEDIA_ENT_T_V4L2_SUBDEV_FLASH
+ignore define MEDIA_ENT_T_V4L2_SUBDEV_LENS
+ignore define MEDIA_ENT_T_V4L2_SUBDEV_DECODER
+ignore define MEDIA_ENT_T_V4L2_SUBDEV_TUNER

Documentation/media/uapi/mediactl/media-controller.rst

···
     media-controller-intro
     media-controller-model
     media-types
-
+    media-header
 
 .. _media-user-func:
 

Documentation/media/uapi/mediactl/media-header.rst

···
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_header:
+
+****************************
+Media Controller Header File
+****************************
+
+.. kernel-include:: $BUILDDIR/media.h.rst
+

Documentation/media/uapi/mediactl/media-ioc-device-info.rst

···
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _media-ioc-device-info:
+.. _media_ioc_device_info:
 
 ***************************
 ioctl MEDIA_IOC_DEVICE_INFO

Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst

···
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _media-ioc-enum-entities:
+.. _media_ioc_enum_entities:
 
 *****************************
 ioctl MEDIA_IOC_ENUM_ENTITIES
···
 call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
 structure. The driver fills the rest of the structure or returns an
 EINVAL error code when the id is invalid.
+
+.. _media-ent-id-flag-next:
 
 Entities can be enumerated by or'ing the id with the
 ``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information

Documentation/media/uapi/mediactl/media-ioc-enum-links.rst

···
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _media-ioc-enum-links:
+.. _media_ioc_enum_links:
 
 **************************
 ioctl MEDIA_IOC_ENUM_LINKS
···
 If the ``pads`` field is not NULL, the driver fills the ``pads`` array
 with information about the entity's pads. The array must have enough
 room to store all the entity's pads. The number of pads can be retrieved
-with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
-ioctl.
+with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
 
 If the ``links`` field is not NULL, the driver fills the ``links`` array
 with information about the entity's outbound links. The array must have
 enough room to store all the entity's outbound links. The number of
-outbound links can be retrieved with the
-:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
+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.

Documentation/media/uapi/mediactl/media-ioc-g-topology.rst

···
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _media-g-topology:
+.. _media_ioc_g_topology:
 
 **************************
 ioctl MEDIA_IOC_G_TOPOLOGY

Documentation/media/uapi/mediactl/media-ioc-setup-link.rst

···
 .. -*- coding: utf-8; mode: rst -*-
 
-.. _media-ioc-setup-link:
+.. _media_ioc_setup_link:
 
 **************************
 ioctl MEDIA_IOC_SETUP_LINK

Documentation/media/uapi/mediactl/media-types.rst

···
 
     -  .. row 1
 
+       ..  _MEDIA-ENT-F-UNKNOWN:
+       .. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN:
+
        -  ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
 
        -  Unknown entity. That generally indicates that a driver didn't
···
 
     -  .. row 2
 
+       ..  _MEDIA-ENT-F-IO-V4L:
+
        -  ``MEDIA_ENT_F_IO_V4L``
 
        -  Data streaming input and/or output entity.
 
     -  .. row 3
+
+       ..  _MEDIA-ENT-F-IO-VBI:
 
        -  ``MEDIA_ENT_F_IO_VBI``
 
···
 
     -  .. row 4
 
+       ..  _MEDIA-ENT-F-IO-SWRADIO:
+
        -  ``MEDIA_ENT_F_IO_SWRADIO``
 
        -  V4L Software Digital Radio (SDR) streaming input or output entity
 
     -  .. row 5
+
+       ..  _MEDIA-ENT-F-IO-DTV:
 
        -  ``MEDIA_ENT_F_IO_DTV``
 
···
 
     -  .. row 6
 
+       ..  _MEDIA-ENT-F-DTV-DEMOD:
+
        -  ``MEDIA_ENT_F_DTV_DEMOD``
 
        -  Digital TV demodulator entity.
 
     -  .. row 7
+
+       ..  _MEDIA-ENT-F-TS-DEMUX:
 
        -  ``MEDIA_ENT_F_TS_DEMUX``
 
···
 
     -  .. row 8
 
+       ..  _MEDIA-ENT-F-DTV-CA:
+
        -  ``MEDIA_ENT_F_DTV_CA``
 
        -  Digital TV Conditional Access module (CAM) entity
 
     -  .. row 9
+
+       ..  _MEDIA-ENT-F-DTV-NET-DECAP:
 
        -  ``MEDIA_ENT_F_DTV_NET_DECAP``
 
···
 
     -  .. row 10
 
+       ..  _MEDIA-ENT-F-CONN-RF:
+
        -  ``MEDIA_ENT_F_CONN_RF``
 
        -  Connector for a Radio Frequency (RF) signal.
 
     -  .. row 11
+
+       ..  _MEDIA-ENT-F-CONN-SVIDEO:
 
        -  ``MEDIA_ENT_F_CONN_SVIDEO``
 
···
 
     -  .. row 12
 
+       ..  _MEDIA-ENT-F-CONN-COMPOSITE:
+
        -  ``MEDIA_ENT_F_CONN_COMPOSITE``
 
        -  Connector for a RGB composite signal.
 
     -  .. row 13
+
+       ..  _MEDIA-ENT-F-CAM-SENSOR:
 
        -  ``MEDIA_ENT_F_CAM_SENSOR``
 
···
 
     -  .. row 14
 
+       ..  _MEDIA-ENT-F-FLASH:
+
        -  ``MEDIA_ENT_F_FLASH``
 
        -  Flash controller entity.
 
     -  .. row 15
 
+       ..  _MEDIA-ENT-F-LENS:
+
        -  ``MEDIA_ENT_F_LENS``
 
        -  Lens controller entity.
 
     -  .. row 16
+
+       ..  _MEDIA-ENT-F-ATV-DECODER:
 
        -  ``MEDIA_ENT_F_ATV_DECODER``
 
···
 
     -  .. row 17
 
+       ..  _MEDIA-ENT-F-TUNER:
+
        -  ``MEDIA_ENT_F_TUNER``
 
        -  Digital TV, analog TV, radio and/or software radio tuner, with
···
 
     -  .. row 18
 
+       ..  _MEDIA-ENT-F-IF-VID-DECODER:
+
        -  ``MEDIA_ENT_F_IF_VID_DECODER``
 
        -  IF-PLL video decoder. It receives the IF from a PLL and decodes
···
 	  Those devices use a different I2C address than the tuner PLL.
 
     -  .. row 19
+
+       ..  _MEDIA-ENT-F-IF-AUD-DECODER:
 
        -  ``MEDIA_ENT_F_IF_AUD_DECODER``
 
···
 
     -  .. row 20
 
+       ..  _MEDIA-ENT-F-AUDIO-CAPTURE:
+
        -  ``MEDIA_ENT_F_AUDIO_CAPTURE``
 
        -  Audio Capture Function Entity.
 
     -  .. row 21
+
+       ..  _MEDIA-ENT-F-AUDIO-PLAYBACK:
 
        -  ``MEDIA_ENT_F_AUDIO_PLAYBACK``
 
···
 
     -  .. row 22
 
+       ..  _MEDIA-ENT-F-AUDIO-MIXER:
+
        -  ``MEDIA_ENT_F_AUDIO_MIXER``
 
        -  Audio Mixer Function Entity.
 
     -  .. row 23
+
+       ..  _MEDIA-ENT-F-PROC-VIDEO-COMPOSER:
 
        -  ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER``
 
···
 	  means.
 
     -  ..  row 24
+
+       ..  _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER:
 
        -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
 
···
 
     -  ..  row 25
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV``
 
        -  Video pixel encoding converter. An entity capable of pixel
···
 	  conversions.
 
     -  ..  row 26
+
+       ..  _MEDIA-ENT-F-PROC-VIDEO-LUT:
 
        -  ``MEDIA_ENT_F_PROC_VIDEO_LUT``
 
···
 
     -  ..  row 27
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-SCALER:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
 
        -  Video scaler. An entity capable of video scaling must have
···
 	  skipping are considered as scaling.
 
     -  ..  row 28
+
+       ..  _MEDIA-ENT-F-PROC-VIDEO-STATISTICS:
 
        -  ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
 
···
 
     -  .. row 1
 
+       ..  _MEDIA-ENT-FL-DEFAULT:
+
        -  ``MEDIA_ENT_FL_DEFAULT``
 
        -  Default entity for its type. Used to discover the default audio,
 	  VBI and video devices, the default camera sensor, ...
 
     -  .. row 2
+
+       ..  _MEDIA-ENT-FL-CONNECTOR:
 
        -  ``MEDIA_ENT_FL_CONNECTOR``
 
···
 
     -  .. row 1
 
+       ..  _MEDIA-INTF-T-DVB-FE:
+
        -  ``MEDIA_INTF_T_DVB_FE``
 
        -  Device node interface for the Digital TV frontend
···
        -  typically, /dev/dvb/adapter?/frontend?
 
     -  .. row 2
+
+       ..  _MEDIA-INTF-T-DVB-DEMUX:
 
        -  ``MEDIA_INTF_T_DVB_DEMUX``
 
···
 
     -  .. row 3
 
+       ..  _MEDIA-INTF-T-DVB-DVR:
+
        -  ``MEDIA_INTF_T_DVB_DVR``
 
        -  Device node interface for the Digital TV DVR
···
        -  typically, /dev/dvb/adapter?/dvr?
 
     -  .. row 4
+
+       ..  _MEDIA-INTF-T-DVB-CA:
 
        -  ``MEDIA_INTF_T_DVB_CA``
 
···
 
     -  .. row 5
 
-       -  ``MEDIA_INTF_T_DVB_FE``
+       ..  _MEDIA-INTF-T-DVB-NET:
+
+       -  ``MEDIA_INTF_T_DVB_NET``
 
        -  Device node interface for the Digital TV network control
 
        -  typically, /dev/dvb/adapter?/net?
 
     -  .. row 6
+
+       ..  _MEDIA-INTF-T-V4L-VIDEO:
 
        -  ``MEDIA_INTF_T_V4L_VIDEO``
 
···
 
     -  .. row 7
 
+       ..  _MEDIA-INTF-T-V4L-VBI:
+
        -  ``MEDIA_INTF_T_V4L_VBI``
 
        -  Device node interface for VBI (V4L)
···
        -  typically, /dev/vbi?
 
     -  .. row 8
+
+       ..  _MEDIA-INTF-T-V4L-RADIO:
 
        -  ``MEDIA_INTF_T_V4L_RADIO``
 
···
 
     -  .. row 9
 
+       ..  _MEDIA-INTF-T-V4L-SUBDEV:
+
        -  ``MEDIA_INTF_T_V4L_SUBDEV``
 
        -  Device node interface for a V4L subdevice
···
        -  typically, /dev/v4l-subdev?
 
     -  .. row 10
+
+       ..  _MEDIA-INTF-T-V4L-SWRADIO:
 
        -  ``MEDIA_INTF_T_V4L_SWRADIO``
 
···
 
     -  .. row 11
 
+       ..  _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
+
        -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
 
        -  Device node interface for ALSA PCM Capture
···
        -  typically, /dev/snd/pcmC?D?c
 
     -  .. row 12
+
+       ..  _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
 
        -  ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
 
···
 
     -  .. row 13
 
+       ..  _MEDIA-INTF-T-ALSA-CONTROL:
+
        -  ``MEDIA_INTF_T_ALSA_CONTROL``
 
        -  Device node interface for ALSA Control
···
        -  typically, /dev/snd/controlC?
 
     -  .. row 14
+
+       ..  _MEDIA-INTF-T-ALSA-COMPRESS:
 
        -  ``MEDIA_INTF_T_ALSA_COMPRESS``
 
···
 
     -  .. row 15
 
+       ..  _MEDIA-INTF-T-ALSA-RAWMIDI:
+
        -  ``MEDIA_INTF_T_ALSA_RAWMIDI``
 
        -  Device node interface for ALSA Raw MIDI
···
        -  typically, /dev/snd/midi?
 
     -  .. row 16
+
+       ..  _MEDIA-INTF-T-ALSA-HWDEP:
 
        -  ``MEDIA_INTF_T_ALSA_HWDEP``
 
···
 
     -  .. row 17
 
+       ..  _MEDIA-INTF-T-ALSA-SEQUENCER:
+
        -  ``MEDIA_INTF_T_ALSA_SEQUENCER``
 
        -  Device node interface for ALSA Sequencer
···
        -  typically, /dev/snd/seq
 
     -  .. row 18
+
+       ..  _MEDIA-INTF-T-ALSA-TIMER:
 
        -  ``MEDIA_INTF_T_ALSA_TIMER``
 
···
 
     -  .. row 1
 
+       ..  _MEDIA-PAD-FL-SINK:
+
        -  ``MEDIA_PAD_FL_SINK``
 
        -  Input pad, relative to the entity. Input pads sink data and are
···
 
     -  .. row 2
 
+       ..  _MEDIA-PAD-FL-SOURCE:
+
        -  ``MEDIA_PAD_FL_SOURCE``
 
        -  Output pad, relative to the entity. Output pads source data and
 	  are origins of links.
 
     -  .. row 3
+
+       ..  _MEDIA-PAD-FL-MUST-CONNECT:
 
        -  ``MEDIA_PAD_FL_MUST_CONNECT``
 
···
 
     -  .. row 1
 
+       ..  _MEDIA-LNK-FL-ENABLED:
+
        -  ``MEDIA_LNK_FL_ENABLED``
 
        -  The link is enabled and can be used to transfer media data. When
···
 
     -  .. row 2
 
+       ..  _MEDIA-LNK-FL-IMMUTABLE:
+
        -  ``MEDIA_LNK_FL_IMMUTABLE``
 
        -  The link enabled state can't be modified at runtime. An immutable
 	  link is always enabled.
 
     -  .. row 3
+
+       ..  _MEDIA-LNK-FL-DYNAMIC:
 
        -  ``MEDIA_LNK_FL_DYNAMIC``
 
···
 
     -  .. row 4
 
+       ..  _MEDIA-LNK-FL-LINK-TYPE:
+
        -  ``MEDIA_LNK_FL_LINK_TYPE``
 
        -  This is a bitmask that defines the type of the link. Currently,
 	  two types of links are supported:
 
+	  .. _MEDIA-LNK-FL-DATA-LINK:
+
 	  ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
+
+	  .. _MEDIA-LNK-FL-INTERFACE-LINK:
 
 	  ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
 	  interface and an entity