[PATCH 01/11] [media] v4l2-framework.rst: remove videobuf quick chapter

[PATCH 01/11] [media] v4l2-framework.rst: remove videobuf quick chapter

[Mauro Carvalho Chehab]

As we merged the videobuf chapter at the kABI section, and it
is a way more complete, just remove the small videobuf chapter
that came from framework.txt.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-framework.rst | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index c97ffd0d783b..9204d9329124 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,22 +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.
 
-
-
-video buffer helper functions
------------------------------
-
-The v4l2 core API provides a set of standard methods (called "videobuf")
-for dealing with video buffers. Those methods allow a driver to implement
-read(), mmap() and overlay() in a consistent way.  There are currently
-methods for using video buffers on devices that supports DMA with
-scatter/gather method (videobuf-dma-sg), DMA with linear access
-(videobuf-dma-contig), and vmalloced buffers, mostly used on USB drivers
-(videobuf-vmalloc).
-
-Please see Documentation/video4linux/videobuf for more information on how
-to use the videobuf layer.
-
 struct v4l2_fh
 --------------
 
-- 
2.7.4

[PATCH 02/11] [media] v4l2-event.rst: add text from v4l2-framework.rst

[Mauro Carvalho Chehab]

Move the v4l2 event-specific text from v4l2-framework.rst
to v4l2-event.rst. That helps to keep the text together with
the functions it describes, and makes easier to identify
documentation gaps.

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

diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst
index 6ac94efc07bf..567ff7b1a3c2 100644
--- a/Documentation/media/kapi/v4l2-event.rst
+++ b/Documentation/media/kapi/v4l2-event.rst
@@ -1,3 +1,110 @@
+
+V4L2 events
+-----------
+
+The V4L2 events provide a generic way to pass events to user space.
+The driver must use v4l2_fh to be able to support V4L2 events.
+
+Events are defined by a type and an optional ID. The ID may refer to a V4L2
+object such as a control ID. If unused, then the ID is 0.
+
+When the user subscribes to an event the driver will allocate a number of
+kevent structs for that event. So every (type, ID) event tuple will have
+its own set of kevent structs. This guarantees that if a driver is generating
+lots of events of one type in a short time, then that will not overwrite
+events of another type.
+
+But if you get more events of one type than the number of kevents that were
+reserved, then the oldest event will be dropped and the new one added.
+
+Furthermore, the internal struct v4l2_subscribed_event has merge() and
+replace() callbacks which drivers can set. These callbacks are called when
+a new event is raised and there is no more room. The replace() callback
+allows you to replace the payload of the old event with that of the new event,
+merging any relevant data from the old payload into the new payload that
+replaces it. It is called when this event type has only one kevent struct
+allocated. The merge() callback allows you to merge the oldest event payload
+into that of the second-oldest event payload. It is called when there are two
+or more kevent structs allocated.
+
+This way no status information is lost, just the intermediate steps leading
+up to that state.
+
+A good example of these replace/merge callbacks is in v4l2-event.c:
+ctrls_replace() and ctrls_merge() callbacks for the control event.
+
+Note: these callbacks can be called from interrupt context, so they must be
+fast.
+
+Useful functions:
+
+.. code-block:: none
+
+	void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
+
+  Queue events to video device. The driver's only responsibility is to fill
+  in the type and the data fields. The other fields will be filled in by
+  V4L2.
+
+.. code-block:: none
+
+	int v4l2_event_subscribe(struct v4l2_fh *fh,
+				 struct v4l2_event_subscription *sub, unsigned elems,
+				 const struct v4l2_subscribed_event_ops *ops)
+
+  The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
+  is able to produce events with specified event id. Then it calls
+  v4l2_event_subscribe() to subscribe the event.
+
+  The elems argument is the size of the event queue for this event. If it is 0,
+  then the framework will fill in a default value (this depends on the event
+  type).
+
+  The ops argument allows the driver to specify a number of callbacks:
+  * add:     called when a new listener gets added (subscribing to the same
+             event twice will only cause this callback to get called once)
+  * del:     called when a listener stops listening
+  * replace: replace event 'old' with event 'new'.
+  * merge:   merge event 'old' into event 'new'.
+  All 4 callbacks are optional, if you don't want to specify any callbacks
+  the ops argument itself maybe NULL.
+
+.. code-block:: none
+
+	int v4l2_event_unsubscribe(struct v4l2_fh *fh,
+				   struct v4l2_event_subscription *sub)
+
+  vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
+  v4l2_event_unsubscribe() directly unless it wants to be involved in
+  unsubscription process.
+
+  The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
+  drivers may want to handle this in a special way.
+
+.. code-block:: none
+
+	int v4l2_event_pending(struct v4l2_fh *fh)
+
+  Returns the number of pending events. Useful when implementing poll.
+
+Events are delivered to user space through the poll system call. The driver
+can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
+
+There are standard and private events. New standard events must use the
+smallest available event type. The drivers must allocate their events from
+their own class starting from class base. Class base is
+V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
+The first event type in the class is reserved for future use, so the first
+available event type is 'class base + 1'.
+
+An example on how the V4L2 events may be used can be found in the OMAP
+3 ISP driver (drivers/media/platform/omap3isp).
+
+A subdev can directly send an event to the v4l2_device notify function with
+V4L2_DEVICE_NOTIFY_EVENT. This allows the bridge to map the subdev that sends
+the event to the video node(s) associated with the subdev that need to be
+informed about such an event.
+
 V4L2 event kAPI
 ^^^^^^^^^^^^^^^
 
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index 9204d9329124..d46380ac7c1d 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -213,113 +213,6 @@ device node:
 
   Same, but it calls v4l2_fh_is_singular with filp->private_data.
 
-
-V4L2 events
------------
-
-The V4L2 events provide a generic way to pass events to user space.
-The driver must use v4l2_fh to be able to support V4L2 events.
-
-Events are defined by a type and an optional ID. The ID may refer to a V4L2
-object such as a control ID. If unused, then the ID is 0.
-
-When the user subscribes to an event the driver will allocate a number of
-kevent structs for that event. So every (type, ID) event tuple will have
-its own set of kevent structs. This guarantees that if a driver is generating
-lots of events of one type in a short time, then that will not overwrite
-events of another type.
-
-But if you get more events of one type than the number of kevents that were
-reserved, then the oldest event will be dropped and the new one added.
-
-Furthermore, the internal struct v4l2_subscribed_event has merge() and
-replace() callbacks which drivers can set. These callbacks are called when
-a new event is raised and there is no more room. The replace() callback
-allows you to replace the payload of the old event with that of the new event,
-merging any relevant data from the old payload into the new payload that
-replaces it. It is called when this event type has only one kevent struct
-allocated. The merge() callback allows you to merge the oldest event payload
-into that of the second-oldest event payload. It is called when there are two
-or more kevent structs allocated.
-
-This way no status information is lost, just the intermediate steps leading
-up to that state.
-
-A good example of these replace/merge callbacks is in v4l2-event.c:
-ctrls_replace() and ctrls_merge() callbacks for the control event.
-
-Note: these callbacks can be called from interrupt context, so they must be
-fast.
-
-Useful functions:
-
-.. code-block:: none
-
-	void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
-
-  Queue events to video device. The driver's only responsibility is to fill
-  in the type and the data fields. The other fields will be filled in by
-  V4L2.
-
-.. code-block:: none
-
-	int v4l2_event_subscribe(struct v4l2_fh *fh,
-				 struct v4l2_event_subscription *sub, unsigned elems,
-				 const struct v4l2_subscribed_event_ops *ops)
-
-  The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
-  is able to produce events with specified event id. Then it calls
-  v4l2_event_subscribe() to subscribe the event.
-
-  The elems argument is the size of the event queue for this event. If it is 0,
-  then the framework will fill in a default value (this depends on the event
-  type).
-
-  The ops argument allows the driver to specify a number of callbacks:
-  * add:     called when a new listener gets added (subscribing to the same
-             event twice will only cause this callback to get called once)
-  * del:     called when a listener stops listening
-  * replace: replace event 'old' with event 'new'.
-  * merge:   merge event 'old' into event 'new'.
-  All 4 callbacks are optional, if you don't want to specify any callbacks
-  the ops argument itself maybe NULL.
-
-.. code-block:: none
-
-	int v4l2_event_unsubscribe(struct v4l2_fh *fh,
-				   struct v4l2_event_subscription *sub)
-
-  vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
-  v4l2_event_unsubscribe() directly unless it wants to be involved in
-  unsubscription process.
-
-  The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
-  drivers may want to handle this in a special way.
-
-.. code-block:: none
-
-	int v4l2_event_pending(struct v4l2_fh *fh)
-
-  Returns the number of pending events. Useful when implementing poll.
-
-Events are delivered to user space through the poll system call. The driver
-can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
-
-There are standard and private events. New standard events must use the
-smallest available event type. The drivers must allocate their events from
-their own class starting from class base. Class base is
-V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
-The first event type in the class is reserved for future use, so the first
-available event type is 'class base + 1'.
-
-An example on how the V4L2 events may be used can be found in the OMAP
-3 ISP driver (drivers/media/platform/omap3isp).
-
-A subdev can directly send an event to the v4l2_device notify function with
-V4L2_DEVICE_NOTIFY_EVENT. This allows the bridge to map the subdev that sends
-the event to the video node(s) associated with the subdev that need to be
-informed about such an event.
-
 V4L2 clocks
 -----------
 
-- 
2.7.4

[PATCH 03/11] [media] v4l2-event.h: document all functions

[Mauro Carvalho Chehab]

Several functions weren't documented. Document them all.

While here, makes checkpatch.pl happy.

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

diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 9792f906423b..ca854203b8b9 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -73,14 +73,15 @@ struct video_device;
  * @list:	List node for the v4l2_fh->available list.
  * @sev:	Pointer to parent v4l2_subscribed_event.
  * @event:	The event itself.
-  */
+ */
 struct v4l2_kevent {
 	struct list_head	list;
 	struct v4l2_subscribed_event *sev;
 	struct v4l2_event	event;
 };
 
-/** struct v4l2_subscribed_event_ops - Subscribed event operations.
+/**
+ * struct v4l2_subscribed_event_ops - Subscribed event operations.
  *
  * @add:	Optional callback, called when a new listener is added
  * @del:	Optional callback, called when a listener stops listening
@@ -88,20 +89,23 @@ struct v4l2_kevent {
  * @merge:	Optional callback that can merge event 'old' into event 'new'.
  */
 struct v4l2_subscribed_event_ops {
-	int  (*add)(struct v4l2_subscribed_event *sev, unsigned elems);
+	int  (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
 	void (*del)(struct v4l2_subscribed_event *sev);
 	void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
 	void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
 };
 
 /**
- * struct v4l2_subscribed_event - Internal struct representing a subscribed event.
+ * struct v4l2_subscribed_event - Internal struct representing a subscribed
+ *		event.
+ *
  * @list:	List node for the v4l2_fh->subscribed list.
  * @type:	Event type.
  * @id:	Associated object ID (e.g. control ID). 0 if there isn't any.
  * @flags:	Copy of v4l2_event_subscription->flags.
  * @fh:	Filehandle that subscribed to this event.
- * @node:	List node that hooks into the object's event list (if there is one).
+ * @node:	List node that hooks into the object's event list
+ *		(if there is one).
  * @ops:	v4l2_subscribed_event_ops
  * @elems:	The number of elements in the events array.
  * @first:	The index of the events containing the oldest available event.
@@ -116,27 +120,124 @@ struct v4l2_subscribed_event {
 	struct v4l2_fh		*fh;
 	struct list_head	node;
 	const struct v4l2_subscribed_event_ops *ops;
-	unsigned		elems;
-	unsigned		first;
-	unsigned		in_use;
+	unsigned int		elems;
+	unsigned int		first;
+	unsigned int		in_use;
 	struct v4l2_kevent	events[];
 };
 
+/**
+ * v4l2_event_dequeue - Dequeue events from video device.
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @event: pointer to struct v4l2_event
+ * @nonblocking: if not zero, waits for an event to arrive
+ */
 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
 		       int nonblocking);
+
+/**
+ * v4l2_event_queue - Queue events to video device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @ev: pointer to &struct v4l2_event
+ *
+ * The event will be queued for all &struct v4l2_fh file handlers.
+ *
+ * .. note::
+ *    The driver's only responsibility is to fill in the type and the data
+ *    fields.The other fields will be filled in by  V4L2.
+ */
 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_queue_fh - Queue events to video device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @ev: pointer to &struct v4l2_event
+ *
+ *
+ * The event will be queued only for the specified &struct v4l2_fh file handler.
+ *
+ * .. note::
+ *    The driver's only responsibility is to fill in the type and the data
+ *    fields.The other fields will be filled in by  V4L2.
+ */
 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_pending - Check if an event is available
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Returns the number of pending events.
+ */
 int v4l2_event_pending(struct v4l2_fh *fh);
+
+/**
+ * v4l2_event_subscribe - Subscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ * @elems: size of the events queue
+ * @ops: pointer to &v4l2_subscribed_event_ops
+ *
+ * .. note::
+ *
+ *    if @elems is zero, the framework will fill in a default value,
+ *    with is currently 1 element.
+ */
 int v4l2_event_subscribe(struct v4l2_fh *fh,
-			 const struct v4l2_event_subscription *sub, unsigned elems,
+			 const struct v4l2_event_subscription *sub,
+			 unsigned int elems,
 			 const struct v4l2_subscribed_event_ops *ops);
+/**
+ * v4l2_event_unsubscribe - Unsubscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_event_unsubscribe(struct v4l2_fh *fh,
 			   const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_event_unsubscribe_all - Unsubscribes to all events
+ *
+ * @fh: pointer to &struct v4l2_fh
+ */
 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
-int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh,
+
+/**
+ * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ *
+ * .. note::
+ *
+ *	This function should be used for the &struct v4l2_subdev_core_ops
+ *	%unsubscribe_event field.
+ */
+int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
+				  struct v4l2_fh *fh,
 				  struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subscribe -
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
-				const struct v4l2_event_subscription *sub);
+				    const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
+ *	meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
-		struct v4l2_fh *fh, struct v4l2_event_subscription *sub);
+					   struct v4l2_fh *fh,
+					   struct v4l2_event_subscription *sub);
 #endif /* V4L2_EVENT_H */
-- 
2.7.4

[PATCH 04/11] [media] v4l2-event.rst: add cross-references and markups

[Mauro Carvalho Chehab]

Improve events documentation by adding cross references,
sub-titles and other markup elements.

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

diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst
index 567ff7b1a3c2..0aed99459732 100644
--- a/Documentation/media/kapi/v4l2-event.rst
+++ b/Documentation/media/kapi/v4l2-event.rst
@@ -3,7 +3,7 @@ V4L2 events
 -----------
 
 The V4L2 events provide a generic way to pass events to user space.
-The driver must use v4l2_fh to be able to support V4L2 events.
+The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events.
 
 Events are defined by a type and an optional ID. The ID may refer to a V4L2
 object such as a control ID. If unused, then the ID is 0.
@@ -17,93 +17,118 @@ events of another type.
 But if you get more events of one type than the number of kevents that were
 reserved, then the oldest event will be dropped and the new one added.
 
-Furthermore, the internal struct v4l2_subscribed_event has merge() and
-replace() callbacks which drivers can set. These callbacks are called when
-a new event is raised and there is no more room. The replace() callback
-allows you to replace the payload of the old event with that of the new event,
-merging any relevant data from the old payload into the new payload that
-replaces it. It is called when this event type has only one kevent struct
-allocated. The merge() callback allows you to merge the oldest event payload
-into that of the second-oldest event payload. It is called when there are two
-or more kevent structs allocated.
+Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
+``merge()`` and ``replace()`` callbacks which drivers can set. These
+callbacks are called when a new event is raised and there is no more room.
+The ``replace()`` callback allows you to replace the payload of the old event
+with that of the new event, merging any relevant data from the old payload
+into the new payload that replaces it. It is called when this event type has
+only one kevent struct allocated. The ``merge()`` callback allows you to merge
+the oldest event payload into that of the second-oldest event payload. It is
+called when there are two or more kevent structs allocated.
 
 This way no status information is lost, just the intermediate steps leading
 up to that state.
 
-A good example of these replace/merge callbacks is in v4l2-event.c:
-ctrls_replace() and ctrls_merge() callbacks for the control event.
+A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c:
+``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event.
 
-Note: these callbacks can be called from interrupt context, so they must be
-fast.
+.. note::
+	these callbacks can be called from interrupt context, so they must
+	be fast.
 
-Useful functions:
+In order to queue events to video device, drivers should call:
 
-.. code-block:: none
+	:cpp:func:`v4l2_event_queue <v4l2_event_queue>`
+	(:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`)
 
-	void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
+The driver's only responsibility is to fill in the type and the data fields.
+The other fields will be filled in by V4L2.
 
-  Queue events to video device. The driver's only responsibility is to fill
-  in the type and the data fields. The other fields will be filled in by
-  V4L2.
+Event subscription
+~~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+Subscribing to an event is via:
 
-	int v4l2_event_subscribe(struct v4l2_fh *fh,
-				 struct v4l2_event_subscription *sub, unsigned elems,
-				 const struct v4l2_subscribed_event_ops *ops)
+	:cpp:func:`v4l2_event_subscribe <v4l2_event_subscribe>`
+	(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` ,
+	elems, :c:type:`ops <v4l2_subscribed_event_ops>`)
 
-  The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
-  is able to produce events with specified event id. Then it calls
-  v4l2_event_subscribe() to subscribe the event.
 
-  The elems argument is the size of the event queue for this event. If it is 0,
-  then the framework will fill in a default value (this depends on the event
-  type).
+This function is used to implement :c:type:`video_device`->
+:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``,
+but the driver must check first if the driver is able to produce events
+with specified event id, and then should call
+:cpp:func:`v4l2_event_subscribe` to subscribe the event.
 
-  The ops argument allows the driver to specify a number of callbacks:
-  * add:     called when a new listener gets added (subscribing to the same
-             event twice will only cause this callback to get called once)
-  * del:     called when a listener stops listening
-  * replace: replace event 'old' with event 'new'.
-  * merge:   merge event 'old' into event 'new'.
-  All 4 callbacks are optional, if you don't want to specify any callbacks
-  the ops argument itself maybe NULL.
+The elems argument is the size of the event queue for this event. If it is 0,
+then the framework will fill in a default value (this depends on the event
+type).
 
-.. code-block:: none
+The ops argument allows the driver to specify a number of callbacks:
 
-	int v4l2_event_unsubscribe(struct v4l2_fh *fh,
-				   struct v4l2_event_subscription *sub)
+======== ==============================================================
+Callback Description
+======== ==============================================================
+add      called when a new listener gets added (subscribing to the same
+         event twice will only cause this callback to get called once)
+del      called when a listener stops listening
+replace  replace event 'old' with event 'new'.
+merge    merge event 'old' into event 'new'.
+======== ==============================================================
 
-  vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
-  v4l2_event_unsubscribe() directly unless it wants to be involved in
-  unsubscription process.
+All 4 callbacks are optional, if you don't want to specify any callbacks
+the ops argument itself maybe ``NULL``.
 
-  The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
-  drivers may want to handle this in a special way.
+Unsubscribing an event
+~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+Unsubscribing to an event is via:
 
-	int v4l2_event_pending(struct v4l2_fh *fh)
+	:cpp:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>`
+	(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`)
 
-  Returns the number of pending events. Useful when implementing poll.
+This function is used to implement :c:type:`video_device`->
+:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``.
+A driver may call :cpp:func:`v4l2_event_unsubscribe` directly unless it
+wants to be involved in unsubscription process.
+
+The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The
+drivers may want to handle this in a special way.
+
+Check if there's a pending event
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Checking if there's a pending event is via:
+
+	:cpp:func:`v4l2_event_pending <v4l2_event_pending>`
+	(:c:type:`fh <v4l2_fh>`)
+
+
+This function returns the number of pending events. Useful when implementing
+poll.
+
+How events work
+~~~~~~~~~~~~~~~
 
 Events are delivered to user space through the poll system call. The driver
-can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
+can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for
+``poll_wait()``.
 
 There are standard and private events. New standard events must use the
 smallest available event type. The drivers must allocate their events from
 their own class starting from class base. Class base is
-V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
+``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number.
 The first event type in the class is reserved for future use, so the first
 available event type is 'class base + 1'.
 
 An example on how the V4L2 events may be used can be found in the OMAP
-3 ISP driver (drivers/media/platform/omap3isp).
+3 ISP driver (``drivers/media/platform/omap3isp``).
 
-A subdev can directly send an event to the v4l2_device notify function with
-V4L2_DEVICE_NOTIFY_EVENT. This allows the bridge to map the subdev that sends
-the event to the video node(s) associated with the subdev that need to be
-informed about such an event.
+A subdev can directly send an event to the :c:type:`v4l2_device` notify
+function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map
+the subdev that sends the event to the video node(s) associated with the
+subdev that need to be informed about such an event.
 
 V4L2 event kAPI
 ^^^^^^^^^^^^^^^
-- 
2.7.4

[PATCH 05/11] [media] v4l2-fh.h: add documentation for it

[Mauro Carvalho Chehab]

This header file was undocumented. Add documentation for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-core.rst |   1 +
 Documentation/media/kapi/v4l2-fh.rst   |   3 +
 include/media/v4l2-fh.h                | 128 ++++++++++++++++++++++++---------
 3 files changed, 100 insertions(+), 32 deletions(-)
 create mode 100644 Documentation/media/kapi/v4l2-fh.rst

diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index 6fa30f8908dd..67eaf0c0b6b6 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -8,6 +8,7 @@ Video2Linux devices
     v4l2-dev
     v4l2-controls
     v4l2-device
+    v4l2-fh
     v4l2-dv-timings
     v4l2-event
     v4l2-flash-led-class
diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst
new file mode 100644
index 000000000000..9309c18e967a
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-fh.rst
@@ -0,0 +1,3 @@
+V4L2 File Handler kAPI
+^^^^^^^^^^^^^^^^^^^^^^
+.. kernel-doc:: include/media/v4l2-fh.h
diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h
index 803516775162..e19e6246e21c 100644
--- a/include/media/v4l2-fh.h
+++ b/include/media/v4l2-fh.h
@@ -33,6 +33,21 @@
 struct video_device;
 struct v4l2_ctrl_handler;
 
+/**
+ * struct v4l2_fh - Describes a V4L2 file handler
+ *
+ * @list: list of file handlers
+ * @vdev: pointer to &struct video_device
+ * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
+ * @prio: priority of the file handler, as defined by &enum v4l2_priority
+ *
+ * @wait: event' s wait queue
+ * @subscribed: list of subscribed events
+ * @available: list of events waiting to be dequeued
+ * @navailable: number of available events at @available list
+ * @sequence: event sequence number
+ * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
+ */
 struct v4l2_fh {
 	struct list_head	list;
 	struct video_device	*vdev;
@@ -41,8 +56,8 @@ struct v4l2_fh {
 
 	/* Events */
 	wait_queue_head_t	wait;
-	struct list_head	subscribed; /* Subscribed events */
-	struct list_head	available; /* Dequeueable event */
+	struct list_head	subscribed;
+	struct list_head	available;
 	unsigned int		navailable;
 	u32			sequence;
 
@@ -51,53 +66,102 @@ struct v4l2_fh {
 #endif
 };
 
-/*
- * Initialise the file handle. Parts of the V4L2 framework using the
+/**
+ * v4l2_fh_init - Initialise the file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @vdev: pointer to &struct video_device
+ *
+ * Parts of the V4L2 framework using the
  * file handles should be initialised in this function. Must be called
- * from driver's v4l2_file_operations->open() handler if the driver
- * uses v4l2_fh.
+ * from driver's v4l2_file_operations->open\(\) handler if the driver
+ * uses &struct v4l2_fh.
  */
 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
-/*
- * Add the fh to the list of file handles on a video_device. The file
- * handle must be initialised first.
+
+/**
+ * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * .. note::
+ *    The @fh file handle must be initialised first.
  */
 void v4l2_fh_add(struct v4l2_fh *fh);
-/*
- * Can be used as the open() op of v4l2_file_operations.
- * It allocates a v4l2_fh and inits and adds it to the video_device associated
- * with the file pointer.
+
+/**
+ * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
+ *	of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
+ * It allocates a v4l2_fh and inits and adds it to the &struct video_device
+ * associated with the file pointer.
  */
 int v4l2_fh_open(struct file *filp);
-/*
- * Remove file handle from the list of file handles. Must be called in
- * v4l2_file_operations->release() handler if the driver uses v4l2_fh.
- * On error filp->private_data will be NULL, otherwise it will point to
- * the v4l2_fh struct.
+
+/**
+ * v4l2_fh_del - Remove file handle from the list of file handles.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * On error filp->private_data will be %NULL, otherwise it will point to
+ * the &struct v4l2_fh.
+ *
+ * .. note::
+ *    Must be called in v4l2_file_operations->release\(\) handler if the driver
+ *    uses &struct v4l2_fh.
  */
 void v4l2_fh_del(struct v4l2_fh *fh);
-/*
- * Release resources related to a file handle. Parts of the V4L2
- * framework using the v4l2_fh must release their resources here, too.
- * Must be called in v4l2_file_operations->release() handler if the
- * driver uses v4l2_fh.
+
+/**
+ * v4l2_fh_exit - Release resources related to a file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Parts of the V4L2 framework using the v4l2_fh must release their
+ * resources here, too.
+ *
+ * .. note::
+ *    Must be called in v4l2_file_operations->release\(\) handler if the
+ *    driver uses &struct v4l2_fh.
  */
 void v4l2_fh_exit(struct v4l2_fh *fh);
-/*
- * Can be used as the release() op of v4l2_file_operations.
+
+/**
+ * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
+ *	of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
  * It deletes and exits the v4l2_fh associated with the file pointer and
  * frees it. It will do nothing if filp->private_data (the pointer to the
- * v4l2_fh struct) is NULL. This function always returns 0.
+ * v4l2_fh struct) is %NULL.
+ *
+ * This function always returns 0.
  */
 int v4l2_fh_release(struct file *filp);
-/*
- * Returns 1 if this filehandle is the only filehandle opened for the
- * associated video_device. If fh is NULL, then it returns 0.
+
+/**
+ * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
+ *	 opened for the associated video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * If @fh is NULL, then it returns 0.
  */
 int v4l2_fh_is_singular(struct v4l2_fh *fh);
-/*
- * Helper function with struct file as argument. If filp->private_data is
- * NULL, then it will return 0.
+
+/**
+ * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
+ *	filehandle opened for the associated video_device.
+ *
+ * @filp: pointer to struct file
+ *
+ * This is a helper function variant of v4l2_fh_is_singular() with uses
+ * struct file as argument.
+ *
+ * If filp->private_data is %NULL, then it will return 0.
  */
 static inline int v4l2_fh_is_singular_file(struct file *filp)
 {
-- 
2.7.4

[PATCH 06/11] [media] v4l2-fh.rst: add fh contents from v4l2-framework.rst

[Mauro Carvalho Chehab]

Move the v4l2_fh specific content from v4l2-framework.rst
to v4l2-fh.rst.

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

diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst
index 9309c18e967a..f39374262d3f 100644
--- a/Documentation/media/kapi/v4l2-fh.rst
+++ b/Documentation/media/kapi/v4l2-fh.rst
@@ -1,3 +1,137 @@
+V4L2 File handlers
+------------------
+
+struct v4l2_fh provides a way to easily keep file handle specific data
+that is used by the V4L2 framework. New drivers must use struct v4l2_fh
+since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY).
+
+The users of v4l2_fh (in the V4L2 framework, not the driver) know
+whether a driver uses v4l2_fh as its file->private_data pointer by
+testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
+set whenever v4l2_fh_init() is called.
+
+struct v4l2_fh is allocated as a part of the driver's own file handle
+structure and file->private_data is set to it in the driver's open
+function by the driver.
+
+In many cases the struct v4l2_fh will be embedded in a larger structure.
+In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
+v4l2_fh_del+v4l2_fh_exit in release().
+
+Drivers can extract their own file handle structure by using the container_of
+macro. Example:
+
+.. code-block:: none
+
+	struct my_fh {
+		int blah;
+		struct v4l2_fh fh;
+	};
+
+	...
+
+	int my_open(struct file *file)
+	{
+		struct my_fh *my_fh;
+		struct video_device *vfd;
+		int ret;
+
+		...
+
+		my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+
+		...
+
+		v4l2_fh_init(&my_fh->fh, vfd);
+
+		...
+
+		file->private_data = &my_fh->fh;
+		v4l2_fh_add(&my_fh->fh);
+		return 0;
+	}
+
+	int my_release(struct file *file)
+	{
+		struct v4l2_fh *fh = file->private_data;
+		struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
+
+		...
+		v4l2_fh_del(&my_fh->fh);
+		v4l2_fh_exit(&my_fh->fh);
+		kfree(my_fh);
+		return 0;
+	}
+
+Below is a short description of the v4l2_fh functions used:
+
+.. code-block:: none
+
+	void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
+
+  Initialise the file handle. This *MUST* be performed in the driver's
+  v4l2_file_operations->open() handler.
+
+.. code-block:: none
+
+	void v4l2_fh_add(struct v4l2_fh *fh)
+
+  Add a v4l2_fh to video_device file handle list. Must be called once the
+  file handle is completely initialized.
+
+.. code-block:: none
+
+	void v4l2_fh_del(struct v4l2_fh *fh)
+
+  Unassociate the file handle from video_device(). The file handle
+  exit function may now be called.
+
+.. code-block:: none
+
+	void v4l2_fh_exit(struct v4l2_fh *fh)
+
+  Uninitialise the file handle. After uninitialisation the v4l2_fh
+  memory can be freed.
+
+
+If struct v4l2_fh is not embedded, then you can use these helper functions:
+
+.. code-block:: none
+
+	int v4l2_fh_open(struct file *filp)
+
+  This allocates a struct v4l2_fh, initializes it and adds it to the struct
+  video_device associated with the file struct.
+
+.. code-block:: none
+
+	int v4l2_fh_release(struct file *filp)
+
+  This deletes it from the struct video_device associated with the file
+  struct, uninitialised the v4l2_fh and frees it.
+
+These two functions can be plugged into the v4l2_file_operation's open() and
+release() ops.
+
+
+Several drivers need to do something when the first file handle is opened and
+when the last file handle closes. Two helper functions were added to check
+whether the v4l2_fh struct is the only open filehandle of the associated
+device node:
+
+.. code-block:: none
+
+	int v4l2_fh_is_singular(struct v4l2_fh *fh)
+
+  Returns 1 if the file handle is the only open file handle, else 0.
+
+.. code-block:: none
+
+	int v4l2_fh_is_singular_file(struct file *filp)
+
+  Same, but it calls v4l2_fh_is_singular with filp->private_data.
+
+
 V4L2 File Handler kAPI
 ^^^^^^^^^^^^^^^^^^^^^^
 .. kernel-doc:: include/media/v4l2-fh.h
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index d46380ac7c1d..8b4f684e1a7a 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -80,139 +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_fh
---------------
-
-struct v4l2_fh provides a way to easily keep file handle specific data
-that is used by the V4L2 framework. New drivers must use struct v4l2_fh
-since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY).
-
-The users of v4l2_fh (in the V4L2 framework, not the driver) know
-whether a driver uses v4l2_fh as its file->private_data pointer by
-testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
-set whenever v4l2_fh_init() is called.
-
-struct v4l2_fh is allocated as a part of the driver's own file handle
-structure and file->private_data is set to it in the driver's open
-function by the driver.
-
-In many cases the struct v4l2_fh will be embedded in a larger structure.
-In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
-v4l2_fh_del+v4l2_fh_exit in release().
-
-Drivers can extract their own file handle structure by using the container_of
-macro. Example:
-
-.. code-block:: none
-
-	struct my_fh {
-		int blah;
-		struct v4l2_fh fh;
-	};
-
-	...
-
-	int my_open(struct file *file)
-	{
-		struct my_fh *my_fh;
-		struct video_device *vfd;
-		int ret;
-
-		...
-
-		my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
-
-		...
-
-		v4l2_fh_init(&my_fh->fh, vfd);
-
-		...
-
-		file->private_data = &my_fh->fh;
-		v4l2_fh_add(&my_fh->fh);
-		return 0;
-	}
-
-	int my_release(struct file *file)
-	{
-		struct v4l2_fh *fh = file->private_data;
-		struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
-
-		...
-		v4l2_fh_del(&my_fh->fh);
-		v4l2_fh_exit(&my_fh->fh);
-		kfree(my_fh);
-		return 0;
-	}
-
-Below is a short description of the v4l2_fh functions used:
-
-.. code-block:: none
-
-	void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
-
-  Initialise the file handle. This *MUST* be performed in the driver's
-  v4l2_file_operations->open() handler.
-
-.. code-block:: none
-
-	void v4l2_fh_add(struct v4l2_fh *fh)
-
-  Add a v4l2_fh to video_device file handle list. Must be called once the
-  file handle is completely initialized.
-
-.. code-block:: none
-
-	void v4l2_fh_del(struct v4l2_fh *fh)
-
-  Unassociate the file handle from video_device(). The file handle
-  exit function may now be called.
-
-.. code-block:: none
-
-	void v4l2_fh_exit(struct v4l2_fh *fh)
-
-  Uninitialise the file handle. After uninitialisation the v4l2_fh
-  memory can be freed.
-
-
-If struct v4l2_fh is not embedded, then you can use these helper functions:
-
-.. code-block:: none
-
-	int v4l2_fh_open(struct file *filp)
-
-  This allocates a struct v4l2_fh, initializes it and adds it to the struct
-  video_device associated with the file struct.
-
-.. code-block:: none
-
-	int v4l2_fh_release(struct file *filp)
-
-  This deletes it from the struct video_device associated with the file
-  struct, uninitialised the v4l2_fh and frees it.
-
-These two functions can be plugged into the v4l2_file_operation's open() and
-release() ops.
-
-
-Several drivers need to do something when the first file handle is opened and
-when the last file handle closes. Two helper functions were added to check
-whether the v4l2_fh struct is the only open filehandle of the associated
-device node:
-
-.. code-block:: none
-
-	int v4l2_fh_is_singular(struct v4l2_fh *fh)
-
-  Returns 1 if the file handle is the only open file handle, else 0.
-
-.. code-block:: none
-
-	int v4l2_fh_is_singular_file(struct file *filp)
-
-  Same, but it calls v4l2_fh_is_singular with filp->private_data.
-
 V4L2 clocks
 -----------
 
-- 
2.7.4

[PATCH 07/11] [media] v4l2-fh.rst: add cross references and markups

[Mauro Carvalho Chehab]

Add cross-references with the kernel-doc functions/structs
and improve the markups.

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

diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst
index f39374262d3f..a212698d5725 100644
--- a/Documentation/media/kapi/v4l2-fh.rst
+++ b/Documentation/media/kapi/v4l2-fh.rst
@@ -1,27 +1,35 @@
 V4L2 File handlers
 ------------------
 
-struct v4l2_fh provides a way to easily keep file handle specific data
-that is used by the V4L2 framework. New drivers must use struct v4l2_fh
-since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY).
+struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
+data that is used by the V4L2 framework.
 
-The users of v4l2_fh (in the V4L2 framework, not the driver) know
-whether a driver uses v4l2_fh as its file->private_data pointer by
-testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
-set whenever v4l2_fh_init() is called.
+.. attention::
+	New drivers must use struct :c:type:`v4l2_fh`
+	since it is also used to implement priority handling
+	(:ref:`VIDIOC_G_PRIORITY`).
 
-struct v4l2_fh is allocated as a part of the driver's own file handle
-structure and file->private_data is set to it in the driver's open
+The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
+whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
+by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
+This bit is set whenever :cpp:func:`v4l2_fh_init` is called.
+
+struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
+structure and ``file->private_data`` is set to it in the driver's ``open()``
 function by the driver.
 
-In many cases the struct v4l2_fh will be embedded in a larger structure.
-In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
-v4l2_fh_del+v4l2_fh_exit in release().
+In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
+structure. In that case you should call:
+
+#) :cpp:func:`v4l2_fh_init` and :cpp:func:`v4l2_fh_add` in ``open()``
+#) :cpp:func:`v4l2_fh_del` and :cpp:func:`v4l2_fh_exit` in ``release()``
 
 Drivers can extract their own file handle structure by using the container_of
-macro. Example:
+macro.
 
-.. code-block:: none
+Example:
+
+.. code-block:: c
 
 	struct my_fh {
 		int blah;
@@ -63,73 +71,66 @@ macro. Example:
 		return 0;
 	}
 
-Below is a short description of the v4l2_fh functions used:
+Below is a short description of the :c:type:`v4l2_fh` functions used:
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_init <v4l2_fh_init>`
+(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
 
-	void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
 
-  Initialise the file handle. This *MUST* be performed in the driver's
-  v4l2_file_operations->open() handler.
+- Initialise the file handle. This **MUST** be performed in the driver's
+  :c:type:`v4l2_file_operations`->open() handler.
 
-.. code-block:: none
 
-	void v4l2_fh_add(struct v4l2_fh *fh)
+:cpp:func:`v4l2_fh_add <v4l2_fh_add>`
+(:c:type:`fh <v4l2_fh>`)
 
-  Add a v4l2_fh to video_device file handle list. Must be called once the
-  file handle is completely initialized.
+- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
+  Must be called once the file handle is completely initialized.
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_del <v4l2_fh_del>`
+(:c:type:`fh <v4l2_fh>`)
 
-	void v4l2_fh_del(struct v4l2_fh *fh)
-
-  Unassociate the file handle from video_device(). The file handle
+- Unassociate the file handle from :c:type:`video_device`. The file handle
   exit function may now be called.
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_exit <v4l2_fh_exit>`
+(:c:type:`fh <v4l2_fh>`)
 
-	void v4l2_fh_exit(struct v4l2_fh *fh)
-
-  Uninitialise the file handle. After uninitialisation the v4l2_fh
+- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
   memory can be freed.
 
 
-If struct v4l2_fh is not embedded, then you can use these helper functions:
+If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_open <v4l2_fh_open>`
+(struct file \*filp)
 
-	int v4l2_fh_open(struct file *filp)
+- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
+  the struct :c:type:`video_device` associated with the file struct.
 
-  This allocates a struct v4l2_fh, initializes it and adds it to the struct
-  video_device associated with the file struct.
+:cpp:func:`v4l2_fh_release <v4l2_fh_release>`
+(struct file \*filp)
 
-.. code-block:: none
-
-	int v4l2_fh_release(struct file *filp)
-
-  This deletes it from the struct video_device associated with the file
-  struct, uninitialised the v4l2_fh and frees it.
-
-These two functions can be plugged into the v4l2_file_operation's open() and
-release() ops.
+- This deletes it from the struct :c:type:`video_device` associated with the
+  file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
 
+These two functions can be plugged into the v4l2_file_operation's ``open()``
+and ``release()`` ops.
 
 Several drivers need to do something when the first file handle is opened and
 when the last file handle closes. Two helper functions were added to check
-whether the v4l2_fh struct is the only open filehandle of the associated
-device node:
+whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
+associated device node:
 
-.. code-block:: none
+:cpp:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
+(:c:type:`fh <v4l2_fh>`)
 
-	int v4l2_fh_is_singular(struct v4l2_fh *fh)
+-  Returns 1 if the file handle is the only open file handle, else 0.
 
-  Returns 1 if the file handle is the only open file handle, else 0.
+:cpp:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
+(struct file \*filp)
 
-.. code-block:: none
-
-	int v4l2_fh_is_singular_file(struct file *filp)
-
-  Same, but it calls v4l2_fh_is_singular with filp->private_data.
+- Same, but it calls v4l2_fh_is_singular with filp->private_data.
 
 
 V4L2 File Handler kAPI
-- 
2.7.4

[PATCH 08/11] [media] move V4L2 clocks to a separate .rst file

[Mauro Carvalho Chehab]

Move the v4l2 clocks stuff from v4l2-framework to a separate
file and adds an attention that came from the v4l2-clk.h.

Note: as this is meant to be a temporary kAPI, and it is
used only by two drivers (soc_camera and em28xx), where
the first one is in deprecation process, it probably not
a worth effort to document its header.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-clocks.rst    | 29 +++++++++++++++++++++++++++++
 Documentation/media/kapi/v4l2-core.rst      |  1 +
 Documentation/media/kapi/v4l2-framework.rst | 25 -------------------------
 3 files changed, 30 insertions(+), 25 deletions(-)
 create mode 100644 Documentation/media/kapi/v4l2-clocks.rst

diff --git a/Documentation/media/kapi/v4l2-clocks.rst b/Documentation/media/kapi/v4l2-clocks.rst
new file mode 100644
index 000000000000..b8a895860a8a
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-clocks.rst
@@ -0,0 +1,29 @@
+V4L2 clocks
+-----------
+
+.. attention::
+
+	This is a temporary API and it shall be replaced by the generic
+	clock API, when the latter becomes widely available.
+
+Many subdevices, like camera sensors, TV decoders and encoders, need a clock
+signal to be supplied by the system. Often this clock is supplied by the
+respective bridge device. The Linux kernel provides a Common Clock Framework for
+this purpose. However, it is not (yet) available on all architectures. Besides,
+the nature of the multi-functional (clock, data + synchronisation, I2C control)
+connection of subdevices to the system might impose special requirements on the
+clock API usage. E.g. V4L2 has to support clock provider driver unregistration
+while a subdevice driver is holding a reference to the clock. For these reasons
+a V4L2 clock helper API has been developed and is provided to bridge and
+subdevice drivers.
+
+The API consists of two parts: two functions to register and unregister a V4L2
+clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control
+a clock object, similar to the respective generic clock API calls:
+v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(),
+v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide
+clock operations that will be called when clock users invoke respective API
+methods.
+
+It is expected that once the CCF becomes available on all relevant
+architectures this API will be removed.
diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index 67eaf0c0b6b6..c69d167bce7a 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -9,6 +9,7 @@ Video2Linux devices
     v4l2-controls
     v4l2-device
     v4l2-fh
+    v4l2-clocks
     v4l2-dv-timings
     v4l2-event
     v4l2-flash-led-class
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index 8b4f684e1a7a..7f4f26e666a2 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -79,28 +79,3 @@ and the v4l2_fh struct keeps track of filehandle instances.
 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 clocks
------------
-
-Many subdevices, like camera sensors, TV decoders and encoders, need a clock
-signal to be supplied by the system. Often this clock is supplied by the
-respective bridge device. The Linux kernel provides a Common Clock Framework for
-this purpose. However, it is not (yet) available on all architectures. Besides,
-the nature of the multi-functional (clock, data + synchronisation, I2C control)
-connection of subdevices to the system might impose special requirements on the
-clock API usage. E.g. V4L2 has to support clock provider driver unregistration
-while a subdevice driver is holding a reference to the clock. For these reasons
-a V4L2 clock helper API has been developed and is provided to bridge and
-subdevice drivers.
-
-The API consists of two parts: two functions to register and unregister a V4L2
-clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control
-a clock object, similar to the respective generic clock API calls:
-v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(),
-v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide
-clock operations that will be called when clock users invoke respective API
-methods.
-
-It is expected that once the CCF becomes available on all relevant
-architectures this API will be removed.
-- 
2.7.4

[PATCH 09/11] [media] rename v4l2-framework.rst to v4l2-intro.rst

[Mauro Carvalho Chehab]

Now that the only remaining chapters at v4l2-framework are
the introduction ones, let' s rename the file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-core.rst                          | 2 +-
 Documentation/media/kapi/{v4l2-framework.rst => v4l2-intro.rst} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/media/kapi/{v4l2-framework.rst => v4l2-intro.rst} (100%)

diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index c69d167bce7a..6285c18978d1 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -4,7 +4,7 @@ Video2Linux devices
 .. toctree::
     :maxdepth: 1
 
-    v4l2-framework
+    v4l2-intro
     v4l2-dev
     v4l2-controls
     v4l2-device
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-intro.rst
similarity index 100%
rename from Documentation/media/kapi/v4l2-framework.rst
rename to Documentation/media/kapi/v4l2-intro.rst
-- 
2.7.4

[PATCH 10/11] [media] doc-rst: reorganize the kAPI v4l2 chapters

[Mauro Carvalho Chehab]

Reorganize the order of the document, putting the chapters
on a more logical order and renaming some sections.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-common.rst          |  4 ++++
 Documentation/media/kapi/v4l2-controls.rst        |  4 ++--
 Documentation/media/kapi/v4l2-core.rst            | 11 ++++++-----
 Documentation/media/kapi/v4l2-dev.rst             | 12 ++++++------
 Documentation/media/kapi/v4l2-device.rst          |  8 ++++----
 Documentation/media/kapi/v4l2-dv-timings.rst      |  4 ++--
 Documentation/media/kapi/v4l2-event.rst           |  4 ++--
 Documentation/media/kapi/v4l2-fh.rst              |  5 +++--
 Documentation/media/kapi/v4l2-flash-led-class.rst |  4 ++--
 Documentation/media/kapi/v4l2-intro.rst           | 15 ++++-----------
 Documentation/media/kapi/v4l2-mc.rst              |  4 ++--
 Documentation/media/kapi/v4l2-mediabus.rst        |  4 ++--
 Documentation/media/kapi/v4l2-mem2mem.rst         |  5 +++--
 Documentation/media/kapi/v4l2-rect.rst            |  4 ++--
 Documentation/media/kapi/v4l2-subdev.rst          | 12 ------------
 Documentation/media/kapi/v4l2-tuner.rst           |  4 ++--
 Documentation/media/kapi/v4l2-tveeprom.rst        |  4 ++--
 Documentation/media/kapi/v4l2-videobuf2.rst       |  4 ++--
 18 files changed, 50 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/media/kapi/v4l2-common.rst

diff --git a/Documentation/media/kapi/v4l2-common.rst b/Documentation/media/kapi/v4l2-common.rst
new file mode 100644
index 000000000000..d1ea1c9e35a0
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-common.rst
@@ -0,0 +1,4 @@
+V4L2 common functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-common.h
diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst
index 2d433305fd4e..07a179eeb2fb 100644
--- a/Documentation/media/kapi/v4l2-controls.rst
+++ b/Documentation/media/kapi/v4l2-controls.rst
@@ -808,7 +808,7 @@ 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
------------------
+v4l2_ctrl functions and data structures
+---------------------------------------
 
 .. kernel-doc:: include/media/v4l2-ctrls.h
diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index 6285c18978d1..e9677150ed99 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -6,20 +6,21 @@ Video2Linux devices
 
     v4l2-intro
     v4l2-dev
-    v4l2-controls
     v4l2-device
     v4l2-fh
+    v4l2-subdev
+    v4l2-event
+    v4l2-controls
+    v4l2-videobuf
+    v4l2-videobuf2
     v4l2-clocks
     v4l2-dv-timings
-    v4l2-event
     v4l2-flash-led-class
     v4l2-mc
     v4l2-mediabus
     v4l2-mem2mem
     v4l2-of
     v4l2-rect
-    v4l2-subdev
     v4l2-tuner
+    v4l2-common
     v4l2-tveeprom
-    v4l2-videobuf2
-    v4l2-videobuf
diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
index 306306d8a43d..b03f9b33ad93 100644
--- a/Documentation/media/kapi/v4l2-dev.rst
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -1,5 +1,5 @@
-Video device creation
-=====================
+Video device' s internal representation
+=======================================
 
 The actual device nodes in the ``/dev`` directory are created using the
 :c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
@@ -309,8 +309,8 @@ it has been initialized:
 This can be done from the release callback.
 
 
-video_device helper functions
------------------------------
+helper functions
+----------------
 
 There are a few useful helper functions:
 
@@ -357,7 +357,7 @@ The name is used as a hint by userspace tools such as udev. The function
 should be used where possible instead of accessing the video_device::num and
 video_device::minor fields.
 
-video_device kAPI
------------------
+video_device functions and data structures
+------------------------------------------
 
 .. kernel-doc:: include/media/v4l2-dev.h
diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst
index 8e275d0ff0f5..c9115bcd8a9d 100644
--- a/Documentation/media/kapi/v4l2-device.rst
+++ b/Documentation/media/kapi/v4l2-device.rst
@@ -1,5 +1,5 @@
-V4L2 Device register logic
---------------------------
+V4L2 device instance
+--------------------
 
 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
@@ -138,7 +138,7 @@ Since the initial refcount is 1 you also need to call
 or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
 will never reach 0.
 
-V4L2 device kAPI
-^^^^^^^^^^^^^^^^
+v4l2_device functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. 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
index 4b08a49c54a4..55274329d229 100644
--- a/Documentation/media/kapi/v4l2-dv-timings.rst
+++ b/Documentation/media/kapi/v4l2-dv-timings.rst
@@ -1,4 +1,4 @@
-V4L2 DV Timings kAPI
-^^^^^^^^^^^^^^^^^^^^
+V4L2 DV Timings functions
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-dv-timings.h
diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst
index 0aed99459732..d81bbf23b6b1 100644
--- a/Documentation/media/kapi/v4l2-event.rst
+++ b/Documentation/media/kapi/v4l2-event.rst
@@ -130,8 +130,8 @@ function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map
 the subdev that sends the event to the video node(s) associated with the
 subdev that need to be informed about such an event.
 
-V4L2 event kAPI
-^^^^^^^^^^^^^^^
+V4L2 event functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-event.h
 
diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst
index a212698d5725..ef4ae046c0c5 100644
--- a/Documentation/media/kapi/v4l2-fh.rst
+++ b/Documentation/media/kapi/v4l2-fh.rst
@@ -133,6 +133,7 @@ associated device node:
 - Same, but it calls v4l2_fh_is_singular with filp->private_data.
 
 
-V4L2 File Handler kAPI
-^^^^^^^^^^^^^^^^^^^^^^
+V4L2 fh functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. kernel-doc:: include/media/v4l2-fh.h
diff --git a/Documentation/media/kapi/v4l2-flash-led-class.rst b/Documentation/media/kapi/v4l2-flash-led-class.rst
index 251ed6b3aab3..20798bdac387 100644
--- a/Documentation/media/kapi/v4l2-flash-led-class.rst
+++ b/Documentation/media/kapi/v4l2-flash-led-class.rst
@@ -1,4 +1,4 @@
-V4L2 Flash and LED class kAPI
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+V4L2 flash functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-flash-led-class.h
diff --git a/Documentation/media/kapi/v4l2-intro.rst b/Documentation/media/kapi/v4l2-intro.rst
index 7f4f26e666a2..e614d8d4ca1c 100644
--- a/Documentation/media/kapi/v4l2-intro.rst
+++ b/Documentation/media/kapi/v4l2-intro.rst
@@ -1,10 +1,3 @@
-Overview of the V4L2 driver framework
-=====================================
-
-This text documents the various structures provided by the V4L2 framework and
-their relationships.
-
-
 Introduction
 ------------
 
@@ -39,8 +32,8 @@ source that is available in samples/v4l/. It is a skeleton driver for
 a PCI capture card, and demonstrates how to use the V4L2 driver
 framework. It can be used as a template for real PCI video capture driver.
 
-Structure of a driver
----------------------
+Structure of a V4L driver
+-------------------------
 
 All drivers have the following structure:
 
@@ -68,8 +61,8 @@ This is a rough schematic of how it all relates:
 	  \-filehandle instances
 
 
-Structure of the framework
---------------------------
+Structure of the V4L2 framework
+-------------------------------
 
 The framework closely resembles the driver structure: it has a v4l2_device
 struct for the device instance data, a v4l2_subdev struct to refer to
diff --git a/Documentation/media/kapi/v4l2-mc.rst b/Documentation/media/kapi/v4l2-mc.rst
index c94ce0fa3839..8af347013490 100644
--- a/Documentation/media/kapi/v4l2-mc.rst
+++ b/Documentation/media/kapi/v4l2-mc.rst
@@ -1,4 +1,4 @@
-V4L2 Media Controller kAPI
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+V4L2 Media Controller functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-mc.h
diff --git a/Documentation/media/kapi/v4l2-mediabus.rst b/Documentation/media/kapi/v4l2-mediabus.rst
index b3c246b51c2c..e64131906d11 100644
--- a/Documentation/media/kapi/v4l2-mediabus.rst
+++ b/Documentation/media/kapi/v4l2-mediabus.rst
@@ -1,4 +1,4 @@
-V4L2 Media Bus kAPI
-^^^^^^^^^^^^^^^^^^^
+V4L2 Media Bus functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-mediabus.h
diff --git a/Documentation/media/kapi/v4l2-mem2mem.rst b/Documentation/media/kapi/v4l2-mem2mem.rst
index 61f9923286c7..5536b4a71e51 100644
--- a/Documentation/media/kapi/v4l2-mem2mem.rst
+++ b/Documentation/media/kapi/v4l2-mem2mem.rst
@@ -1,3 +1,4 @@
-V4L2 Memory to Memory kAPI
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+V4L2 Memory to Memory functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. kernel-doc:: include/media/v4l2-mem2mem.h
diff --git a/Documentation/media/kapi/v4l2-rect.rst b/Documentation/media/kapi/v4l2-rect.rst
index bb86dcbc5a3c..8df5067ad57d 100644
--- a/Documentation/media/kapi/v4l2-rect.rst
+++ b/Documentation/media/kapi/v4l2-rect.rst
@@ -1,4 +1,4 @@
-V4L2 rect kAPI
-^^^^^^^^^^^^^^
+V4L2 rect helper functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/v4l2-rect.h
diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst
index 456fdec69042..7e45b23ad3bd 100644
--- a/Documentation/media/kapi/v4l2-subdev.rst
+++ b/Documentation/media/kapi/v4l2-subdev.rst
@@ -440,18 +440,6 @@ 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 sub-device asynchronous kAPI
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 .. kernel-doc:: include/media/v4l2-async.h
-
-
-V4L2 common kAPI
-^^^^^^^^^^^^^^^^
-
-.. kernel-doc:: include/media/v4l2-common.h
diff --git a/Documentation/media/kapi/v4l2-tuner.rst b/Documentation/media/kapi/v4l2-tuner.rst
index 37b0ef310a62..86e894639651 100644
--- a/Documentation/media/kapi/v4l2-tuner.rst
+++ b/Documentation/media/kapi/v4l2-tuner.rst
@@ -1,5 +1,5 @@
-Tuner kAPI
-^^^^^^^^^^
+Tuner functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/tuner.h
 
diff --git a/Documentation/media/kapi/v4l2-tveeprom.rst b/Documentation/media/kapi/v4l2-tveeprom.rst
index f7ef71742e93..33422cb26aa7 100644
--- a/Documentation/media/kapi/v4l2-tveeprom.rst
+++ b/Documentation/media/kapi/v4l2-tveeprom.rst
@@ -1,4 +1,4 @@
-Hauppauge TV EEPROM kAPI
-^^^^^^^^^^^^^^^^^^^^^^^^
+Hauppauge TV EEPROM functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/tveeprom.h
diff --git a/Documentation/media/kapi/v4l2-videobuf2.rst b/Documentation/media/kapi/v4l2-videobuf2.rst
index bdb8b83f1ea0..3c4cb1e7e05f 100644
--- a/Documentation/media/kapi/v4l2-videobuf2.rst
+++ b/Documentation/media/kapi/v4l2-videobuf2.rst
@@ -1,7 +1,7 @@
 .. _vb2_framework:
 
-V4L2 videobuf2 kAPI
-^^^^^^^^^^^^^^^^^^^
+V4L2 videobuf2 functions and data structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. kernel-doc:: include/media/videobuf2-core.h
 
-- 
2.7.4

[PATCH 11/11] [media] doc-rst: Fix some typedef ugly warnings

[Mauro Carvalho Chehab]

Sphinx can't handle well typedefs. Change two typedef
occurrences, in order to cleanup some of such warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-ctrls.h      | 4 +++-
 include/media/v4l2-dv-timings.h | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 8b59336b2217..d6f63406b885 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -534,6 +534,8 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
 			const struct v4l2_ctrl_ops *ops,
 			u32 id, u8 max, u8 def, const s64 *qmenu_int);
 
+typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
+
 /**
  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
  * handler @hdl.
@@ -550,7 +552,7 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
  */
 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
 			  struct v4l2_ctrl_handler *add,
-			  bool (*filter)(const struct v4l2_ctrl *ctrl));
+			  v4l2_ctrl_filter filter);
 
 /**
  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 1113c8874c26..65caadf13eec 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -28,7 +28,7 @@
  */
 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
 
-/**
+/*
  * v4l2_check_dv_timings_fnc - timings check callback
  *
  * @t: the v4l2_dv_timings struct.
-- 
2.7.4