[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 <mchehab@s-opensource.com>

Documentation/media/Makefile

@@ -5,7 +5,7 @@ UAPI = $(srctree)/include/uapi/linux
 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))
 
@@ -46,5 +46,8 @@ $(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.ex
 $(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:
 	-rm ${TARGETS}

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

@@ -22,7 +22,7 @@ Media Controller
     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
@@ -39,6 +39,8 @@ 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
 about the entity with the smallest id strictly larger than the requested

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
@@ -44,14 +44,12 @@ MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
 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

@@ -15,6 +15,9 @@ Types and flags used to represent the media graph elements
 
     -  .. 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
@@ -22,36 +25,48 @@ Types and flags used to represent the media graph elements
 
     -  .. 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``
 
        -  V4L VBI streaming input or output entity
 
     -  .. 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``
 
        -  DVB Digital TV streaming input or output entity
 
     -  .. 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``
 
        -  MPEG Transport stream demux entity. Could be implemented on
@@ -59,12 +74,16 @@ Types and flags used to represent the media graph elements
 
     -  .. 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``
 
        -  Digital TV network ULE/MLE desencapsulation entity. Could be
@@ -72,42 +91,56 @@ Types and flags used to represent the media graph elements
 
     -  .. 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``
 
        -  Connector for a S-Video signal.
 
     -  .. 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``
 
        -  Camera video sensor entity.
 
     -  .. 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``
 
        -  Analog video decoder, the basic function of the video decoder is
@@ -119,6 +152,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 17
 
+       ..  _MEDIA-ENT-F-TUNER:
+
        -  ``MEDIA_ENT_F_TUNER``
 
        -  Digital TV, analog TV, radio and/or software radio tuner, with
@@ -129,6 +164,8 @@ Types and flags used to represent the media graph elements
 
     -  .. 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
@@ -139,6 +176,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 19
 
+       ..  _MEDIA-ENT-F-IF-AUD-DECODER:
+
        -  ``MEDIA_ENT_F_IF_AUD_DECODER``
 
        -  IF-PLL sound decoder. It receives the IF from a PLL and decodes
@@ -150,24 +189,32 @@ Types and flags used to represent the media graph elements
 
     -  .. 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``
 
        -  Audio Playback Function Entity.
 
     -  .. 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``
 
        -  Video composer (blender). An entity capable of video
@@ -179,6 +226,8 @@ Types and flags used to represent the media graph elements
 
     -  ..  row 24
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
 
        -  Video pixel formatter. An entity capable of pixel formatting
@@ -191,6 +240,8 @@ Types and flags used to represent the media graph elements
 
     -  ..  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
@@ -203,6 +254,8 @@ Types and flags used to represent the media graph elements
 
     -  ..  row 26
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-LUT:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_LUT``
 
        -  Video look-up table. An entity capable of video lookup table
@@ -215,6 +268,8 @@ Types and flags used to represent the media graph elements
 
     -  ..  row 27
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-SCALER:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
 
        -  Video scaler. An entity capable of video scaling must have
@@ -228,6 +283,8 @@ Types and flags used to represent the media graph elements
 
     -  ..  row 28
 
+       ..  _MEDIA-ENT-F-PROC-VIDEO-STATISTICS:
+
        -  ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
 
        -  Video statistics computation (histogram, 3A, ...). An entity
@@ -246,6 +303,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 1
 
+       ..  _MEDIA-ENT-FL-DEFAULT:
+
        -  ``MEDIA_ENT_FL_DEFAULT``
 
        -  Default entity for its type. Used to discover the default audio,
@@ -253,6 +312,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 2
 
+       ..  _MEDIA-ENT-FL-CONNECTOR:
+
        -  ``MEDIA_ENT_FL_CONNECTOR``
 
        -  The entity represents a data conector
@@ -268,6 +329,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 1
 
+       ..  _MEDIA-INTF-T-DVB-FE:
+
        -  ``MEDIA_INTF_T_DVB_FE``
 
        -  Device node interface for the Digital TV frontend
@@ -276,6 +339,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 2
 
+       ..  _MEDIA-INTF-T-DVB-DEMUX:
+
        -  ``MEDIA_INTF_T_DVB_DEMUX``
 
        -  Device node interface for the Digital TV demux
@@ -284,6 +349,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 3
 
+       ..  _MEDIA-INTF-T-DVB-DVR:
+
        -  ``MEDIA_INTF_T_DVB_DVR``
 
        -  Device node interface for the Digital TV DVR
@@ -292,6 +359,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 4
 
+       ..  _MEDIA-INTF-T-DVB-CA:
+
        -  ``MEDIA_INTF_T_DVB_CA``
 
        -  Device node interface for the Digital TV Conditional Access
@@ -300,7 +369,9 @@ Types and flags used to represent the media graph elements
 
     -  .. 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
 
@@ -308,6 +379,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 6
 
+       ..  _MEDIA-INTF-T-V4L-VIDEO:
+
        -  ``MEDIA_INTF_T_V4L_VIDEO``
 
        -  Device node interface for video (V4L)
@@ -316,6 +389,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 7
 
+       ..  _MEDIA-INTF-T-V4L-VBI:
+
        -  ``MEDIA_INTF_T_V4L_VBI``
 
        -  Device node interface for VBI (V4L)
@@ -324,6 +399,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 8
 
+       ..  _MEDIA-INTF-T-V4L-RADIO:
+
        -  ``MEDIA_INTF_T_V4L_RADIO``
 
        -  Device node interface for radio (V4L)
@@ -332,6 +409,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 9
 
+       ..  _MEDIA-INTF-T-V4L-SUBDEV:
+
        -  ``MEDIA_INTF_T_V4L_SUBDEV``
 
        -  Device node interface for a V4L subdevice
@@ -340,6 +419,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 10
 
+       ..  _MEDIA-INTF-T-V4L-SWRADIO:
+
        -  ``MEDIA_INTF_T_V4L_SWRADIO``
 
        -  Device node interface for Software Defined Radio (V4L)
@@ -348,6 +429,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 11
 
+       ..  _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
+
        -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
 
        -  Device node interface for ALSA PCM Capture
@@ -356,6 +439,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 12
 
+       ..  _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
+
        -  ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
 
        -  Device node interface for ALSA PCM Playback
@@ -364,6 +449,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 13
 
+       ..  _MEDIA-INTF-T-ALSA-CONTROL:
+
        -  ``MEDIA_INTF_T_ALSA_CONTROL``
 
        -  Device node interface for ALSA Control
@@ -372,6 +459,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 14
 
+       ..  _MEDIA-INTF-T-ALSA-COMPRESS:
+
        -  ``MEDIA_INTF_T_ALSA_COMPRESS``
 
        -  Device node interface for ALSA Compress
@@ -380,6 +469,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 15
 
+       ..  _MEDIA-INTF-T-ALSA-RAWMIDI:
+
        -  ``MEDIA_INTF_T_ALSA_RAWMIDI``
 
        -  Device node interface for ALSA Raw MIDI
@@ -388,6 +479,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 16
 
+       ..  _MEDIA-INTF-T-ALSA-HWDEP:
+
        -  ``MEDIA_INTF_T_ALSA_HWDEP``
 
        -  Device node interface for ALSA Hardware Dependent
@@ -396,6 +489,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 17
 
+       ..  _MEDIA-INTF-T-ALSA-SEQUENCER:
+
        -  ``MEDIA_INTF_T_ALSA_SEQUENCER``
 
        -  Device node interface for ALSA Sequencer
@@ -404,6 +499,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 18
 
+       ..  _MEDIA-INTF-T-ALSA-TIMER:
+
        -  ``MEDIA_INTF_T_ALSA_TIMER``
 
        -  Device node interface for ALSA Timer
@@ -421,6 +518,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 1
 
+       ..  _MEDIA-PAD-FL-SINK:
+
        -  ``MEDIA_PAD_FL_SINK``
 
        -  Input pad, relative to the entity. Input pads sink data and are
@@ -428,6 +527,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 2
 
+       ..  _MEDIA-PAD-FL-SOURCE:
+
        -  ``MEDIA_PAD_FL_SOURCE``
 
        -  Output pad, relative to the entity. Output pads source data and
@@ -435,6 +536,8 @@ Types and flags used to represent the media graph elements
 
     -  .. row 3
 
+       ..  _MEDIA-PAD-FL-MUST-CONNECT:
+
        -  ``MEDIA_PAD_FL_MUST_CONNECT``
 
        -  If this flag is set and the pad is linked to any other pad, then
@@ -458,6 +561,8 @@ must be set for every pad.
 
     -  .. row 1
 
+       ..  _MEDIA-LNK-FL-ENABLED:
+
        -  ``MEDIA_LNK_FL_ENABLED``
 
        -  The link is enabled and can be used to transfer media data. When
@@ -466,6 +571,8 @@ must be set for every pad.
 
     -  .. row 2
 
+       ..  _MEDIA-LNK-FL-IMMUTABLE:
+
        -  ``MEDIA_LNK_FL_IMMUTABLE``
 
        -  The link enabled state can't be modified at runtime. An immutable
@@ -473,6 +580,8 @@ must be set for every pad.
 
     -  .. row 3
 
+       ..  _MEDIA-LNK-FL-DYNAMIC:
+
        -  ``MEDIA_LNK_FL_DYNAMIC``
 
        -  The link enabled state can be modified during streaming. This flag
@@ -480,12 +589,18 @@ must be set for every pad.
 
     -  .. 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