[PATCH 1/7] [media] doc-rst: Convert media API to rst

[PATCH 1/7] [media] doc-rst: Convert media API to rst

[Mauro Carvalho Chehab]

Move the contents of the media section at
DocBooks/DocBook/device-drivers.tmpl to a new ReST book.

For now, the contents is kept as-is. Next patches will fix
the warnings and add cross-references that were removed due to
the conversion.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/DocBook/device-drivers.tmpl |  58 -----
 Documentation/index.rst                   |   1 +
 Documentation/media/media_drivers.rst     | 414 ++++++++++++++++++++++++++++++
 drivers/media/dvb-core/demux.h            |  71 +----
 drivers/media/dvb-core/dvb_frontend.h     |  27 +-
 include/media/media-device.h              | 231 -----------------
 6 files changed, 423 insertions(+), 379 deletions(-)
 create mode 100644 Documentation/media/media_drivers.rst

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index a20a45b45c30..e9f77f2fe27b 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -219,64 +219,6 @@ X!Isound/sound_firmware.c
 -->
   </chapter>
 
-  <chapter id="mediadev">
-     <title>Media Devices</title>
-
-     <sect1><title>Video2Linux devices</title>
-!Iinclude/media/tuner.h
-!Iinclude/media/tuner-types.h
-!Iinclude/media/tveeprom.h
-!Iinclude/media/v4l2-async.h
-!Iinclude/media/v4l2-ctrls.h
-!Iinclude/media/v4l2-dv-timings.h
-!Iinclude/media/v4l2-event.h
-!Iinclude/media/v4l2-flash-led-class.h
-!Iinclude/media/v4l2-mc.h
-!Iinclude/media/v4l2-mediabus.h
-!Iinclude/media/v4l2-mem2mem.h
-!Iinclude/media/v4l2-of.h
-!Iinclude/media/v4l2-rect.h
-!Iinclude/media/v4l2-subdev.h
-!Iinclude/media/videobuf2-core.h
-!Iinclude/media/videobuf2-v4l2.h
-!Iinclude/media/videobuf2-memops.h
-     </sect1>
-     <sect1><title>Digital TV (DVB) devices</title>
-	<sect1><title>Digital TV Common functions</title>
-!Idrivers/media/dvb-core/dvb_math.h
-!Idrivers/media/dvb-core/dvb_ringbuffer.h
-!Idrivers/media/dvb-core/dvbdev.h
-	</sect1>
-	<sect1><title>Digital TV Frontend kABI</title>
-!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
-!Idrivers/media/dvb-core/dvb_frontend.h
-	</sect1>
-	<sect1><title>Digital TV Demux kABI</title>
-!Pdrivers/media/dvb-core/demux.h Digital TV Demux
-	<sect1><title>Demux Callback API</title>
-!Pdrivers/media/dvb-core/demux.h Demux Callback
-	</sect1>
-!Idrivers/media/dvb-core/demux.h
-	</sect1>
-	<sect1><title>Digital TV Conditional Access kABI</title>
-!Idrivers/media/dvb-core/dvb_ca_en50221.h
-	</sect1>
-     </sect1>
-    <sect1><title>Remote Controller devices</title>
-!Iinclude/media/rc-core.h
-!Iinclude/media/lirc_dev.h
-    </sect1>
-    <sect1><title>Media Controller devices</title>
-!Pinclude/media/media-device.h Media Controller
-!Iinclude/media/media-device.h
-!Iinclude/media/media-devnode.h
-!Iinclude/media/media-entity.h
-    </sect1>
-    <sect1><title>Consumer Electronics Control devices</title>
-!Iinclude/media/cec-edid.h
-    </sect1>
-
-  </chapter>
 
   <chapter id="uart16x50">
      <title>16x50 UART Driver</title>
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ad07716c73f4..985872404147 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -15,6 +15,7 @@ Contents:
 
    kernel-documentation
    media/media_uapi
+   media/media_drivers.rst
 
 Indices and tables
 ==================
diff --git a/Documentation/media/media_drivers.rst b/Documentation/media/media_drivers.rst
new file mode 100644
index 000000000000..722170cb7f40
--- /dev/null
+++ b/Documentation/media/media_drivers.rst
@@ -0,0 +1,414 @@
+==========
+Media core
+==========
+
+Video2Linux devices
+-------------------
+
+.. kernel-doc:: include/media/tuner.h
+
+.. kernel-doc:: include/media/tuner-types.h
+
+.. kernel-doc:: include/media/tveeprom.h
+
+.. kernel-doc:: include/media/v4l2-async.h
+
+.. kernel-doc:: include/media/v4l2-ctrls.h
+
+.. kernel-doc:: include/media/v4l2-dv-timings.h
+
+.. kernel-doc:: include/media/v4l2-event.h
+
+.. kernel-doc:: include/media/v4l2-flash-led-class.h
+
+.. kernel-doc:: include/media/v4l2-mc.h
+
+.. kernel-doc:: include/media/v4l2-mediabus.h
+
+.. kernel-doc:: include/media/v4l2-mem2mem.h
+
+.. kernel-doc:: include/media/v4l2-of.h
+
+.. kernel-doc:: include/media/v4l2-rect.h
+
+.. kernel-doc:: include/media/v4l2-subdev.h
+
+.. kernel-doc:: include/media/videobuf2-core.h
+
+.. kernel-doc:: include/media/videobuf2-v4l2.h
+
+.. kernel-doc:: include/media/videobuf2-memops.h
+
+
+Digital TV (DVB) devices
+------------------------
+
+Digital TV Common functions
+---------------------------
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
+
+.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
+
+
+Digital TV Frontend kABI
+------------------------
+
+Digital TV Frontend
+~~~~~~~~~~~~~~~~~~~
+
+The Digital TV Frontend kABI defines a driver-internal interface for
+registering low-level, hardware specific driver to a hardware independent
+frontend layer. It is only of interest for Digital TV device driver writers.
+The header file for this API is named dvb_frontend.h and located in
+drivers/media/dvb-core.
+
+Before using the Digital TV frontend core, the bridge driver should attach
+the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
+in order to register the new frontend at the subsystem. At device
+detach/removal, the bridge driver should call dvb_unregister_frontend() to
+remove the frontend from the core and then dvb_frontend_detach() to free the
+memory allocated by the frontend drivers.
+
+The drivers should also call dvb_frontend_suspend() as part of their
+handler for the &device_driver.suspend(), and dvb_frontend_resume() as
+part of their handler for &device_driver.resume().
+
+few other optional functions are provided to handle some special cases.
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
+
+
+Digital TV Demux kABI
+---------------------
+
+Digital TV Demux
+~~~~~~~~~~~~~~~~
+
+The Kernel Digital TV Demux kABI defines a driver-internal interface for
+registering low-level, hardware specific driver to a hardware independent
+demux layer. It is only of interest for Digital TV device driver writers.
+The header file for this kABI is named demux.h and located in
+drivers/media/dvb-core.
+
+The demux kABI should be implemented for each demux in the system. It is
+used to select the TS source of a demux and to manage the demux resources.
+When the demux client allocates a resource via the demux kABI, it receives
+a pointer to the kABI of that resource.
+
+Each demux receives its TS input from a DVB front-end or from memory, as
+set via this demux kABI. In a system with more than one front-end, the kABI
+can be used to select one of the DVB front-ends as a TS source for a demux,
+unless this is fixed in the HW platform.
+
+The demux kABI only controls front-ends regarding to their connections with
+demuxes; the kABI used to set the other front-end parameters, such as
+tuning, are devined via the Digital TV Frontend kABI.
+
+The functions that implement the abstract interface demux should be defined
+static or module private and registered to the Demux core for external
+access. It is not necessary to implement every function in the struct
+&dmx_demux. For example, a demux interface might support Section filtering,
+but not PES filtering. The kABI client is expected to check the value of any
+function pointer before calling the function: the value of NULL means
+that the function is not available.
+
+Whenever the functions of the demux API modify shared data, the
+possibilities of lost update and race condition problems should be
+addressed, e.g. by protecting parts of code with mutexes.
+
+Note that functions called from a bottom half context must not sleep.
+Even a simple memory allocation without using %GFP_ATOMIC can result in a
+kernel thread being put to sleep if swapping is needed. For example, the
+Linux Kernel calls the functions of a network device interface from a
+bottom half context. Thus, if a demux kABI function is called from network
+device code, the function must not sleep.
+
+
+
+Demux Callback API
+------------------
+
+Demux Callback
+~~~~~~~~~~~~~~
+
+This kernel-space API comprises the callback functions that deliver filtered
+data to the demux client. Unlike the other DVB kABIs, these functions are
+provided by the client and called from the demux code.
+
+The function pointers of this abstract interface are not packed into a
+structure as in the other demux APIs, because the callback functions are
+registered and used independent of each other. As an example, it is possible
+for the API client to provide several callback functions for receiving TS
+packets and no callbacks for PES packets or sections.
+
+The functions that implement the callback API need not be re-entrant: when
+a demux driver calls one of these functions, the driver is not allowed to
+call the function again before the original call returns. If a callback is
+triggered by a hardware interrupt, it is recommended to use the Linux
+bottom half mechanism or start a tasklet instead of making the callback
+function call directly from a hardware interrupt.
+
+This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
+callbacks.
+
+
+.. kernel-doc:: drivers/media/dvb-core/demux.h
+
+
+Digital TV Conditional Access kABI
+----------------------------------
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
+
+
+Remote Controller devices
+-------------------------
+
+.. kernel-doc:: include/media/rc-core.h
+
+.. kernel-doc:: include/media/lirc_dev.h
+
+
+Media Controller devices
+------------------------
+
+Media Controller
+~~~~~~~~~~~~~~~~
+
+
+The media controller userspace API is documented in DocBook format in
+Documentation/DocBook/media/v4l/media-controller.xml. This document focus
+on the kernel-side implementation of the media framework.
+
+* Abstract media device model:
+
+Discovering a device internal topology, and configuring it at runtime, is one
+of the goals of the media framework. To achieve this, hardware devices are
+modelled as an oriented graph of building blocks called entities connected
+through pads.
+
+An entity is a basic media hardware building block. It can correspond to
+a large variety of logical blocks such as physical hardware devices
+(CMOS sensor for instance), logical hardware devices (a building block
+in a System-on-Chip image processing pipeline), DMA channels or physical
+connectors.
+
+A pad is a connection endpoint through which an entity can interact with
+other entities. Data (not restricted to video) produced by an entity
+flows from the entity's output to one or more entity inputs. Pads should
+not be confused with physical pins at chip boundaries.
+
+A link is a point-to-point oriented connection between two pads, either
+on the same entity or on different entities. Data flows from a source
+pad to a sink pad.
+
+
+* Media device:
+
+A media device is represented by a struct &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 &media_device instance in a
+larger driver-specific structure.
+
+Drivers register media device instances by calling
+__media_device_register() via the macro media_device_register()
+and unregistered by calling
+media_device_unregister().
+
+* Entities, pads and links:
+
+- Entities
+
+Entities are represented by a struct &media_entity instance, defined in
+include/media/media-entity.h. The structure is usually embedded into a
+higher-level structure, such as a v4l2_subdev or video_device instance,
+although drivers can allocate entities directly.
+
+Drivers initialize entity pads by calling
+media_entity_pads_init().
+
+Drivers register entities with a media device by calling
+media_device_register_entity()
+and unregistred by calling
+media_device_unregister_entity().
+
+- Interfaces
+
+Interfaces are represented by a struct &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 struct
+&media_intf_devnode.
+
+Drivers initialize and create device node interfaces by calling
+media_devnode_create()
+and remove them by calling:
+media_devnode_remove().
+
+- Pads
+
+Pads are represented by a struct &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 &media_pad structure, making the
+&media_pad pointer the canonical way to store and pass link references.
+
+Pads have flags that describe the pad capabilities and state.
+
+%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
+%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
+
+NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
+be set for each pad.
+
+- Links
+
+Links are represented by a struct &media_link instance, defined in
+include/media/media-entity.h. There are two types of links:
+
+1. pad to pad links:
+
+Associate two entities via their PADs. Each entity has a list that points
+to all links originating at or targeting any of its pads.
+A given link is thus stored twice, once in the source entity and once in
+the target entity.
+
+Drivers create pad to pad links by calling:
+media_create_pad_link() and remove with media_entity_remove_links().
+
+2. interface to entity links:
+
+Associate one interface to a Link.
+
+Drivers create interface to entity links by calling:
+media_create_intf_link() and remove with media_remove_intf_links().
+
+NOTE:
+
+Links can only be created after having both ends already created.
+
+Links have flags that describe the link capabilities and state. The
+valid values are described at media_create_pad_link() and
+media_create_intf_link().
+
+Graph traversal:
+
+The media framework provides APIs to iterate over entities in a graph.
+
+To iterate over all entities belonging to a media device, drivers can use
+the media_device_for_each_entity macro, defined in
+include/media/media-device.h.
+
+struct media_entity *entity;
+
+media_device_for_each_entity(entity, mdev) {
+// entity will point to each entity in turn
+...
+}
+
+Drivers might also need to iterate over all entities in a graph that can be
+reached only through enabled links starting at a given entity. The media
+framework provides a depth-first graph traversal API for that purpose.
+
+Note that graphs with cycles (whether directed or undirected) are *NOT*
+supported by the graph traversal API. To prevent infinite loops, the graph
+traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
+currently defined as 16.
+
+Drivers initiate a graph traversal by calling
+media_entity_graph_walk_start()
+
+The graph structure, provided by the caller, is initialized to start graph
+traversal at the given entity.
+
+Drivers can then retrieve the next entity by calling
+media_entity_graph_walk_next()
+
+When the graph traversal is complete the function will return NULL.
+
+Graph traversal can be interrupted at any moment. No cleanup function call
+is required and the graph structure can be freed normally.
+
+Helper functions can be used to find a link between two given pads, or a pad
+connected to another pad through an enabled link
+media_entity_find_link() and media_entity_remote_pad()
+
+Use count and power handling:
+
+Due to the wide differences between drivers regarding power management
+needs, the media controller does not implement power management. However,
+the &media_entity structure includes a use_count field that media drivers
+can use to track the number of users of every entity for power management
+needs.
+
+The &media_entity.@use_count field is owned by media drivers and must not be
+touched by entity drivers. Access to the field must be protected by the
+&media_device.@graph_mutex lock.
+
+Links setup:
+
+Link properties can be modified at runtime by calling
+media_entity_setup_link()
+
+Pipelines and media streams:
+
+When starting streaming, drivers must notify all entities in the pipeline to
+prevent link states from being modified during streaming by calling
+media_entity_pipeline_start().
+
+The function will mark all entities connected to the given entity through
+enabled links, either directly or indirectly, as streaming.
+
+The &media_pipeline instance pointed to by the pipe argument will be stored
+in every entity in the pipeline. Drivers should embed the &media_pipeline
+structure in higher-level pipeline structures and can then access the
+pipeline through the &media_entity pipe field.
+
+Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
+must be identical for all nested calls to the function.
+
+media_entity_pipeline_start() may return an error. In that case, it will
+clean up any of the changes it did by itself.
+
+When stopping the stream, drivers must notify the entities with
+media_entity_pipeline_stop().
+
+If multiple calls to media_entity_pipeline_start() have been made the same
+number of media_entity_pipeline_stop() calls are required to stop streaming.
+The &media_entity pipe field is reset to NULL on the last nested stop call.
+
+Link configuration will fail with -%EBUSY by default if either end of the
+link is a streaming entity. Links that can be modified while streaming must
+be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
+
+If other operations need to be disallowed on streaming entities (such as
+changing entities configuration parameters) drivers can explicitly check the
+media_entity stream_count field to find out if an entity is streaming. This
+operation must be done with the media_device graph_mutex held.
+
+Link validation:
+
+Link validation is performed by media_entity_pipeline_start() for any
+entity which has sink pads in the pipeline. The
+&media_entity.@link_validate() callback is used for that purpose. In
+@link_validate() callback, entity driver should check that the properties of
+the source pad of the connected entity and its own sink pad match. It is up
+to the type of the entity (and in the end, the properties of the hardware)
+what matching actually means.
+
+Subsystems should facilitate link validation by providing subsystem specific
+helper functions to provide easy access for commonly needed information, and
+in the end provide a way to use driver-specific callbacks.
+
+.. kernel-doc:: include/media/media-device.h
+
+.. kernel-doc:: include/media/media-devnode.h
+
+.. kernel-doc:: include/media/media-entity.h
+
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 6d3b95b8939d..e8f04f8872f8 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -1,6 +1,10 @@
 /*
  * demux.h
  *
+ * The Kernel Digital TV Demux kABI defines a driver-internal interface for
+ * registering low-level, hardware specific driver to a hardware independent
+ * demux layer.
+ *
  * Copyright (c) 2002 Convergence GmbH
  *
  * based on code:
@@ -32,49 +36,6 @@
 #include <linux/time.h>
 #include <linux/dvb/dmx.h>
 
-/**
- * DOC: Digital TV Demux
- *
- * The Kernel Digital TV Demux kABI defines a driver-internal interface for
- * registering low-level, hardware specific driver to a hardware independent
- * demux layer. It is only of interest for Digital TV device driver writers.
- * The header file for this kABI is named demux.h and located in
- * drivers/media/dvb-core.
- *
- * The demux kABI should be implemented for each demux in the system. It is
- * used to select the TS source of a demux and to manage the demux resources.
- * When the demux client allocates a resource via the demux kABI, it receives
- * a pointer to the kABI of that resource.
- *
- * Each demux receives its TS input from a DVB front-end or from memory, as
- * set via this demux kABI. In a system with more than one front-end, the kABI
- * can be used to select one of the DVB front-ends as a TS source for a demux,
- * unless this is fixed in the HW platform.
- *
- * The demux kABI only controls front-ends regarding to their connections with
- * demuxes; the kABI used to set the other front-end parameters, such as
- * tuning, are devined via the Digital TV Frontend kABI.
- *
- * The functions that implement the abstract interface demux should be defined
- * static or module private and registered to the Demux core for external
- * access. It is not necessary to implement every function in the struct
- * &dmx_demux. For example, a demux interface might support Section filtering,
- * but not PES filtering. The kABI client is expected to check the value of any
- * function pointer before calling the function: the value of NULL means
- * that the function is not available.
- *
- * Whenever the functions of the demux API modify shared data, the
- * possibilities of lost update and race condition problems should be
- * addressed, e.g. by protecting parts of code with mutexes.
- *
- * Note that functions called from a bottom half context must not sleep.
- * Even a simple memory allocation without using %GFP_ATOMIC can result in a
- * kernel thread being put to sleep if swapping is needed. For example, the
- * Linux Kernel calls the functions of a network device interface from a
- * bottom half context. Thus, if a demux kABI function is called from network
- * device code, the function must not sleep.
- */
-
 /*
  * Common definitions
  */
@@ -231,30 +192,6 @@ struct dmx_section_feed {
 };
 
 /**
- * DOC: Demux Callback
- *
- * This kernel-space API comprises the callback functions that deliver filtered
- * data to the demux client. Unlike the other DVB kABIs, these functions are
- * provided by the client and called from the demux code.
- *
- * The function pointers of this abstract interface are not packed into a
- * structure as in the other demux APIs, because the callback functions are
- * registered and used independent of each other. As an example, it is possible
- * for the API client to provide several callback functions for receiving TS
- * packets and no callbacks for PES packets or sections.
- *
- * The functions that implement the callback API need not be re-entrant: when
- * a demux driver calls one of these functions, the driver is not allowed to
- * call the function again before the original call returns. If a callback is
- * triggered by a hardware interrupt, it is recommended to use the Linux
- * bottom half mechanism or start a tasklet instead of making the callback
- * function call directly from a hardware interrupt.
- *
- * This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
- * callbacks.
- */
-
-/**
  * typedef dmx_ts_cb - DVB demux TS filter callback function prototype
  *
  * @buffer1:		Pointer to the start of the filtered TS packets.
diff --git a/drivers/media/dvb-core/dvb_frontend.h b/drivers/media/dvb-core/dvb_frontend.h
index 9592573a0b41..8c551174537a 100644
--- a/drivers/media/dvb-core/dvb_frontend.h
+++ b/drivers/media/dvb-core/dvb_frontend.h
@@ -1,6 +1,10 @@
 /*
  * dvb_frontend.h
  *
+ * The Digital TV Frontend kABI defines a driver-internal interface for
+ * registering low-level, hardware specific driver to a hardware independent
+ * frontend layer.
+ *
  * Copyright (C) 2001 convergence integrated media GmbH
  * Copyright (C) 2004 convergence GmbH
  *
@@ -42,29 +46,6 @@
 
 #include "dvbdev.h"
 
-/**
- * DOC: Digital TV Frontend
- *
- * The Digital TV Frontend kABI defines a driver-internal interface for
- * registering low-level, hardware specific driver to a hardware independent
- * frontend layer. It is only of interest for Digital TV device driver writers.
- * The header file for this API is named dvb_frontend.h and located in
- * drivers/media/dvb-core.
- *
- * Before using the Digital TV frontend core, the bridge driver should attach
- * the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
- * in order to register the new frontend at the subsystem. At device
- * detach/removal, the bridge driver should call dvb_unregister_frontend() to
- * remove the frontend from the core and then dvb_frontend_detach() to free the
- * memory allocated by the frontend drivers.
- *
- * The drivers should also call dvb_frontend_suspend() as part of their
- * handler for the &device_driver.suspend(), and dvb_frontend_resume() as
- * part of their handler for &device_driver.resume().
- *
- * A few other optional functions are provided to handle some special cases.
- */
-
 /*
  * Maximum number of Delivery systems per frontend. It
  * should be smaller or equal to 32
diff --git a/include/media/media-device.h b/include/media/media-device.h
index f743ae2210ee..4605fee0c228 100644
--- a/include/media/media-device.h
+++ b/include/media/media-device.h
@@ -29,237 +29,6 @@
 #include <media/media-devnode.h>
 #include <media/media-entity.h>
 
-/**
- * DOC: Media Controller
- *
- * The media controller userspace API is documented in DocBook format in
- * Documentation/DocBook/media/v4l/media-controller.xml. This document focus
- * on the kernel-side implementation of the media framework.
- *
- * * Abstract media device model:
- *
- * Discovering a device internal topology, and configuring it at runtime, is one
- * of the goals of the media framework. To achieve this, hardware devices are
- * modelled as an oriented graph of building blocks called entities connected
- * through pads.
- *
- * An entity is a basic media hardware building block. It can correspond to
- * a large variety of logical blocks such as physical hardware devices
- * (CMOS sensor for instance), logical hardware devices (a building block
- * in a System-on-Chip image processing pipeline), DMA channels or physical
- * connectors.
- *
- * A pad is a connection endpoint through which an entity can interact with
- * other entities. Data (not restricted to video) produced by an entity
- * flows from the entity's output to one or more entity inputs. Pads should
- * not be confused with physical pins at chip boundaries.
- *
- * A link is a point-to-point oriented connection between two pads, either
- * on the same entity or on different entities. Data flows from a source
- * pad to a sink pad.
- *
- *
- * * Media device:
- *
- * A media device is represented by a struct &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 &media_device instance in a
- * larger driver-specific structure.
- *
- * Drivers register media device instances by calling
- *	__media_device_register() via the macro media_device_register()
- * and unregistered by calling
- *	media_device_unregister().
- *
- * * Entities, pads and links:
- *
- * - Entities
- *
- * Entities are represented by a struct &media_entity instance, defined in
- * include/media/media-entity.h. The structure is usually embedded into a
- * higher-level structure, such as a v4l2_subdev or video_device instance,
- * although drivers can allocate entities directly.
- *
- * Drivers initialize entity pads by calling
- *	media_entity_pads_init().
- *
- * Drivers register entities with a media device by calling
- *	media_device_register_entity()
- * and unregistred by calling
- *	media_device_unregister_entity().
- *
- * - Interfaces
- *
- * Interfaces are represented by a struct &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 struct
- * &media_intf_devnode.
- *
- * Drivers initialize and create device node interfaces by calling
- *	media_devnode_create()
- * and remove them by calling:
- *	media_devnode_remove().
- *
- * - Pads
- *
- * Pads are represented by a struct &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 &media_pad structure, making the
- * &media_pad pointer the canonical way to store and pass link references.
- *
- * Pads have flags that describe the pad capabilities and state.
- *
- *	%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
- *	%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
- *
- * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
- * be set for each pad.
- *
- * - Links
- *
- * Links are represented by a struct &media_link instance, defined in
- * include/media/media-entity.h. There are two types of links:
- *
- * 1. pad to pad links:
- *
- * Associate two entities via their PADs. Each entity has a list that points
- * to all links originating at or targeting any of its pads.
- * A given link is thus stored twice, once in the source entity and once in
- * the target entity.
- *
- * Drivers create pad to pad links by calling:
- *	media_create_pad_link() and remove with media_entity_remove_links().
- *
- * 2. interface to entity links:
- *
- * Associate one interface to a Link.
- *
- * Drivers create interface to entity links by calling:
- *	media_create_intf_link() and remove with media_remove_intf_links().
- *
- * NOTE:
- *
- * Links can only be created after having both ends already created.
- *
- * Links have flags that describe the link capabilities and state. The
- * valid values are described at media_create_pad_link() and
- * media_create_intf_link().
- *
- * Graph traversal:
- *
- * The media framework provides APIs to iterate over entities in a graph.
- *
- * To iterate over all entities belonging to a media device, drivers can use
- * the media_device_for_each_entity macro, defined in
- * include/media/media-device.h.
- *
- * 	struct media_entity *entity;
- *
- * 	media_device_for_each_entity(entity, mdev) {
- * 		// entity will point to each entity in turn
- * 		...
- * 	}
- *
- * Drivers might also need to iterate over all entities in a graph that can be
- * reached only through enabled links starting at a given entity. The media
- * framework provides a depth-first graph traversal API for that purpose.
- *
- * Note that graphs with cycles (whether directed or undirected) are *NOT*
- * supported by the graph traversal API. To prevent infinite loops, the graph
- * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
- * currently defined as 16.
- *
- * Drivers initiate a graph traversal by calling
- *	media_entity_graph_walk_start()
- *
- * The graph structure, provided by the caller, is initialized to start graph
- * traversal at the given entity.
- *
- * Drivers can then retrieve the next entity by calling
- *	media_entity_graph_walk_next()
- *
- * When the graph traversal is complete the function will return NULL.
- *
- * Graph traversal can be interrupted at any moment. No cleanup function call
- * is required and the graph structure can be freed normally.
- *
- * Helper functions can be used to find a link between two given pads, or a pad
- * connected to another pad through an enabled link
- *	media_entity_find_link() and media_entity_remote_pad()
- *
- * Use count and power handling:
- *
- * Due to the wide differences between drivers regarding power management
- * needs, the media controller does not implement power management. However,
- * the &media_entity structure includes a use_count field that media drivers
- * can use to track the number of users of every entity for power management
- * needs.
- *
- * The &media_entity.@use_count field is owned by media drivers and must not be
- * touched by entity drivers. Access to the field must be protected by the
- * &media_device.@graph_mutex lock.
- *
- * Links setup:
- *
- * Link properties can be modified at runtime by calling
- *	media_entity_setup_link()
- *
- * Pipelines and media streams:
- *
- * When starting streaming, drivers must notify all entities in the pipeline to
- * prevent link states from being modified during streaming by calling
- *	media_entity_pipeline_start().
- *
- * The function will mark all entities connected to the given entity through
- * enabled links, either directly or indirectly, as streaming.
- *
- * The &media_pipeline instance pointed to by the pipe argument will be stored
- * in every entity in the pipeline. Drivers should embed the &media_pipeline
- * structure in higher-level pipeline structures and can then access the
- * pipeline through the &media_entity pipe field.
- *
- * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
- * must be identical for all nested calls to the function.
- *
- * media_entity_pipeline_start() may return an error. In that case, it will
- * clean up any of the changes it did by itself.
- *
- * When stopping the stream, drivers must notify the entities with
- *	media_entity_pipeline_stop().
- *
- * If multiple calls to media_entity_pipeline_start() have been made the same
- * number of media_entity_pipeline_stop() calls are required to stop streaming.
- * The &media_entity pipe field is reset to NULL on the last nested stop call.
- *
- * Link configuration will fail with -%EBUSY by default if either end of the
- * link is a streaming entity. Links that can be modified while streaming must
- * be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
- *
- * If other operations need to be disallowed on streaming entities (such as
- * changing entities configuration parameters) drivers can explicitly check the
- * media_entity stream_count field to find out if an entity is streaming. This
- * operation must be done with the media_device graph_mutex held.
- *
- * Link validation:
- *
- * Link validation is performed by media_entity_pipeline_start() for any
- * entity which has sink pads in the pipeline. The
- * &media_entity.@link_validate() callback is used for that purpose. In
- * @link_validate() callback, entity driver should check that the properties of
- * the source pad of the connected entity and its own sink pad match. It is up
- * to the type of the entity (and in the end, the properties of the hardware)
- * what matching actually means.
- *
- * Subsystems should facilitate link validation by providing subsystem specific
- * helper functions to provide easy access for commonly needed information, and
- * in the end provide a way to use driver-specific callbacks.
- */
-
 struct ida;
 struct device;
 
-- 
2.7.4

[PATCH 2/7] [media] doc-rst: media_drivers.rst: Fix paragraph headers for MC

[Mauro Carvalho Chehab]

Fix the paragraph identation for the media controller
headers.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/media_drivers.rst | 41 ++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/Documentation/media/media_drivers.rst b/Documentation/media/media_drivers.rst
index 722170cb7f40..507a40f69d05 100644
--- a/Documentation/media/media_drivers.rst
+++ b/Documentation/media/media_drivers.rst
@@ -183,7 +183,8 @@ The media controller userspace API is documented in DocBook format in
 Documentation/DocBook/media/v4l/media-controller.xml. This document focus
 on the kernel-side implementation of the media framework.
 
-* Abstract media device model:
+Abstract media device model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Discovering a device internal topology, and configuring it at runtime, is one
 of the goals of the media framework. To achieve this, hardware devices are
@@ -205,8 +206,8 @@ A link is a point-to-point oriented connection between two pads, either
 on the same entity or on different entities. Data flows from a source
 pad to a sink pad.
 
-
-* Media device:
+Media device
+^^^^^^^^^^^^
 
 A media device is represented by a struct &media_device instance, defined in
 include/media/media-device.h. Allocation of the structure is handled by the
@@ -218,9 +219,8 @@ __media_device_register() via the macro media_device_register()
 and unregistered by calling
 media_device_unregister().
 
-* Entities, pads and links:
-
-- Entities
+Entities
+^^^^^^^^
 
 Entities are represented by a struct &media_entity instance, defined in
 include/media/media-entity.h. The structure is usually embedded into a
@@ -235,7 +235,8 @@ media_device_register_entity()
 and unregistred by calling
 media_device_unregister_entity().
 
-- Interfaces
+Interfaces
+^^^^^^^^^^
 
 Interfaces are represented by a struct &media_interface instance, defined in
 include/media/media-entity.h. Currently, only one type of interface is
@@ -247,8 +248,8 @@ media_devnode_create()
 and remove them by calling:
 media_devnode_remove().
 
-- Pads
-
+Pads
+^^^^
 Pads are represented by a struct &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
@@ -267,7 +268,8 @@ Pads have flags that describe the pad capabilities and state.
 NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
 be set for each pad.
 
-- Links
+Links
+^^^^^
 
 Links are represented by a struct &media_link instance, defined in
 include/media/media-entity.h. There are two types of links:
@@ -289,15 +291,16 @@ Associate one interface to a Link.
 Drivers create interface to entity links by calling:
 media_create_intf_link() and remove with media_remove_intf_links().
 
-NOTE:
+.. note::
 
-Links can only be created after having both ends already created.
+   Links can only be created after having both ends already created.
 
 Links have flags that describe the link capabilities and state. The
 valid values are described at media_create_pad_link() and
 media_create_intf_link().
 
-Graph traversal:
+Graph traversal
+^^^^^^^^^^^^^^^
 
 The media framework provides APIs to iterate over entities in a graph.
 
@@ -339,7 +342,8 @@ Helper functions can be used to find a link between two given pads, or a pad
 connected to another pad through an enabled link
 media_entity_find_link() and media_entity_remote_pad()
 
-Use count and power handling:
+Use count and power handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Due to the wide differences between drivers regarding power management
 needs, the media controller does not implement power management. However,
@@ -351,12 +355,14 @@ The &media_entity.@use_count field is owned by media drivers and must not be
 touched by entity drivers. Access to the field must be protected by the
 &media_device.@graph_mutex lock.
 
-Links setup:
+Links setup
+^^^^^^^^^^^
 
 Link properties can be modified at runtime by calling
 media_entity_setup_link()
 
-Pipelines and media streams:
+Pipelines and media streams
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When starting streaming, drivers must notify all entities in the pipeline to
 prevent link states from being modified during streaming by calling
@@ -392,7 +398,8 @@ changing entities configuration parameters) drivers can explicitly check the
 media_entity stream_count field to find out if an entity is streaming. This
 operation must be done with the media_device graph_mutex held.
 
-Link validation:
+Link validation
+^^^^^^^^^^^^^^^
 
 Link validation is performed by media_entity_pipeline_start() for any
 entity which has sink pads in the pipeline. The
-- 
2.7.4

[PATCH 3/7] [media] doc-rst: split media_drivers.rst into one file per API type

[Mauro Carvalho Chehab]

Just like the uAPI book is split into parts, let's split the
kAPI documentation. That should make easier to maintain, and
will split the final documentation into smaller html files.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/dtv-core.rst  | 122 ++++++++++
 Documentation/media/kapi/mc-core.rst   | 247 +++++++++++++++++++
 Documentation/media/kapi/rc-core.rst   |   6 +
 Documentation/media/kapi/v4l2-core.rst |  36 +++
 Documentation/media/media_drivers.rst  | 432 ++-------------------------------
 5 files changed, 428 insertions(+), 415 deletions(-)
 create mode 100644 Documentation/media/kapi/dtv-core.rst
 create mode 100644 Documentation/media/kapi/mc-core.rst
 create mode 100644 Documentation/media/kapi/rc-core.rst
 create mode 100644 Documentation/media/kapi/v4l2-core.rst

diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst
new file mode 100644
index 000000000000..fa462d5d0247
--- /dev/null
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -0,0 +1,122 @@
+Digital TV (DVB) devices
+------------------------
+
+Digital TV Common functions
+---------------------------
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
+
+.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
+
+
+Digital TV Frontend kABI
+------------------------
+
+Digital TV Frontend
+~~~~~~~~~~~~~~~~~~~
+
+The Digital TV Frontend kABI defines a driver-internal interface for
+registering low-level, hardware specific driver to a hardware independent
+frontend layer. It is only of interest for Digital TV device driver writers.
+The header file for this API is named dvb_frontend.h and located in
+drivers/media/dvb-core.
+
+Before using the Digital TV frontend core, the bridge driver should attach
+the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
+in order to register the new frontend at the subsystem. At device
+detach/removal, the bridge driver should call dvb_unregister_frontend() to
+remove the frontend from the core and then dvb_frontend_detach() to free the
+memory allocated by the frontend drivers.
+
+The drivers should also call dvb_frontend_suspend() as part of their
+handler for the &device_driver.suspend(), and dvb_frontend_resume() as
+part of their handler for &device_driver.resume().
+
+few other optional functions are provided to handle some special cases.
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
+
+
+Digital TV Demux kABI
+---------------------
+
+Digital TV Demux
+~~~~~~~~~~~~~~~~
+
+The Kernel Digital TV Demux kABI defines a driver-internal interface for
+registering low-level, hardware specific driver to a hardware independent
+demux layer. It is only of interest for Digital TV device driver writers.
+The header file for this kABI is named demux.h and located in
+drivers/media/dvb-core.
+
+The demux kABI should be implemented for each demux in the system. It is
+used to select the TS source of a demux and to manage the demux resources.
+When the demux client allocates a resource via the demux kABI, it receives
+a pointer to the kABI of that resource.
+
+Each demux receives its TS input from a DVB front-end or from memory, as
+set via this demux kABI. In a system with more than one front-end, the kABI
+can be used to select one of the DVB front-ends as a TS source for a demux,
+unless this is fixed in the HW platform.
+
+The demux kABI only controls front-ends regarding to their connections with
+demuxes; the kABI used to set the other front-end parameters, such as
+tuning, are devined via the Digital TV Frontend kABI.
+
+The functions that implement the abstract interface demux should be defined
+static or module private and registered to the Demux core for external
+access. It is not necessary to implement every function in the struct
+&dmx_demux. For example, a demux interface might support Section filtering,
+but not PES filtering. The kABI client is expected to check the value of any
+function pointer before calling the function: the value of NULL means
+that the function is not available.
+
+Whenever the functions of the demux API modify shared data, the
+possibilities of lost update and race condition problems should be
+addressed, e.g. by protecting parts of code with mutexes.
+
+Note that functions called from a bottom half context must not sleep.
+Even a simple memory allocation without using %GFP_ATOMIC can result in a
+kernel thread being put to sleep if swapping is needed. For example, the
+Linux Kernel calls the functions of a network device interface from a
+bottom half context. Thus, if a demux kABI function is called from network
+device code, the function must not sleep.
+
+
+
+Demux Callback API
+------------------
+
+Demux Callback
+~~~~~~~~~~~~~~
+
+This kernel-space API comprises the callback functions that deliver filtered
+data to the demux client. Unlike the other DVB kABIs, these functions are
+provided by the client and called from the demux code.
+
+The function pointers of this abstract interface are not packed into a
+structure as in the other demux APIs, because the callback functions are
+registered and used independent of each other. As an example, it is possible
+for the API client to provide several callback functions for receiving TS
+packets and no callbacks for PES packets or sections.
+
+The functions that implement the callback API need not be re-entrant: when
+a demux driver calls one of these functions, the driver is not allowed to
+call the function again before the original call returns. If a callback is
+triggered by a hardware interrupt, it is recommended to use the Linux
+bottom half mechanism or start a tasklet instead of making the callback
+function call directly from a hardware interrupt.
+
+This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
+callbacks.
+
+
+.. kernel-doc:: drivers/media/dvb-core/demux.h
+
+
+Digital TV Conditional Access kABI
+----------------------------------
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst
new file mode 100644
index 000000000000..2ec242b6e4c3
--- /dev/null
+++ b/Documentation/media/kapi/mc-core.rst
@@ -0,0 +1,247 @@
+Media Controller devices
+------------------------
+
+Media Controller
+~~~~~~~~~~~~~~~~
+
+
+The media controller userspace API is documented in DocBook format in
+Documentation/DocBook/media/v4l/media-controller.xml. This document focus
+on the kernel-side implementation of the media framework.
+
+Abstract media device model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Discovering a device internal topology, and configuring it at runtime, is one
+of the goals of the media framework. To achieve this, hardware devices are
+modelled as an oriented graph of building blocks called entities connected
+through pads.
+
+An entity is a basic media hardware building block. It can correspond to
+a large variety of logical blocks such as physical hardware devices
+(CMOS sensor for instance), logical hardware devices (a building block
+in a System-on-Chip image processing pipeline), DMA channels or physical
+connectors.
+
+A pad is a connection endpoint through which an entity can interact with
+other entities. Data (not restricted to video) produced by an entity
+flows from the entity's output to one or more entity inputs. Pads should
+not be confused with physical pins at chip boundaries.
+
+A link is a point-to-point oriented connection between two pads, either
+on the same entity or on different entities. Data flows from a source
+pad to a sink pad.
+
+Media device
+^^^^^^^^^^^^
+
+A media device is represented by a struct &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 &media_device instance in a
+larger driver-specific structure.
+
+Drivers register media device instances by calling
+__media_device_register() via the macro media_device_register()
+and unregistered by calling
+media_device_unregister().
+
+Entities
+^^^^^^^^
+
+Entities are represented by a struct &media_entity instance, defined in
+include/media/media-entity.h. The structure is usually embedded into a
+higher-level structure, such as a v4l2_subdev or video_device instance,
+although drivers can allocate entities directly.
+
+Drivers initialize entity pads by calling
+media_entity_pads_init().
+
+Drivers register entities with a media device by calling
+media_device_register_entity()
+and unregistred by calling
+media_device_unregister_entity().
+
+Interfaces
+^^^^^^^^^^
+
+Interfaces are represented by a struct &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 struct
+&media_intf_devnode.
+
+Drivers initialize and create device node interfaces by calling
+media_devnode_create()
+and remove them by calling:
+media_devnode_remove().
+
+Pads
+^^^^
+Pads are represented by a struct &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 &media_pad structure, making the
+&media_pad pointer the canonical way to store and pass link references.
+
+Pads have flags that describe the pad capabilities and state.
+
+%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
+%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
+
+NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
+be set for each pad.
+
+Links
+^^^^^
+
+Links are represented by a struct &media_link instance, defined in
+include/media/media-entity.h. There are two types of links:
+
+1. pad to pad links:
+
+Associate two entities via their PADs. Each entity has a list that points
+to all links originating at or targeting any of its pads.
+A given link is thus stored twice, once in the source entity and once in
+the target entity.
+
+Drivers create pad to pad links by calling:
+media_create_pad_link() and remove with media_entity_remove_links().
+
+2. interface to entity links:
+
+Associate one interface to a Link.
+
+Drivers create interface to entity links by calling:
+media_create_intf_link() and remove with media_remove_intf_links().
+
+.. note::
+
+   Links can only be created after having both ends already created.
+
+Links have flags that describe the link capabilities and state. The
+valid values are described at media_create_pad_link() and
+media_create_intf_link().
+
+Graph traversal
+^^^^^^^^^^^^^^^
+
+The media framework provides APIs to iterate over entities in a graph.
+
+To iterate over all entities belonging to a media device, drivers can use
+the media_device_for_each_entity macro, defined in
+include/media/media-device.h.
+
+struct media_entity *entity;
+
+media_device_for_each_entity(entity, mdev) {
+// entity will point to each entity in turn
+...
+}
+
+Drivers might also need to iterate over all entities in a graph that can be
+reached only through enabled links starting at a given entity. The media
+framework provides a depth-first graph traversal API for that purpose.
+
+Note that graphs with cycles (whether directed or undirected) are *NOT*
+supported by the graph traversal API. To prevent infinite loops, the graph
+traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
+currently defined as 16.
+
+Drivers initiate a graph traversal by calling
+media_entity_graph_walk_start()
+
+The graph structure, provided by the caller, is initialized to start graph
+traversal at the given entity.
+
+Drivers can then retrieve the next entity by calling
+media_entity_graph_walk_next()
+
+When the graph traversal is complete the function will return NULL.
+
+Graph traversal can be interrupted at any moment. No cleanup function call
+is required and the graph structure can be freed normally.
+
+Helper functions can be used to find a link between two given pads, or a pad
+connected to another pad through an enabled link
+media_entity_find_link() and media_entity_remote_pad()
+
+Use count and power handling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to the wide differences between drivers regarding power management
+needs, the media controller does not implement power management. However,
+the &media_entity structure includes a use_count field that media drivers
+can use to track the number of users of every entity for power management
+needs.
+
+The &media_entity.@use_count field is owned by media drivers and must not be
+touched by entity drivers. Access to the field must be protected by the
+&media_device.@graph_mutex lock.
+
+Links setup
+^^^^^^^^^^^
+
+Link properties can be modified at runtime by calling
+media_entity_setup_link()
+
+Pipelines and media streams
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When starting streaming, drivers must notify all entities in the pipeline to
+prevent link states from being modified during streaming by calling
+media_entity_pipeline_start().
+
+The function will mark all entities connected to the given entity through
+enabled links, either directly or indirectly, as streaming.
+
+The &media_pipeline instance pointed to by the pipe argument will be stored
+in every entity in the pipeline. Drivers should embed the &media_pipeline
+structure in higher-level pipeline structures and can then access the
+pipeline through the &media_entity pipe field.
+
+Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
+must be identical for all nested calls to the function.
+
+media_entity_pipeline_start() may return an error. In that case, it will
+clean up any of the changes it did by itself.
+
+When stopping the stream, drivers must notify the entities with
+media_entity_pipeline_stop().
+
+If multiple calls to media_entity_pipeline_start() have been made the same
+number of media_entity_pipeline_stop() calls are required to stop streaming.
+The &media_entity pipe field is reset to NULL on the last nested stop call.
+
+Link configuration will fail with -%EBUSY by default if either end of the
+link is a streaming entity. Links that can be modified while streaming must
+be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
+
+If other operations need to be disallowed on streaming entities (such as
+changing entities configuration parameters) drivers can explicitly check the
+media_entity stream_count field to find out if an entity is streaming. This
+operation must be done with the media_device graph_mutex held.
+
+Link validation
+^^^^^^^^^^^^^^^
+
+Link validation is performed by media_entity_pipeline_start() for any
+entity which has sink pads in the pipeline. The
+&media_entity.@link_validate() callback is used for that purpose. In
+@link_validate() callback, entity driver should check that the properties of
+the source pad of the connected entity and its own sink pad match. It is up
+to the type of the entity (and in the end, the properties of the hardware)
+what matching actually means.
+
+Subsystems should facilitate link validation by providing subsystem specific
+helper functions to provide easy access for commonly needed information, and
+in the end provide a way to use driver-specific callbacks.
+
+.. kernel-doc:: include/media/media-device.h
+
+.. kernel-doc:: include/media/media-devnode.h
+
+.. kernel-doc:: include/media/media-entity.h
+
diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst
new file mode 100644
index 000000000000..8c8e3bbac0d7
--- /dev/null
+++ b/Documentation/media/kapi/rc-core.rst
@@ -0,0 +1,6 @@
+Remote Controller devices
+-------------------------
+
+.. kernel-doc:: include/media/rc-core.h
+
+.. kernel-doc:: include/media/lirc_dev.h
diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
new file mode 100644
index 000000000000..a1b73e8d6795
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -0,0 +1,36 @@
+Video2Linux devices
+-------------------
+
+.. kernel-doc:: include/media/tuner.h
+
+.. kernel-doc:: include/media/tuner-types.h
+
+.. kernel-doc:: include/media/tveeprom.h
+
+.. kernel-doc:: include/media/v4l2-async.h
+
+.. kernel-doc:: include/media/v4l2-ctrls.h
+
+.. kernel-doc:: include/media/v4l2-dv-timings.h
+
+.. kernel-doc:: include/media/v4l2-event.h
+
+.. kernel-doc:: include/media/v4l2-flash-led-class.h
+
+.. kernel-doc:: include/media/v4l2-mc.h
+
+.. kernel-doc:: include/media/v4l2-mediabus.h
+
+.. kernel-doc:: include/media/v4l2-mem2mem.h
+
+.. kernel-doc:: include/media/v4l2-of.h
+
+.. kernel-doc:: include/media/v4l2-rect.h
+
+.. kernel-doc:: include/media/v4l2-subdev.h
+
+.. kernel-doc:: include/media/videobuf2-core.h
+
+.. kernel-doc:: include/media/videobuf2-v4l2.h
+
+.. kernel-doc:: include/media/videobuf2-memops.h
diff --git a/Documentation/media/media_drivers.rst b/Documentation/media/media_drivers.rst
index 507a40f69d05..e2388f02d2b8 100644
--- a/Documentation/media/media_drivers.rst
+++ b/Documentation/media/media_drivers.rst
@@ -1,421 +1,23 @@
-==========
-Media core
-==========
+.. -*- coding: utf-8; mode: rst -*-
 
-Video2Linux devices
--------------------
+.. include:: <isonum.txt>
 
-.. kernel-doc:: include/media/tuner.h
+=========================
+Media subsystem core kAPI
+=========================
 
-.. kernel-doc:: include/media/tuner-types.h
+**Copyright** |copy| 2009-2016 : LinuxTV Developers
 
-.. kernel-doc:: include/media/tveeprom.h
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation. A copy of
+the license is included in the chapter entitled "GNU Free Documentation
+License".
 
-.. kernel-doc:: include/media/v4l2-async.h
-
-.. kernel-doc:: include/media/v4l2-ctrls.h
-
-.. kernel-doc:: include/media/v4l2-dv-timings.h
-
-.. kernel-doc:: include/media/v4l2-event.h
-
-.. kernel-doc:: include/media/v4l2-flash-led-class.h
-
-.. kernel-doc:: include/media/v4l2-mc.h
-
-.. kernel-doc:: include/media/v4l2-mediabus.h
-
-.. kernel-doc:: include/media/v4l2-mem2mem.h
-
-.. kernel-doc:: include/media/v4l2-of.h
-
-.. kernel-doc:: include/media/v4l2-rect.h
-
-.. kernel-doc:: include/media/v4l2-subdev.h
-
-.. kernel-doc:: include/media/videobuf2-core.h
-
-.. kernel-doc:: include/media/videobuf2-v4l2.h
-
-.. kernel-doc:: include/media/videobuf2-memops.h
-
-
-Digital TV (DVB) devices
-------------------------
-
-Digital TV Common functions
----------------------------
-
-.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
-
-.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
-
-.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
-
-
-Digital TV Frontend kABI
-------------------------
-
-Digital TV Frontend
-~~~~~~~~~~~~~~~~~~~
-
-The Digital TV Frontend kABI defines a driver-internal interface for
-registering low-level, hardware specific driver to a hardware independent
-frontend layer. It is only of interest for Digital TV device driver writers.
-The header file for this API is named dvb_frontend.h and located in
-drivers/media/dvb-core.
-
-Before using the Digital TV frontend core, the bridge driver should attach
-the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
-in order to register the new frontend at the subsystem. At device
-detach/removal, the bridge driver should call dvb_unregister_frontend() to
-remove the frontend from the core and then dvb_frontend_detach() to free the
-memory allocated by the frontend drivers.
-
-The drivers should also call dvb_frontend_suspend() as part of their
-handler for the &device_driver.suspend(), and dvb_frontend_resume() as
-part of their handler for &device_driver.resume().
-
-few other optional functions are provided to handle some special cases.
-
-.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
-
-
-Digital TV Demux kABI
----------------------
-
-Digital TV Demux
-~~~~~~~~~~~~~~~~
-
-The Kernel Digital TV Demux kABI defines a driver-internal interface for
-registering low-level, hardware specific driver to a hardware independent
-demux layer. It is only of interest for Digital TV device driver writers.
-The header file for this kABI is named demux.h and located in
-drivers/media/dvb-core.
-
-The demux kABI should be implemented for each demux in the system. It is
-used to select the TS source of a demux and to manage the demux resources.
-When the demux client allocates a resource via the demux kABI, it receives
-a pointer to the kABI of that resource.
-
-Each demux receives its TS input from a DVB front-end or from memory, as
-set via this demux kABI. In a system with more than one front-end, the kABI
-can be used to select one of the DVB front-ends as a TS source for a demux,
-unless this is fixed in the HW platform.
-
-The demux kABI only controls front-ends regarding to their connections with
-demuxes; the kABI used to set the other front-end parameters, such as
-tuning, are devined via the Digital TV Frontend kABI.
-
-The functions that implement the abstract interface demux should be defined
-static or module private and registered to the Demux core for external
-access. It is not necessary to implement every function in the struct
-&dmx_demux. For example, a demux interface might support Section filtering,
-but not PES filtering. The kABI client is expected to check the value of any
-function pointer before calling the function: the value of NULL means
-that the function is not available.
-
-Whenever the functions of the demux API modify shared data, the
-possibilities of lost update and race condition problems should be
-addressed, e.g. by protecting parts of code with mutexes.
-
-Note that functions called from a bottom half context must not sleep.
-Even a simple memory allocation without using %GFP_ATOMIC can result in a
-kernel thread being put to sleep if swapping is needed. For example, the
-Linux Kernel calls the functions of a network device interface from a
-bottom half context. Thus, if a demux kABI function is called from network
-device code, the function must not sleep.
-
-
-
-Demux Callback API
-------------------
-
-Demux Callback
-~~~~~~~~~~~~~~
-
-This kernel-space API comprises the callback functions that deliver filtered
-data to the demux client. Unlike the other DVB kABIs, these functions are
-provided by the client and called from the demux code.
-
-The function pointers of this abstract interface are not packed into a
-structure as in the other demux APIs, because the callback functions are
-registered and used independent of each other. As an example, it is possible
-for the API client to provide several callback functions for receiving TS
-packets and no callbacks for PES packets or sections.
-
-The functions that implement the callback API need not be re-entrant: when
-a demux driver calls one of these functions, the driver is not allowed to
-call the function again before the original call returns. If a callback is
-triggered by a hardware interrupt, it is recommended to use the Linux
-bottom half mechanism or start a tasklet instead of making the callback
-function call directly from a hardware interrupt.
-
-This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
-callbacks.
-
-
-.. kernel-doc:: drivers/media/dvb-core/demux.h
-
-
-Digital TV Conditional Access kABI
-----------------------------------
-
-.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
-
-
-Remote Controller devices
--------------------------
-
-.. kernel-doc:: include/media/rc-core.h
-
-.. kernel-doc:: include/media/lirc_dev.h
-
-
-Media Controller devices
-------------------------
-
-Media Controller
-~~~~~~~~~~~~~~~~
-
-
-The media controller userspace API is documented in DocBook format in
-Documentation/DocBook/media/v4l/media-controller.xml. This document focus
-on the kernel-side implementation of the media framework.
-
-Abstract media device model
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Discovering a device internal topology, and configuring it at runtime, is one
-of the goals of the media framework. To achieve this, hardware devices are
-modelled as an oriented graph of building blocks called entities connected
-through pads.
-
-An entity is a basic media hardware building block. It can correspond to
-a large variety of logical blocks such as physical hardware devices
-(CMOS sensor for instance), logical hardware devices (a building block
-in a System-on-Chip image processing pipeline), DMA channels or physical
-connectors.
-
-A pad is a connection endpoint through which an entity can interact with
-other entities. Data (not restricted to video) produced by an entity
-flows from the entity's output to one or more entity inputs. Pads should
-not be confused with physical pins at chip boundaries.
-
-A link is a point-to-point oriented connection between two pads, either
-on the same entity or on different entities. Data flows from a source
-pad to a sink pad.
-
-Media device
-^^^^^^^^^^^^
-
-A media device is represented by a struct &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 &media_device instance in a
-larger driver-specific structure.
-
-Drivers register media device instances by calling
-__media_device_register() via the macro media_device_register()
-and unregistered by calling
-media_device_unregister().
-
-Entities
-^^^^^^^^
-
-Entities are represented by a struct &media_entity instance, defined in
-include/media/media-entity.h. The structure is usually embedded into a
-higher-level structure, such as a v4l2_subdev or video_device instance,
-although drivers can allocate entities directly.
-
-Drivers initialize entity pads by calling
-media_entity_pads_init().
-
-Drivers register entities with a media device by calling
-media_device_register_entity()
-and unregistred by calling
-media_device_unregister_entity().
-
-Interfaces
-^^^^^^^^^^
-
-Interfaces are represented by a struct &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 struct
-&media_intf_devnode.
-
-Drivers initialize and create device node interfaces by calling
-media_devnode_create()
-and remove them by calling:
-media_devnode_remove().
-
-Pads
-^^^^
-Pads are represented by a struct &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 &media_pad structure, making the
-&media_pad pointer the canonical way to store and pass link references.
-
-Pads have flags that describe the pad capabilities and state.
-
-%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
-%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
-
-NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
-be set for each pad.
-
-Links
-^^^^^
-
-Links are represented by a struct &media_link instance, defined in
-include/media/media-entity.h. There are two types of links:
-
-1. pad to pad links:
-
-Associate two entities via their PADs. Each entity has a list that points
-to all links originating at or targeting any of its pads.
-A given link is thus stored twice, once in the source entity and once in
-the target entity.
-
-Drivers create pad to pad links by calling:
-media_create_pad_link() and remove with media_entity_remove_links().
-
-2. interface to entity links:
-
-Associate one interface to a Link.
-
-Drivers create interface to entity links by calling:
-media_create_intf_link() and remove with media_remove_intf_links().
-
-.. note::
-
-   Links can only be created after having both ends already created.
-
-Links have flags that describe the link capabilities and state. The
-valid values are described at media_create_pad_link() and
-media_create_intf_link().
-
-Graph traversal
-^^^^^^^^^^^^^^^
-
-The media framework provides APIs to iterate over entities in a graph.
-
-To iterate over all entities belonging to a media device, drivers can use
-the media_device_for_each_entity macro, defined in
-include/media/media-device.h.
-
-struct media_entity *entity;
-
-media_device_for_each_entity(entity, mdev) {
-// entity will point to each entity in turn
-...
-}
-
-Drivers might also need to iterate over all entities in a graph that can be
-reached only through enabled links starting at a given entity. The media
-framework provides a depth-first graph traversal API for that purpose.
-
-Note that graphs with cycles (whether directed or undirected) are *NOT*
-supported by the graph traversal API. To prevent infinite loops, the graph
-traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
-currently defined as 16.
-
-Drivers initiate a graph traversal by calling
-media_entity_graph_walk_start()
-
-The graph structure, provided by the caller, is initialized to start graph
-traversal at the given entity.
-
-Drivers can then retrieve the next entity by calling
-media_entity_graph_walk_next()
-
-When the graph traversal is complete the function will return NULL.
-
-Graph traversal can be interrupted at any moment. No cleanup function call
-is required and the graph structure can be freed normally.
-
-Helper functions can be used to find a link between two given pads, or a pad
-connected to another pad through an enabled link
-media_entity_find_link() and media_entity_remote_pad()
-
-Use count and power handling
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Due to the wide differences between drivers regarding power management
-needs, the media controller does not implement power management. However,
-the &media_entity structure includes a use_count field that media drivers
-can use to track the number of users of every entity for power management
-needs.
-
-The &media_entity.@use_count field is owned by media drivers and must not be
-touched by entity drivers. Access to the field must be protected by the
-&media_device.@graph_mutex lock.
-
-Links setup
-^^^^^^^^^^^
-
-Link properties can be modified at runtime by calling
-media_entity_setup_link()
-
-Pipelines and media streams
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When starting streaming, drivers must notify all entities in the pipeline to
-prevent link states from being modified during streaming by calling
-media_entity_pipeline_start().
-
-The function will mark all entities connected to the given entity through
-enabled links, either directly or indirectly, as streaming.
-
-The &media_pipeline instance pointed to by the pipe argument will be stored
-in every entity in the pipeline. Drivers should embed the &media_pipeline
-structure in higher-level pipeline structures and can then access the
-pipeline through the &media_entity pipe field.
-
-Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
-must be identical for all nested calls to the function.
-
-media_entity_pipeline_start() may return an error. In that case, it will
-clean up any of the changes it did by itself.
-
-When stopping the stream, drivers must notify the entities with
-media_entity_pipeline_stop().
-
-If multiple calls to media_entity_pipeline_start() have been made the same
-number of media_entity_pipeline_stop() calls are required to stop streaming.
-The &media_entity pipe field is reset to NULL on the last nested stop call.
-
-Link configuration will fail with -%EBUSY by default if either end of the
-link is a streaming entity. Links that can be modified while streaming must
-be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
-
-If other operations need to be disallowed on streaming entities (such as
-changing entities configuration parameters) drivers can explicitly check the
-media_entity stream_count field to find out if an entity is streaming. This
-operation must be done with the media_device graph_mutex held.
-
-Link validation
-^^^^^^^^^^^^^^^
-
-Link validation is performed by media_entity_pipeline_start() for any
-entity which has sink pads in the pipeline. The
-&media_entity.@link_validate() callback is used for that purpose. In
-@link_validate() callback, entity driver should check that the properties of
-the source pad of the connected entity and its own sink pad match. It is up
-to the type of the entity (and in the end, the properties of the hardware)
-what matching actually means.
-
-Subsystems should facilitate link validation by providing subsystem specific
-helper functions to provide easy access for commonly needed information, and
-in the end provide a way to use driver-specific callbacks.
-
-.. kernel-doc:: include/media/media-device.h
-
-.. kernel-doc:: include/media/media-devnode.h
-
-.. kernel-doc:: include/media/media-entity.h
+.. toctree::
+    :maxdepth: 5
 
+    kapi/v4l2-core
+    kapi/dtv-core
+    kapi/rc-core
+    kapi/mc-core
-- 
2.7.4

[PATCH 4/7] [media] doc-rst: Fix issues with RC documentation

[Mauro Carvalho Chehab]

The kernel-doc script is now broken if it doesn't find all
exported symbols documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/rc-core.rst |  9 ++++++++
 include/media/lirc_dev.h             |  2 +-
 include/media/rc-core.h              | 45 ++++++++++++++++++++++++++++++++++--
 include/media/rc-map.h               | 17 +++++++++++++-
 4 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst
index 8c8e3bbac0d7..9c244ac9ce92 100644
--- a/Documentation/media/kapi/rc-core.rst
+++ b/Documentation/media/kapi/rc-core.rst
@@ -1,6 +1,15 @@
 Remote Controller devices
 -------------------------
 
+Remote Controller core
+~~~~~~~~~~~~~~~~~~~~~~
+
 .. kernel-doc:: include/media/rc-core.h
 
+.. kernel-doc:: include/media/rc-core.h include/media/rc-map.h
+   :export: drivers/media/rc/rc-main.c drivers/media/rc/rc-raw.c
+
+LIRC
+~~~~
+
 .. kernel-doc:: include/media/lirc_dev.h
diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index 0ab59a571fee..cec7d35602d1 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -140,7 +140,7 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf,
  *			second.
  *
  * @features:		lirc compatible hardware features, like LIRC_MODE_RAW,
- *			LIRC_CAN_*, as defined at include/media/lirc.h.
+ *			LIRC_CAN\_\*, as defined at include/media/lirc.h.
  *
  * @chunk_size:		Size of each FIFO buffer.
  *
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index b6586a91129c..ff54a71f5cd2 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -29,9 +29,16 @@ do {								\
 		printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__);	\
 } while (0)
 
+/**
+ * enum rc_driver_type - type of the RC output
+ *
+ * @RC_DRIVER_SCANCODE:	Driver or hardware generates a scancode
+ * @RC_DRIVER_IR_RAW:	Driver or hardware generates pulse/space sequences.
+ *			It needs a Infra-Red pulse/space decoder
+ */
 enum rc_driver_type {
-	RC_DRIVER_SCANCODE = 0,	/* Driver or hardware generates a scancode */
-	RC_DRIVER_IR_RAW,	/* Needs a Infra-Red pulse/space decoder */
+	RC_DRIVER_SCANCODE = 0,
+	RC_DRIVER_IR_RAW,
 };
 
 /**
@@ -185,12 +192,46 @@ struct rc_dev {
  * Remote Controller, at sys/class/rc.
  */
 
+/**
+ * rc_allocate_device - Allocates a RC device
+ *
+ * returns a pointer to struct rc_dev.
+ */
 struct rc_dev *rc_allocate_device(void);
+
+/**
+ * rc_free_device - Frees a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 void rc_free_device(struct rc_dev *dev);
+
+/**
+ * rc_register_device - Registers a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 int rc_register_device(struct rc_dev *dev);
+
+/**
+ * rc_unregister_device - Unregisters a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 void rc_unregister_device(struct rc_dev *dev);
 
+/**
+ * rc_open - Opens a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
 int rc_open(struct rc_dev *rdev);
+
+/**
+ * rc_open - Closes a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
 void rc_close(struct rc_dev *rdev);
 
 void rc_repeat(struct rc_dev *dev);
diff --git a/include/media/rc-map.h b/include/media/rc-map.h
index 6e6557dbeb9f..726bd9374fd2 100644
--- a/include/media/rc-map.h
+++ b/include/media/rc-map.h
@@ -98,10 +98,25 @@ struct rc_map_list {
 
 /* Routines from rc-map.c */
 
+/**
+ * rc_map_register() - Registers a Remote Controler scancode map
+ *
+ * @map:	pointer to struct rc_map_list
+ */
 int rc_map_register(struct rc_map_list *map);
+
+/**
+ * rc_map_unregister() - Unregisters a Remote Controler scancode map
+ *
+ * @map:	pointer to struct rc_map_list
+ */
 void rc_map_unregister(struct rc_map_list *map);
+
+/**
+ * rc_map_get - gets an RC map from its name
+ * @name: name of the RC scancode map
+ */
 struct rc_map *rc_map_get(const char *name);
-void rc_map_init(void);
 
 /* Names of the several keytables defined in-kernel */
 
-- 
2.7.4

[PATCH 5/7] [media] doc-rst: Fix conversion for v4l2 core functions

[Mauro Carvalho Chehab]

The conversion from DocBook lead into some conversion issues,
basically due to the lack of proper support at kernel-doc.

So, address them:

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- kernel-doc doesn't escape things like *pointer, so we
  need to manually add a escape char before it.

- On some cases, kernel-doc conversion requires violating
  the 80-cols, as otherwise it won't properly parse the
  source code.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-core.rst | 21 +++++++++++++++++++++
 include/media/tuner-types.h            |  8 ++++++--
 include/media/tveeprom.h               | 18 +++++++++++++++---
 include/media/v4l2-mc.h                | 13 ++++++++-----
 include/media/v4l2-subdev.h            |  4 ++--
 include/media/videobuf2-core.h         | 30 ++++++++++++++++++------------
 6 files changed, 70 insertions(+), 24 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index a1b73e8d6795..4e2aa721d9c8 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -34,3 +34,24 @@ Video2Linux devices
 .. kernel-doc:: include/media/videobuf2-v4l2.h
 
 .. kernel-doc:: include/media/videobuf2-memops.h
+
+
+
+
+.. kernel-doc:: include/media/tveeprom.h
+   :export: drivers/media/common/tveeprom.c
+
+.. kernel-doc:: include/media/v4l2-ctrls.h
+   :export: drivers/media/v4l2-core/v4l2-ctrls.c
+
+.. kernel-doc:: include/media/v4l2-dv-timings.h
+   :export: drivers/media/v4l2-core/v4l2-dv-timings.c
+
+.. kernel-doc:: include/media/v4l2-flash-led-class.h
+   :export: drivers/media/v4l2-core/v4l2-flash-led-class.c
+
+.. kernel-doc:: include/media/v4l2-mc.h
+   :export: drivers/media/v4l2-core/v4l2-mc.c
+
+.. kernel-doc:: include/media/videobuf2-core.h
+   :export: drivers/media/v4l2-core/videobuf2-core.c
diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index 094e112cc325..aed539068d2d 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -35,8 +35,12 @@ enum param_type {
  * those ranges, as they're defined inside the driver. This is used by
  * analog tuners that are compatible with the "Philips way" to setup the
  * tuners. On those devices, the tuner set is done via 4 bytes:
- *	divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
- *	band switch byte (BB).
+ *
+ *	#) divider byte1 (DB1)
+ *	#) divider byte 2 (DB2)
+ *	#) Control byte (CB)
+ *	#) band switch byte (BB)
+ *
  * Some tuners also have an additional optional Auxiliary byte (AB).
  */
 struct tuner_range {
diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h
index 8be898739e0c..c56501ee0484 100644
--- a/include/media/tveeprom.h
+++ b/include/media/tveeprom.h
@@ -27,31 +27,43 @@ enum tveeprom_audio_processor {
  * struct tveeprom - Contains the fields parsed from Hauppauge eeproms
  *
  * @has_radio:			1 if the device has radio; 0 otherwise.
+ *
  * @has_ir:			If has_ir == 0, then it is unknown what the IR
  *				capabilities are. Otherwise:
- *					bit 0) 1 (= IR capabilities are known);
- *					bit 1) IR receiver present;
- *					bit 2) IR transmitter (blaster) present.
+ *				bit 0) 1 (= IR capabilities are known);
+ *				bit 1) IR receiver present;
+ *				bit 2) IR transmitter (blaster) present.
+ *
  * @has_MAC_address:		0: no MAC, 1: MAC present, 2: unknown.
  * @tuner_type:			type of the tuner (TUNER_*, as defined at
  *				include/media/tuner.h).
+ *
  * @tuner_formats:		Supported analog TV standards (V4L2_STD_*).
  * @tuner_hauppauge_model:	Hauppauge's code for the device model number.
  * @tuner2_type:		type of the second tuner (TUNER_*, as defined
  *				at include/media/tuner.h).
+ *
  * @tuner2_formats:		Tuner 2 supported analog TV standards
  *				(V4L2_STD_*).
+ *
  * @tuner2_hauppauge_model:	tuner 2 Hauppauge's code for the device model
  *				number.
+ *
  * @audio_processor:		analog audio decoder, as defined by enum
  *				tveeprom_audio_processor.
+ *
  * @decoder_processor:		Hauppauge's code for the decoder chipset.
  *				Unused by the drivers, as they probe the
  *				decoder based on the PCI or USB ID.
+ *
  * @model:			Hauppauge's model number
+ *
  * @revision:			Card revision number
+ *
  * @serial_number:		Card's serial number
+ *
  * @rev_str:			Card revision converted to number
+ *
  * @MAC_address:		MAC address for the network interface
  */
 struct tveeprom {
diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h
index 7a8d6037a4bb..28c3f9d9c209 100644
--- a/include/media/v4l2-mc.h
+++ b/include/media/v4l2-mc.h
@@ -114,11 +114,14 @@ struct usb_device;
  * Add links between the entities commonly found on PC customer's hardware at
  * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
  * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
- * NOTE: webcams are modelled on a very simple way: the sensor is
- * connected directly to the I/O entity. All dirty details, like
- * scaler and crop HW are hidden. While such mapping is enough for v4l2
- * interface centric PC-consumer's hardware, V4L2 subdev centric camera
- * hardware should not use this routine, as it will not build the right graph.
+ *
+ * .. note::
+ *
+ *    Webcams are modelled on a very simple way: the sensor is
+ *    connected directly to the I/O entity. All dirty details, like
+ *    scaler and crop HW are hidden. While such mapping is enough for v4l2
+ *    interface centric PC-consumer's hardware, V4L2 subdev centric camera
+ *    hardware should not use this routine, as it will not build the right graph.
  */
 int v4l2_mc_create_media_graph(struct media_device *mdev);
 
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 32fc7a4beb5e..4c880e86a1aa 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -225,7 +225,7 @@ struct v4l2_subdev_core_ops {
  *
  * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code.
  *		 freq->type must be filled in. Normally done by video_ioctl2
- *		or the bridge driver.
+ *		 or the bridge driver.
  *
  * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
  *
@@ -233,7 +233,7 @@ struct v4l2_subdev_core_ops {
  *
  * @s_tuner: callback for VIDIOC_S_TUNER ioctl handler code. vt->type must be
  *	     filled in. Normally done by video_ioctl2 or the
- *	bridge driver.
+ *	     bridge driver.
  *
  * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code.
  *
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 88e3ab496e8f..01cdd5bf90c8 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -86,11 +86,17 @@ struct vb2_threadio_data;
  * @mmap:	setup a userspace mapping for a given memory buffer under
  *		the provided virtual memory region.
  *
- * Required ops for USERPTR types: get_userptr, put_userptr.
- * Required ops for MMAP types: alloc, put, num_users, mmap.
- * Required ops for read/write access types: alloc, put, num_users, vaddr.
- * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
- *				  unmap_dmabuf.
+ * Those operations are used by the videobuf2 core to implement the memory
+ * handling/memory allocators for each type of supported streaming I/O method.
+ *
+ * .. note::
+ *    #) Required ops for USERPTR types: get_userptr, put_userptr.
+ *
+ *    #) Required ops for MMAP types: alloc, put, num_users, mmap.
+ *
+ *    #) Required ops for read/write access types: alloc, put, num_users, vaddr.
+ *
+ *    #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
  */
 struct vb2_mem_ops {
 	void		*(*alloc)(void *alloc_ctx, unsigned long size,
@@ -279,19 +285,19 @@ struct vb2_buffer {
  *			second time with the actually allocated number of
  *			buffers to verify if that is OK.
  *			The driver should return the required number of buffers
- *			in *num_buffers, the required number of planes per
- *			buffer in *num_planes, the size of each plane should be
+ *			in \*num_buffers, the required number of planes per
+ *			buffer in \*num_planes, the size of each plane should be
  *			set in the sizes[] array and optional per-plane
  *			allocator specific context in the alloc_ctxs[] array.
- *			When called from VIDIOC_REQBUFS, *num_planes == 0, the
+ *			When called from VIDIOC_REQBUFS, \*num_planes == 0, the
  *			driver has to use the currently configured format to
- *			determine the plane sizes and *num_buffers is the total
+ *			determine the plane sizes and \*num_buffers is the total
  *			number of buffers that are being allocated. When called
- *			from VIDIOC_CREATE_BUFS, *num_planes != 0 and it
+ *			from VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
  *			describes the requested number of planes and sizes[]
  *			contains the requested plane sizes. If either
- *			*num_planes or the requested sizes are invalid callback
- *			must return -EINVAL. In this case *num_buffers are
+ *			\*num_planes or the requested sizes are invalid callback
+ *			must return -EINVAL. In this case \*num_buffers are
  *			being allocated additionally to q->num_buffers.
  * @wait_prepare:	release any locks taken while calling vb2 functions;
  *			it is called before an ioctl needs to wait for a new
-- 
2.7.4

[PATCH 6/7] [media] doc-rst: Fix conversion for MC core functions

[Mauro Carvalho Chehab]

There were lots of issues at the media controller side,
after the conversion:

- Some documentation at the header files weren't using the
  kernel-doc start block;

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- Fix the cross-references at the media controller description.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/mc-core.rst | 186 ++++++++++++++++++++---------------
 include/media/media-device.h         |  24 ++---
 include/media/media-entity.h         |  83 +++++++++-------
 3 files changed, 163 insertions(+), 130 deletions(-)

diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst
index 2ec242b6e4c3..2ab541ba6e88 100644
--- a/Documentation/media/kapi/mc-core.rst
+++ b/Documentation/media/kapi/mc-core.rst
@@ -4,9 +4,8 @@ Media Controller devices
 Media Controller
 ~~~~~~~~~~~~~~~~
 
-
-The media controller userspace API is documented in DocBook format in
-Documentation/DocBook/media/v4l/media-controller.xml. This document focus
+The media controller userspace API is documented in
+:ref:`the Media Controller uAPI book <media_common>`. This document focus
 on the kernel-side implementation of the media framework.
 
 Abstract media device model
@@ -35,72 +34,77 @@ pad to a sink pad.
 Media device
 ^^^^^^^^^^^^
 
-A media device is represented by a struct &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 &media_device instance in a
-larger driver-specific structure.
+A media device is represented by a :c:type:`struct media_device <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
+structure.
 
 Drivers register media device instances by calling
-__media_device_register() via the macro media_device_register()
-and unregistered by calling
-media_device_unregister().
+:cpp:func:`__media_device_register()` via the macro ``media_device_register()``
+and unregistered by calling :cpp:func:`media_device_unregister()`.
 
 Entities
 ^^^^^^^^
 
-Entities are represented by a struct &media_entity instance, defined in
-include/media/media-entity.h. The structure is usually embedded into a
-higher-level structure, such as a v4l2_subdev or video_device instance,
-although drivers can allocate entities directly.
+Entities are represented by a :c:type:`struct media_entity <media_entity>`
+instance, defined in ``include/media/media-entity.h``. The structure is usually
+embedded into a higher-level structure, such as
+:ref:`v4l2_subdev` or :ref:`video_device`
+instances, although drivers can allocate entities directly.
 
 Drivers initialize entity pads by calling
-media_entity_pads_init().
+:cpp:func:`media_entity_pads_init()`.
 
 Drivers register entities with a media device by calling
-media_device_register_entity()
+:cpp:func:`media_device_register_entity()`
 and unregistred by calling
-media_device_unregister_entity().
+:cpp:func:`media_device_unregister_entity()`.
 
 Interfaces
 ^^^^^^^^^^
 
-Interfaces are represented by a struct &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 struct
-&media_intf_devnode.
+Interfaces are represented by a
+:c:type:`struct media_interface <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>`.
 
 Drivers initialize and create device node interfaces by calling
-media_devnode_create()
+:cpp:func:`media_devnode_create()`
 and remove them by calling:
-media_devnode_remove().
+:cpp:func:`media_devnode_remove()`.
 
 Pads
 ^^^^
-Pads are represented by a struct &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 represented by a :c:type:`struct media_pad <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 &media_pad structure, making the
-&media_pad pointer the canonical way to store and pass link references.
+
+Both information are stored in the :c:type:`struct media_pad`, making the
+:c:type:`media_pad` pointer the canonical way to store and pass link references.
 
 Pads have flags that describe the pad capabilities and state.
 
-%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
-%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
+``MEDIA_PAD_FL_SINK`` indicates that the pad supports sinking data.
+``MEDIA_PAD_FL_SOURCE`` indicates that the pad supports sourcing data.
 
-NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
-be set for each pad.
+.. note::
+
+  One and only one of ``MEDIA_PAD_FL_SINK`` or ``MEDIA_PAD_FL_SOURCE`` must
+  be set for each pad.
 
 Links
 ^^^^^
 
-Links are represented by a struct &media_link instance, defined in
-include/media/media-entity.h. There are two types of links:
+Links are represented by a :c:type:`struct media_link <media_link>` instance,
+defined in ``include/media/media-entity.h``. There are two types of links:
 
-1. pad to pad links:
+**1. pad to pad links**:
 
 Associate two entities via their PADs. Each entity has a list that points
 to all links originating at or targeting any of its pads.
@@ -108,22 +112,24 @@ A given link is thus stored twice, once in the source entity and once in
 the target entity.
 
 Drivers create pad to pad links by calling:
-media_create_pad_link() and remove with media_entity_remove_links().
+:cpp:func:`media_create_pad_link()` and remove with
+:cpp:func:`media_entity_remove_links()`.
 
-2. interface to entity links:
+**2. interface to entity links**:
 
 Associate one interface to a Link.
 
 Drivers create interface to entity links by calling:
-media_create_intf_link() and remove with media_remove_intf_links().
+:cpp:func:`media_create_intf_link()` and remove with
+:cpp:func:`media_remove_intf_links()`.
 
 .. note::
 
    Links can only be created after having both ends already created.
 
 Links have flags that describe the link capabilities and state. The
-valid values are described at media_create_pad_link() and
-media_create_intf_link().
+valid values are described at :cpp:func:`media_create_pad_link()` and
+:cpp:func:`media_create_intf_link()`.
 
 Graph traversal
 ^^^^^^^^^^^^^^^
@@ -132,92 +138,103 @@ The media framework provides APIs to iterate over entities in a graph.
 
 To iterate over all entities belonging to a media device, drivers can use
 the media_device_for_each_entity macro, defined in
-include/media/media-device.h.
+``include/media/media-device.h``.
 
-struct media_entity *entity;
+..  code-block:: c
 
-media_device_for_each_entity(entity, mdev) {
-// entity will point to each entity in turn
-...
-}
+    struct media_entity *entity;
+
+    media_device_for_each_entity(entity, mdev) {
+    // entity will point to each entity in turn
+    ...
+    }
 
 Drivers might also need to iterate over all entities in a graph that can be
 reached only through enabled links starting at a given entity. The media
 framework provides a depth-first graph traversal API for that purpose.
 
-Note that graphs with cycles (whether directed or undirected) are *NOT*
-supported by the graph traversal API. To prevent infinite loops, the graph
-traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
-currently defined as 16.
+.. note::
+
+   Graphs with cycles (whether directed or undirected) are **NOT**
+   supported by the graph traversal API. To prevent infinite loops, the graph
+   traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``,
+   currently defined as 16.
 
 Drivers initiate a graph traversal by calling
-media_entity_graph_walk_start()
+:cpp:func:`media_entity_graph_walk_start()`
 
 The graph structure, provided by the caller, is initialized to start graph
 traversal at the given entity.
 
 Drivers can then retrieve the next entity by calling
-media_entity_graph_walk_next()
+:cpp:func:`media_entity_graph_walk_next()`
 
-When the graph traversal is complete the function will return NULL.
+When the graph traversal is complete the function will return ``NULL``.
 
 Graph traversal can be interrupted at any moment. No cleanup function call
 is required and the graph structure can be freed normally.
 
 Helper functions can be used to find a link between two given pads, or a pad
 connected to another pad through an enabled link
-media_entity_find_link() and media_entity_remote_pad()
+:cpp:func:`media_entity_find_link()` and
+:cpp:func:`media_entity_remote_pad()`.
 
 Use count and power handling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Due to the wide differences between drivers regarding power management
 needs, the media controller does not implement power management. However,
-the &media_entity structure includes a use_count field that media drivers
+the :c:type:`struct media_entity <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 &media_entity.@use_count field is owned by media drivers and must not be
+The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by
+media drivers and must not be
 touched by entity drivers. Access to the field must be protected by the
-&media_device.@graph_mutex lock.
+:c:type:`media_device`.\ ``graph_mutex`` lock.
 
 Links setup
 ^^^^^^^^^^^
 
 Link properties can be modified at runtime by calling
-media_entity_setup_link()
+:cpp:func:`media_entity_setup_link()`.
 
 Pipelines and media streams
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When starting streaming, drivers must notify all entities in the pipeline to
 prevent link states from being modified during streaming by calling
-media_entity_pipeline_start().
+:cpp:func:`media_entity_pipeline_start()`.
 
 The function will mark all entities connected to the given entity through
 enabled links, either directly or indirectly, as streaming.
 
-The &media_pipeline instance pointed to by the pipe argument will be stored
-in every entity in the pipeline. Drivers should embed the &media_pipeline
-structure in higher-level pipeline structures and can then access the
-pipeline through the &media_entity pipe field.
+The :c:type:`struct media_pipeline <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>`
+in higher-level pipeline structures and can then access the
+pipeline through the :c:type:`struct media_entity <media_entity>`
+pipe field.
 
-Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
-must be identical for all nested calls to the function.
+Calls to :cpp:func:`media_entity_pipeline_start()` can be nested.
+The pipeline pointer must be identical for all nested calls to the function.
 
-media_entity_pipeline_start() may return an error. In that case, it will
-clean up any of the changes it did by itself.
+:cpp:func:`media_entity_pipeline_start()` may return an error. In that case,
+it will clean up any of the changes it did by itself.
 
 When stopping the stream, drivers must notify the entities with
-media_entity_pipeline_stop().
+:cpp:func:`media_entity_pipeline_stop()`.
 
-If multiple calls to media_entity_pipeline_start() have been made the same
-number of media_entity_pipeline_stop() calls are required to stop streaming.
-The &media_entity pipe field is reset to NULL on the last nested stop call.
+If multiple calls to :cpp:func:`media_entity_pipeline_start()` have been
+made the same number of :cpp:func:`media_entity_pipeline_stop()` calls
+are required to stop streaming.
+The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
+nested stop call.
 
-Link configuration will fail with -%EBUSY by default if either end of the
+Link configuration will fail with ``-EBUSY`` by default if either end of the
 link is a streaming entity. Links that can be modified while streaming must
-be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
+be marked with the ``MEDIA_LNK_FL_DYNAMIC`` flag.
 
 If other operations need to be disallowed on streaming entities (such as
 changing entities configuration parameters) drivers can explicitly check the
@@ -227,13 +244,13 @@ operation must be done with the media_device graph_mutex held.
 Link validation
 ^^^^^^^^^^^^^^^
 
-Link validation is performed by media_entity_pipeline_start() for any
-entity which has sink pads in the pipeline. The
-&media_entity.@link_validate() callback is used for that purpose. In
-@link_validate() callback, entity driver should check that the properties of
-the source pad of the connected entity and its own sink pad match. It is up
-to the type of the entity (and in the end, the properties of the hardware)
-what matching actually means.
+Link validation is performed by :cpp:func:`media_entity_pipeline_start()`
+for any entity which has sink pads in the pipeline. The
+:c:type:`media_entity`.\ ``link_validate()`` callback is used for that
+purpose. In ``link_validate()`` callback, entity driver should check
+that the properties of the source pad of the connected entity and its own
+sink pad match. It is up to the type of the entity (and in the end, the
+properties of the hardware) what matching actually means.
 
 Subsystems should facilitate link validation by providing subsystem specific
 helper functions to provide easy access for commonly needed information, and
@@ -245,3 +262,10 @@ in the end provide a way to use driver-specific callbacks.
 
 .. kernel-doc:: include/media/media-entity.h
 
+
+
+.. kernel-doc:: include/media/media-device.h
+   :export: drivers/media/media-device.c
+
+.. kernel-doc:: include/media/media-entity.h
+   :export: drivers/media/media-entity.c
diff --git a/include/media/media-device.h b/include/media/media-device.h
index 4605fee0c228..28195242386c 100644
--- a/include/media/media-device.h
+++ b/include/media/media-device.h
@@ -242,13 +242,11 @@ void media_device_cleanup(struct media_device *mdev);
  *    without breaking binary compatibility. The version major must be
  *    incremented when binary compatibility is broken.
  *
- * Notes:
+ * .. note::
  *
- * Upon successful registration a character device named media[0-9]+ is created.
- * The device major and minor numbers are dynamic. The model name is exported as
- * a sysfs attribute.
+ *    #) Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute.
  *
- * Unregistering a media device that hasn't been registered is *NOT* safe.
+ *    #) Unregistering a media device that hasn't been registered is **NOT** safe.
  *
  * Return: returns zero on success or a negative error code.
  */
@@ -296,14 +294,16 @@ void media_device_unregister(struct media_device *mdev);
  *	This can be used to report the default audio and video devices or the
  *	default camera sensor.
  *
- * NOTE: Drivers should set the entity function before calling this function.
- * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
- * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
+ * .. note::
+ *
+ *    Drivers should set the entity function before calling this function.
+ *    Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
+ *    %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
  */
 int __must_check media_device_register_entity(struct media_device *mdev,
 					      struct media_entity *entity);
 
-/*
+/**
  * media_device_unregister_entity() - unregisters a media entity.
  *
  * @entity:	pointer to struct &media_entity to be unregistered
@@ -317,8 +317,10 @@ int __must_check media_device_register_entity(struct media_device *mdev,
  * When a media device is unregistered, all its entities are unregistered
  * automatically. No manual entities unregistration is then required.
  *
- * Note: the media_entity instance itself must be freed explicitly by
- * the driver if required.
+ * .. note::
+ *
+ *    The media_entity instance itself must be freed explicitly by
+ *    the driver if required.
  */
 void media_device_unregister_entity(struct media_entity *entity);
 
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index cbb266f7f2b5..83877719bef4 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -104,7 +104,7 @@ struct media_entity_graph {
 	int top;
 };
 
-/*
+/**
  * struct media_pipeline - Media pipeline related information
  *
  * @streaming_count:	Streaming start count - streaming stop count
@@ -180,7 +180,7 @@ struct media_pad {
  *			view. The media_entity_pipeline_start() function
  *			validates all links by calling this operation. Optional.
  *
- * Note: Those these callbacks are called with struct media_device.@graph_mutex
+ * .. note:: Those these callbacks are called with struct media_device.@graph_mutex
  * mutex held.
  */
 struct media_entity_operations {
@@ -602,19 +602,20 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
  * @flags:	Link flags, as defined in include/uapi/linux/media.h.
  *
  * Valid values for flags:
- * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
- *	used to transfer media data. When two or more links target a sink pad,
- *	only one of them can be enabled at a time.
  *
- * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
- *	be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
- *	%MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
- *	always enabled.
+ * - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can
+ *   be used to transfer media data. When two or more links target a sink pad,
+ *   only one of them can be enabled at a time.
  *
- * NOTE:
+ * - A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
+ *   be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
+ *   %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
+ *   always enabled.
  *
- * Before calling this function, media_entity_pads_init() and
- * media_device_register_entity() should be called previously for both ends.
+ * .. note::
+ *
+ *    Before calling this function, media_entity_pads_init() and
+ *    media_device_register_entity() should be called previously for both ends.
  */
 __must_check int media_create_pad_link(struct media_entity *source,
 			u16 source_pad, struct media_entity *sink,
@@ -641,6 +642,7 @@ __must_check int media_create_pad_link(struct media_entity *source,
  *	and @sink are NULL.
  *
  * Valid values for flags:
+ *
  * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
  *	used to transfer media data. If multiple links are created and this
  *	flag is passed as an argument, only the first created link will have
@@ -677,8 +679,10 @@ void __media_entity_remove_links(struct media_entity *entity);
  *
  * @entity:	pointer to &media_entity
  *
- * Note: this is called automatically when an entity is unregistered via
- * media_device_register_entity().
+ * .. note::
+ *
+ *    This is called automatically when an entity is unregistered via
+ *    media_device_register_entity().
  */
 void media_entity_remove_links(struct media_entity *entity);
 
@@ -728,9 +732,11 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
  * being enabled, the link_setup operation must return -EBUSY and can't
  * implicitly disable the first enabled link.
  *
- * NOTE: the valid values of the flags for the link is the same as described
- * on media_create_pad_link(), for pad to pad links or the same as described
- * on media_create_intf_link(), for interface to entity links.
+ * .. note::
+ *
+ *    The valid values of the flags for the link is the same as described
+ *    on media_create_pad_link(), for pad to pad links or the same as described
+ *    on media_create_intf_link(), for interface to entity links.
  */
 int media_entity_setup_link(struct media_link *link, u32 flags);
 
@@ -844,7 +850,7 @@ __must_check int media_entity_pipeline_start(struct media_entity *entity,
  * @entity: Starting entity
  * @pipe: Media pipeline to be assigned to all entities in the pipeline.
  *
- * Note: This is the non-locking version of media_entity_pipeline_start()
+ * ..note:: This is the non-locking version of media_entity_pipeline_start()
  */
 __must_check int __media_entity_pipeline_start(struct media_entity *entity,
 					       struct media_pipeline *pipe);
@@ -868,7 +874,7 @@ void media_entity_pipeline_stop(struct media_entity *entity);
  *
  * @entity: Starting entity
  *
- * Note: This is the non-locking version of media_entity_pipeline_stop()
+ * .. note:: This is the non-locking version of media_entity_pipeline_stop()
  */
 void __media_entity_pipeline_stop(struct media_entity *entity);
 
@@ -909,20 +915,21 @@ struct media_link *
  *
  *
  * Valid values for flags:
- * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
- *	the entity hardware. That's the default value for interfaces. An
- *	interface may be disabled if the hardware is busy due to the usage
- *	of some other interface that it is currently controlling the hardware.
- *	A typical example is an hybrid TV device that handle only one type of
- *	stream on a given time. So, when the digital TV is streaming,
- *	the V4L2 interfaces won't be enabled, as such device is not able to
- *	also stream analog TV or radio.
  *
- * Note:
+ * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
+ *   the entity hardware. That's the default value for interfaces. An
+ *   interface may be disabled if the hardware is busy due to the usage
+ *   of some other interface that it is currently controlling the hardware.
+ *   A typical example is an hybrid TV device that handle only one type of
+ *   stream on a given time. So, when the digital TV is streaming,
+ *   the V4L2 interfaces won't be enabled, as such device is not able to
+ *   also stream analog TV or radio.
  *
- * Before calling this function, media_devnode_create() should be called for
- * the interface and media_device_register_entity() should be called for the
- * interface that will be part of the link.
+ * .. note::
+ *
+ *    Before calling this function, media_devnode_create() should be called for
+ *    the interface and media_device_register_entity() should be called for the
+ *    interface that will be part of the link.
  */
 __must_check media_create_intf_link(struct media_entity *entity,
 				    struct media_interface *intf,
@@ -932,7 +939,7 @@ __must_check media_create_intf_link(struct media_entity *entity,
  *
  * @link:	pointer to &media_link.
  *
- * Note: this is an unlocked version of media_remove_intf_link()
+ * .. note:: This is an unlocked version of media_remove_intf_link()
  */
 void __media_remove_intf_link(struct media_link *link);
 
@@ -941,7 +948,7 @@ void __media_remove_intf_link(struct media_link *link);
  *
  * @link:	pointer to &media_link.
  *
- * Note: prefer to use this one, instead of __media_remove_intf_link()
+ * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
  */
 void media_remove_intf_link(struct media_link *link);
 
@@ -950,7 +957,7 @@ void media_remove_intf_link(struct media_link *link);
  *
  * @intf:	pointer to &media_interface
  *
- * Note: this is an unlocked version of media_remove_intf_links().
+ * .. note:: This is an unlocked version of media_remove_intf_links().
  */
 void __media_remove_intf_links(struct media_interface *intf);
 
@@ -959,12 +966,12 @@ void __media_remove_intf_links(struct media_interface *intf);
  *
  * @intf:	pointer to &media_interface
  *
- * Notes:
+ * ..note::
  *
- * this is called automatically when an entity is unregistered via
- * media_device_register_entity() and by media_devnode_remove().
+ *   - This is called automatically when an entity is unregistered via
+ *     media_device_register_entity() and by media_devnode_remove().
  *
- * Prefer to use this one, instead of __media_remove_intf_links().
+ *   - Prefer to use this one, instead of __media_remove_intf_links().
  */
 void media_remove_intf_links(struct media_interface *intf);
 
-- 
2.7.4

[PATCH 7/7] [media] doc-rst: Fix conversion for dvb-core.rst

[Mauro Carvalho Chehab]

The conversion from DocBook required some fixes:

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- Fix the cross-references at the media controller description.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/dtv-core.rst | 40 +++++++++++-----
 drivers/media/dvb-core/demux.h        | 90 +++++++++++++++++------------------
 2 files changed, 72 insertions(+), 58 deletions(-)

diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst
index fa462d5d0247..3291190c1865 100644
--- a/Documentation/media/kapi/dtv-core.rst
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -11,6 +11,15 @@ Digital TV Common functions
 .. kernel-doc:: drivers/media/dvb-core/dvbdev.h
 
 
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
+   :export: drivers/media/dvb-core/dvb_math.c
+
+.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
+   :export: drivers/media/dvb-core/dvbdev.c
+
+
+
 Digital TV Frontend kABI
 ------------------------
 
@@ -24,17 +33,20 @@ The header file for this API is named dvb_frontend.h and located in
 drivers/media/dvb-core.
 
 Before using the Digital TV frontend core, the bridge driver should attach
-the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
+the frontend demod, tuner and SEC devices and call
+:cpp:func:`dvb_register_frontend()`,
 in order to register the new frontend at the subsystem. At device
-detach/removal, the bridge driver should call dvb_unregister_frontend() to
-remove the frontend from the core and then dvb_frontend_detach() to free the
-memory allocated by the frontend drivers.
+detach/removal, the bridge driver should call
+:cpp:func:`dvb_unregister_frontend()` to
+remove the frontend from the core and then :cpp:func:`dvb_frontend_detach()`
+to free the memory allocated by the frontend drivers.
 
-The drivers should also call dvb_frontend_suspend() as part of their
-handler for the &device_driver.suspend(), and dvb_frontend_resume() as
-part of their handler for &device_driver.resume().
+The drivers should also call :cpp:func:`dvb_frontend_suspend()` as part of
+their handler for the :c:type:`device_driver`.\ ``suspend()``, and
+:cpp:func:`dvb_frontend_resume()` as
+part of their handler for :c:type:`device_driver`.\ ``resume()``.
 
-few other optional functions are provided to handle some special cases.
+A few other optional functions are provided to handle some special cases.
 
 .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
 
@@ -70,7 +82,7 @@ static or module private and registered to the Demux core for external
 access. It is not necessary to implement every function in the struct
 &dmx_demux. For example, a demux interface might support Section filtering,
 but not PES filtering. The kABI client is expected to check the value of any
-function pointer before calling the function: the value of NULL means
+function pointer before calling the function: the value of ``NULL`` means
 that the function is not available.
 
 Whenever the functions of the demux API modify shared data, the
@@ -78,7 +90,7 @@ possibilities of lost update and race condition problems should be
 addressed, e.g. by protecting parts of code with mutexes.
 
 Note that functions called from a bottom half context must not sleep.
-Even a simple memory allocation without using %GFP_ATOMIC can result in a
+Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
 kernel thread being put to sleep if swapping is needed. For example, the
 Linux Kernel calls the functions of a network device interface from a
 bottom half context. Thus, if a demux kABI function is called from network
@@ -109,14 +121,16 @@ triggered by a hardware interrupt, it is recommended to use the Linux
 bottom half mechanism or start a tasklet instead of making the callback
 function call directly from a hardware interrupt.
 
-This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
+This mechanism is implemented by :cpp:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()`
 callbacks.
 
-
 .. kernel-doc:: drivers/media/dvb-core/demux.h
 
-
 Digital TV Conditional Access kABI
 ----------------------------------
 
 .. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
+
+
+.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
+   :export: drivers/media/dvb-core/dvb_ca_en50221.c
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index e8f04f8872f8..ad42252b1c66 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -379,10 +379,10 @@ enum dmx_demux_caps {
  *	@open is called and decrement it when @close is called.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EUSERS, if maximum usage count was reached;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EUSERS, if maximum usage count was reached;
+ *	-EINVAL, on bad parameter.
  *
  * @close: This function reserves the demux for use by the caller and, if
  *	necessary, initializes the demux. When the demux is no longer needed,
@@ -392,10 +392,10 @@ enum dmx_demux_caps {
  *	@open is called and decrement it when @close is called.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
- *	It returns
- *		0 on success;
- *		-ENODEV, if demux was not in use (e. g. no users);
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-ENODEV, if demux was not in use (e. g. no users);
+ *	-EINVAL, on bad parameter.
  *
  * @write: This function provides the demux driver with a memory buffer
  *	containing TS packets. Instead of receiving TS packets from the DVB
@@ -410,12 +410,12 @@ enum dmx_demux_caps {
  *	The @buf function parameter contains a pointer to the TS data in
  *	kernel-space memory.
  *	The @count function parameter contains the length of the TS data.
- *	It returns
- *		0 on success;
- *		-ERESTARTSYS, if mutex lock was interrupted;
- *		-EINTR, if a signal handling is pending;
- *		-ENODEV, if demux was removed;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-ERESTARTSYS, if mutex lock was interrupted;
+ *	-EINTR, if a signal handling is pending;
+ *	-ENODEV, if demux was removed;
+ *	-EINVAL, on bad parameter.
  *
  * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS
  *	packets carrying a certain PID. The TS feed normally corresponds to a
@@ -426,11 +426,11 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @callback function parameter contains a pointer to the callback
  *	function for passing received TS packet.
- *	It returns
- *		0 on success;
- *		-ERESTARTSYS, if mutex lock was interrupted;
- *		-EBUSY, if no more TS feeds is available;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-ERESTARTSYS, if mutex lock was interrupted;
+ *	-EBUSY, if no more TS feeds is available;
+ *	-EINVAL, on bad parameter.
  *
  * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed.
  *	Any filtering in progress on the TS feed should be stopped before
@@ -439,9 +439,9 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @feed function parameter contains a pointer to the TS feed API and
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EINVAL on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL on bad parameter.
  *
  * @allocate_section_feed: Allocates a new section feed, i.e. a demux resource
  *	for filtering and receiving sections. On platforms with hardware
@@ -457,10 +457,10 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @callback function parameter contains a pointer to the callback
  *	function for passing received TS packet.
- *	It returns
- *		0 on success;
- *		-EBUSY, if no more TS feeds is available;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EBUSY, if no more TS feeds is available;
+ *	-EINVAL, on bad parameter.
  *
  * @release_section_feed: Releases the resources allocated with
  *	@allocate_section_feed, including allocated filters. Any filtering in
@@ -470,9 +470,9 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @feed function parameter contains a pointer to the TS feed API and
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL, on bad parameter.
  *
  * @add_frontend: Registers a connectivity between a demux and a front-end,
  *	i.e., indicates that the demux can be connected via a call to
@@ -486,9 +486,9 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @frontend function parameter contains a pointer to the front-end
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL, on bad parameter.
  *
  * @remove_frontend: Indicates that the given front-end, registered by a call
  *	to @add_frontend, can no longer be connected as a TS source by this
@@ -502,10 +502,10 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @frontend function parameter contains a pointer to the front-end
  *	instance data.
- *	It returns
- *		0 on success;
- *		-ENODEV, if the front-end was not found,
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-ENODEV, if the front-end was not found,
+ *	-EINVAL, on bad parameter.
  *
  * @get_frontends: Provides the APIs of the front-ends that have been
  *	registered for this demux. Any of the front-ends obtained with this
@@ -529,17 +529,17 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @frontend function parameter contains a pointer to the front-end
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EINVAL, on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL, on bad parameter.
  *
  * @disconnect_frontend: Disconnects the demux and a front-end previously
  *	connected by a @connect_frontend call.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
- *	It returns
- *		0 on success;
- *		-EINVAL on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL on bad parameter.
  *
  * @get_pes_pids: Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0,
  *	DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0.
@@ -547,9 +547,9 @@ enum dmx_demux_caps {
  *	instance data.
  *	The @pids function parameter contains an array with five u16 elements
  *	where the PIDs will be stored.
- *	It returns
- *		0 on success;
- *		-EINVAL on bad parameter.
+ *	It returns:
+ *	0 on success;
+ *	-EINVAL on bad parameter.
  */
 
 struct dmx_demux {
-- 
2.7.4