[PATCH 01/12] [media] v4l2-device.h: document functions

[PATCH 01/12] [media] v4l2-device.h: document functions

[Mauro Carvalho Chehab]

The functions at v4l2-device.h are not using the proper
markups. Add it, and include at the v4l2-core.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-core.rst |   2 +
 include/media/v4l2-device.h            | 194 ++++++++++++++++++++++++---------
 2 files changed, 143 insertions(+), 53 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index a1b73e8d6795..db571a4f498a 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -11,6 +11,8 @@ Video2Linux devices
 
 .. kernel-doc:: include/media/v4l2-ctrls.h
 
+.. kernel-doc:: include/media/v4l2-device.h
+
 .. kernel-doc:: include/media/v4l2-dv-timings.h
 
 .. kernel-doc:: include/media/v4l2-event.h
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index d5d45a8d3998..a9d6aa41790e 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -25,100 +25,188 @@
 #include <media/v4l2-subdev.h>
 #include <media/v4l2-dev.h>
 
-/* Each instance of a V4L2 device should create the v4l2_device struct,
-   either stand-alone or embedded in a larger struct.
-
-   It allows easy access to sub-devices (see v4l2-subdev.h) and provides
-   basic V4L2 device-level support.
- */
-
 #define V4L2_DEVICE_NAME_SIZE (20 + 16)
 
 struct v4l2_ctrl_handler;
 
+/**
+ * struct v4l2_device - main struct to for V4L2 device drivers
+ *
+ * @dev: pointer to struct device.
+ * @mdev: pointer to struct media_device
+ * @subdevs: used to keep track of the registered subdevs
+ * @lock: lock this struct; can be used by the driver as well
+ *	if this struct is embedded into a larger struct.
+ * @name: unique device name, by default the driver name + bus ID
+ * @notify: notify callback called by some sub-devices.
+ * @ctrl_handler: The control handler. May be NULL.
+ * @prio: Device's priority state
+ * @ref: Keep track of the references to this struct.
+ * @release: Release function that is called when the ref count
+ *	goes to 0.
+ *
+ * Each instance of a V4L2 device should create the v4l2_device struct,
+ * either stand-alone or embedded in a larger struct.
+ *
+ * It allows easy access to sub-devices (see v4l2-subdev.h) and provides
+ * basic V4L2 device-level support.
+ *
+ * .. note::
+ *
+ *    #) dev->driver_data points to this struct.
+ *    #) dev might be NULL if there is no parent device
+ */
+
 struct v4l2_device {
-	/* dev->driver_data points to this struct.
-	   Note: dev might be NULL if there is no parent device
-	   as is the case with e.g. ISA devices. */
 	struct device *dev;
 #if defined(CONFIG_MEDIA_CONTROLLER)
 	struct media_device *mdev;
 #endif
-	/* used to keep track of the registered subdevs */
 	struct list_head subdevs;
-	/* lock this struct; can be used by the driver as well if this
-	   struct is embedded into a larger struct. */
 	spinlock_t lock;
-	/* unique device name, by default the driver name + bus ID */
 	char name[V4L2_DEVICE_NAME_SIZE];
-	/* notify callback called by some sub-devices. */
 	void (*notify)(struct v4l2_subdev *sd,
 			unsigned int notification, void *arg);
-	/* The control handler. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
-	/* Device's priority state */
 	struct v4l2_prio_state prio;
-	/* Keep track of the references to this struct. */
 	struct kref ref;
-	/* Release function that is called when the ref count goes to 0. */
 	void (*release)(struct v4l2_device *v4l2_dev);
 };
 
+/**
+ * v4l2_device_get - gets a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to increment the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
 static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
 {
 	kref_get(&v4l2_dev->ref);
 }
 
+/**
+ * v4l2_device_put - putss a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to decrement the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
 int v4l2_device_put(struct v4l2_device *v4l2_dev);
 
-/* Initialize v4l2_dev and make dev->driver_data point to v4l2_dev.
-   dev may be NULL in rare cases (ISA devices). In that case you
-   must fill in the v4l2_dev->name field before calling this function. */
-int __must_check v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
+/**
+ * v4l2_device_register -Initialize v4l2_dev and make dev->driver_data
+ * 	point to v4l2_dev.
+ *
+ * @dev: pointer to struct device
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * .. note::
+ *	dev may be NULL in rare cases (ISA devices).
+ *	In such case the caller must fill in the v4l2_dev->name field
+ *	before calling this function.
+ */
+int __must_check v4l2_device_register(struct device *dev,
+				      struct v4l2_device *v4l2_dev);
 
-/* Optional function to initialize the name field of struct v4l2_device using
-   the driver name and a driver-global atomic_t instance.
-   This function will increment the instance counter and returns the instance
-   value used in the name.
-
-   Example:
-
-   static atomic_t drv_instance = ATOMIC_INIT(0);
-
-   ...
-
-   instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
-
-   The first time this is called the name field will be set to foo0 and
-   this function returns 0. If the name ends with a digit (e.g. cx18),
-   then the name will be set to cx18-0 since cx180 looks really odd. */
+/**
+ * v4l2_device_set_name - Optional function to initialize the
+ * 	name field of struct v4l2_device
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @basename: base name for the device name
+ * @instance: pointer to a static atomic_t var with the instance usage for
+ * 	the device driver.
+ *
+ * v4l2_device_set_name() initializes the name field of struct v4l2_device
+ * using the driver name and a driver-global atomic_t instance.
+ *
+ * This function will increment the instance counter and returns the
+ * instance value used in the name.
+ *
+ * Example:
+ *
+ *   static atomic_t drv_instance = ATOMIC_INIT(0);
+ *
+ *   ...
+ *
+ *   instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
+ *
+ * The first time this is called the name field will be set to foo0 and
+ * this function returns 0. If the name ends with a digit (e.g. cx18),
+ * then the name will be set to cx18-0 since cx180 would look really odd.
+ */
 int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
-						atomic_t *instance);
+			 atomic_t *instance);
 
-/* Set v4l2_dev->dev to NULL. Call when the USB parent disconnects.
-   Since the parent disappears this ensures that v4l2_dev doesn't have an
-   invalid parent pointer. */
+/**
+ * v4l2_device_disconnect - Change V4L2 device state to disconnected.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * Should be called when the USB parent disconnects.
+ * Since the parent disappears, this ensures that v4l2_dev doesn't have
+ * an invalid parent pointer.
+ *
+ * .. note:: This function sets v4l2_dev->dev to NULL.
+ */
 void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
 
-/* Unregister all sub-devices and any other resources related to v4l2_dev. */
+/**
+ *  v4l2_device_unregister - Unregister all sub-devices and any other
+ *	 resources related to v4l2_dev.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ */
 void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
 
-/* Register a subdev with a v4l2 device. While registered the subdev module
-   is marked as in-use. An error is returned if the module is no longer
-   loaded when you attempt to register it. */
+/**
+ * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * While registered, the subdev module is marked as in-use.
+ *
+ * An error is returned if the module is no longer loaded on any attempts
+ * to register it.
+ */
 int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
-						struct v4l2_subdev *sd);
-/* Unregister a subdev with a v4l2 device. Can also be called if the subdev
-   wasn't registered. In that case it will do nothing. */
+					     struct v4l2_subdev *sd);
+
+/**
+ * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * .. note ::
+ *
+ *	Can also be called if the subdev wasn't registered. In such
+ *	case, it will do nothing.
+ */
 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
 
-/* Register device nodes for all subdev of the v4l2 device that are marked with
- * the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+/**
+ * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
+ *	of the v4l2 device that are marked with
+ * 	the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
  */
 int __must_check
 v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
 
-/* Send a notification to v4l2_device. */
+/**
+ * v4l2_subdev_notify - Sends a notification to v4l2_device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ * @notification: type of notification. Please notice that the notification
+ * 	type is driver-specific.
+ * @arg: arguments for the notification. Those are specific to each
+ *	notification type.
+ */
 static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
 				      unsigned int notification, void *arg)
 {
-- 
2.7.4

[PATCH 02/12] [media] doc-rst: Split v4l-core into one file per kAPI

[Mauro Carvalho Chehab]

Sphinx produce a 1:1 mapping between a rst file and an html file.

So, we need to split the kernel-doc tags on multiple documents.

A side effect is that we're now having a better name for each
section of the kAPI documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-async.rst            |  4 ++
 Documentation/media/kapi/v4l2-controls.rst         |  5 ++
 Documentation/media/kapi/v4l2-core.rst             | 55 ++++++++--------------
 Documentation/media/kapi/v4l2-device.rst           |  4 ++
 Documentation/media/kapi/v4l2-dv-timings.rst       |  4 ++
 Documentation/media/kapi/v4l2-event.rst            |  5 ++
 Documentation/media/kapi/v4l2-flash-led-class.rst  |  4 ++
 Documentation/media/kapi/v4l2-mc.rst               |  4 ++
 Documentation/media/kapi/v4l2-mediabus.rst         |  4 ++
 Documentation/media/kapi/v4l2-mem2mem.rst          |  3 ++
 Documentation/media/kapi/v4l2-of.rst               |  3 ++
 Documentation/media/kapi/v4l2-rect.rst             |  4 ++
 Documentation/media/kapi/v4l2-subdev.rst           |  4 ++
 Documentation/media/kapi/v4l2-tuner.rst            |  6 +++
 Documentation/media/kapi/v4l2-tveeprom.rst         |  4 ++
 .../media/kapi/{videobuf.rst => v4l2-videobuf.rst} |  0
 Documentation/media/kapi/v4l2-videobuf2.rst        |  8 ++++
 Documentation/media/media_kapi.rst                 |  3 --
 18 files changed, 86 insertions(+), 38 deletions(-)
 create mode 100644 Documentation/media/kapi/v4l2-async.rst
 create mode 100644 Documentation/media/kapi/v4l2-device.rst
 create mode 100644 Documentation/media/kapi/v4l2-dv-timings.rst
 create mode 100644 Documentation/media/kapi/v4l2-event.rst
 create mode 100644 Documentation/media/kapi/v4l2-flash-led-class.rst
 create mode 100644 Documentation/media/kapi/v4l2-mc.rst
 create mode 100644 Documentation/media/kapi/v4l2-mediabus.rst
 create mode 100644 Documentation/media/kapi/v4l2-mem2mem.rst
 create mode 100644 Documentation/media/kapi/v4l2-of.rst
 create mode 100644 Documentation/media/kapi/v4l2-rect.rst
 create mode 100644 Documentation/media/kapi/v4l2-subdev.rst
 create mode 100644 Documentation/media/kapi/v4l2-tuner.rst
 create mode 100644 Documentation/media/kapi/v4l2-tveeprom.rst
 rename Documentation/media/kapi/{videobuf.rst => v4l2-videobuf.rst} (100%)
 create mode 100644 Documentation/media/kapi/v4l2-videobuf2.rst

diff --git a/Documentation/media/kapi/v4l2-async.rst b/Documentation/media/kapi/v4l2-async.rst
new file mode 100644
index 000000000000..372aa29fbf29
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-async.rst
@@ -0,0 +1,4 @@
+V4L2 Async kAPI
+^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-async.h
diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst
index 8ff9ee806042..58b6b3d74ca7 100644
--- a/Documentation/media/kapi/v4l2-controls.rst
+++ b/Documentation/media/kapi/v4l2-controls.rst
@@ -824,3 +824,8 @@ notify function is called.
 
 There can be only one notify function per control handler. Any attempt
 to set another notify function will cause a WARN_ON.
+
+V4L2 control kAPI
+-----------------
+
+.. kernel-doc:: include/media/v4l2-ctrls.h
diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index db571a4f498a..8c127ccdb0ae 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -1,38 +1,23 @@
 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-device.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
+.. toctree::
+    :maxdepth: 1
+
+    v4l2-framework
+    v4l2-async
+    v4l2-controls
+    v4l2-device
+    v4l2-dv-timings
+    v4l2-event
+    v4l2-flash-led-class
+    v4l2-mc
+    v4l2-mediabus
+    v4l2-mem2mem
+    v4l2-of
+    v4l2-rect
+    v4l2-subdev
+    v4l2-tuner
+    v4l2-tveeprom
+    v4l2-videobuf2
+    v4l2-videobuf
diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst
new file mode 100644
index 000000000000..e324fbcb0353
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-device.rst
@@ -0,0 +1,4 @@
+V4L2 Device kAPI
+^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-device.h
diff --git a/Documentation/media/kapi/v4l2-dv-timings.rst b/Documentation/media/kapi/v4l2-dv-timings.rst
new file mode 100644
index 000000000000..4b08a49c54a4
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-dv-timings.rst
@@ -0,0 +1,4 @@
+V4L2 DV Timings kAPI
+^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-dv-timings.h
diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst
new file mode 100644
index 000000000000..6ac94efc07bf
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-event.rst
@@ -0,0 +1,5 @@
+V4L2 event kAPI
+^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-event.h
+
diff --git a/Documentation/media/kapi/v4l2-flash-led-class.rst b/Documentation/media/kapi/v4l2-flash-led-class.rst
new file mode 100644
index 000000000000..251ed6b3aab3
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-flash-led-class.rst
@@ -0,0 +1,4 @@
+V4L2 Flash and LED class kAPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-flash-led-class.h
diff --git a/Documentation/media/kapi/v4l2-mc.rst b/Documentation/media/kapi/v4l2-mc.rst
new file mode 100644
index 000000000000..c94ce0fa3839
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-mc.rst
@@ -0,0 +1,4 @@
+V4L2 Media Controller kAPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-mc.h
diff --git a/Documentation/media/kapi/v4l2-mediabus.rst b/Documentation/media/kapi/v4l2-mediabus.rst
new file mode 100644
index 000000000000..b3c246b51c2c
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-mediabus.rst
@@ -0,0 +1,4 @@
+V4L2 Media Bus kAPI
+^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-mediabus.h
diff --git a/Documentation/media/kapi/v4l2-mem2mem.rst b/Documentation/media/kapi/v4l2-mem2mem.rst
new file mode 100644
index 000000000000..61f9923286c7
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-mem2mem.rst
@@ -0,0 +1,3 @@
+V4L2 Memory to Memory kAPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. kernel-doc:: include/media/v4l2-mem2mem.h
diff --git a/Documentation/media/kapi/v4l2-of.rst b/Documentation/media/kapi/v4l2-of.rst
new file mode 100644
index 000000000000..1ddf76b00944
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-of.rst
@@ -0,0 +1,3 @@
+V4L2 Open Firmware kAPI
+^^^^^^^^^^^^^^^^^^^^^^^
+.. kernel-doc:: include/media/v4l2-of.h
diff --git a/Documentation/media/kapi/v4l2-rect.rst b/Documentation/media/kapi/v4l2-rect.rst
new file mode 100644
index 000000000000..bb86dcbc5a3c
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-rect.rst
@@ -0,0 +1,4 @@
+V4L2 rect kAPI
+^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-rect.h
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
new file mode 100644
index 000000000000..1b262aa7e250
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -0,0 +1,4 @@
+V4L2 subdev kAPI
+^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-subdev.h
diff --git a/Documentation/media/kapi/v4l2-tuner.rst b/Documentation/media/kapi/v4l2-tuner.rst
new file mode 100644
index 000000000000..37b0ef310a62
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-tuner.rst
@@ -0,0 +1,6 @@
+Tuner kAPI
+^^^^^^^^^^
+
+.. kernel-doc:: include/media/tuner.h
+
+.. kernel-doc:: include/media/tuner-types.h
diff --git a/Documentation/media/kapi/v4l2-tveeprom.rst b/Documentation/media/kapi/v4l2-tveeprom.rst
new file mode 100644
index 000000000000..f7ef71742e93
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-tveeprom.rst
@@ -0,0 +1,4 @@
+Hauppauge TV EEPROM kAPI
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/tveeprom.h
diff --git a/Documentation/media/kapi/videobuf.rst b/Documentation/media/kapi/v4l2-videobuf.rst
similarity index 100%
rename from Documentation/media/kapi/videobuf.rst
rename to Documentation/media/kapi/v4l2-videobuf.rst
diff --git a/Documentation/media/kapi/v4l2-videobuf2.rst b/Documentation/media/kapi/v4l2-videobuf2.rst
new file mode 100644
index 000000000000..b4f2d6983ef3
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-videobuf2.rst
@@ -0,0 +1,8 @@
+V4L2 videobuf2 kAPI
+^^^^^^^^^^^^^^^^^^^
+
+.. 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_kapi.rst b/Documentation/media/media_kapi.rst
index 431fc3e43d6a..b71e8e8048ca 100644
--- a/Documentation/media/media_kapi.rst
+++ b/Documentation/media/media_kapi.rst
@@ -28,9 +28,6 @@ For more details see the file COPYING in the source distribution of Linux.
     :maxdepth: 5
     :numbered:
 
-    kapi/v4l2-framework
-    kapi/v4l2-controls
-    kapi/videobuf
     kapi/v4l2-core
     kapi/dtv-core
     kapi/rc-core
-- 
2.7.4

[PATCH 03/12] [media] v4l2-device.rst: add contents from v4l2-framework

[Mauro Carvalho Chehab]

Part of the contents of v4l2-framework is related to the
kAPI defined by v4l2-device. Move such contents to the
v4l2-device.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-device.rst    | 140 +++++++++++++++++++++++++++-
 Documentation/media/kapi/v4l2-framework.rst | 139 ---------------------------
 2 files changed, 139 insertions(+), 140 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst
index e324fbcb0353..6d521b313beb 100644
--- a/Documentation/media/kapi/v4l2-device.rst
+++ b/Documentation/media/kapi/v4l2-device.rst
@@ -1,4 +1,142 @@
-V4L2 Device kAPI
+V4L2 Device register logic
+--------------------------
+
+Each device instance is represented by a struct v4l2_device (v4l2-device.h).
+Very simple devices can just allocate this struct, but most of the time you
+would embed this struct inside a larger struct.
+
+You must register the device instance:
+
+.. code-block:: none
+
+	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
+
+Registration will initialize the v4l2_device struct. If the dev->driver_data
+field is NULL, it will be linked to v4l2_dev.
+
+Drivers that want integration with the media device framework need to set
+dev->driver_data manually to point to the driver-specific device structure
+that embed the struct v4l2_device instance. This is achieved by a
+dev_set_drvdata() call before registering the V4L2 device instance. They must
+also set the struct v4l2_device mdev field to point to a properly initialized
+and registered media_device instance.
+
+If v4l2_dev->name is empty then it will be set to a value derived from dev
+(driver name followed by the bus_id, to be precise). If you set it up before
+calling v4l2_device_register then it will be untouched. If dev is NULL, then
+you **must** setup v4l2_dev->name before calling v4l2_device_register.
+
+You can use v4l2_device_set_name() to set the name based on a driver name and
+a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
+etc. If the name ends with a digit, then it will insert a dash: cx18-0,
+cx18-1, etc. This function returns the instance number.
+
+The first 'dev' argument is normally the struct device pointer of a pci_dev,
+usb_interface or platform_device. It is rare for dev to be NULL, but it happens
+with ISA devices or when one device creates multiple PCI devices, thus making
+it impossible to associate v4l2_dev with a particular parent.
+
+You can also supply a notify() callback that can be called by sub-devices to
+notify you of events. Whether you need to set this depends on the sub-device.
+Any notifications a sub-device supports must be defined in a header in
+include/media/<subdevice>.h.
+
+You unregister with:
+
+.. code-block:: none
+
+	v4l2_device_unregister(struct v4l2_device *v4l2_dev);
+
+If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
+Unregistering will also automatically unregister all subdevs from the device.
+
+If you have a hotpluggable device (e.g. a USB device), then when a disconnect
+happens the parent device becomes invalid. Since v4l2_device has a pointer to
+that parent device it has to be cleared as well to mark that the parent is
+gone. To do this call:
+
+.. code-block:: none
+
+	v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
+
+This does *not* unregister the subdevs, so you still need to call the
+v4l2_device_unregister() function for that. If your driver is not hotpluggable,
+then there is no need to call v4l2_device_disconnect().
+
+Sometimes you need to iterate over all devices registered by a specific
+driver. This is usually the case if multiple device drivers use the same
+hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
+hardware. The same is true for alsa drivers for example.
+
+You can iterate over all registered devices as follows:
+
+.. code-block:: none
+
+	static int callback(struct device *dev, void *p)
+	{
+		struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
+
+		/* test if this device was inited */
+		if (v4l2_dev == NULL)
+			return 0;
+		...
+		return 0;
+	}
+
+	int iterate(void *p)
+	{
+		struct device_driver *drv;
+		int err;
+
+		/* Find driver 'ivtv' on the PCI bus.
+		pci_bus_type is a global. For USB busses use usb_bus_type. */
+		drv = driver_find("ivtv", &pci_bus_type);
+		/* iterate over all ivtv device instances */
+		err = driver_for_each_device(drv, NULL, p, callback);
+		put_driver(drv);
+		return err;
+	}
+
+Sometimes you need to keep a running counter of the device instance. This is
+commonly used to map a device instance to an index of a module option array.
+
+The recommended approach is as follows:
+
+.. code-block:: none
+
+	static atomic_t drv_instance = ATOMIC_INIT(0);
+
+	static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
+	{
+		...
+		state->instance = atomic_inc_return(&drv_instance) - 1;
+	}
+
+If you have multiple device nodes then it can be difficult to know when it is
+safe to unregister v4l2_device for hotpluggable devices. For this purpose
+v4l2_device has refcounting support. The refcount is increased whenever
+video_register_device is called and it is decreased whenever that device node
+is released. When the refcount reaches zero, then the v4l2_device release()
+callback is called. You can do your final cleanup there.
+
+If other device nodes (e.g. ALSA) are created, then you can increase and
+decrease the refcount manually as well by calling:
+
+.. code-block:: none
+
+	void v4l2_device_get(struct v4l2_device *v4l2_dev);
+
+or:
+
+.. code-block:: none
+
+	int v4l2_device_put(struct v4l2_device *v4l2_dev);
+
+Since the initial refcount is 1 you also need to call v4l2_device_put in the
+disconnect() callback (for USB devices) or in the remove() callback (for e.g.
+PCI devices), otherwise the refcount will never reach 0.
+
+V4L2 device kAPI
 ^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-device.h
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index 740875ddfcec..1fdc96bd7411 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,145 +80,6 @@ The V4L2 framework also optionally integrates with the media framework. If a
 driver sets the struct v4l2_device mdev field, sub-devices and video nodes
 will automatically appear in the media framework as entities.
 
-
-struct v4l2_device
-------------------
-
-Each device instance is represented by a struct v4l2_device (v4l2-device.h).
-Very simple devices can just allocate this struct, but most of the time you
-would embed this struct inside a larger struct.
-
-You must register the device instance:
-
-.. code-block:: none
-
-	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
-
-Registration will initialize the v4l2_device struct. If the dev->driver_data
-field is NULL, it will be linked to v4l2_dev.
-
-Drivers that want integration with the media device framework need to set
-dev->driver_data manually to point to the driver-specific device structure
-that embed the struct v4l2_device instance. This is achieved by a
-dev_set_drvdata() call before registering the V4L2 device instance. They must
-also set the struct v4l2_device mdev field to point to a properly initialized
-and registered media_device instance.
-
-If v4l2_dev->name is empty then it will be set to a value derived from dev
-(driver name followed by the bus_id, to be precise). If you set it up before
-calling v4l2_device_register then it will be untouched. If dev is NULL, then
-you **must** setup v4l2_dev->name before calling v4l2_device_register.
-
-You can use v4l2_device_set_name() to set the name based on a driver name and
-a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
-etc. If the name ends with a digit, then it will insert a dash: cx18-0,
-cx18-1, etc. This function returns the instance number.
-
-The first 'dev' argument is normally the struct device pointer of a pci_dev,
-usb_interface or platform_device. It is rare for dev to be NULL, but it happens
-with ISA devices or when one device creates multiple PCI devices, thus making
-it impossible to associate v4l2_dev with a particular parent.
-
-You can also supply a notify() callback that can be called by sub-devices to
-notify you of events. Whether you need to set this depends on the sub-device.
-Any notifications a sub-device supports must be defined in a header in
-include/media/<subdevice>.h.
-
-You unregister with:
-
-.. code-block:: none
-
-	v4l2_device_unregister(struct v4l2_device *v4l2_dev);
-
-If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
-Unregistering will also automatically unregister all subdevs from the device.
-
-If you have a hotpluggable device (e.g. a USB device), then when a disconnect
-happens the parent device becomes invalid. Since v4l2_device has a pointer to
-that parent device it has to be cleared as well to mark that the parent is
-gone. To do this call:
-
-.. code-block:: none
-
-	v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
-
-This does *not* unregister the subdevs, so you still need to call the
-v4l2_device_unregister() function for that. If your driver is not hotpluggable,
-then there is no need to call v4l2_device_disconnect().
-
-Sometimes you need to iterate over all devices registered by a specific
-driver. This is usually the case if multiple device drivers use the same
-hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
-hardware. The same is true for alsa drivers for example.
-
-You can iterate over all registered devices as follows:
-
-.. code-block:: none
-
-	static int callback(struct device *dev, void *p)
-	{
-		struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
-
-		/* test if this device was inited */
-		if (v4l2_dev == NULL)
-			return 0;
-		...
-		return 0;
-	}
-
-	int iterate(void *p)
-	{
-		struct device_driver *drv;
-		int err;
-
-		/* Find driver 'ivtv' on the PCI bus.
-		pci_bus_type is a global. For USB busses use usb_bus_type. */
-		drv = driver_find("ivtv", &pci_bus_type);
-		/* iterate over all ivtv device instances */
-		err = driver_for_each_device(drv, NULL, p, callback);
-		put_driver(drv);
-		return err;
-	}
-
-Sometimes you need to keep a running counter of the device instance. This is
-commonly used to map a device instance to an index of a module option array.
-
-The recommended approach is as follows:
-
-.. code-block:: none
-
-	static atomic_t drv_instance = ATOMIC_INIT(0);
-
-	static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
-	{
-		...
-		state->instance = atomic_inc_return(&drv_instance) - 1;
-	}
-
-If you have multiple device nodes then it can be difficult to know when it is
-safe to unregister v4l2_device for hotpluggable devices. For this purpose
-v4l2_device has refcounting support. The refcount is increased whenever
-video_register_device is called and it is decreased whenever that device node
-is released. When the refcount reaches zero, then the v4l2_device release()
-callback is called. You can do your final cleanup there.
-
-If other device nodes (e.g. ALSA) are created, then you can increase and
-decrease the refcount manually as well by calling:
-
-.. code-block:: none
-
-	void v4l2_device_get(struct v4l2_device *v4l2_dev);
-
-or:
-
-.. code-block:: none
-
-	int v4l2_device_put(struct v4l2_device *v4l2_dev);
-
-Since the initial refcount is 1 you also need to call v4l2_device_put in the
-disconnect() callback (for USB devices) or in the remove() callback (for e.g.
-PCI devices), otherwise the refcount will never reach 0.
-
 struct v4l2_subdev
 ------------------
 
-- 
2.7.4

[PATCH 04/12] [media] v4l2-device.rst: do cross references with kernel-doc

[Mauro Carvalho Chehab]

This document describes the main kAPI interfaces for the
v4l2-device.h header. Add cross references to the documentation
produced via kernel-doc.

While here, also use monotonic font for constants.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-device.rst | 130 ++++++++++++++++---------------
 1 file changed, 66 insertions(+), 64 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst
index 6d521b313beb..8e275d0ff0f5 100644
--- a/Documentation/media/kapi/v4l2-device.rst
+++ b/Documentation/media/kapi/v4l2-device.rst
@@ -1,67 +1,69 @@
 V4L2 Device register logic
 --------------------------
 
-Each device instance is represented by a struct v4l2_device (v4l2-device.h).
+Each device instance is represented by a struct :c:type:`v4l2_device`.
 Very simple devices can just allocate this struct, but most of the time you
 would embed this struct inside a larger struct.
 
-You must register the device instance:
+You must register the device instance by calling:
 
-.. code-block:: none
+	:cpp:func:`v4l2_device_register <v4l2_device_register>`
+	(dev, :c:type:`v4l2_dev <v4l2_device>`).
 
-	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
-
-Registration will initialize the v4l2_device struct. If the dev->driver_data
-field is NULL, it will be linked to v4l2_dev.
+Registration will initialize the :c:type:`v4l2_device` struct. If the
+dev->driver_data field is ``NULL``, it will be linked to
+:c:type:`v4l2_dev <v4l2_device>` argument.
 
 Drivers that want integration with the media device framework need to set
 dev->driver_data manually to point to the driver-specific device structure
-that embed the struct v4l2_device instance. This is achieved by a
-dev_set_drvdata() call before registering the V4L2 device instance. They must
-also set the struct v4l2_device mdev field to point to a properly initialized
-and registered media_device instance.
-
-If v4l2_dev->name is empty then it will be set to a value derived from dev
-(driver name followed by the bus_id, to be precise). If you set it up before
-calling v4l2_device_register then it will be untouched. If dev is NULL, then
-you **must** setup v4l2_dev->name before calling v4l2_device_register.
-
-You can use v4l2_device_set_name() to set the name based on a driver name and
-a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
-etc. If the name ends with a digit, then it will insert a dash: cx18-0,
-cx18-1, etc. This function returns the instance number.
-
-The first 'dev' argument is normally the struct device pointer of a pci_dev,
-usb_interface or platform_device. It is rare for dev to be NULL, but it happens
-with ISA devices or when one device creates multiple PCI devices, thus making
-it impossible to associate v4l2_dev with a particular parent.
-
-You can also supply a notify() callback that can be called by sub-devices to
-notify you of events. Whether you need to set this depends on the sub-device.
-Any notifications a sub-device supports must be defined in a header in
-include/media/<subdevice>.h.
-
-You unregister with:
-
-.. code-block:: none
-
-	v4l2_device_unregister(struct v4l2_device *v4l2_dev);
-
-If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
-Unregistering will also automatically unregister all subdevs from the device.
+that embed the struct :c:type:`v4l2_device` instance. This is achieved by a
+``dev_set_drvdata()`` call before registering the V4L2 device instance.
+They must also set the struct :c:type:`v4l2_device` mdev field to point to a
+properly initialized and registered :c:type:`media_device` instance.
+
+If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
+value derived from dev (driver name followed by the bus_id, to be precise).
+If you set it up before  calling :cpp:func:`v4l2_device_register` then it will
+be untouched. If dev is ``NULL``, then you **must** setup
+:c:type:`v4l2_dev <v4l2_device>`\ ->name before calling
+:cpp:func:`v4l2_device_register`.
+
+You can use :cpp:func:`v4l2_device_set_name` to set the name based on a driver
+name and a driver-global atomic_t instance. This will generate names like
+``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert
+a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number.
+
+The first ``dev`` argument is normally the ``struct device`` pointer of a
+``pci_dev``, ``usb_interface`` or ``platform_device``. It is rare for dev to
+be ``NULL``, but it happens with ISA devices or when one device creates
+multiple PCI devices, thus making it impossible to associate
+:c:type:`v4l2_dev <v4l2_device>` with a particular parent.
+
+You can also supply a ``notify()`` callback that can be called by sub-devices
+to notify you of events. Whether you need to set this depends on the
+sub-device. Any notifications a sub-device supports must be defined in a header
+in ``include/media/subdevice.h``.
+
+V4L2 devices are unregistered by calling:
+
+	:cpp:func:`v4l2_device_unregister`
+	(:c:type:`v4l2_dev <v4l2_device>`).
+
+If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`,
+it will be reset to ``NULL``. Unregistering will also automatically unregister
+all subdevs from the device.
 
 If you have a hotpluggable device (e.g. a USB device), then when a disconnect
-happens the parent device becomes invalid. Since v4l2_device has a pointer to
-that parent device it has to be cleared as well to mark that the parent is
-gone. To do this call:
+happens the parent device becomes invalid. Since :c:type:`v4l2_device` has a
+pointer to that parent device it has to be cleared as well to mark that the
+parent is gone. To do this call:
 
-.. code-block:: none
-
-	v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
+	:cpp:func:`v4l2_device_disconnect`
+	(:c:type:`v4l2_dev <v4l2_device>`).
 
 This does *not* unregister the subdevs, so you still need to call the
-v4l2_device_unregister() function for that. If your driver is not hotpluggable,
-then there is no need to call v4l2_device_disconnect().
+:cpp:func:`v4l2_device_unregister` function for that. If your driver is not
+hotpluggable, then there is no need to call :cpp:func:`v4l2_device_disconnect`.
 
 Sometimes you need to iterate over all devices registered by a specific
 driver. This is usually the case if multiple device drivers use the same
@@ -70,7 +72,7 @@ hardware. The same is true for alsa drivers for example.
 
 You can iterate over all registered devices as follows:
 
-.. code-block:: none
+.. code-block:: c
 
 	static int callback(struct device *dev, void *p)
 	{
@@ -102,7 +104,7 @@ commonly used to map a device instance to an index of a module option array.
 
 The recommended approach is as follows:
 
-.. code-block:: none
+.. code-block:: c
 
 	static atomic_t drv_instance = ATOMIC_INIT(0);
 
@@ -113,28 +115,28 @@ The recommended approach is as follows:
 	}
 
 If you have multiple device nodes then it can be difficult to know when it is
-safe to unregister v4l2_device for hotpluggable devices. For this purpose
-v4l2_device has refcounting support. The refcount is increased whenever
-video_register_device is called and it is decreased whenever that device node
-is released. When the refcount reaches zero, then the v4l2_device release()
-callback is called. You can do your final cleanup there.
+safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
+purpose :c:type:`v4l2_device` has refcounting support. The refcount is
+increased whenever :cpp:func:`video_register_device` is called and it is
+decreased whenever that device node is released. When the refcount reaches
+zero, then the :c:type:`v4l2_device` release() callback is called. You can
+do your final cleanup there.
 
 If other device nodes (e.g. ALSA) are created, then you can increase and
 decrease the refcount manually as well by calling:
 
-.. code-block:: none
-
-	void v4l2_device_get(struct v4l2_device *v4l2_dev);
+	:cpp:func:`v4l2_device_get`
+	(:c:type:`v4l2_dev <v4l2_device>`).
 
 or:
 
-.. code-block:: none
+	:cpp:func:`v4l2_device_put`
+	(:c:type:`v4l2_dev <v4l2_device>`).
 
-	int v4l2_device_put(struct v4l2_device *v4l2_dev);
-
-Since the initial refcount is 1 you also need to call v4l2_device_put in the
-disconnect() callback (for USB devices) or in the remove() callback (for e.g.
-PCI devices), otherwise the refcount will never reach 0.
+Since the initial refcount is 1 you also need to call
+:cpp:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices)
+or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
+will never reach 0.
 
 V4L2 device kAPI
 ^^^^^^^^^^^^^^^^
-- 
2.7.4

[PATCH 05/12] [media] v4l2-subdev.rst: add documentation from v4l2-framework.rst

[Mauro Carvalho Chehab]

There are lots of documentation about V4L2 subdevices at
v4l2-framework.rst. Move them to its specific chapter at
v4l2-subdev.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-framework.rst | 257 ----------------------------
 Documentation/media/kapi/v4l2-subdev.rst    | 256 +++++++++++++++++++++++++++
 2 files changed, 256 insertions(+), 257 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index 1fdc96bd7411..a7f64b38af5c 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,263 +80,6 @@ The V4L2 framework also optionally integrates with the media framework. If a
 driver sets the struct v4l2_device mdev field, sub-devices and video nodes
 will automatically appear in the media framework as entities.
 
-struct v4l2_subdev
-------------------
-
-Many drivers need to communicate with sub-devices. These devices can do all
-sort of tasks, but most commonly they handle audio and/or video muxing,
-encoding or decoding. For webcams common sub-devices are sensors and camera
-controllers.
-
-Usually these are I2C devices, but not necessarily. In order to provide the
-driver with a consistent interface to these sub-devices the v4l2_subdev struct
-(v4l2-subdev.h) was created.
-
-Each sub-device driver must have a v4l2_subdev struct. This struct can be
-stand-alone for simple sub-devices or it might be embedded in a larger struct
-if more state information needs to be stored. Usually there is a low-level
-device struct (e.g. i2c_client) that contains the device data as setup
-by the kernel. It is recommended to store that pointer in the private
-data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
-from a v4l2_subdev to the actual low-level bus-specific device data.
-
-You also need a way to go from the low-level struct to v4l2_subdev. For the
-common i2c_client struct the i2c_set_clientdata() call is used to store a
-v4l2_subdev pointer, for other busses you may have to use other methods.
-
-Bridges might also need to store per-subdev private data, such as a pointer to
-bridge-specific per-subdev private data. The v4l2_subdev structure provides
-host private data for that purpose that can be accessed with
-v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata().
-
-From the bridge driver perspective you load the sub-device module and somehow
-obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
-i2c_get_clientdata(). For other busses something similar needs to be done.
-Helper functions exists for sub-devices on an I2C bus that do most of this
-tricky work for you.
-
-Each v4l2_subdev contains function pointers that sub-device drivers can
-implement (or leave NULL if it is not applicable). Since sub-devices can do
-so many different things and you do not want to end up with a huge ops struct
-of which only a handful of ops are commonly implemented, the function pointers
-are sorted according to category and each category has its own ops struct.
-
-The top-level ops struct contains pointers to the category ops structs, which
-may be NULL if the subdev driver does not support anything from that category.
-
-It looks like this:
-
-.. code-block:: none
-
-	struct v4l2_subdev_core_ops {
-		int (*log_status)(struct v4l2_subdev *sd);
-		int (*init)(struct v4l2_subdev *sd, u32 val);
-		...
-	};
-
-	struct v4l2_subdev_tuner_ops {
-		...
-	};
-
-	struct v4l2_subdev_audio_ops {
-		...
-	};
-
-	struct v4l2_subdev_video_ops {
-		...
-	};
-
-	struct v4l2_subdev_pad_ops {
-		...
-	};
-
-	struct v4l2_subdev_ops {
-		const struct v4l2_subdev_core_ops  *core;
-		const struct v4l2_subdev_tuner_ops *tuner;
-		const struct v4l2_subdev_audio_ops *audio;
-		const struct v4l2_subdev_video_ops *video;
-		const struct v4l2_subdev_pad_ops *video;
-	};
-
-The core ops are common to all subdevs, the other categories are implemented
-depending on the sub-device. E.g. a video device is unlikely to support the
-audio ops and vice versa.
-
-This setup limits the number of function pointers while still making it easy
-to add new ops and categories.
-
-A sub-device driver initializes the v4l2_subdev struct using:
-
-.. code-block:: none
-
-	v4l2_subdev_init(sd, &ops);
-
-Afterwards you need to initialize subdev->name with a unique name and set the
-module owner. This is done for you if you use the i2c helper functions.
-
-If integration with the media framework is needed, you must initialize the
-media_entity struct embedded in the v4l2_subdev struct (entity field) by
-calling media_entity_pads_init(), if the entity has pads:
-
-.. code-block:: none
-
-	struct media_pad *pads = &my_sd->pads;
-	int err;
-
-	err = media_entity_pads_init(&sd->entity, npads, pads);
-
-The pads array must have been previously initialized. There is no need to
-manually set the struct media_entity function and name fields, but the
-revision field must be initialized if needed.
-
-A reference to the entity will be automatically acquired/released when the
-subdev device node (if any) is opened/closed.
-
-Don't forget to cleanup the media entity before the sub-device is destroyed:
-
-.. code-block:: none
-
-	media_entity_cleanup(&sd->entity);
-
-If the subdev driver intends to process video and integrate with the media
-framework, it must implement format related functionality using
-v4l2_subdev_pad_ops instead of v4l2_subdev_video_ops.
-
-In that case, the subdev driver may set the link_validate field to provide
-its own link validation function. The link validation function is called for
-every link in the pipeline where both of the ends of the links are V4L2
-sub-devices. The driver is still responsible for validating the correctness
-of the format configuration between sub-devices and video nodes.
-
-If link_validate op is not set, the default function
-v4l2_subdev_link_validate_default() is used instead. This function ensures
-that width, height and the media bus pixel code are equal on both source and
-sink of the link. Subdev drivers are also free to use this function to
-perform the checks mentioned above in addition to their own checks.
-
-There are currently two ways to register subdevices with the V4L2 core. The
-first (traditional) possibility is to have subdevices registered by bridge
-drivers. This can be done when the bridge driver has the complete information
-about subdevices connected to it and knows exactly when to register them. This
-is typically the case for internal subdevices, like video data processing units
-within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
-to SoCs, which pass information about them to bridge drivers, usually in their
-platform data.
-
-There are however also situations where subdevices have to be registered
-asynchronously to bridge devices. An example of such a configuration is a Device
-Tree based system where information about subdevices is made available to the
-system independently from the bridge devices, e.g. when subdevices are defined
-in DT as I2C device nodes. The API used in this second case is described further
-below.
-
-Using one or the other registration method only affects the probing process, the
-run-time bridge-subdevice interaction is in both cases the same.
-
-In the synchronous case a device (bridge) driver needs to register the
-v4l2_subdev with the v4l2_device:
-
-.. code-block:: none
-
-	int err = v4l2_device_register_subdev(v4l2_dev, sd);
-
-This can fail if the subdev module disappeared before it could be registered.
-After this function was called successfully the subdev->dev field points to
-the v4l2_device.
-
-If the v4l2_device parent device has a non-NULL mdev field, the sub-device
-entity will be automatically registered with the media device.
-
-You can unregister a sub-device using:
-
-.. code-block:: none
-
-	v4l2_device_unregister_subdev(sd);
-
-Afterwards the subdev module can be unloaded and sd->dev == NULL.
-
-You can call an ops function either directly:
-
-.. code-block:: none
-
-	err = sd->ops->core->g_std(sd, &norm);
-
-but it is better and easier to use this macro:
-
-.. code-block:: none
-
-	err = v4l2_subdev_call(sd, core, g_std, &norm);
-
-The macro will to the right NULL pointer checks and returns -ENODEV if subdev
-is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_std is
-NULL, or the actual result of the subdev->ops->core->g_std ops.
-
-It is also possible to call all or a subset of the sub-devices:
-
-.. code-block:: none
-
-	v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
-
-Any subdev that does not support this ops is skipped and error results are
-ignored. If you want to check for errors use this:
-
-.. code-block:: none
-
-	err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
-
-Any error except -ENOIOCTLCMD will exit the loop with that error. If no
-errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
-
-The second argument to both calls is a group ID. If 0, then all subdevs are
-called. If non-zero, then only those whose group ID match that value will
-be called. Before a bridge driver registers a subdev it can set sd->grp_id
-to whatever value it wants (it's 0 by default). This value is owned by the
-bridge driver and the sub-device driver will never modify or use it.
-
-The group ID gives the bridge driver more control how callbacks are called.
-For example, there may be multiple audio chips on a board, each capable of
-changing the volume. But usually only one will actually be used when the
-user want to change the volume. You can set the group ID for that subdev to
-e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
-v4l2_device_call_all(). That ensures that it will only go to the subdev
-that needs it.
-
-If the sub-device needs to notify its v4l2_device parent of an event, then
-it can call v4l2_subdev_notify(sd, notification, arg). This macro checks
-whether there is a notify() callback defined and returns -ENODEV if not.
-Otherwise the result of the notify() call is returned.
-
-The advantage of using v4l2_subdev is that it is a generic struct and does
-not contain any knowledge about the underlying hardware. So a driver might
-contain several subdevs that use an I2C bus, but also a subdev that is
-controlled through GPIO pins. This distinction is only relevant when setting
-up the device, but once the subdev is registered it is completely transparent.
-
-
-In the asynchronous case subdevice probing can be invoked independently of the
-bridge driver availability. The subdevice driver then has to verify whether all
-the requirements for a successful probing are satisfied. This can include a
-check for a master clock availability. If any of the conditions aren't satisfied
-the driver might decide to return -EPROBE_DEFER to request further reprobing
-attempts. Once all conditions are met the subdevice shall be registered using
-the v4l2_async_register_subdev() function. Unregistration is performed using
-the v4l2_async_unregister_subdev() call. Subdevices registered this way are
-stored in a global list of subdevices, ready to be picked up by bridge drivers.
-
-Bridge drivers in turn have to register a notifier object with an array of
-subdevice descriptors that the bridge device needs for its operation. This is
-performed using the v4l2_async_notifier_register() call. To unregister the
-notifier the driver has to call v4l2_async_notifier_unregister(). The former of
-the two functions takes two arguments: a pointer to struct v4l2_device and a
-pointer to struct v4l2_async_notifier. The latter contains a pointer to an array
-of pointers to subdevice descriptors of type struct v4l2_async_subdev type. The
-V4L2 core will then use these descriptors to match asynchronously registered
-subdevices to them. If a match is detected the .bound() notifier callback is
-called. After all subdevices have been located the .complete() callback is
-called. When a subdevice is removed from the system the .unbind() method is
-called. All three callbacks are optional.
-
-
 V4L2 sub-device userspace API
 -----------------------------
 
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 1b262aa7e250..3e2b25b47ff4 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -1,3 +1,259 @@
+V4L2 sub-devices
+----------------
+
+Many drivers need to communicate with sub-devices. These devices can do all
+sort of tasks, but most commonly they handle audio and/or video muxing,
+encoding or decoding. For webcams common sub-devices are sensors and camera
+controllers.
+
+Usually these are I2C devices, but not necessarily. In order to provide the
+driver with a consistent interface to these sub-devices the v4l2_subdev struct
+(v4l2-subdev.h) was created.
+
+Each sub-device driver must have a v4l2_subdev struct. This struct can be
+stand-alone for simple sub-devices or it might be embedded in a larger struct
+if more state information needs to be stored. Usually there is a low-level
+device struct (e.g. i2c_client) that contains the device data as setup
+by the kernel. It is recommended to store that pointer in the private
+data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
+from a v4l2_subdev to the actual low-level bus-specific device data.
+
+You also need a way to go from the low-level struct to v4l2_subdev. For the
+common i2c_client struct the i2c_set_clientdata() call is used to store a
+v4l2_subdev pointer, for other busses you may have to use other methods.
+
+Bridges might also need to store per-subdev private data, such as a pointer to
+bridge-specific per-subdev private data. The v4l2_subdev structure provides
+host private data for that purpose that can be accessed with
+v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata().
+
+From the bridge driver perspective you load the sub-device module and somehow
+obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
+i2c_get_clientdata(). For other busses something similar needs to be done.
+Helper functions exists for sub-devices on an I2C bus that do most of this
+tricky work for you.
+
+Each v4l2_subdev contains function pointers that sub-device drivers can
+implement (or leave NULL if it is not applicable). Since sub-devices can do
+so many different things and you do not want to end up with a huge ops struct
+of which only a handful of ops are commonly implemented, the function pointers
+are sorted according to category and each category has its own ops struct.
+
+The top-level ops struct contains pointers to the category ops structs, which
+may be NULL if the subdev driver does not support anything from that category.
+
+It looks like this:
+
+.. code-block:: none
+
+	struct v4l2_subdev_core_ops {
+		int (*log_status)(struct v4l2_subdev *sd);
+		int (*init)(struct v4l2_subdev *sd, u32 val);
+		...
+	};
+
+	struct v4l2_subdev_tuner_ops {
+		...
+	};
+
+	struct v4l2_subdev_audio_ops {
+		...
+	};
+
+	struct v4l2_subdev_video_ops {
+		...
+	};
+
+	struct v4l2_subdev_pad_ops {
+		...
+	};
+
+	struct v4l2_subdev_ops {
+		const struct v4l2_subdev_core_ops  *core;
+		const struct v4l2_subdev_tuner_ops *tuner;
+		const struct v4l2_subdev_audio_ops *audio;
+		const struct v4l2_subdev_video_ops *video;
+		const struct v4l2_subdev_pad_ops *video;
+	};
+
+The core ops are common to all subdevs, the other categories are implemented
+depending on the sub-device. E.g. a video device is unlikely to support the
+audio ops and vice versa.
+
+This setup limits the number of function pointers while still making it easy
+to add new ops and categories.
+
+A sub-device driver initializes the v4l2_subdev struct using:
+
+.. code-block:: none
+
+	v4l2_subdev_init(sd, &ops);
+
+Afterwards you need to initialize subdev->name with a unique name and set the
+module owner. This is done for you if you use the i2c helper functions.
+
+If integration with the media framework is needed, you must initialize the
+media_entity struct embedded in the v4l2_subdev struct (entity field) by
+calling media_entity_pads_init(), if the entity has pads:
+
+.. code-block:: none
+
+	struct media_pad *pads = &my_sd->pads;
+	int err;
+
+	err = media_entity_pads_init(&sd->entity, npads, pads);
+
+The pads array must have been previously initialized. There is no need to
+manually set the struct media_entity function and name fields, but the
+revision field must be initialized if needed.
+
+A reference to the entity will be automatically acquired/released when the
+subdev device node (if any) is opened/closed.
+
+Don't forget to cleanup the media entity before the sub-device is destroyed:
+
+.. code-block:: none
+
+	media_entity_cleanup(&sd->entity);
+
+If the subdev driver intends to process video and integrate with the media
+framework, it must implement format related functionality using
+v4l2_subdev_pad_ops instead of v4l2_subdev_video_ops.
+
+In that case, the subdev driver may set the link_validate field to provide
+its own link validation function. The link validation function is called for
+every link in the pipeline where both of the ends of the links are V4L2
+sub-devices. The driver is still responsible for validating the correctness
+of the format configuration between sub-devices and video nodes.
+
+If link_validate op is not set, the default function
+v4l2_subdev_link_validate_default() is used instead. This function ensures
+that width, height and the media bus pixel code are equal on both source and
+sink of the link. Subdev drivers are also free to use this function to
+perform the checks mentioned above in addition to their own checks.
+
+There are currently two ways to register subdevices with the V4L2 core. The
+first (traditional) possibility is to have subdevices registered by bridge
+drivers. This can be done when the bridge driver has the complete information
+about subdevices connected to it and knows exactly when to register them. This
+is typically the case for internal subdevices, like video data processing units
+within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
+to SoCs, which pass information about them to bridge drivers, usually in their
+platform data.
+
+There are however also situations where subdevices have to be registered
+asynchronously to bridge devices. An example of such a configuration is a Device
+Tree based system where information about subdevices is made available to the
+system independently from the bridge devices, e.g. when subdevices are defined
+in DT as I2C device nodes. The API used in this second case is described further
+below.
+
+Using one or the other registration method only affects the probing process, the
+run-time bridge-subdevice interaction is in both cases the same.
+
+In the synchronous case a device (bridge) driver needs to register the
+v4l2_subdev with the v4l2_device:
+
+.. code-block:: none
+
+	int err = v4l2_device_register_subdev(v4l2_dev, sd);
+
+This can fail if the subdev module disappeared before it could be registered.
+After this function was called successfully the subdev->dev field points to
+the v4l2_device.
+
+If the v4l2_device parent device has a non-NULL mdev field, the sub-device
+entity will be automatically registered with the media device.
+
+You can unregister a sub-device using:
+
+.. code-block:: none
+
+	v4l2_device_unregister_subdev(sd);
+
+Afterwards the subdev module can be unloaded and sd->dev == NULL.
+
+You can call an ops function either directly:
+
+.. code-block:: none
+
+	err = sd->ops->core->g_std(sd, &norm);
+
+but it is better and easier to use this macro:
+
+.. code-block:: none
+
+	err = v4l2_subdev_call(sd, core, g_std, &norm);
+
+The macro will to the right NULL pointer checks and returns -ENODEV if subdev
+is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_std is
+NULL, or the actual result of the subdev->ops->core->g_std ops.
+
+It is also possible to call all or a subset of the sub-devices:
+
+.. code-block:: none
+
+	v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
+
+Any subdev that does not support this ops is skipped and error results are
+ignored. If you want to check for errors use this:
+
+.. code-block:: none
+
+	err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
+
+Any error except -ENOIOCTLCMD will exit the loop with that error. If no
+errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
+
+The second argument to both calls is a group ID. If 0, then all subdevs are
+called. If non-zero, then only those whose group ID match that value will
+be called. Before a bridge driver registers a subdev it can set sd->grp_id
+to whatever value it wants (it's 0 by default). This value is owned by the
+bridge driver and the sub-device driver will never modify or use it.
+
+The group ID gives the bridge driver more control how callbacks are called.
+For example, there may be multiple audio chips on a board, each capable of
+changing the volume. But usually only one will actually be used when the
+user want to change the volume. You can set the group ID for that subdev to
+e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
+v4l2_device_call_all(). That ensures that it will only go to the subdev
+that needs it.
+
+If the sub-device needs to notify its v4l2_device parent of an event, then
+it can call v4l2_subdev_notify(sd, notification, arg). This macro checks
+whether there is a notify() callback defined and returns -ENODEV if not.
+Otherwise the result of the notify() call is returned.
+
+The advantage of using v4l2_subdev is that it is a generic struct and does
+not contain any knowledge about the underlying hardware. So a driver might
+contain several subdevs that use an I2C bus, but also a subdev that is
+controlled through GPIO pins. This distinction is only relevant when setting
+up the device, but once the subdev is registered it is completely transparent.
+
+
+In the asynchronous case subdevice probing can be invoked independently of the
+bridge driver availability. The subdevice driver then has to verify whether all
+the requirements for a successful probing are satisfied. This can include a
+check for a master clock availability. If any of the conditions aren't satisfied
+the driver might decide to return -EPROBE_DEFER to request further reprobing
+attempts. Once all conditions are met the subdevice shall be registered using
+the v4l2_async_register_subdev() function. Unregistration is performed using
+the v4l2_async_unregister_subdev() call. Subdevices registered this way are
+stored in a global list of subdevices, ready to be picked up by bridge drivers.
+
+Bridge drivers in turn have to register a notifier object with an array of
+subdevice descriptors that the bridge device needs for its operation. This is
+performed using the v4l2_async_notifier_register() call. To unregister the
+notifier the driver has to call v4l2_async_notifier_unregister(). The former of
+the two functions takes two arguments: a pointer to struct v4l2_device and a
+pointer to struct v4l2_async_notifier. The latter contains a pointer to an array
+of pointers to subdevice descriptors of type struct v4l2_async_subdev type. The
+V4L2 core will then use these descriptors to match asynchronously registered
+subdevices to them. If a match is detected the .bound() notifier callback is
+called. After all subdevices have been located the .complete() callback is
+called. When a subdevice is removed from the system the .unbind() method is
+called. All three callbacks are optional.
+
 V4L2 subdev kAPI
 ^^^^^^^^^^^^^^^^
 
-- 
2.7.4

[PATCH 06/12] [media] v4l2-subdev.h: Improve documentation

[Mauro Carvalho Chehab]

This header were poorly documented, and weren't using the
kernel-doc format. Document everything but the macros using
the right format.

While here, also fix the other comments to match the
Linux CodingStyle.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/media/v4l2-core/v4l2-subdev.c |  10 -
 include/media/v4l2-subdev.h           | 586 ++++++++++++++++++++++------------
 2 files changed, 390 insertions(+), 206 deletions(-)

diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c
index 953eab08e420..34a1e7c8b306 100644
--- a/drivers/media/v4l2-core/v4l2-subdev.c
+++ b/drivers/media/v4l2-core/v4l2-subdev.c
@@ -621,16 +621,6 @@ void v4l2_subdev_init(struct v4l2_subdev *sd, const struct v4l2_subdev_ops *ops)
 }
 EXPORT_SYMBOL(v4l2_subdev_init);
 
-/**
- * v4l2_subdev_notify_event() - Delivers event notification for subdevice
- * @sd: The subdev for which to deliver the event
- * @ev: The event to deliver
- *
- * Will deliver the specified event to all userspace event listeners which are
- * subscribed to the v42l subdev event queue as well as to the bridge driver
- * using the notify callback. The notification type for the notify callback
- * will be V4L2_DEVICE_NOTIFY_EVENT.
- */
 void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
 			      const struct v4l2_event *ev)
 {
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 4c880e86a1aa..996e1590cf32 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -1,21 +1,17 @@
 /*
-    V4L2 sub-device support header.
-
-    Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *  V4L2 sub-device support header.
+ *
+ *  Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
  */
 
 #ifndef _V4L2_SUBDEV_H
@@ -52,55 +48,64 @@ struct v4l2_subdev_fh;
 struct tuner_setup;
 struct v4l2_mbus_frame_desc;
 
-/* decode_vbi_line */
+/**
+ * struct v4l2_decode_vbi_line - used to decode_vbi_line
+ *
+ * @is_second_field: Set to 0 for the first (odd) field;
+ *	set to 1 for the second (even) field.
+ * @p: Pointer to the sliced VBI data from the decoder. On exit, points to
+ *	the start of the payload.
+ * @line: Line number of the sliced VBI data (1-23)
+ * @type: VBI service type (V4L2_SLICED_*). 0 if no service found
+ */
 struct v4l2_decode_vbi_line {
-	u32 is_second_field;	/* Set to 0 for the first (odd) field,
-				   set to 1 for the second (even) field. */
-	u8 *p; 			/* Pointer to the sliced VBI data from the decoder.
-				   On exit points to the start of the payload. */
-	u32 line;		/* Line number of the sliced VBI data (1-23) */
-	u32 type;		/* VBI service type (V4L2_SLICED_*). 0 if no service found */
+	u32 is_second_field;
+	u8 *p;
+	u32 line;
+	u32 type;
 };
 
-/* Sub-devices are devices that are connected somehow to the main bridge
-   device. These devices are usually audio/video muxers/encoders/decoders or
-   sensors and webcam controllers.
-
-   Usually these devices are controlled through an i2c bus, but other busses
-   may also be used.
-
-   The v4l2_subdev struct provides a way of accessing these devices in a
-   generic manner. Most operations that these sub-devices support fall in
-   a few categories: core ops, audio ops, video ops and tuner ops.
-
-   More categories can be added if needed, although this should remain a
-   limited set (no more than approx. 8 categories).
-
-   Each category has its own set of ops that subdev drivers can implement.
-
-   A subdev driver can leave the pointer to the category ops NULL if
-   it does not implement them (e.g. an audio subdev will generally not
-   implement the video category ops). The exception is the core category:
-   this must always be present.
-
-   These ops are all used internally so it is no problem to change, remove
-   or add ops or move ops from one to another category. Currently these
-   ops are based on the original ioctls, but since ops are not limited to
-   one argument there is room for improvement here once all i2c subdev
-   drivers are converted to use these ops.
+/*
+ * Sub-devices are devices that are connected somehow to the main bridge
+ * device. These devices are usually audio/video muxers/encoders/decoders or
+ * sensors and webcam controllers.
+ *
+ * Usually these devices are controlled through an i2c bus, but other busses
+ * may also be used.
+ *
+ * The v4l2_subdev struct provides a way of accessing these devices in a
+ * generic manner. Most operations that these sub-devices support fall in
+ * a few categories: core ops, audio ops, video ops and tuner ops.
+ *
+ * More categories can be added if needed, although this should remain a
+ * limited set (no more than approx. 8 categories).
+ *
+ * Each category has its own set of ops that subdev drivers can implement.
+ *
+ * A subdev driver can leave the pointer to the category ops NULL if
+ * it does not implement them (e.g. an audio subdev will generally not
+ * implement the video category ops). The exception is the core category:
+ * this must always be present.
+ *
+ * These ops are all used internally so it is no problem to change, remove
+ * or add ops or move ops from one to another category. Currently these
+ * ops are based on the original ioctls, but since ops are not limited to
+ * one argument there is room for improvement here once all i2c subdev
+ * drivers are converted to use these ops.
  */
 
-/* Core ops: it is highly recommended to implement at least these ops:
-
-   log_status
-   g_register
-   s_register
-
-   This provides basic debugging support.
-
-   The ioctl ops is meant for generic ioctl-like commands. Depending on
-   the use-case it might be better to use subdev-specific ops (currently
-   not yet implemented) since ops provide proper type-checking.
+/*
+ * Core ops: it is highly recommended to implement at least these ops:
+ *
+ * log_status
+ * g_register
+ * s_register
+ *
+ * This provides basic debugging support.
+ *
+ * The ioctl ops is meant for generic ioctl-like commands. Depending on
+ * the use-case it might be better to use subdev-specific ops (currently
+ * not yet implemented) since ops provide proper type-checking.
  */
 
 /* Subdevice external IO pin configuration */
@@ -110,18 +115,32 @@ struct v4l2_decode_vbi_line {
 #define V4L2_SUBDEV_IO_PIN_SET_VALUE	(1 << 3) /* Set output value */
 #define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW	(1 << 4) /* ACTIVE HIGH assumed */
 
+/**
+ * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
+ *
+ * @flags: bitmask with flags for this pin's config:
+ *	   %V4L2_SUBDEV_IO_PIN_DISABLE - disables a pin config,
+ *	   %V4L2_SUBDEV_IO_PIN_OUTPUT - if pin is an output,
+ *	   %V4L2_SUBDEV_IO_PIN_INPUT - if pin is an input,
+ *	   %V4L2_SUBDEV_IO_PIN_SET_VALUE - to set the output value via @value
+ *	   and %V4L2_SUBDEV_IO_PIN_ACTIVE_LOW - if active is 0.
+ * @pin: Chip external IO pin to configure
+ * @function: Internal signal pad/function to route to IO pin
+ * @value: Initial value for pin - e.g. GPIO output value
+ * @strength: Pin drive strength
+ */
 struct v4l2_subdev_io_pin_config {
-	u32 flags;	/* V4L2_SUBDEV_IO_PIN_* flags for this pin's config */
-	u8 pin;		/* Chip external IO pin to configure */
-	u8 function;	/* Internal signal pad/function to route to IO pin */
-	u8 value;	/* Initial value for pin - e.g. GPIO output value */
-	u8 strength;	/* Pin drive strength */
+	u32 flags;
+	u8 pin;
+	u8 function;
+	u8 value;
+	u8 strength;
 };
 
 /**
  * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
  *
- * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code.
+ * @log_status: callback for %VIDIOC_LOG_STATUS ioctl handler code.
  *
  * @s_io_pin_config: configure one or more chip I/O pins for chips that
  *	multiplex different internal signal pads out to IO pins.  This function
@@ -143,19 +162,19 @@ struct v4l2_subdev_io_pin_config {
  * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with
  *	a direction argument if needed.
  *
- * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code.
+ * @queryctrl: callback for %VIDIOC_QUERYCTL ioctl handler code.
  *
- * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code.
+ * @g_ctrl: callback for %VIDIOC_G_CTRL ioctl handler code.
  *
- * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code.
+ * @s_ctrl: callback for %VIDIOC_S_CTRL ioctl handler code.
  *
- * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code.
+ * @g_ext_ctrls: callback for %VIDIOC_G_EXT_CTRLS ioctl handler code.
  *
- * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code.
+ * @s_ext_ctrls: callback for %VIDIOC_S_EXT_CTRLS ioctl handler code.
  *
- * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code.
+ * @try_ext_ctrls: callback for %VIDIOC_TRY_EXT_CTRLS ioctl handler code.
  *
- * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code.
+ * @querymenu: callback for %VIDIOC_QUERYMENU ioctl handler code.
  *
  * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core.
  *	   used to provide support for private ioctls used on the driver.
@@ -163,9 +182,9 @@ struct v4l2_subdev_io_pin_config {
  * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
  *		    in order to fix data passed from/to userspace.
  *
- * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @g_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
  *
- * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @s_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
  *
  * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
  *	mode (on == 1).
@@ -173,7 +192,7 @@ struct v4l2_subdev_io_pin_config {
  * @interrupt_service_routine: Called by the bridge chip's interrupt service
  *	handler, when an interrupt status has be raised due to this subdev,
  *	so that this subdev can handle the details.  It may schedule work to be
- *	performed later.  It must not sleep.  *Called from an IRQ context*.
+ *	performed later.  It must not sleep. **Called from an IRQ context**.
  *
  * @subscribe_event: used by the drivers to request the control framework that
  *		     for it to be warned when the value of a control changes.
@@ -219,25 +238,25 @@ struct v4l2_subdev_core_ops {
 /**
  * struct s_radio - Callbacks used when v4l device was opened in radio mode.
  *
- * @s_radio: callback for VIDIOC_S_RADIO ioctl handler code.
+ * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
  *
- * @s_frequency: callback for VIDIOC_S_FREQUENCY ioctl handler code.
+ * @s_frequency: callback for %VIDIOC_S_FREQUENCY ioctl handler code.
  *
- * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code.
- *		 freq->type must be filled in. Normally done by video_ioctl2
+ * @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.
  *
- * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
+ * @enum_freq_bands: callback for %VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
  *
- * @g_tuner: callback for VIDIOC_G_TUNER ioctl handler code.
+ * @g_tuner: callback for %VIDIOC_G_TUNER ioctl handler code.
  *
- * @s_tuner: callback for VIDIOC_S_TUNER ioctl handler code. vt->type must be
+ * @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.
  *
- * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code.
+ * @g_modulator: callback for %VIDIOC_G_MODULATOR ioctl handler code.
  *
- * @s_modulator: callback for VIDIOC_S_MODULATOR ioctl handler code.
+ * @s_modulator: callback for %VIDIOC_S_MODULATOR ioctl handler code.
  *
  * @s_type_addr: sets tuner type and its I2C addr.
  *
@@ -268,7 +287,7 @@ struct v4l2_subdev_tuner_ops {
  * @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
  *	way to select I2S clock used by driving digital audio streams at some
  *	board designs. Usual values for the frequency are 1024000 and 2048000.
- *	If the frequency is not supported, then -EINVAL is returned.
+ *	If the frequency is not supported, then %-EINVAL is returned.
  *
  * @s_routing: used to define the input and/or output pins of an audio chip,
  *	and any additional configuration data.
@@ -300,7 +319,8 @@ struct v4l2_subdev_audio_ops {
 /**
  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
  *
- * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags
+ * @flags: bitmask flags: %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX and
+ *			  %V4L2_MBUS_FRAME_DESC_FL_BLOB.
  * @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
  * @length: number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB
  *	    is set
@@ -325,7 +345,7 @@ struct v4l2_mbus_frame_desc {
 
 /**
  * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
- * 				  in video mode.
+ *				  in video mode.
  *
  * @s_routing: see s_routing in audio_ops, except this version is for video
  *	devices.
@@ -335,9 +355,9 @@ struct v4l2_mbus_frame_desc {
  *	regarding clock frequency dividers, etc. If not used, then set flags
  *	to 0. If the frequency is not supported, then -EINVAL is returned.
  *
- * @g_std: callback for VIDIOC_G_STD ioctl handler code.
+ * @g_std: callback for %VIDIOC_G_STD ioctl handler code.
  *
- * @s_std: callback for VIDIOC_S_STD ioctl handler code.
+ * @s_std: callback for %VIDIOC_S_STD ioctl handler code.
  *
  * @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
  *	video input devices.
@@ -345,33 +365,33 @@ struct v4l2_mbus_frame_desc {
  * @g_std_output: get current standard for video OUTPUT devices. This is ignored
  *	by video input devices.
  *
- * @querystd: callback for VIDIOC_QUERYSTD ioctl handler code.
+ * @querystd: callback for %VIDIOC_QUERYSTD ioctl handler code.
  *
- * @g_tvnorms: get v4l2_std_id with all standards supported by the video
+ * @g_tvnorms: get &v4l2_std_id with all standards supported by the video
  *	CAPTURE device. This is ignored by video output devices.
  *
  * @g_tvnorms_output: get v4l2_std_id with all standards supported by the video
  *	OUTPUT device. This is ignored by video capture devices.
  *
- * @g_input_status: get input status. Same as the status field in the v4l2_input
- *	struct.
+ * @g_input_status: get input status. Same as the status field in the
+ *	&struct &v4l2_input
  *
  * @s_stream: used to notify the driver that a video stream will start or has
  *	stopped.
  *
- * @cropcap: callback for VIDIOC_CROPCAP ioctl handler code.
+ * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code.
  *
- * @g_crop: callback for VIDIOC_G_CROP ioctl handler code.
+ * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code.
  *
- * @s_crop: callback for VIDIOC_S_CROP ioctl handler code.
+ * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code.
  *
- * @g_parm: callback for VIDIOC_G_PARM ioctl handler code.
+ * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code.
  *
- * @s_parm: callback for VIDIOC_S_PARM ioctl handler code.
+ * @s_parm: callback for %VIDIOC_S_PARM ioctl handler code.
  *
- * @g_frame_interval: callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code.
+ * @g_frame_interval: callback for %VIDIOC_G_FRAMEINTERVAL ioctl handler code.
  *
- * @s_frame_interval: callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code.
+ * @s_frame_interval: callback for %VIDIOC_S_FRAMEINTERVAL ioctl handler code.
  *
  * @s_dv_timings: Set custom dv timings in the sub device. This is used
  *	when sub device is capable of setting detailed timing information
@@ -379,7 +399,7 @@ struct v4l2_mbus_frame_desc {
  *
  * @g_dv_timings: Get custom dv timings in the sub device.
  *
- * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
+ * @query_dv_timings: callback for %VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
  *
  * @g_mbus_config: get supported mediabus configurations
  *
@@ -428,31 +448,31 @@ struct v4l2_subdev_video_ops {
 
 /**
  * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
- * 				  in video mode via the vbi device node.
+ *				  in video mode via the vbi device node.
  *
  *  @decode_vbi_line: video decoders that support sliced VBI need to implement
- *	this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
+ *	this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the
  *	start of the VBI data that was generated by the decoder. The driver
  *	then parses the sliced VBI data and sets the other fields in the
  *	struct accordingly. The pointer p is updated to point to the start of
  *	the payload which can be copied verbatim into the data field of the
- *	v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
+ *	&struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the
  *	type field is set to 0 on return.
  *
  * @s_vbi_data: used to generate VBI signals on a video signal.
- *	v4l2_sliced_vbi_data is filled with the data packets that should be
- *	output. Note that if you set the line field to 0, then that VBI signal
- *	is disabled. If no valid VBI data was found, then the type field is
- *	set to 0 on return.
+ *	&struct v4l2_sliced_vbi_data is filled with the data packets that
+ *	should be output. Note that if you set the line field to 0, then that
+ *	VBI signal is disabled. If no valid VBI data was found, then the type
+ *	field is set to 0 on return.
  *
  * @g_vbi_data: used to obtain the sliced VBI packet from a readback register.
  *	Not all video decoders support this. If no data is available because
- *	the readback register contains invalid or erroneous data -EIO is
+ *	the readback register contains invalid or erroneous data %-EIO is
  *	returned. Note that you must fill in the 'id' member and the 'field'
  *	member (to determine whether CC data from the first or second field
  *	should be obtained).
  *
- * @g_sliced_vbi_cap: callback for VIDIOC_SLICED_VBI_CAP ioctl handler code.
+ * @g_sliced_vbi_cap: callback for %VIDIOC_SLICED_VBI_CAP ioctl handler code.
  *
  * @s_raw_fmt: setup the video encoder/decoder for raw VBI.
  *
@@ -485,58 +505,99 @@ struct v4l2_subdev_sensor_ops {
 	int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
 };
 
-/*
-   [rt]x_g_parameters: Get the current operating parameters and state of the
-	the IR receiver or transmitter.
-
-   [rt]x_s_parameters: Set the current operating parameters and state of the
-	the IR receiver or transmitter.  It is recommended to call
-	[rt]x_g_parameters first to fill out the current state, and only change
-	the fields that need to be changed.  Upon return, the actual device
-	operating parameters and state will be returned.  Note that hardware
-	limitations may prevent the actual settings from matching the requested
-	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
-	was requested.  An exception is when the shutdown parameter is true.
-	The last used operational parameters will be returned, but the actual
-	state of the hardware be different to minimize power consumption and
-	processing when shutdown is true.
-
-   rx_read: Reads received codes or pulse width data.
-	The semantics are similar to a non-blocking read() call.
-
-   tx_write: Writes codes or pulse width data for transmission.
-	The semantics are similar to a non-blocking write() call.
+/**
+ * enum v4l2_subdev_ir_mode- describes the type of IR supported
+ *
+ * @V4L2_SUBDEV_IR_MODE_PULSE_WIDTH: IR uses struct ir_raw_event records
  */
-
 enum v4l2_subdev_ir_mode {
-	V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* uses struct ir_raw_event records */
+	V4L2_SUBDEV_IR_MODE_PULSE_WIDTH,
 };
 
+/**
+ * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
+ *
+ * @bytes_per_data_element: bytes per data element of data in read or
+ *	write call.
+ * @mode: IR mode as defined by &enum v4l2_subdev_ir_mode.
+ * @enable: device is active if true
+ * @interrupt_enable: IR interrupts are enabled if true
+ * @shutdown: if true: set hardware to low/no power, false: normal mode
+ *
+ * @modulation: if true, it uses carrier, if false: baseband
+ * @max_pulse_width:  maximum pulse width in ns, valid only for baseband signal
+ * @carrier_freq: carrier frequency in Hz, valid only for modulated signal
+ * @duty_cycle: duty cycle percentage, valid only for modulated signal
+ * @invert_level: invert signal level
+ *
+ * @invert_carrier_sense: Send 0/space as a carrier burst. used only in TX.
+ *
+ * @noise_filter_min_width: min time of a valid pulse, in ns. Used only for RX.
+ * @carrier_range_lower: Lower carrier range, in Hz, valid only for modulated
+ *	signal. Used only for RX.
+ * @carrier_range_upper: Upper carrier range, in Hz, valid only for modulated
+ *	signal. Used only for RX.
+ * @resolution: The receive resolution, in ns . Used only for RX.
+ */
 struct v4l2_subdev_ir_parameters {
-	/* Either Rx or Tx */
-	unsigned int bytes_per_data_element; /* of data in read or write call */
+	unsigned int bytes_per_data_element;
 	enum v4l2_subdev_ir_mode mode;
 
 	bool enable;
 	bool interrupt_enable;
-	bool shutdown; /* true: set hardware to low/no power, false: normal */
+	bool shutdown;
 
-	bool modulation;           /* true: uses carrier, false: baseband */
-	u32 max_pulse_width;       /* ns,      valid only for baseband signal */
-	unsigned int carrier_freq; /* Hz,      valid only for modulated signal*/
-	unsigned int duty_cycle;   /* percent, valid only for modulated signal*/
-	bool invert_level;	   /* invert signal level */
+	bool modulation;
+	u32 max_pulse_width;
+	unsigned int carrier_freq;
+	unsigned int duty_cycle;
+	bool invert_level;
 
 	/* Tx only */
-	bool invert_carrier_sense; /* Send 0/space as a carrier burst */
+	bool invert_carrier_sense;
 
 	/* Rx only */
-	u32 noise_filter_min_width;       /* ns, min time of a valid pulse */
-	unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */
-	unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */
-	u32 resolution;                   /* ns */
+	u32 noise_filter_min_width;
+	unsigned int carrier_range_lower;
+	unsigned int carrier_range_upper;
+	u32 resolution;
 };
 
+/**
+ * struct v4l2_subdev_ir_ops - operations for IR subdevices
+ *
+ * @rx_read: Reads received codes or pulse width data.
+ *	The semantics are similar to a non-blocking read() call.
+ * @rx_g_parameters: Get the current operating parameters and state of the
+ *	the IR receiver.
+ * @rx_s_parameters: Set the current operating parameters and state of the
+ *	the IR receiver.  It is recommended to call
+ *	[rt]x_g_parameters first to fill out the current state, and only change
+ *	the fields that need to be changed.  Upon return, the actual device
+ *	operating parameters and state will be returned.  Note that hardware
+ *	limitations may prevent the actual settings from matching the requested
+ *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ *	was requested.  An exception is when the shutdown parameter is true.
+ *	The last used operational parameters will be returned, but the actual
+ *	state of the hardware be different to minimize power consumption and
+ *	processing when shutdown is true.
+ *
+ * @tx_write: Writes codes or pulse width data for transmission.
+ *	The semantics are similar to a non-blocking write() call.
+ * @tx_g_parameters: Get the current operating parameters and state of the
+ *	the IR transmitter.
+ * @tx_s_parameters: Set the current operating parameters and state of the
+ *	the IR transmitter.  It is recommended to call
+ *	[rt]x_g_parameters first to fill out the current state, and only change
+ *	the fields that need to be changed.  Upon return, the actual device
+ *	operating parameters and state will be returned.  Note that hardware
+ *	limitations may prevent the actual settings from matching the requested
+ *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ *	was requested.  An exception is when the shutdown parameter is true.
+ *	The last used operational parameters will be returned, but the actual
+ *	state of the hardware be different to minimize power consumption and
+ *	processing when shutdown is true.
+ */
 struct v4l2_subdev_ir_ops {
 	/* Receiver */
 	int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
@@ -557,11 +618,16 @@ struct v4l2_subdev_ir_ops {
 				struct v4l2_subdev_ir_parameters *params);
 };
 
-/*
- * Used for storing subdev pad information. This structure only needs
- * to be passed to the pad op if the 'which' field of the main argument
- * is set to V4L2_SUBDEV_FORMAT_TRY. For V4L2_SUBDEV_FORMAT_ACTIVE it is
- * safe to pass NULL.
+/**
+ * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
+ *
+ * @try_fmt: pointer to &struct v4l2_mbus_framefmt
+ * @try_crop: pointer to &struct v4l2_rect to be used for crop
+ * @try_compose: pointer to &struct v4l2_rect to be used for compose
+ *
+ * This structure only needs to be passed to the pad op if the 'which' field
+ * of the main argument is set to %V4L2_SUBDEV_FORMAT_TRY. For
+ * %V4L2_SUBDEV_FORMAT_ACTIVE it is safe to pass %NULL.
  */
 struct v4l2_subdev_pad_config {
 	struct v4l2_mbus_framefmt try_fmt;
@@ -573,30 +639,30 @@ struct v4l2_subdev_pad_config {
  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
  *
  * @init_cfg: initialize the pad config to default values
- * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
+ * @enum_mbus_code: callback for %VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
  *		    code.
- * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
+ * @enum_frame_size: callback for %VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
  *		     code.
  *
- * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
+ * @enum_frame_interval: callback for %VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
  *			 handler code.
  *
- * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT ioctl handler code.
+ * @get_fmt: callback for %VIDIOC_SUBDEV_G_FMT ioctl handler code.
  *
- * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT ioctl handler code.
+ * @set_fmt: callback for %VIDIOC_SUBDEV_S_FMT ioctl handler code.
  *
- * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
+ * @get_selection: callback for %VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
  *
- * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
+ * @set_selection: callback for %VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
  *
- * @get_edid: callback for VIDIOC_SUBDEV_G_EDID ioctl handler code.
+ * @get_edid: callback for %VIDIOC_SUBDEV_G_EDID ioctl handler code.
  *
- * @set_edid: callback for VIDIOC_SUBDEV_S_EDID ioctl handler code.
+ * @set_edid: callback for %VIDIOC_SUBDEV_S_EDID ioctl handler code.
  *
- * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
+ * @dv_timings_cap: callback for %VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
  *		    code.
  *
- * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
+ * @enum_dv_timings: callback for %VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
  *		     code.
  *
  * @link_validate: used by the media controller code to check if the links
@@ -648,6 +714,18 @@ struct v4l2_subdev_pad_ops {
 			      struct v4l2_mbus_frame_desc *fd);
 };
 
+/**
+ * struct v4l2_subdev_ops - Subdev operations
+ *
+ * @core: pointer to &struct v4l2_subdev_core_ops. Can be %NULL
+ * @tuner: pointer to &struct v4l2_subdev_tuner_ops. Can be %NULL
+ * @audio: pointer to &struct v4l2_subdev_audio_ops. Can be %NULL
+ * @video: pointer to &struct v4l2_subdev_video_ops. Can be %NULL
+ * @vbi: pointer to &struct v4l2_subdev_vbi_ops. Can be %NULL
+ * @ir: pointer to &struct v4l2_subdev_ir_ops. Can be %NULL
+ * @sensor: pointer to &struct v4l2_subdev_sensor_ops. Can be %NULL
+ * @pad: pointer to &struct v4l2_subdev_pad_ops. Can be %NULL
+ */
 struct v4l2_subdev_ops {
 	const struct v4l2_subdev_core_ops	*core;
 	const struct v4l2_subdev_tuner_ops	*tuner;
@@ -659,19 +737,22 @@ struct v4l2_subdev_ops {
 	const struct v4l2_subdev_pad_ops	*pad;
 };
 
-/*
- * Internal ops. Never call this from drivers, only the v4l2 framework can call
- * these ops.
+/**
+ * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
  *
- * registered: called when this subdev is registered. When called the v4l2_dev
+ * @registered: called when this subdev is registered. When called the v4l2_dev
  *	field is set to the correct v4l2_device.
  *
- * unregistered: called when this subdev is unregistered. When called the
+ * @unregistered: called when this subdev is unregistered. When called the
  *	v4l2_dev field is still set to the correct v4l2_device.
  *
- * open: called when the subdev device node is opened by an application.
+ * @open: called when the subdev device node is opened by an application.
  *
- * close: called when the subdev device node is closed.
+ * @close: called when the subdev device node is closed.
+ *
+ * .. note::
+ *	Never call this from drivers, only the v4l2 framework can call
+ *	these ops.
  */
 struct v4l2_subdev_internal_ops {
 	int (*registered)(struct v4l2_subdev *sd);
@@ -693,17 +774,60 @@ struct v4l2_subdev_internal_ops {
 
 struct regulator_bulk_data;
 
+/**
+ * struct v4l2_subdev_platform_data - regulators config struct
+ *
+ * @regulators: Optional regulators used to power on/off the subdevice
+ * @num_regulators: Number of regululators
+ * @host_priv: Per-subdevice data, specific for a certain video host device
+ */
 struct v4l2_subdev_platform_data {
-	/* Optional regulators uset to power on/off the subdevice */
 	struct regulator_bulk_data *regulators;
 	int num_regulators;
 
-	/* Per-subdevice data, specific for a certain video host device */
 	void *host_priv;
 };
 
-/* Each instance of a subdev driver should create this struct, either
-   stand-alone or embedded in a larger struct.
+/**
+ * struct v4l2_subdev - describes a V4L2 sub-device
+ *
+ * @entity: pointer to &struct media_entity
+ * @list: List of sub-devices
+ * @owner: The owner is the same as the driver's &struct device owner.
+ * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev
+ *	ownner. Initialized by v4l2_device_register_subdev().
+ * @flags: subdev flags. Can be:
+ *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
+ *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
+ *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
+ *   device node;
+ *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
+ *   events.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @ops: pointer to &struct v4l2_subdev_ops
+ * @internal_ops: pointer to &struct v4l2_subdev_internal_ops.
+ *	Never call these internal ops from within a driver!
+ * @ctrl_handler: The control handler of this subdev. May be NULL.
+ * @name: Name of the sub-device. Please notice that the name must be unique.
+ * @grp_id: can be used to group similar subdevs. Value is driver-specific
+ * @dev_priv: pointer to private data
+ * @host_priv: pointer to private data used by the device where the subdev
+ *	is attached.
+ * @devnode: subdev device node
+ * @dev: pointer to the physical device, if any
+ * @of_node: The device_node of the subdev, usually the same as dev->of_node.
+ * @async_list: Links this subdev to a global subdev_list or @notifier->done
+ *	list.
+ * @asd: Pointer to respective &struct v4l2_async_subdev.
+ * @notifier: Pointer to the managing notifier.
+ * @pdata: common part of subdevice platform data
+ *
+ * Each instance of a subdev driver should create this struct, either
+ * stand-alone or embedded in a larger struct.
+ *
+ * This structure should be initialized by v4l2_subdev_init() or one of
+ * its variants: v4l2_spi_subdev_init(), v4l2_i2c_subdev_init().
  */
 struct v4l2_subdev {
 #if defined(CONFIG_MEDIA_CONTROLLER)
@@ -715,30 +839,18 @@ struct v4l2_subdev {
 	u32 flags;
 	struct v4l2_device *v4l2_dev;
 	const struct v4l2_subdev_ops *ops;
-	/* Never call these internal ops from within a driver! */
 	const struct v4l2_subdev_internal_ops *internal_ops;
-	/* The control handler of this subdev. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
-	/* name must be unique */
 	char name[V4L2_SUBDEV_NAME_SIZE];
-	/* can be used to group similar subdevs, value is driver-specific */
 	u32 grp_id;
-	/* pointer to private data */
 	void *dev_priv;
 	void *host_priv;
-	/* subdev device node */
 	struct video_device *devnode;
-	/* pointer to the physical device, if any */
 	struct device *dev;
-	/* The device_node of the subdev, usually the same as dev->of_node. */
 	struct device_node *of_node;
-	/* Links this subdev to a global subdev_list or @notifier->done list. */
 	struct list_head async_list;
-	/* Pointer to respective struct v4l2_async_subdev. */
 	struct v4l2_async_subdev *asd;
-	/* Pointer to the managing notifier. */
 	struct v4l2_async_notifier *notifier;
-	/* common part of subdevice platform data */
 	struct v4l2_subdev_platform_data *pdata;
 };
 
@@ -747,8 +859,11 @@ struct v4l2_subdev {
 #define vdev_to_v4l2_subdev(vdev) \
 	((struct v4l2_subdev *)video_get_drvdata(vdev))
 
-/*
- * Used for storing subdev information per file handle
+/**
+ * struct v4l2_subdev_fh - Used for storing subdev information per file handle
+ *
+ * @vfh: pointer to struct v4l2_fh
+ * @pad: pointer to v4l2_subdev_pad_config
  */
 struct v4l2_subdev_fh {
 	struct v4l2_fh vfh;
@@ -778,53 +893,132 @@ __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
 
 extern const struct v4l2_file_operations v4l2_subdev_fops;
 
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private device data to be stored.
+ */
 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
 {
 	sd->dev_priv = p;
 }
 
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private device data to be stored.
+ */
 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
 {
 	return sd->dev_priv;
 }
 
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private host data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private data to be stored.
+ */
 static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
 {
 	sd->host_priv = p;
 }
 
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private host data to be stored.
+ */
 static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)
 {
 	return sd->host_priv;
 }
 
 #ifdef CONFIG_MEDIA_CONTROLLER
+
+/**
+ * v4l2_subdev_link_validate_default - validates a media link
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @link: pointer to &struct media_link
+ * @source_fmt: pointer to &struct v4l2_subdev_format
+ * @sink_fmt: pointer to &struct v4l2_subdev_format
+ *
+ * This function ensures that width, height and the media bus pixel
+ * code are equal on both source and sink of the link.
+ */
 int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
 				      struct media_link *link,
 				      struct v4l2_subdev_format *source_fmt,
 				      struct v4l2_subdev_format *sink_fmt);
+
+/**
+ * v4l2_subdev_link_validate - validates a media link
+ *
+ * @link: pointer to &struct media_link
+ *
+ * This function calls the subdev's link_validate ops to validate
+ * if a media link is valid for streaming. It also internally
+ * calls v4l2_subdev_link_validate_default() to ensure that
+ * width, height and the media bus pixel code are equal on both
+ * source and sink of the link.
+ */
 int v4l2_subdev_link_validate(struct media_link *link);
 
-struct v4l2_subdev_pad_config *
-v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+/**
+ * v4l2_subdev_alloc_pad_config - Allocates memory for pad config
+ *
+ * @sd: pointer to struct v4l2_subdev
+ */
+struct
+v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_subdev_free_pad_config - Frees memory allocated by
+ *	v4l2_subdev_alloc_pad_config().
+ *
+ * @cfg: pointer to &struct v4l2_subdev_pad_config
+ */
 void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
 #endif /* CONFIG_MEDIA_CONTROLLER */
 
+/**
+ * v4l2_subdev_init - initializes the sub-device struct
+ *
+ * @sd: pointer to the &struct v4l2_subdev to be initialized
+ * @ops: pointer to &struct v4l2_subdev_ops.
+ */
 void v4l2_subdev_init(struct v4l2_subdev *sd,
 		      const struct v4l2_subdev_ops *ops);
 
-/* Call an ops of a v4l2_subdev, doing the right checks against
-   NULL pointers.
-
-   Example: err = v4l2_subdev_call(sd, video, s_std, norm);
+/*
+ * Call an ops of a v4l2_subdev, doing the right checks against
+ * NULL pointers.
+ *
+ * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
  */
 #define v4l2_subdev_call(sd, o, f, args...)				\
 	(!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ?	\
-		(sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD))
+		(sd)->ops->o->f((sd), ##args) : -ENOIOCTLCMD))
 
 #define v4l2_subdev_has_op(sd, o, f) \
 	((sd)->ops->o && (sd)->ops->o->f)
 
+/**
+ * v4l2_subdev_notify_event() - Delivers event notification for subdevice
+ * @sd: The subdev for which to deliver the event
+ * @ev: The event to deliver
+ *
+ * Will deliver the specified event to all userspace event listeners which are
+ * subscribed to the v42l subdev event queue as well as to the bridge driver
+ * using the notify callback. The notification type for the notify callback
+ * will be %V4L2_DEVICE_NOTIFY_EVENT.
+ */
 void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
 			      const struct v4l2_event *ev);
 
-- 
2.7.4

[PATCH 07/12] [media] v4l2-subdev.rst: add cross-references

[Mauro Carvalho Chehab]

Enrich the subdevice description by linking it to the
functions and structs from v4l2-subdev.h.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-subdev.rst | 158 ++++++++++++++++---------------
 1 file changed, 83 insertions(+), 75 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 3e2b25b47ff4..101902c930b9 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -7,35 +7,37 @@ encoding or decoding. For webcams common sub-devices are sensors and camera
 controllers.
 
 Usually these are I2C devices, but not necessarily. In order to provide the
-driver with a consistent interface to these sub-devices the v4l2_subdev struct
-(v4l2-subdev.h) was created.
+driver with a consistent interface to these sub-devices the
+:c:type:`v4l2_subdev` struct (v4l2-subdev.h) was created.
 
-Each sub-device driver must have a v4l2_subdev struct. This struct can be
-stand-alone for simple sub-devices or it might be embedded in a larger struct
-if more state information needs to be stored. Usually there is a low-level
-device struct (e.g. i2c_client) that contains the device data as setup
-by the kernel. It is recommended to store that pointer in the private
-data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
-from a v4l2_subdev to the actual low-level bus-specific device data.
+Each sub-device driver must have a :c:type:`v4l2_subdev` struct. This struct
+can be stand-alone for simple sub-devices or it might be embedded in a larger
+struct if more state information needs to be stored. Usually there is a
+low-level device struct (e.g. ``i2c_client``) that contains the device data as
+setup by the kernel. It is recommended to store that pointer in the private
+data of :c:type:`v4l2_subdev` using :cpp:func:`v4l2_set_subdevdata`. That makes
+it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific
+device data.
 
-You also need a way to go from the low-level struct to v4l2_subdev. For the
-common i2c_client struct the i2c_set_clientdata() call is used to store a
-v4l2_subdev pointer, for other busses you may have to use other methods.
+You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`.
+For the common i2c_client struct the i2c_set_clientdata() call is used to store
+a :c:type:`v4l2_subdev` pointer, for other busses you may have to use other
+methods.
 
 Bridges might also need to store per-subdev private data, such as a pointer to
-bridge-specific per-subdev private data. The v4l2_subdev structure provides
-host private data for that purpose that can be accessed with
-v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata().
+bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure
+provides host private data for that purpose that can be accessed with
+:cpp:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`.
 
-From the bridge driver perspective you load the sub-device module and somehow
-obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
-i2c_get_clientdata(). For other busses something similar needs to be done.
+From the bridge driver perspective, you load the sub-device module and somehow
+obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
+``i2c_get_clientdata()``. For other busses something similar needs to be done.
 Helper functions exists for sub-devices on an I2C bus that do most of this
 tricky work for you.
 
-Each v4l2_subdev contains function pointers that sub-device drivers can
-implement (or leave NULL if it is not applicable). Since sub-devices can do
-so many different things and you do not want to end up with a huge ops struct
+Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers
+can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can
+do so many different things and you do not want to end up with a huge ops struct
 of which only a handful of ops are commonly implemented, the function pointers
 are sorted according to category and each category has its own ops struct.
 
@@ -44,7 +46,7 @@ may be NULL if the subdev driver does not support anything from that category.
 
 It looks like this:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct v4l2_subdev_core_ops {
 		int (*log_status)(struct v4l2_subdev *sd);
@@ -83,20 +85,22 @@ audio ops and vice versa.
 This setup limits the number of function pointers while still making it easy
 to add new ops and categories.
 
-A sub-device driver initializes the v4l2_subdev struct using:
+A sub-device driver initializes the :c:type:`v4l2_subdev` struct using:
 
-.. code-block:: none
+	:cpp:func:`v4l2_subdev_init <v4l2_subdev_init>`
+	(:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`).
 
-	v4l2_subdev_init(sd, &ops);
 
-Afterwards you need to initialize subdev->name with a unique name and set the
-module owner. This is done for you if you use the i2c helper functions.
+Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a
+unique name and set the module owner. This is done for you if you use the
+i2c helper functions.
 
 If integration with the media framework is needed, you must initialize the
-media_entity struct embedded in the v4l2_subdev struct (entity field) by
-calling media_entity_pads_init(), if the entity has pads:
+:c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct
+(entity field) by calling :cpp:func:`media_entity_pads_init`, if the entity has
+pads:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct media_pad *pads = &my_sd->pads;
 	int err;
@@ -104,7 +108,7 @@ calling media_entity_pads_init(), if the entity has pads:
 	err = media_entity_pads_init(&sd->entity, npads, pads);
 
 The pads array must have been previously initialized. There is no need to
-manually set the struct media_entity function and name fields, but the
+manually set the struct :c:type:`media_entity` function and name fields, but the
 revision field must be initialized if needed.
 
 A reference to the entity will be automatically acquired/released when the
@@ -112,13 +116,13 @@ subdev device node (if any) is opened/closed.
 
 Don't forget to cleanup the media entity before the sub-device is destroyed:
 
-.. code-block:: none
+.. code-block:: c
 
 	media_entity_cleanup(&sd->entity);
 
 If the subdev driver intends to process video and integrate with the media
 framework, it must implement format related functionality using
-v4l2_subdev_pad_ops instead of v4l2_subdev_video_ops.
+:c:type:`v4l2_subdev_pad_ops` instead of :c:type:`v4l2_subdev_video_ops`.
 
 In that case, the subdev driver may set the link_validate field to provide
 its own link validation function. The link validation function is called for
@@ -127,9 +131,9 @@ sub-devices. The driver is still responsible for validating the correctness
 of the format configuration between sub-devices and video nodes.
 
 If link_validate op is not set, the default function
-v4l2_subdev_link_validate_default() is used instead. This function ensures
-that width, height and the media bus pixel code are equal on both source and
-sink of the link. Subdev drivers are also free to use this function to
+:cpp:func:`v4l2_subdev_link_validate_default` is used instead. This function
+ensures that width, height and the media bus pixel code are equal on both source
+and sink of the link. Subdev drivers are also free to use this function to
 perform the checks mentioned above in addition to their own checks.
 
 There are currently two ways to register subdevices with the V4L2 core. The
@@ -152,105 +156,109 @@ Using one or the other registration method only affects the probing process, the
 run-time bridge-subdevice interaction is in both cases the same.
 
 In the synchronous case a device (bridge) driver needs to register the
-v4l2_subdev with the v4l2_device:
+:c:type:`v4l2_subdev` with the v4l2_device:
 
-.. code-block:: none
-
-	int err = v4l2_device_register_subdev(v4l2_dev, sd);
+	:cpp:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
+	(:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`).
 
 This can fail if the subdev module disappeared before it could be registered.
 After this function was called successfully the subdev->dev field points to
-the v4l2_device.
+the :c:type:`v4l2_device`.
 
 If the v4l2_device parent device has a non-NULL mdev field, the sub-device
 entity will be automatically registered with the media device.
 
 You can unregister a sub-device using:
 
-.. code-block:: none
+	:cpp:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>`
+	(:c:type:`sd <v4l2_subdev>`).
 
-	v4l2_device_unregister_subdev(sd);
 
-Afterwards the subdev module can be unloaded and sd->dev == NULL.
+Afterwards the subdev module can be unloaded and
+:c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
 
 You can call an ops function either directly:
 
-.. code-block:: none
+.. code-block:: c
 
 	err = sd->ops->core->g_std(sd, &norm);
 
 but it is better and easier to use this macro:
 
-.. code-block:: none
+.. code-block:: c
 
 	err = v4l2_subdev_call(sd, core, g_std, &norm);
 
-The macro will to the right NULL pointer checks and returns -ENODEV if subdev
-is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_std is
-NULL, or the actual result of the subdev->ops->core->g_std ops.
+The macro will to the right ``NULL`` pointer checks and returns ``-ENODEV``
+if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
+:c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the
+:c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
 
 It is also possible to call all or a subset of the sub-devices:
 
-.. code-block:: none
+.. code-block:: c
 
 	v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
 
 Any subdev that does not support this ops is skipped and error results are
 ignored. If you want to check for errors use this:
 
-.. code-block:: none
+.. code-block:: c
 
 	err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
 
-Any error except -ENOIOCTLCMD will exit the loop with that error. If no
-errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
+Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
+errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
 
 The second argument to both calls is a group ID. If 0, then all subdevs are
 called. If non-zero, then only those whose group ID match that value will
-be called. Before a bridge driver registers a subdev it can set sd->grp_id
-to whatever value it wants (it's 0 by default). This value is owned by the
-bridge driver and the sub-device driver will never modify or use it.
+be called. Before a bridge driver registers a subdev it can set
+:c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
+default). This value is owned by the bridge driver and the sub-device driver
+will never modify or use it.
 
 The group ID gives the bridge driver more control how callbacks are called.
 For example, there may be multiple audio chips on a board, each capable of
 changing the volume. But usually only one will actually be used when the
 user want to change the volume. You can set the group ID for that subdev to
 e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
-v4l2_device_call_all(). That ensures that it will only go to the subdev
+``v4l2_device_call_all()``. That ensures that it will only go to the subdev
 that needs it.
 
 If the sub-device needs to notify its v4l2_device parent of an event, then
-it can call v4l2_subdev_notify(sd, notification, arg). This macro checks
-whether there is a notify() callback defined and returns -ENODEV if not.
-Otherwise the result of the notify() call is returned.
+it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks
+whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
+Otherwise the result of the ``notify()`` call is returned.
 
-The advantage of using v4l2_subdev is that it is a generic struct and does
-not contain any knowledge about the underlying hardware. So a driver might
+The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
+does not contain any knowledge about the underlying hardware. So a driver might
 contain several subdevs that use an I2C bus, but also a subdev that is
 controlled through GPIO pins. This distinction is only relevant when setting
 up the device, but once the subdev is registered it is completely transparent.
 
-
 In the asynchronous case subdevice probing can be invoked independently of the
 bridge driver availability. The subdevice driver then has to verify whether all
 the requirements for a successful probing are satisfied. This can include a
 check for a master clock availability. If any of the conditions aren't satisfied
-the driver might decide to return -EPROBE_DEFER to request further reprobing
+the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
 attempts. Once all conditions are met the subdevice shall be registered using
-the v4l2_async_register_subdev() function. Unregistration is performed using
-the v4l2_async_unregister_subdev() call. Subdevices registered this way are
-stored in a global list of subdevices, ready to be picked up by bridge drivers.
+the :cpp:func:`v4l2_async_register_subdev` function. Unregistration is
+performed using the :cpp:func:`v4l2_async_unregister_subdev` call. Subdevices
+registered this way are stored in a global list of subdevices, ready to be
+picked up by bridge drivers.
 
 Bridge drivers in turn have to register a notifier object with an array of
 subdevice descriptors that the bridge device needs for its operation. This is
-performed using the v4l2_async_notifier_register() call. To unregister the
-notifier the driver has to call v4l2_async_notifier_unregister(). The former of
-the two functions takes two arguments: a pointer to struct v4l2_device and a
-pointer to struct v4l2_async_notifier. The latter contains a pointer to an array
-of pointers to subdevice descriptors of type struct v4l2_async_subdev type. The
-V4L2 core will then use these descriptors to match asynchronously registered
-subdevices to them. If a match is detected the .bound() notifier callback is
-called. After all subdevices have been located the .complete() callback is
+performed using the :cpp:func:`v4l2_async_notifier_register` call. To
+unregister the notifier the driver has to call
+:cpp:func:`v4l2_async_notifier_unregister`. The former of the two functions
+takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to
+struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array
+of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev`
+type. The V4L2 core will then use these descriptors to match asynchronously
+registered
+subdevices to them. If a match is detected the ``.bound()`` notifier callback
+is called. After all subdevices have been located the .complete() callback is
 called. When a subdevice is removed from the system the .unbind() method is
 called. All three callbacks are optional.
 
-- 
2.7.4

[PATCH 08/12] [media] doc-rst: merge v4l2-async.rst with v4l2-subdev.rst

[Mauro Carvalho Chehab]

The Async API is actually part of the v4l2 subdev.
Move its declarations to it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-async.rst  | 4 ----
 Documentation/media/kapi/v4l2-core.rst   | 1 -
 Documentation/media/kapi/v4l2-subdev.rst | 5 +++++
 3 files changed, 5 insertions(+), 5 deletions(-)
 delete mode 100644 Documentation/media/kapi/v4l2-async.rst

diff --git a/Documentation/media/kapi/v4l2-async.rst b/Documentation/media/kapi/v4l2-async.rst
deleted file mode 100644
index 372aa29fbf29..000000000000
--- a/Documentation/media/kapi/v4l2-async.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-V4L2 Async kAPI
-^^^^^^^^^^^^^^^
-
-.. kernel-doc:: include/media/v4l2-async.h
diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index 8c127ccdb0ae..fc623e9ca871 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -5,7 +5,6 @@ Video2Linux devices
     :maxdepth: 1
 
     v4l2-framework
-    v4l2-async
     v4l2-controls
     v4l2-device
     v4l2-dv-timings
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 101902c930b9..829016940597 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -266,3 +266,8 @@ V4L2 subdev kAPI
 ^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-subdev.h
+
+V4L2 subdev async kAPI
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-async.h
-- 
2.7.4

[PATCH 09/12] [media] v4l2-async: document the remaining stuff

[Mauro Carvalho Chehab]

There are one enum and 4 functions undocumented there.
Document them. That will fix the broken links at the
v4l2-subdev.rst file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-async.h | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h
index 1d6d7da4c45d..8e2a236a4d03 100644
--- a/include/media/v4l2-async.h
+++ b/include/media/v4l2-async.h
@@ -23,6 +23,19 @@ struct v4l2_async_notifier;
 /* A random max subdevice number, used to allocate an array on stack */
 #define V4L2_MAX_SUBDEVS 128U
 
+/**
+ * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
+ *	in order to identify a match
+ *
+ * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
+ * 	v4l2_async_subdev.match ops
+ * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
+ * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
+ * @V4L2_ASYNC_MATCH_OF: Match will use OF node
+ *
+ * This enum is used by the asyncrhronous sub-device logic to define the
+ * algorithm that will be used to match an asynchronous device.
+ */
 enum v4l2_async_match_type {
 	V4L2_ASYNC_MATCH_CUSTOM,
 	V4L2_ASYNC_MATCH_DEVNAME,
@@ -91,9 +104,35 @@ struct v4l2_async_notifier {
 		       struct v4l2_async_subdev *asd);
 };
 
+/**
+ * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
 int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
 				 struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
+ *
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
 void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_register_subdev - registers a sub-device to the asynchronous
+ * 	subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 int v4l2_async_register_subdev(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
+ * 	subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
 #endif
-- 
2.7.4

[PATCH 10/12] [media] v4l2-subdev.rst: add two sections from v4l2-framework.rst

[Mauro Carvalho Chehab]

There are two additional subdev-specific sections at the
v4l2-framework file. Move them to the subdev chapter, in order
to better organize the book.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-framework.rst | 165 ---------------------------
 Documentation/media/kapi/v4l2-subdev.rst    | 166 ++++++++++++++++++++++++++++
 2 files changed, 166 insertions(+), 165 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index a7f64b38af5c..de341fc5b235 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,171 +80,6 @@ The V4L2 framework also optionally integrates with the media framework. If a
 driver sets the struct v4l2_device mdev field, sub-devices and video nodes
 will automatically appear in the media framework as entities.
 
-V4L2 sub-device userspace API
------------------------------
-
-Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
-sub-devices can also be controlled directly by userspace applications.
-
-Device nodes named v4l-subdevX can be created in /dev to access sub-devices
-directly. If a sub-device supports direct userspace configuration it must set
-the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
-
-After registering sub-devices, the v4l2_device driver can create device nodes
-for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
-v4l2_device_register_subdev_nodes(). Those device nodes will be automatically
-removed when sub-devices are unregistered.
-
-The device node handles a subset of the V4L2 API.
-
-VIDIOC_QUERYCTRL
-VIDIOC_QUERYMENU
-VIDIOC_G_CTRL
-VIDIOC_S_CTRL
-VIDIOC_G_EXT_CTRLS
-VIDIOC_S_EXT_CTRLS
-VIDIOC_TRY_EXT_CTRLS
-
-	The controls ioctls are identical to the ones defined in V4L2. They
-	behave identically, with the only exception that they deal only with
-	controls implemented in the sub-device. Depending on the driver, those
-	controls can be also be accessed through one (or several) V4L2 device
-	nodes.
-
-VIDIOC_DQEVENT
-VIDIOC_SUBSCRIBE_EVENT
-VIDIOC_UNSUBSCRIBE_EVENT
-
-	The events ioctls are identical to the ones defined in V4L2. They
-	behave identically, with the only exception that they deal only with
-	events generated by the sub-device. Depending on the driver, those
-	events can also be reported by one (or several) V4L2 device nodes.
-
-	Sub-device drivers that want to use events need to set the
-	V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
-	v4l2_subdev::nevents to events queue depth before registering the
-	sub-device. After registration events can be queued as usual on the
-	v4l2_subdev::devnode device node.
-
-	To properly support events, the poll() file operation is also
-	implemented.
-
-Private ioctls
-
-	All ioctls not in the above list are passed directly to the sub-device
-	driver through the core::ioctl operation.
-
-
-I2C sub-device drivers
-----------------------
-
-Since these drivers are so common, special helper functions are available to
-ease the use of these drivers (v4l2-common.h).
-
-The recommended method of adding v4l2_subdev support to an I2C driver is to
-embed the v4l2_subdev struct into the state struct that is created for each
-I2C device instance. Very simple devices have no state struct and in that case
-you can just create a v4l2_subdev directly.
-
-A typical state struct would look like this (where 'chipname' is replaced by
-the name of the chip):
-
-.. code-block:: none
-
-	struct chipname_state {
-		struct v4l2_subdev sd;
-		...  /* additional state fields */
-	};
-
-Initialize the v4l2_subdev struct as follows:
-
-.. code-block:: none
-
-	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
-
-This function will fill in all the fields of v4l2_subdev and ensure that the
-v4l2_subdev and i2c_client both point to one another.
-
-You should also add a helper inline function to go from a v4l2_subdev pointer
-to a chipname_state struct:
-
-.. code-block:: none
-
-	static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
-	{
-		return container_of(sd, struct chipname_state, sd);
-	}
-
-Use this to go from the v4l2_subdev struct to the i2c_client struct:
-
-.. code-block:: none
-
-	struct i2c_client *client = v4l2_get_subdevdata(sd);
-
-And this to go from an i2c_client to a v4l2_subdev struct:
-
-.. code-block:: none
-
-	struct v4l2_subdev *sd = i2c_get_clientdata(client);
-
-Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
-is called. This will unregister the sub-device from the bridge driver. It is
-safe to call this even if the sub-device was never registered.
-
-You need to do this because when the bridge driver destroys the i2c adapter
-the remove() callbacks are called of the i2c devices on that adapter.
-After that the corresponding v4l2_subdev structures are invalid, so they
-have to be unregistered first. Calling v4l2_device_unregister_subdev(sd)
-from the remove() callback ensures that this is always done correctly.
-
-
-The bridge driver also has some helper functions it can use:
-
-.. code-block:: none
-
-	struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
-					"module_foo", "chipid", 0x36, NULL);
-
-This loads the given module (can be NULL if no module needs to be loaded) and
-calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
-If all goes well, then it registers the subdev with the v4l2_device.
-
-You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
-of possible I2C addresses that it should probe. These probe addresses are
-only used if the previous argument is 0. A non-zero argument means that you
-know the exact i2c address so in that case no probing will take place.
-
-Both functions return NULL if something went wrong.
-
-Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
-the same as the module name. It allows you to specify a chip variant, e.g.
-"saa7114" or "saa7115". In general though the i2c driver autodetects this.
-The use of chipid is something that needs to be looked at more closely at a
-later date. It differs between i2c drivers and as such can be confusing.
-To see which chip variants are supported you can look in the i2c driver code
-for the i2c_device_id table. This lists all the possibilities.
-
-There are two more helper functions:
-
-v4l2_i2c_new_subdev_cfg: this function adds new irq and platform_data
-arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not
-0 then that will be used (non-probing variant), otherwise the probed_addrs
-are probed.
-
-For example: this will probe for address 0x10:
-
-.. code-block:: none
-
-	struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
-			  "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
-
-v4l2_i2c_new_subdev_board uses an i2c_board_info struct which is passed
-to the i2c driver and replaces the irq, platform_data and addr arguments.
-
-If the subdev supports the s_config core ops, then that op is called with
-the irq and platform_data arguments after the subdev was setup. The older
-v4l2_i2c_new_(probed\_)subdev functions will call s_config as well, but with
-irq set to 0 and platform_data set to NULL.
 
 struct video_device
 -------------------
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 829016940597..2845a749409c 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -262,6 +262,172 @@ is called. After all subdevices have been located the .complete() callback is
 called. When a subdevice is removed from the system the .unbind() method is
 called. All three callbacks are optional.
 
+V4L2 sub-device userspace API
+-----------------------------
+
+Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
+sub-devices can also be controlled directly by userspace applications.
+
+Device nodes named v4l-subdevX can be created in /dev to access sub-devices
+directly. If a sub-device supports direct userspace configuration it must set
+the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
+
+After registering sub-devices, the v4l2_device driver can create device nodes
+for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
+v4l2_device_register_subdev_nodes(). Those device nodes will be automatically
+removed when sub-devices are unregistered.
+
+The device node handles a subset of the V4L2 API.
+
+VIDIOC_QUERYCTRL
+VIDIOC_QUERYMENU
+VIDIOC_G_CTRL
+VIDIOC_S_CTRL
+VIDIOC_G_EXT_CTRLS
+VIDIOC_S_EXT_CTRLS
+VIDIOC_TRY_EXT_CTRLS
+
+	The controls ioctls are identical to the ones defined in V4L2. They
+	behave identically, with the only exception that they deal only with
+	controls implemented in the sub-device. Depending on the driver, those
+	controls can be also be accessed through one (or several) V4L2 device
+	nodes.
+
+VIDIOC_DQEVENT
+VIDIOC_SUBSCRIBE_EVENT
+VIDIOC_UNSUBSCRIBE_EVENT
+
+	The events ioctls are identical to the ones defined in V4L2. They
+	behave identically, with the only exception that they deal only with
+	events generated by the sub-device. Depending on the driver, those
+	events can also be reported by one (or several) V4L2 device nodes.
+
+	Sub-device drivers that want to use events need to set the
+	V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
+	v4l2_subdev::nevents to events queue depth before registering the
+	sub-device. After registration events can be queued as usual on the
+	v4l2_subdev::devnode device node.
+
+	To properly support events, the poll() file operation is also
+	implemented.
+
+Private ioctls
+
+	All ioctls not in the above list are passed directly to the sub-device
+	driver through the core::ioctl operation.
+
+
+I2C sub-device drivers
+----------------------
+
+Since these drivers are so common, special helper functions are available to
+ease the use of these drivers (v4l2-common.h).
+
+The recommended method of adding v4l2_subdev support to an I2C driver is to
+embed the v4l2_subdev struct into the state struct that is created for each
+I2C device instance. Very simple devices have no state struct and in that case
+you can just create a v4l2_subdev directly.
+
+A typical state struct would look like this (where 'chipname' is replaced by
+the name of the chip):
+
+.. code-block:: none
+
+	struct chipname_state {
+		struct v4l2_subdev sd;
+		...  /* additional state fields */
+	};
+
+Initialize the v4l2_subdev struct as follows:
+
+.. code-block:: none
+
+	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
+
+This function will fill in all the fields of v4l2_subdev and ensure that the
+v4l2_subdev and i2c_client both point to one another.
+
+You should also add a helper inline function to go from a v4l2_subdev pointer
+to a chipname_state struct:
+
+.. code-block:: none
+
+	static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
+	{
+		return container_of(sd, struct chipname_state, sd);
+	}
+
+Use this to go from the v4l2_subdev struct to the i2c_client struct:
+
+.. code-block:: none
+
+	struct i2c_client *client = v4l2_get_subdevdata(sd);
+
+And this to go from an i2c_client to a v4l2_subdev struct:
+
+.. code-block:: none
+
+	struct v4l2_subdev *sd = i2c_get_clientdata(client);
+
+Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
+is called. This will unregister the sub-device from the bridge driver. It is
+safe to call this even if the sub-device was never registered.
+
+You need to do this because when the bridge driver destroys the i2c adapter
+the remove() callbacks are called of the i2c devices on that adapter.
+After that the corresponding v4l2_subdev structures are invalid, so they
+have to be unregistered first. Calling v4l2_device_unregister_subdev(sd)
+from the remove() callback ensures that this is always done correctly.
+
+
+The bridge driver also has some helper functions it can use:
+
+.. code-block:: none
+
+	struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
+					"module_foo", "chipid", 0x36, NULL);
+
+This loads the given module (can be NULL if no module needs to be loaded) and
+calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
+If all goes well, then it registers the subdev with the v4l2_device.
+
+You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
+of possible I2C addresses that it should probe. These probe addresses are
+only used if the previous argument is 0. A non-zero argument means that you
+know the exact i2c address so in that case no probing will take place.
+
+Both functions return NULL if something went wrong.
+
+Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
+the same as the module name. It allows you to specify a chip variant, e.g.
+"saa7114" or "saa7115". In general though the i2c driver autodetects this.
+The use of chipid is something that needs to be looked at more closely at a
+later date. It differs between i2c drivers and as such can be confusing.
+To see which chip variants are supported you can look in the i2c driver code
+for the i2c_device_id table. This lists all the possibilities.
+
+There are two more helper functions:
+
+v4l2_i2c_new_subdev_cfg: this function adds new irq and platform_data
+arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not
+0 then that will be used (non-probing variant), otherwise the probed_addrs
+are probed.
+
+For example: this will probe for address 0x10:
+
+.. code-block:: none
+
+	struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
+			  "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
+
+v4l2_i2c_new_subdev_board uses an i2c_board_info struct which is passed
+to the i2c driver and replaces the irq, platform_data and addr arguments.
+
+If the subdev supports the s_config core ops, then that op is called with
+the irq and platform_data arguments after the subdev was setup. The older
+v4l2_i2c_new_(probed\_)subdev functions will call s_config as well, but with
+irq set to 0 and platform_data set to NULL.
+
 V4L2 subdev kAPI
 ^^^^^^^^^^^^^^^^
 
-- 
2.7.4

[PATCH 11/12] [media] v4l2-subdev.rst: add cross references to new sections

[Mauro Carvalho Chehab]

The two new sections were missing cross-references, and had
some other minor issues with the markups. Add such things.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-subdev.rst | 152 +++++++++++++++++--------------
 1 file changed, 82 insertions(+), 70 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 2845a749409c..80982a9d002f 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -265,27 +265,28 @@ called. All three callbacks are optional.
 V4L2 sub-device userspace API
 -----------------------------
 
-Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
-sub-devices can also be controlled directly by userspace applications.
+Beside exposing a kernel API through the :c:type:`v4l2_subdev_ops` structure,
+V4L2 sub-devices can also be controlled directly by userspace applications.
 
-Device nodes named v4l-subdevX can be created in /dev to access sub-devices
-directly. If a sub-device supports direct userspace configuration it must set
-the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
+Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
+sub-devices directly. If a sub-device supports direct userspace configuration
+it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered.
 
-After registering sub-devices, the v4l2_device driver can create device nodes
-for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
-v4l2_device_register_subdev_nodes(). Those device nodes will be automatically
-removed when sub-devices are unregistered.
+After registering sub-devices, the :c:type:`v4l2_device` driver can create
+device nodes for all registered sub-devices marked with
+``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling
+:cpp:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be
+automatically removed when sub-devices are unregistered.
 
 The device node handles a subset of the V4L2 API.
 
-VIDIOC_QUERYCTRL
-VIDIOC_QUERYMENU
-VIDIOC_G_CTRL
-VIDIOC_S_CTRL
-VIDIOC_G_EXT_CTRLS
-VIDIOC_S_EXT_CTRLS
-VIDIOC_TRY_EXT_CTRLS
+``VIDIOC_QUERYCTRL``,
+``VIDIOC_QUERYMENU``,
+``VIDIOC_G_CTRL``,
+``VIDIOC_S_CTRL``,
+``VIDIOC_G_EXT_CTRLS``,
+``VIDIOC_S_EXT_CTRLS`` and
+``VIDIOC_TRY_EXT_CTRLS``:
 
 	The controls ioctls are identical to the ones defined in V4L2. They
 	behave identically, with the only exception that they deal only with
@@ -293,9 +294,9 @@ VIDIOC_TRY_EXT_CTRLS
 	controls can be also be accessed through one (or several) V4L2 device
 	nodes.
 
-VIDIOC_DQEVENT
-VIDIOC_SUBSCRIBE_EVENT
-VIDIOC_UNSUBSCRIBE_EVENT
+``VIDIOC_DQEVENT``,
+``VIDIOC_SUBSCRIBE_EVENT`` and
+``VIDIOC_UNSUBSCRIBE_EVENT``
 
 	The events ioctls are identical to the ones defined in V4L2. They
 	behave identically, with the only exception that they deal only with
@@ -303,12 +304,12 @@ VIDIOC_UNSUBSCRIBE_EVENT
 	events can also be reported by one (or several) V4L2 device nodes.
 
 	Sub-device drivers that want to use events need to set the
-	V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
-	v4l2_subdev::nevents to events queue depth before registering the
-	sub-device. After registration events can be queued as usual on the
-	v4l2_subdev::devnode device node.
+	``V4L2_SUBDEV_USES_EVENTS`` :c:type:`v4l2_subdev`.flags and initialize
+	:c:type:`v4l2_subdev`.nevents to events queue depth before registering
+	the sub-device. After registration events can be queued as usual on the
+	:c:type:`v4l2_subdev`.devnode device node.
 
-	To properly support events, the poll() file operation is also
+	To properly support events, the ``poll()`` file operation is also
 	implemented.
 
 Private ioctls
@@ -321,84 +322,89 @@ I2C sub-device drivers
 ----------------------
 
 Since these drivers are so common, special helper functions are available to
-ease the use of these drivers (v4l2-common.h).
+ease the use of these drivers (``v4l2-common.h``).
 
-The recommended method of adding v4l2_subdev support to an I2C driver is to
-embed the v4l2_subdev struct into the state struct that is created for each
-I2C device instance. Very simple devices have no state struct and in that case
-you can just create a v4l2_subdev directly.
+The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver
+is to embed the :c:type:`v4l2_subdev` struct into the state struct that is
+created for each I2C device instance. Very simple devices have no state
+struct and in that case you can just create a :c:type:`v4l2_subdev` directly.
 
 A typical state struct would look like this (where 'chipname' is replaced by
 the name of the chip):
 
-.. code-block:: none
+.. code-block:: c
 
 	struct chipname_state {
 		struct v4l2_subdev sd;
 		...  /* additional state fields */
 	};
 
-Initialize the v4l2_subdev struct as follows:
+Initialize the :c:type:`v4l2_subdev` struct as follows:
 
-.. code-block:: none
+.. code-block:: c
 
 	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
 
-This function will fill in all the fields of v4l2_subdev and ensure that the
-v4l2_subdev and i2c_client both point to one another.
+This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that
+the :c:type:`v4l2_subdev` and i2c_client both point to one another.
 
-You should also add a helper inline function to go from a v4l2_subdev pointer
-to a chipname_state struct:
+You should also add a helper inline function to go from a :c:type:`v4l2_subdev`
+pointer to a chipname_state struct:
 
-.. code-block:: none
+.. code-block:: c
 
 	static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
 	{
 		return container_of(sd, struct chipname_state, sd);
 	}
 
-Use this to go from the v4l2_subdev struct to the i2c_client struct:
+Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client``
+struct:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 
-And this to go from an i2c_client to a v4l2_subdev struct:
+And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct v4l2_subdev *sd = i2c_get_clientdata(client);
 
-Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
-is called. This will unregister the sub-device from the bridge driver. It is
-safe to call this even if the sub-device was never registered.
+Make sure to call
+:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
+when the ``remove()`` callback is called. This will unregister the sub-device
+from the bridge driver. It is safe to call this even if the sub-device was
+never registered.
 
 You need to do this because when the bridge driver destroys the i2c adapter
-the remove() callbacks are called of the i2c devices on that adapter.
+the ``remove()`` callbacks are called of the i2c devices on that adapter.
 After that the corresponding v4l2_subdev structures are invalid, so they
-have to be unregistered first. Calling v4l2_device_unregister_subdev(sd)
-from the remove() callback ensures that this is always done correctly.
+have to be unregistered first. Calling
+:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
+from the ``remove()`` callback ensures that this is always done correctly.
 
 
 The bridge driver also has some helper functions it can use:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
 					"module_foo", "chipid", 0x36, NULL);
 
-This loads the given module (can be NULL if no module needs to be loaded) and
-calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
-If all goes well, then it registers the subdev with the v4l2_device.
+This loads the given module (can be ``NULL`` if no module needs to be loaded)
+and calls :cpp:func:`i2c_new_device` with the given ``i2c_adapter`` and
+chip/address arguments. If all goes well, then it registers the subdev with
+the v4l2_device.
 
-You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
-of possible I2C addresses that it should probe. These probe addresses are
-only used if the previous argument is 0. A non-zero argument means that you
+You can also use the last argument of :cpp:func:`v4l2_i2c_new_subdev` to pass
+an array of possible I2C addresses that it should probe. These probe addresses
+are only used if the previous argument is 0. A non-zero argument means that you
 know the exact i2c address so in that case no probing will take place.
 
-Both functions return NULL if something went wrong.
+Both functions return ``NULL`` if something went wrong.
 
-Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
+Note that the chipid you pass to :cpp:func:`v4l2_i2c_new_subdev` is usually
 the same as the module name. It allows you to specify a chip variant, e.g.
 "saa7114" or "saa7115". In general though the i2c driver autodetects this.
 The use of chipid is something that needs to be looked at more closely at a
@@ -408,32 +414,38 @@ for the i2c_device_id table. This lists all the possibilities.
 
 There are two more helper functions:
 
-v4l2_i2c_new_subdev_cfg: this function adds new irq and platform_data
-arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not
-0 then that will be used (non-probing variant), otherwise the probed_addrs
-are probed.
+:cpp:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and
+platform_data arguments and has both 'addr' and 'probed_addrs' arguments:
+if addr is not 0 then that will be used (non-probing variant), otherwise the
+probed_addrs are probed.
 
 For example: this will probe for address 0x10:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
 			  "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
 
-v4l2_i2c_new_subdev_board uses an i2c_board_info struct which is passed
-to the i2c driver and replaces the irq, platform_data and addr arguments.
+:cpp:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct
+which is passed to the i2c driver and replaces the irq, platform_data and addr
+arguments.
 
 If the subdev supports the s_config core ops, then that op is called with
-the irq and platform_data arguments after the subdev was setup. The older
-v4l2_i2c_new_(probed\_)subdev functions will call s_config as well, but with
-irq set to 0 and platform_data set to NULL.
+the irq and platform_data arguments after the subdev was setup.
 
-V4L2 subdev kAPI
-^^^^^^^^^^^^^^^^
+The older :cpp:func:`v4l2_i2c_new_subdev` and
+:cpp:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as
+well, but with irq set to 0 and platform_data set to ``NULL``.
+
+V4L2 sub-device functions and data structures
+---------------------------------------------
+
+V4L2 sub-device kAPI
+^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-subdev.h
 
-V4L2 subdev async kAPI
-^^^^^^^^^^^^^^^^^^^^^^
+V4L2 sub-device asynchronous kAPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-async.h
-- 
2.7.4

[PATCH 12/12] [media] v4l2-common.h: document the subdev functions

[Mauro Carvalho Chehab]

There are some subdev-specific functions at v4l2-common.h
that are mentioned at v4l2-subdev.rst.

Document them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-subdev.rst |  6 ++++
 include/media/v4l2-common.h              | 49 +++++++++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 7 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 80982a9d002f..456fdec69042 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -449,3 +449,9 @@ V4L2 sub-device asynchronous kAPI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-async.h
+
+
+V4L2 common kAPI
+^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-common.h
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 1cc0c5ba16b3..9b1dfcd9e229 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -80,8 +80,6 @@
 
 /* ------------------------------------------------------------------------- */
 
-/* Control helper function */
-
 int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def);
 
 /* ------------------------------------------------------------------------- */
@@ -96,23 +94,60 @@ struct v4l2_device;
 struct v4l2_subdev;
 struct v4l2_subdev_ops;
 
-
-/* Load an i2c module and return an initialized v4l2_subdev struct.
-   The client_type argument is the name of the chip that's on the adapter. */
+/**
+ * v4l2_i2c_new_subdev - Load an i2c module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @client_type:  name of the chip that's on the adapter.
+ * @addr: I2C address. If zero, it will use @probe_addrs
+ * @probe_addrs: array with a list of address. The last entry at such
+ * 	array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev,
 		struct i2c_adapter *adapter, const char *client_type,
 		u8 addr, const unsigned short *probe_addrs);
 
 struct i2c_board_info;
 
+/**
+ * v4l2_i2c_new_subdev_board - Load an i2c module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @info: pointer to struct i2c_board_info used to replace the irq,
+ *	 platform_data and addr arguments.
+ * @probe_addrs: array with a list of address. The last entry at such
+ * 	array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev,
 		struct i2c_adapter *adapter, struct i2c_board_info *info,
 		const unsigned short *probe_addrs);
 
-/* Initialize a v4l2_subdev with data from an i2c_client struct */
+/**
+ * v4l2_i2c_subdev_init - Initializes a &struct v4l2_subdev with data from
+ *	an i2c_client struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @client: pointer to struct i2c_client
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
 		const struct v4l2_subdev_ops *ops);
-/* Return i2c client address of v4l2_subdev. */
+
+/**
+ * v4l2_i2c_subdev_addr - returns i2c client address of &struct v4l2_subdev.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the address of an I2C sub-device
+ */
 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd);
 
 enum v4l2_i2c_tuner_type {
-- 
2.7.4