[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