[PATCH 1/5] [media] v4l2-common.h: Add documentation for other functions

[PATCH 1/5] [media] v4l2-common.h: Add documentation for other functions

[Mauro Carvalho Chehab]

Not all functions at v4l2-common.h are documented. Add
documentation for some other ones.

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

diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 9b1dfcd9e229..350cbf9fb10e 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -78,9 +78,26 @@
 			v4l2_printk(KERN_DEBUG, dev, fmt , ## arg); 	\
 	} while (0)
 
-/* ------------------------------------------------------------------------- */
+/**
+ * v4l2_ctrl_query_fill- Fill in a struct v4l2_queryctrl
+ *
+ * @qctrl: pointer to the &struct v4l2_queryctrl to be filled
+ * @min: minimum value for the control
+ * @max: maximum value for the control
+ * @step: control step
+ * @def: default value for the control
+ *
+ * Fills the &struct v4l2_queryctrl fields for the query control.
+ *
+ * .. note::
+ *
+ *    This function assumes that the @qctrl->id field is filled.
+ *
+ * Returns -EINVAL if the control is not known by the V4L2 core, 0 on success.
+ */
 
-int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def);
+int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl,
+			 s32 min, s32 max, s32 step, s32 def);
 
 /* ------------------------------------------------------------------------- */
 
@@ -172,12 +189,28 @@ const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type);
 
 struct spi_device;
 
-/* Load an spi module and return an initialized v4l2_subdev struct.
-   The client_type argument is the name of the chip that's on the adapter. */
+/**
+ *  v4l2_spi_new_subdev - Load an spi module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device.
+ * @master: pointer to struct spi_master.
+ * @info: pointer to struct spi_board_info.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev,
 		struct spi_master *master, struct spi_board_info *info);
 
-/* Initialize a v4l2_subdev with data from an spi_device struct */
+/**
+ * v4l2_spi_subdev_init - Initialize a v4l2_subdev with data from an
+ *	spi_device struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @spi: pointer to struct spi_device.
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
 void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi,
 		const struct v4l2_subdev_ops *ops);
 #endif
-- 
2.7.4

[PATCH 2/5] [media] mc-core: Fix a cross-reference

[Mauro Carvalho Chehab]

The v4l2_subdev reference was using the wrong tag. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/mc-core.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst
index 4c47f5e3611d..deae3b7c692d 100644
--- a/Documentation/media/kapi/mc-core.rst
+++ b/Documentation/media/kapi/mc-core.rst
@@ -50,7 +50,7 @@ Entities
 Entities are represented by a :c:type:`struct media_entity <media_entity>`
 instance, defined in ``include/media/media-entity.h``. The structure is usually
 embedded into a higher-level structure, such as
-:ref:`v4l2_subdev` or :ref:`video_device`
+:c:type:`v4l2_subdev` or :c:type:`video_device`
 instances, although drivers can allocate entities directly.
 
 Drivers initialize entity pads by calling
-- 
2.7.4

[PATCH 3/5] [media] doc-rst: document v4l2-dev.h

[Mauro Carvalho Chehab]

Add documentation for v4l2-dev.h, and put it at v4l2-framework.rst,
where struct video_device is currently documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-framework.rst |   5 +
 drivers/media/v4l2-core/v4l2-dev.c          |  34 ---
 include/media/v4l2-dev.h                    | 364 ++++++++++++++++++++++++----
 3 files changed, 320 insertions(+), 83 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index de341fc5b235..315388ef6593 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -699,3 +699,8 @@ methods.
 
 It is expected that once the CCF becomes available on all relevant
 architectures this API will be removed.
+
+video_device kAPI
+^^^^^^^^^^^^^^^^^
+
+.. kernel-doc:: include/media/v4l2-dev.h
diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
index 70b559d7ca80..e6da353b39bc 100644
--- a/drivers/media/v4l2-core/v4l2-dev.c
+++ b/drivers/media/v4l2-core/v4l2-dev.c
@@ -812,40 +812,6 @@ static int video_register_media_controller(struct video_device *vdev, int type)
 	return 0;
 }
 
-/**
- *	__video_register_device - register video4linux devices
- *	@vdev: video device structure we want to register
- *	@type: type of device to register
- *	@nr:   which device node number (0 == /dev/video0, 1 == /dev/video1, ...
- *             -1 == first free)
- *	@warn_if_nr_in_use: warn if the desired device node number
- *	       was already in use and another number was chosen instead.
- *	@owner: module that owns the video device node
- *
- *	The registration code assigns minor numbers and device node numbers
- *	based on the requested type and registers the new device node with
- *	the kernel.
- *
- *	This function assumes that struct video_device was zeroed when it
- *	was allocated and does not contain any stale date.
- *
- *	An error is returned if no free minor or device node number could be
- *	found, or if the registration of the device node failed.
- *
- *	Zero is returned on success.
- *
- *	Valid types are
- *
- *	%VFL_TYPE_GRABBER - A frame grabber
- *
- *	%VFL_TYPE_VBI - Vertical blank data (undecoded)
- *
- *	%VFL_TYPE_RADIO - A radio card
- *
- *	%VFL_TYPE_SUBDEV - A subdevice
- *
- *	%VFL_TYPE_SDR - Software Defined Radio
- */
 int __video_register_device(struct video_device *vdev, int type, int nr,
 		int warn_if_nr_in_use, struct module *owner)
 {
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 25a3190308fb..5921c24565cf 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -47,19 +47,105 @@ struct v4l2_ctrl_handler;
 
 /* Priority helper functions */
 
+/**
+ * struct v4l2_prio_state - stores the priority states
+ *
+ * @prios: array with elements to store the array priorities
+ *
+ *
+ * .. note::
+ *    The size of @prios array matches the number of priority types defined
+ *    by :ref:`enum v4l2_priority <v4l2-priority>`.
+ */
 struct v4l2_prio_state {
 	atomic_t prios[4];
 };
 
+/**
+ * v4l2_prio_init - initializes a struct v4l2_prio_state
+ *
+ * @global: pointer to &struct v4l2_prio_state
+ */
 void v4l2_prio_init(struct v4l2_prio_state *global);
+
+/**
+ * v4l2_prio_change - changes the v4l2 file handler priority
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ * @new: Priority type requested, as defined by :ref:`enum v4l2_priority <v4l2-priority>`.
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
 		     enum v4l2_priority new);
+
+/**
+ * v4l2_prio_open - Implements the priority logic for a file handler open
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local);
+
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: priority to be released, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
+
+/**
+ * v4l2_prio_max - Return the maximum priority, as stored at the @global array.
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
+
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>` local
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
 
-
+/**
+ * struct v4l2_file_operations - fs operations used by a V4L2 device
+ *
+ * @owner: pointer to struct module
+ * @read: operations needed to implement the read() syscall
+ * @write: operations needed to implement the write() syscall
+ * @poll: operations needed to implement the poll() syscall
+ * @unlocked_ioctl: operations needed to implement the ioctl() syscall
+ * @compat_ioctl32: operations needed to implement the ioctl() syscall for
+ *	the special case where the Kernel uses 64 bits instructions, but
+ *	the userspace uses 32 bits.
+ * @get_unmapped_area: called by the mmap() syscall, used when %!CONFIG_MMU
+ * @mmap: operations needed to implement the mmap() syscall
+ * @open: operations needed to implement the open() syscall
+ * @release: operations needed to implement the release() syscall
+ *
+ * .. note::
+ *
+ *	Those operations are used to implemente the fs struct file_operations
+ *	at the V4L2 drivers. The V4L2 core overrides the fs ops with some
+ *	extra logic needed by the subsystem.
+ */
 struct v4l2_file_operations {
 	struct module *owner;
 	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
@@ -82,6 +168,47 @@ struct v4l2_file_operations {
  *	the common handler
  */
 
+/**
+ * struct video_device - Structure used to create and manage the V4L2 device
+ *	nodes.
+ *
+ * @entity: &struct media_entity
+ * @intf_devnode: pointer to &struct media_intf_devnode
+ * @pipe: &struct media_pipeline
+ * @fops: pointer to &struct v4l2_file_operations for the video device
+ * @device_caps: device capabilities as used in v4l2_capabilities
+ * @dev: &struct device for the video device
+ * @cdev: character device
+ * @v4l2_dev: pointer to &struct v4l2_device parent
+ * @dev_parent: pointer to &struct device parent
+ * @ctrl_handler: Control handler associated with this device node.
+ *	 May be NULL.
+ * @queue: &struct vb2_queue associated with this device node. May be NULL.
+ * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
+ *	 If NULL, then v4l2_dev->prio will be used.
+ * @name: video device name
+ * @vfl_type: V4L device type
+ * @vfl_dir: V4L receiver, transmitter or m2m
+ * @minor: device node 'minor'. It is set to -1 if the registration failed
+ * @num: number of the video device node
+ * @flags: video device flags. Use bitops to set/clear/test flags
+ * @index: attribute to differentiate multiple indices on one physical device
+ * @fh_lock: Lock for all v4l2_fhs
+ * @fh_list: List of &struct v4l2_fh
+ * @dev_debug: Internal device debug flags, not for use by drivers
+ * @tvnorms: Supported tv norms
+ *
+ * @release: video device release() callback
+ * @ioctl_ops: pointer to &struct v4l2_ioctl_ops with ioctl callbacks
+ *
+ * @valid_ioctls: bitmap with the valid ioctls for this device
+ * @disable_locking: bitmap with the ioctls that don't require locking
+ * @lock: pointer to &struct mutex serialization lock
+ *
+ * .. note::
+ *	Only set @dev_parent if that can't be deduced from @v4l2_dev.
+ */
+
 struct video_device
 {
 #if defined(CONFIG_MEDIA_CONTROLLER)
@@ -89,59 +216,45 @@ struct video_device
 	struct media_intf_devnode *intf_devnode;
 	struct media_pipeline pipe;
 #endif
-	/* device ops */
 	const struct v4l2_file_operations *fops;
 
-	/* device capabilities as used in v4l2_capabilities */
 	u32 device_caps;
 
 	/* sysfs */
-	struct device dev;		/* v4l device */
-	struct cdev *cdev;		/* character device */
+	struct device dev;
+	struct cdev *cdev;
 
-	struct v4l2_device *v4l2_dev;	/* v4l2_device parent */
-	/* Only set parent if that can't be deduced from v4l2_dev */
-	struct device *dev_parent;	/* device parent */
+	struct v4l2_device *v4l2_dev;
+	struct device *dev_parent;
 
-	/* Control handler associated with this device node. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
 
-	/* vb2_queue associated with this device node. May be NULL. */
 	struct vb2_queue *queue;
 
-	/* Priority state. If NULL, then v4l2_dev->prio will be used. */
 	struct v4l2_prio_state *prio;
 
 	/* device info */
 	char name[32];
-	int vfl_type;	/* device type */
-	int vfl_dir;	/* receiver, transmitter or m2m */
-	/* 'minor' is set to -1 if the registration failed */
+	int vfl_type;
+	int vfl_dir;
 	int minor;
 	u16 num;
-	/* use bitops to set/clear/test flags */
 	unsigned long flags;
-	/* attribute to differentiate multiple indices on one physical device */
 	int index;
 
 	/* V4L2 file handles */
-	spinlock_t		fh_lock; /* Lock for all v4l2_fhs */
-	struct list_head	fh_list; /* List of struct v4l2_fh */
+	spinlock_t		fh_lock;
+	struct list_head	fh_list;
 
-	/* Internal device debug flags, not for use by drivers */
 	int dev_debug;
 
-	/* Video standard vars */
-	v4l2_std_id tvnorms;		/* Supported tv norms */
+	v4l2_std_id tvnorms;
 
 	/* callbacks */
 	void (*release)(struct video_device *vdev);
-
-	/* ioctl callbacks */
 	const struct v4l2_ioctl_ops *ioctl_ops;
 	DECLARE_BITMAP(valid_ioctls, BASE_VIDIOC_PRIVATE);
 
-	/* serialization lock */
 	DECLARE_BITMAP(disable_locking, BASE_VIDIOC_PRIVATE);
 	struct mutex *lock;
 };
@@ -151,88 +264,241 @@ struct video_device
 /* dev to video-device */
 #define to_video_device(cd) container_of(cd, struct video_device, dev)
 
+/**
+ * __video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ * @warn_if_nr_in_use: warn if the desired device node number
+ *        was already in use and another number was chosen instead.
+ * @owner: module that owns the video device node
+ *
+ * The registration code assigns minor numbers and device node numbers
+ * based on the requested type and registers the new device node with
+ * the kernel.
+ *
+ * This function assumes that struct video_device was zeroed when it
+ * was allocated and does not contain any stale date.
+ *
+ * An error is returned if no free minor or device node number could be
+ * found, or if the registration of the device node failed.
+ *
+ * Returns 0 on success.
+ *
+ * Valid values for @type are:
+ *
+ *	- %VFL_TYPE_GRABBER - A frame grabber
+ *	- %VFL_TYPE_VBI - Vertical blank data (undecoded)
+ *	- %VFL_TYPE_RADIO - A radio card
+ *	- %VFL_TYPE_SUBDEV - A subdevice
+ *	- %VFL_TYPE_SDR - Software Defined Radio
+ *
+ * .. note::
+ *
+ *	This function is meant to be used only inside the V4L2 core.
+ *	Drivers should use video_register_device() or
+ *	video_register_device_no_warn().
+ */
 int __must_check __video_register_device(struct video_device *vdev, int type,
 		int nr, int warn_if_nr_in_use, struct module *owner);
 
-/* Register video devices. Note that if video_register_device fails,
-   the release() callback of the video_device structure is *not* called, so
-   the caller is responsible for freeing any data. Usually that means that
-   you call video_device_release() on failure. */
+/**
+ *  video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * 	if video_register_device fails, the release() callback of
+ *	&struct video_device structure is *not* called, so the caller
+ *	is responsible for freeing any data. Usually that means that
+ *	you video_device_release() should be called on failure.
+ */
 static inline int __must_check video_register_device(struct video_device *vdev,
 		int type, int nr)
 {
 	return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
 }
 
-/* Same as video_register_device, but no warning is issued if the desired
-   device node number was already in use. */
+/**
+ *  video_register_device_no_warn - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * This function is identical to video_register_device() except that no
+ * warning is issued if the desired device node number was already in use.
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * 	if video_register_device fails, the release() callback of
+ *	&struct video_device structure is *not* called, so the caller
+ *	is responsible for freeing any data. Usually that means that
+ *	you video_device_release() should be called on failure.
+ */
 static inline int __must_check video_register_device_no_warn(
 		struct video_device *vdev, int type, int nr)
 {
 	return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
 }
 
-/* Unregister video devices. Will do nothing if vdev == NULL or
-   video_is_registered() returns false. */
+/**
+ * video_unregister_device - Unregister video devices.
+ *
+ * @vdev: &struct video_device to register
+ *
+ * Does nothing if vdev == NULL or if video_is_registered() returns false.
+ */
 void video_unregister_device(struct video_device *vdev);
 
-/* helper functions to alloc/release struct video_device, the
-   latter can also be used for video_device->release(). */
+/**
+ * video_device_alloc - helper function to alloc &struct video_device
+ *
+ * Returns NULL if %-ENOMEM or a &struct video_device on success.
+ */
 struct video_device * __must_check video_device_alloc(void);
 
-/* this release function frees the vdev pointer */
+/**
+ * video_device_release - helper function to release &struct video_device
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Can also be used for video_device->release().
+ */
 void video_device_release(struct video_device *vdev);
 
-/* this release function does nothing, use when the video_device is a
-   static global struct. Note that having a static video_device is
-   a dubious construction at best. */
+/**
+ * video_device_release_empty - helper function to implement the
+ * 	video_device->release() callback.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * This release function does nothing.
+ *
+ * It should be used when the video_device is a static global struct.
+ *
+ * .. note::
+ *	Having a static video_device is a dubious construction at best.
+ */
 void video_device_release_empty(struct video_device *vdev);
 
-/* returns true if cmd is a known V4L2 ioctl */
+/**
+ * v4l2_is_known_ioctl - Checks if a given cmd is a known V4L ioctl
+ *
+ * @cmd: ioctl command
+ *
+ * returns true if cmd is a known V4L2 ioctl
+ */
 bool v4l2_is_known_ioctl(unsigned int cmd);
 
-/* mark that this command shouldn't use core locking */
-static inline void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd)
+/** v4l2_disable_ioctl_locking - mark that a given command
+ *	shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ */
+static inline void v4l2_disable_ioctl_locking(struct video_device *vdev,
+					      unsigned int cmd)
 {
 	if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
 		set_bit(_IOC_NR(cmd), vdev->disable_locking);
 }
 
-/* Mark that this command isn't implemented. This must be called before
-   video_device_register. See also the comments in determine_valid_ioctls().
-   This function allows drivers to provide just one v4l2_ioctl_ops struct, but
-   disable ioctls based on the specific card that is actually found. */
-static inline void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd)
+/**
+ * v4l2_disable_ioctl- mark that a given command isn't implemented.
+ *	shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ *
+ * This function allows drivers to provide just one v4l2_ioctl_ops struct, but
+ * disable ioctls based on the specific card that is actually found.
+ *
+ * .. note::
+ *
+ *    This must be called before video_register_device.
+ *    See also the comments for determine_valid_ioctls().
+ */
+static inline void v4l2_disable_ioctl(struct video_device *vdev,
+				      unsigned int cmd)
 {
 	if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
 		set_bit(_IOC_NR(cmd), vdev->valid_ioctls);
 }
 
-/* helper functions to access driver private data. */
+/**
+ * video_get_drvdata - gets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * returns a pointer to the private data
+ */
 static inline void *video_get_drvdata(struct video_device *vdev)
 {
 	return dev_get_drvdata(&vdev->dev);
 }
 
+/**
+ * video_set_drvdata - sets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @data: private data pointer
+ */
 static inline void video_set_drvdata(struct video_device *vdev, void *data)
 {
 	dev_set_drvdata(&vdev->dev, data);
 }
 
+/**
+ * video_devdata - gets &struct video_device from struct file.
+ *
+ * @file: pointer to struct file
+ */
 struct video_device *video_devdata(struct file *file);
 
-/* Combine video_get_drvdata and video_devdata as this is
-   used very often. */
+/**
+ * video_drvdata - gets private data from &struct video_device using the
+ *	struct file.
+ *
+ * @file: pointer to struct file
+ *
+ * This is function combines both video_get_drvdata() and video_devdata()
+ * as this is used very often.
+ */
 static inline void *video_drvdata(struct file *file)
 {
 	return video_get_drvdata(video_devdata(file));
 }
 
+/**
+ * video_device_node_name - returns the video device name
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Returns the device name string
+ */
 static inline const char *video_device_node_name(struct video_device *vdev)
 {
 	return dev_name(&vdev->dev);
 }
 
+/**
+ * video_is_registered - returns true if the &struct video_device is registered.
+ *
+ *
+ * @vdev: pointer to &struct video_device
+ */
 static inline int video_is_registered(struct video_device *vdev)
 {
 	return test_bit(V4L2_FL_REGISTERED, &vdev->flags);
-- 
2.7.4

[PATCH 4/5] [media] doc-rst: move v4l2-dev doc to a separate file

[Mauro Carvalho Chehab]

Move the documentation for video device node creation to
a separate file.

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

diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
index fc623e9ca871..6fa30f8908dd 100644
--- a/Documentation/media/kapi/v4l2-core.rst
+++ b/Documentation/media/kapi/v4l2-core.rst
@@ -5,6 +5,7 @@ Video2Linux devices
     :maxdepth: 1
 
     v4l2-framework
+    v4l2-dev
     v4l2-controls
     v4l2-device
     v4l2-dv-timings
diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
new file mode 100644
index 000000000000..f9b75d211ca0
--- /dev/null
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -0,0 +1,343 @@
+Video device creation
+=====================
+
+The actual device nodes in the /dev directory are created using the
+video_device struct (v4l2-dev.h). This struct can either be allocated
+dynamically or embedded in a larger struct.
+
+To allocate it dynamically use:
+
+.. code-block:: none
+
+	struct video_device *vdev = video_device_alloc();
+
+	if (vdev == NULL)
+		return -ENOMEM;
+
+	vdev->release = video_device_release;
+
+If you embed it in a larger struct, then you must set the release()
+callback to your own function:
+
+.. code-block:: none
+
+	struct video_device *vdev = &my_vdev->vdev;
+
+	vdev->release = my_vdev_release;
+
+The release callback must be set and it is called when the last user
+of the video device exits.
+
+The default video_device_release() callback just calls kfree to free the
+allocated memory.
+
+There is also a video_device_release_empty() function that does nothing
+(is empty) and can be used if the struct is embedded and there is nothing
+to do when it is released.
+
+You should also set these fields:
+
+- v4l2_dev: must be set to the v4l2_device parent device.
+
+- name: set to something descriptive and unique.
+
+- vfl_dir: set this to VFL_DIR_RX for capture devices (VFL_DIR_RX has value 0,
+  so this is normally already the default), set to VFL_DIR_TX for output
+  devices and VFL_DIR_M2M for mem2mem (codec) devices.
+
+- fops: set to the v4l2_file_operations struct.
+
+- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
+  (highly recommended to use this and it might become compulsory in the
+  future!), then set this to your v4l2_ioctl_ops struct. The vfl_type and
+  vfl_dir fields are used to disable ops that do not match the type/dir
+  combination. E.g. VBI ops are disabled for non-VBI nodes, and output ops
+  are disabled for a capture device. This makes it possible to provide
+  just one v4l2_ioctl_ops struct for both vbi and video nodes.
+
+- lock: leave to NULL if you want to do all the locking in the driver.
+  Otherwise you give it a pointer to a struct mutex_lock and before the
+  unlocked_ioctl file operation is called this lock will be taken by the
+  core and released afterwards. See the next section for more details.
+
+- queue: a pointer to the struct vb2_queue associated with this device node.
+  If queue is non-NULL, and queue->lock is non-NULL, then queue->lock is
+  used for the queuing ioctls (VIDIOC_REQBUFS, CREATE_BUFS, QBUF, DQBUF,
+  QUERYBUF, PREPARE_BUF, STREAMON and STREAMOFF) instead of the lock above.
+  That way the vb2 queuing framework does not have to wait for other ioctls.
+  This queue pointer is also used by the vb2 helper functions to check for
+  queuing ownership (i.e. is the filehandle calling it allowed to do the
+  operation).
+
+- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
+  If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
+  If you want to have a separate priority state per (group of) device node(s),
+  then you can point it to your own struct v4l2_prio_state.
+
+- dev_parent: you only set this if v4l2_device was registered with NULL as
+  the parent device struct. This only happens in cases where one hardware
+  device has multiple PCI devices that all share the same v4l2_device core.
+
+  The cx88 driver is an example of this: one core v4l2_device struct, but
+  it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
+  (cx8802). Since the v4l2_device cannot be associated with two PCI devices
+  at the same time it is setup without a parent device. But when the struct
+  video_device is initialized you *do* know which parent PCI device to use and
+  so you set dev_device to the correct PCI device.
+
+If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
+in your v4l2_file_operations struct.
+
+Do not use .ioctl! This is deprecated and will go away in the future.
+
+In some cases you want to tell the core that a function you had specified in
+your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this
+function before video_device_register is called:
+
+.. code-block:: none
+
+	void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
+
+This tends to be needed if based on external factors (e.g. which card is
+being used) you want to turns off certain features in v4l2_ioctl_ops without
+having to make a new struct.
+
+The v4l2_file_operations struct is a subset of file_operations. The main
+difference is that the inode argument is omitted since it is never used.
+
+If integration with the media framework is needed, you must initialize the
+media_entity struct embedded in the video_device struct (entity field) by
+calling media_entity_pads_init():
+
+.. code-block:: none
+
+	struct media_pad *pad = &my_vdev->pad;
+	int err;
+
+	err = media_entity_pads_init(&vdev->entity, 1, pad);
+
+The pads array must have been previously initialized. There is no need to
+manually set the struct media_entity type and name fields.
+
+A reference to the entity will be automatically acquired/released when the
+video device is opened/closed.
+
+ioctls and locking
+------------------
+
+The V4L core provides optional locking services. The main service is the
+lock field in struct video_device, which is a pointer to a mutex. If you set
+this pointer, then that will be used by unlocked_ioctl to serialize all ioctls.
+
+If you are using the videobuf2 framework, then there is a second lock that you
+can set: video_device->queue->lock. If set, then this lock will be used instead
+of video_device->lock to serialize all queuing ioctls (see the previous section
+for the full list of those ioctls).
+
+The advantage of using a different lock for the queuing ioctls is that for some
+drivers (particularly USB drivers) certain commands such as setting controls
+can take a long time, so you want to use a separate lock for the buffer queuing
+ioctls. That way your VIDIOC_DQBUF doesn't stall because the driver is busy
+changing the e.g. exposure of the webcam.
+
+Of course, you can always do all the locking yourself by leaving both lock
+pointers at NULL.
+
+If you use the old videobuf then you must pass the video_device lock to the
+videobuf queue initialize function: if videobuf has to wait for a frame to
+arrive, then it will temporarily unlock the lock and relock it afterwards. If
+your driver also waits in the code, then you should do the same to allow other
+processes to access the device node while the first process is waiting for
+something.
+
+In the case of videobuf2 you will need to implement the wait_prepare and
+wait_finish callbacks to unlock/lock if applicable. If you use the queue->lock
+pointer, then you can use the helper functions vb2_ops_wait_prepare/finish.
+
+The implementation of a hotplug disconnect should also take the lock from
+video_device before calling v4l2_device_disconnect. If you are also using
+video_device->queue->lock, then you have to first lock video_device->queue->lock
+followed by video_device->lock. That way you can be sure no ioctl is running
+when you call v4l2_device_disconnect.
+
+video_device registration
+-------------------------
+
+Next you register the video device: this will create the character device
+for you.
+
+.. code-block:: none
+
+	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
+	if (err) {
+		video_device_release(vdev); /* or kfree(my_vdev); */
+		return err;
+	}
+
+If the v4l2_device parent device has a non-NULL mdev field, the video device
+entity will be automatically registered with the media device.
+
+Which device is registered depends on the type argument. The following
+types exist:
+
+VFL_TYPE_GRABBER: videoX for video input/output devices
+VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
+VFL_TYPE_RADIO: radioX for radio tuners
+VFL_TYPE_SDR: swradioX for Software Defined Radio tuners
+
+The last argument gives you a certain amount of control over the device
+device node number used (i.e. the X in videoX). Normally you will pass -1
+to let the v4l2 framework pick the first free number. But sometimes users
+want to select a specific node number. It is common that drivers allow
+the user to select a specific device node number through a driver module
+option. That number is then passed to this function and video_register_device
+will attempt to select that device node number. If that number was already
+in use, then the next free device node number will be selected and it
+will send a warning to the kernel log.
+
+Another use-case is if a driver creates many devices. In that case it can
+be useful to place different video devices in separate ranges. For example,
+video capture devices start at 0, video output devices start at 16.
+So you can use the last argument to specify a minimum device node number
+and the v4l2 framework will try to pick the first free number that is equal
+or higher to what you passed. If that fails, then it will just pick the
+first free number.
+
+Since in this case you do not care about a warning about not being able
+to select the specified device node number, you can call the function
+video_register_device_no_warn() instead.
+
+Whenever a device node is created some attributes are also created for you.
+If you look in /sys/class/video4linux you see the devices. Go into e.g.
+video0 and you will see 'name', 'dev_debug' and 'index' attributes. The 'name'
+attribute is the 'name' field of the video_device struct. The 'dev_debug' attribute
+can be used to enable core debugging. See the next section for more detailed
+information on this.
+
+The 'index' attribute is the index of the device node: for each call to
+video_register_device() the index is just increased by 1. The first video
+device node you register always starts with index 0.
+
+Users can setup udev rules that utilize the index attribute to make fancy
+device names (e.g. 'mpegX' for MPEG video capture device nodes).
+
+After the device was successfully registered, then you can use these fields:
+
+- vfl_type: the device type passed to video_register_device.
+- minor: the assigned device minor number.
+- num: the device node number (i.e. the X in videoX).
+- index: the device index number.
+
+If the registration failed, then you need to call video_device_release()
+to free the allocated video_device struct, or free your own struct if the
+video_device was embedded in it. The vdev->release() callback will never
+be called if the registration failed, nor should you ever attempt to
+unregister the device if the registration failed.
+
+video device debugging
+----------------------
+
+The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
+device in /sys/class/video4linux/<devX>/ allows you to enable logging of
+file operations.
+
+It is a bitmask and the following bits can be set:
+
+.. code-block:: none
+
+	0x01: Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are only logged
+	      if bit 0x08 is also set.
+	0x02: Log the ioctl name arguments and error code. VIDIOC_(D)QBUF ioctls are
+	      only logged if bit 0x08 is also set.
+	0x04: Log the file operations open, release, read, write, mmap and
+	      get_unmapped_area. The read and write operations are only logged if
+	      bit 0x08 is also set.
+	0x08: Log the read and write file operations and the VIDIOC_QBUF and
+	      VIDIOC_DQBUF ioctls.
+	0x10: Log the poll file operation.
+
+video_device cleanup
+--------------------
+
+When the video device nodes have to be removed, either during the unload
+of the driver or because the USB device was disconnected, then you should
+unregister them:
+
+.. code-block:: none
+
+	video_unregister_device(vdev);
+
+This will remove the device nodes from sysfs (causing udev to remove them
+from /dev).
+
+After video_unregister_device() returns no new opens can be done. However,
+in the case of USB devices some application might still have one of these
+device nodes open. So after the unregister all file operations (except
+release, of course) will return an error as well.
+
+When the last user of the video device node exits, then the vdev->release()
+callback is called and you can do the final cleanup there.
+
+Don't forget to cleanup the media entity associated with the video device if
+it has been initialized:
+
+.. code-block:: none
+
+	media_entity_cleanup(&vdev->entity);
+
+This can be done from the release callback.
+
+
+video_device helper functions
+-----------------------------
+
+There are a few useful helper functions:
+
+- file/video_device private data
+
+You can set/get driver private data in the video_device struct using:
+
+.. code-block:: none
+
+	void *video_get_drvdata(struct video_device *vdev);
+	void video_set_drvdata(struct video_device *vdev, void *data);
+
+Note that you can safely call video_set_drvdata() before calling
+video_register_device().
+
+And this function:
+
+.. code-block:: none
+
+	struct video_device *video_devdata(struct file *file);
+
+returns the video_device belonging to the file struct.
+
+The video_drvdata function combines video_get_drvdata with video_devdata:
+
+.. code-block:: none
+
+	void *video_drvdata(struct file *file);
+
+You can go from a video_device struct to the v4l2_device struct using:
+
+.. code-block:: none
+
+	struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
+
+- Device node name
+
+The video_device node kernel name can be retrieved using
+
+.. code-block:: none
+
+	const char *video_device_node_name(struct video_device *vdev);
+
+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
+-----------------
+
+.. kernel-doc:: include/media/v4l2-dev.h
diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst
index 315388ef6593..c97ffd0d783b 100644
--- a/Documentation/media/kapi/v4l2-framework.rst
+++ b/Documentation/media/kapi/v4l2-framework.rst
@@ -81,345 +81,6 @@ driver sets the struct v4l2_device mdev field, sub-devices and video nodes
 will automatically appear in the media framework as entities.
 
 
-struct video_device
--------------------
-
-The actual device nodes in the /dev directory are created using the
-video_device struct (v4l2-dev.h). This struct can either be allocated
-dynamically or embedded in a larger struct.
-
-To allocate it dynamically use:
-
-.. code-block:: none
-
-	struct video_device *vdev = video_device_alloc();
-
-	if (vdev == NULL)
-		return -ENOMEM;
-
-	vdev->release = video_device_release;
-
-If you embed it in a larger struct, then you must set the release()
-callback to your own function:
-
-.. code-block:: none
-
-	struct video_device *vdev = &my_vdev->vdev;
-
-	vdev->release = my_vdev_release;
-
-The release callback must be set and it is called when the last user
-of the video device exits.
-
-The default video_device_release() callback just calls kfree to free the
-allocated memory.
-
-There is also a video_device_release_empty() function that does nothing
-(is empty) and can be used if the struct is embedded and there is nothing
-to do when it is released.
-
-You should also set these fields:
-
-- v4l2_dev: must be set to the v4l2_device parent device.
-
-- name: set to something descriptive and unique.
-
-- vfl_dir: set this to VFL_DIR_RX for capture devices (VFL_DIR_RX has value 0,
-  so this is normally already the default), set to VFL_DIR_TX for output
-  devices and VFL_DIR_M2M for mem2mem (codec) devices.
-
-- fops: set to the v4l2_file_operations struct.
-
-- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
-  (highly recommended to use this and it might become compulsory in the
-  future!), then set this to your v4l2_ioctl_ops struct. The vfl_type and
-  vfl_dir fields are used to disable ops that do not match the type/dir
-  combination. E.g. VBI ops are disabled for non-VBI nodes, and output ops
-  are disabled for a capture device. This makes it possible to provide
-  just one v4l2_ioctl_ops struct for both vbi and video nodes.
-
-- lock: leave to NULL if you want to do all the locking in the driver.
-  Otherwise you give it a pointer to a struct mutex_lock and before the
-  unlocked_ioctl file operation is called this lock will be taken by the
-  core and released afterwards. See the next section for more details.
-
-- queue: a pointer to the struct vb2_queue associated with this device node.
-  If queue is non-NULL, and queue->lock is non-NULL, then queue->lock is
-  used for the queuing ioctls (VIDIOC_REQBUFS, CREATE_BUFS, QBUF, DQBUF,
-  QUERYBUF, PREPARE_BUF, STREAMON and STREAMOFF) instead of the lock above.
-  That way the vb2 queuing framework does not have to wait for other ioctls.
-  This queue pointer is also used by the vb2 helper functions to check for
-  queuing ownership (i.e. is the filehandle calling it allowed to do the
-  operation).
-
-- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
-  If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
-  If you want to have a separate priority state per (group of) device node(s),
-  then you can point it to your own struct v4l2_prio_state.
-
-- dev_parent: you only set this if v4l2_device was registered with NULL as
-  the parent device struct. This only happens in cases where one hardware
-  device has multiple PCI devices that all share the same v4l2_device core.
-
-  The cx88 driver is an example of this: one core v4l2_device struct, but
-  it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
-  (cx8802). Since the v4l2_device cannot be associated with two PCI devices
-  at the same time it is setup without a parent device. But when the struct
-  video_device is initialized you *do* know which parent PCI device to use and
-  so you set dev_device to the correct PCI device.
-
-If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
-in your v4l2_file_operations struct.
-
-Do not use .ioctl! This is deprecated and will go away in the future.
-
-In some cases you want to tell the core that a function you had specified in
-your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this
-function before video_device_register is called:
-
-.. code-block:: none
-
-	void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
-
-This tends to be needed if based on external factors (e.g. which card is
-being used) you want to turns off certain features in v4l2_ioctl_ops without
-having to make a new struct.
-
-The v4l2_file_operations struct is a subset of file_operations. The main
-difference is that the inode argument is omitted since it is never used.
-
-If integration with the media framework is needed, you must initialize the
-media_entity struct embedded in the video_device struct (entity field) by
-calling media_entity_pads_init():
-
-.. code-block:: none
-
-	struct media_pad *pad = &my_vdev->pad;
-	int err;
-
-	err = media_entity_pads_init(&vdev->entity, 1, pad);
-
-The pads array must have been previously initialized. There is no need to
-manually set the struct media_entity type and name fields.
-
-A reference to the entity will be automatically acquired/released when the
-video device is opened/closed.
-
-ioctls and locking
-------------------
-
-The V4L core provides optional locking services. The main service is the
-lock field in struct video_device, which is a pointer to a mutex. If you set
-this pointer, then that will be used by unlocked_ioctl to serialize all ioctls.
-
-If you are using the videobuf2 framework, then there is a second lock that you
-can set: video_device->queue->lock. If set, then this lock will be used instead
-of video_device->lock to serialize all queuing ioctls (see the previous section
-for the full list of those ioctls).
-
-The advantage of using a different lock for the queuing ioctls is that for some
-drivers (particularly USB drivers) certain commands such as setting controls
-can take a long time, so you want to use a separate lock for the buffer queuing
-ioctls. That way your VIDIOC_DQBUF doesn't stall because the driver is busy
-changing the e.g. exposure of the webcam.
-
-Of course, you can always do all the locking yourself by leaving both lock
-pointers at NULL.
-
-If you use the old videobuf then you must pass the video_device lock to the
-videobuf queue initialize function: if videobuf has to wait for a frame to
-arrive, then it will temporarily unlock the lock and relock it afterwards. If
-your driver also waits in the code, then you should do the same to allow other
-processes to access the device node while the first process is waiting for
-something.
-
-In the case of videobuf2 you will need to implement the wait_prepare and
-wait_finish callbacks to unlock/lock if applicable. If you use the queue->lock
-pointer, then you can use the helper functions vb2_ops_wait_prepare/finish.
-
-The implementation of a hotplug disconnect should also take the lock from
-video_device before calling v4l2_device_disconnect. If you are also using
-video_device->queue->lock, then you have to first lock video_device->queue->lock
-followed by video_device->lock. That way you can be sure no ioctl is running
-when you call v4l2_device_disconnect.
-
-video_device registration
--------------------------
-
-Next you register the video device: this will create the character device
-for you.
-
-.. code-block:: none
-
-	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
-	if (err) {
-		video_device_release(vdev); /* or kfree(my_vdev); */
-		return err;
-	}
-
-If the v4l2_device parent device has a non-NULL mdev field, the video device
-entity will be automatically registered with the media device.
-
-Which device is registered depends on the type argument. The following
-types exist:
-
-VFL_TYPE_GRABBER: videoX for video input/output devices
-VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
-VFL_TYPE_RADIO: radioX for radio tuners
-VFL_TYPE_SDR: swradioX for Software Defined Radio tuners
-
-The last argument gives you a certain amount of control over the device
-device node number used (i.e. the X in videoX). Normally you will pass -1
-to let the v4l2 framework pick the first free number. But sometimes users
-want to select a specific node number. It is common that drivers allow
-the user to select a specific device node number through a driver module
-option. That number is then passed to this function and video_register_device
-will attempt to select that device node number. If that number was already
-in use, then the next free device node number will be selected and it
-will send a warning to the kernel log.
-
-Another use-case is if a driver creates many devices. In that case it can
-be useful to place different video devices in separate ranges. For example,
-video capture devices start at 0, video output devices start at 16.
-So you can use the last argument to specify a minimum device node number
-and the v4l2 framework will try to pick the first free number that is equal
-or higher to what you passed. If that fails, then it will just pick the
-first free number.
-
-Since in this case you do not care about a warning about not being able
-to select the specified device node number, you can call the function
-video_register_device_no_warn() instead.
-
-Whenever a device node is created some attributes are also created for you.
-If you look in /sys/class/video4linux you see the devices. Go into e.g.
-video0 and you will see 'name', 'dev_debug' and 'index' attributes. The 'name'
-attribute is the 'name' field of the video_device struct. The 'dev_debug' attribute
-can be used to enable core debugging. See the next section for more detailed
-information on this.
-
-The 'index' attribute is the index of the device node: for each call to
-video_register_device() the index is just increased by 1. The first video
-device node you register always starts with index 0.
-
-Users can setup udev rules that utilize the index attribute to make fancy
-device names (e.g. 'mpegX' for MPEG video capture device nodes).
-
-After the device was successfully registered, then you can use these fields:
-
-- vfl_type: the device type passed to video_register_device.
-- minor: the assigned device minor number.
-- num: the device node number (i.e. the X in videoX).
-- index: the device index number.
-
-If the registration failed, then you need to call video_device_release()
-to free the allocated video_device struct, or free your own struct if the
-video_device was embedded in it. The vdev->release() callback will never
-be called if the registration failed, nor should you ever attempt to
-unregister the device if the registration failed.
-
-video device debugging
-----------------------
-
-The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
-device in /sys/class/video4linux/<devX>/ allows you to enable logging of
-file operations.
-
-It is a bitmask and the following bits can be set:
-
-.. code-block:: none
-
-	0x01: Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are only logged
-	      if bit 0x08 is also set.
-	0x02: Log the ioctl name arguments and error code. VIDIOC_(D)QBUF ioctls are
-	      only logged if bit 0x08 is also set.
-	0x04: Log the file operations open, release, read, write, mmap and
-	      get_unmapped_area. The read and write operations are only logged if
-	      bit 0x08 is also set.
-	0x08: Log the read and write file operations and the VIDIOC_QBUF and
-	      VIDIOC_DQBUF ioctls.
-	0x10: Log the poll file operation.
-
-video_device cleanup
---------------------
-
-When the video device nodes have to be removed, either during the unload
-of the driver or because the USB device was disconnected, then you should
-unregister them:
-
-.. code-block:: none
-
-	video_unregister_device(vdev);
-
-This will remove the device nodes from sysfs (causing udev to remove them
-from /dev).
-
-After video_unregister_device() returns no new opens can be done. However,
-in the case of USB devices some application might still have one of these
-device nodes open. So after the unregister all file operations (except
-release, of course) will return an error as well.
-
-When the last user of the video device node exits, then the vdev->release()
-callback is called and you can do the final cleanup there.
-
-Don't forget to cleanup the media entity associated with the video device if
-it has been initialized:
-
-.. code-block:: none
-
-	media_entity_cleanup(&vdev->entity);
-
-This can be done from the release callback.
-
-
-video_device helper functions
------------------------------
-
-There are a few useful helper functions:
-
-- file/video_device private data
-
-You can set/get driver private data in the video_device struct using:
-
-.. code-block:: none
-
-	void *video_get_drvdata(struct video_device *vdev);
-	void video_set_drvdata(struct video_device *vdev, void *data);
-
-Note that you can safely call video_set_drvdata() before calling
-video_register_device().
-
-And this function:
-
-.. code-block:: none
-
-	struct video_device *video_devdata(struct file *file);
-
-returns the video_device belonging to the file struct.
-
-The video_drvdata function combines video_get_drvdata with video_devdata:
-
-.. code-block:: none
-
-	void *video_drvdata(struct file *file);
-
-You can go from a video_device struct to the v4l2_device struct using:
-
-.. code-block:: none
-
-	struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
-
-- Device node name
-
-The video_device node kernel name can be retrieved using
-
-.. code-block:: none
-
-	const char *video_device_node_name(struct video_device *vdev);
-
-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 buffer helper functions
 -----------------------------
@@ -699,8 +360,3 @@ methods.
 
 It is expected that once the CCF becomes available on all relevant
 architectures this API will be removed.
-
-video_device kAPI
-^^^^^^^^^^^^^^^^^
-
-.. kernel-doc:: include/media/v4l2-dev.h
-- 
2.7.4

[PATCH 5/5] [media] v4l2-dev: add cross-references and improve markup

[Mauro Carvalho Chehab]

Add cross-references for the functions/structs and add
the markup tags to improve its display.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-dev.rst       | 352 +++++++++++++++-------------
 Documentation/media/kapi/v4l2-videobuf.rst  |   2 +
 Documentation/media/kapi/v4l2-videobuf2.rst |   2 +
 3 files changed, 190 insertions(+), 166 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
index f9b75d211ca0..306306d8a43d 100644
--- a/Documentation/media/kapi/v4l2-dev.rst
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -1,13 +1,13 @@
 Video device creation
 =====================
 
-The actual device nodes in the /dev directory are created using the
-video_device struct (v4l2-dev.h). This struct can either be allocated
-dynamically or embedded in a larger struct.
+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
+allocated dynamically or embedded in a larger struct.
 
-To allocate it dynamically use:
+To allocate it dynamically use :cpp:func:`video_device_alloc`:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct video_device *vdev = video_device_alloc();
 
@@ -16,100 +16,110 @@ To allocate it dynamically use:
 
 	vdev->release = video_device_release;
 
-If you embed it in a larger struct, then you must set the release()
+If you embed it in a larger struct, then you must set the ``release()``
 callback to your own function:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct video_device *vdev = &my_vdev->vdev;
 
 	vdev->release = my_vdev_release;
 
-The release callback must be set and it is called when the last user
+The ``release()`` callback must be set and it is called when the last user
 of the video device exits.
 
-The default video_device_release() callback just calls kfree to free the
-allocated memory.
-
-There is also a video_device_release_empty() function that does nothing
-(is empty) and can be used if the struct is embedded and there is nothing
-to do when it is released.
-
-You should also set these fields:
-
-- v4l2_dev: must be set to the v4l2_device parent device.
-
-- name: set to something descriptive and unique.
-
-- vfl_dir: set this to VFL_DIR_RX for capture devices (VFL_DIR_RX has value 0,
-  so this is normally already the default), set to VFL_DIR_TX for output
-  devices and VFL_DIR_M2M for mem2mem (codec) devices.
-
-- fops: set to the v4l2_file_operations struct.
-
-- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
-  (highly recommended to use this and it might become compulsory in the
-  future!), then set this to your v4l2_ioctl_ops struct. The vfl_type and
-  vfl_dir fields are used to disable ops that do not match the type/dir
-  combination. E.g. VBI ops are disabled for non-VBI nodes, and output ops
-  are disabled for a capture device. This makes it possible to provide
-  just one v4l2_ioctl_ops struct for both vbi and video nodes.
-
-- lock: leave to NULL if you want to do all the locking in the driver.
-  Otherwise you give it a pointer to a struct mutex_lock and before the
-  unlocked_ioctl file operation is called this lock will be taken by the
-  core and released afterwards. See the next section for more details.
-
-- queue: a pointer to the struct vb2_queue associated with this device node.
-  If queue is non-NULL, and queue->lock is non-NULL, then queue->lock is
-  used for the queuing ioctls (VIDIOC_REQBUFS, CREATE_BUFS, QBUF, DQBUF,
-  QUERYBUF, PREPARE_BUF, STREAMON and STREAMOFF) instead of the lock above.
-  That way the vb2 queuing framework does not have to wait for other ioctls.
-  This queue pointer is also used by the vb2 helper functions to check for
+The default :cpp:func:`video_device_release` callback currently
+just calls ``kfree`` to free the allocated memory.
+
+There is also a ::cpp:func:`video_device_release_empty` function that does
+nothing (is empty) and should be used if the struct is embedded and there
+is nothing to do when it is released.
+
+You should also set these fields of :c:type:`video_device`:
+
+- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
+  parent device.
+
+- :c:type:`video_device`->name: set to something descriptive and unique.
+
+- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture
+  devices (``VFL_DIR_RX`` has value 0, so this is normally already the
+  default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.
+
+- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
+  struct.
+
+- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
+  to simplify ioctl maintenance (highly recommended to use this and it might
+  become compulsory in the future!), then set this to your
+  :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
+  :c:type:`video_device`->vfl_dir fields are used to disable ops that do not
+  match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes,
+  and output ops  are disabled for a capture device. This makes it possible to
+  provide just one :c:type:`v4l2_ioctl_ops struct` for both vbi and
+  video nodes.
+
+- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
+  locking  in the driver. Otherwise you give it a pointer to a struct
+  ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
+  file operation is called this lock will be taken by the core and released
+  afterwards. See the next section for more details.
+
+- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
+  associated with this device node.
+  If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
+  is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
+  ``QBUF``, ``DQBUF``,  ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and
+  ``STREAMOFF``) instead of the lock above.
+  That way the :ref:`vb2 <vb2_framework>` queuing framework does not have
+  to wait for other ioctls.   This queue pointer is also used by the
+  :ref:`vb2 <vb2_framework>` helper functions to check for
   queuing ownership (i.e. is the filehandle calling it allowed to do the
   operation).
 
-- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
-  If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
-  If you want to have a separate priority state per (group of) device node(s),
-  then you can point it to your own struct v4l2_prio_state.
+- :c:type:`video_device`->prio: keeps track of the priorities. Used to
+  implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
+  If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
+  in :c:type:`v4l2_device`. If you want to have a separate priority state per
+  (group of) device node(s),   then you can point it to your own struct
+  :c:type:`v4l2_prio_state`.
 
-- dev_parent: you only set this if v4l2_device was registered with NULL as
-  the parent device struct. This only happens in cases where one hardware
-  device has multiple PCI devices that all share the same v4l2_device core.
+- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was
+  registered with ``NULL`` as the parent ``device`` struct. This only happens
+  in cases where one hardware device has multiple PCI devices that all share
+  the same :c:type:`v4l2_device` core.
 
-  The cx88 driver is an example of this: one core v4l2_device struct, but
-  it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
-  (cx8802). Since the v4l2_device cannot be associated with two PCI devices
-  at the same time it is setup without a parent device. But when the struct
-  video_device is initialized you *do* know which parent PCI device to use and
-  so you set dev_device to the correct PCI device.
+  The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct,
+  but   it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
+  (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
+  devices at the same time it is setup without a parent device. But when the
+  struct :c:type:`video_device` is initialized you **do** know which parent
+  PCI device to use and so you set ``dev_device`` to the correct PCI device.
 
-If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
-in your v4l2_file_operations struct.
-
-Do not use .ioctl! This is deprecated and will go away in the future.
+If you use :c:type:`v4l2_ioctl_ops`, then you should set
+:c:type:`video_device`->unlocked_ioctl to :cpp:func:`video_ioctl2` in your
+:c:type:`v4l2_file_operations` struct.
 
 In some cases you want to tell the core that a function you had specified in
-your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this
-function before video_device_register is called:
+your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
+calling this function before :cpp:func:`video_register_device` is called:
 
-.. code-block:: none
-
-	void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
+	:cpp:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
+	(:c:type:`vdev <video_device>`, cmd).
 
 This tends to be needed if based on external factors (e.g. which card is
-being used) you want to turns off certain features in v4l2_ioctl_ops without
-having to make a new struct.
+being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops`
+without having to make a new struct.
 
-The v4l2_file_operations struct is a subset of file_operations. The main
-difference is that the inode argument is omitted since it is never used.
+The :c:type:`v4l2_file_operations` struct is a subset of file_operations.
+The main difference is that the inode argument is omitted since it is never
+used.
 
 If integration with the media framework is needed, you must initialize the
-media_entity struct embedded in the video_device struct (entity field) by
-calling media_entity_pads_init():
+:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
+(entity field) by calling :cpp:func:`media_entity_pads_init`:
 
-.. code-block:: none
+.. code-block:: c
 
 	struct media_pad *pad = &my_vdev->pad;
 	int err;
@@ -126,47 +136,52 @@ ioctls and locking
 ------------------
 
 The V4L core provides optional locking services. The main service is the
-lock field in struct video_device, which is a pointer to a mutex. If you set
-this pointer, then that will be used by unlocked_ioctl to serialize all ioctls.
+lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
+If you set this pointer, then that will be used by unlocked_ioctl to
+serialize all ioctls.
 
-If you are using the videobuf2 framework, then there is a second lock that you
-can set: video_device->queue->lock. If set, then this lock will be used instead
-of video_device->lock to serialize all queuing ioctls (see the previous section
+If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there
+is a second lock that you can set: :c:type:`video_device`->queue->lock. If
+set, then this lock will be used instead of :c:type:`video_device`->lock
+to serialize all queuing ioctls (see the previous section
 for the full list of those ioctls).
 
 The advantage of using a different lock for the queuing ioctls is that for some
 drivers (particularly USB drivers) certain commands such as setting controls
 can take a long time, so you want to use a separate lock for the buffer queuing
-ioctls. That way your VIDIOC_DQBUF doesn't stall because the driver is busy
+ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy
 changing the e.g. exposure of the webcam.
 
 Of course, you can always do all the locking yourself by leaving both lock
-pointers at NULL.
+pointers at ``NULL``.
 
-If you use the old videobuf then you must pass the video_device lock to the
-videobuf queue initialize function: if videobuf has to wait for a frame to
-arrive, then it will temporarily unlock the lock and relock it afterwards. If
-your driver also waits in the code, then you should do the same to allow other
+If you use the old :ref:`videobuf framework <vb_framework>` then you must
+pass the :c:type:`video_device`->lock to the videobuf queue initialize
+function: if videobuf has to wait for a frame to arrive, then it will
+temporarily unlock the lock and relock it afterwards. If your driver also
+waits in the code, then you should do the same to allow other
 processes to access the device node while the first process is waiting for
 something.
 
-In the case of videobuf2 you will need to implement the wait_prepare and
-wait_finish callbacks to unlock/lock if applicable. If you use the queue->lock
-pointer, then you can use the helper functions vb2_ops_wait_prepare/finish.
+In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
+``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.
+If you use the ``queue->lock`` pointer, then you can use the helper functions
+:cpp:func:`vb2_ops_wait_prepare` and :cpp:func:`vb2_ops_wait_finish`.
 
 The implementation of a hotplug disconnect should also take the lock from
-video_device before calling v4l2_device_disconnect. If you are also using
-video_device->queue->lock, then you have to first lock video_device->queue->lock
-followed by video_device->lock. That way you can be sure no ioctl is running
-when you call v4l2_device_disconnect.
+:c:type:`video_device` before calling v4l2_device_disconnect. If you are also
+using :c:type:`video_device`->queue->lock, then you have to first lock
+:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
+That way you can be sure no ioctl is running when you call
+:c:type:`v4l2_device_disconnect`.
 
-video_device registration
+Video device registration
 -------------------------
 
-Next you register the video device: this will create the character device
-for you.
+Next you register the video device with :cpp:func:`video_register_device`.
+This will create the character device for you.
 
-.. code-block:: none
+.. code-block:: c
 
 	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
 	if (err) {
@@ -174,19 +189,20 @@ for you.
 		return err;
 	}
 
-If the v4l2_device parent device has a non-NULL mdev field, the video device
-entity will be automatically registered with the media device.
+If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,
+the video device entity will be automatically registered with the media
+device.
 
 Which device is registered depends on the type argument. The following
 types exist:
 
-VFL_TYPE_GRABBER: videoX for video input/output devices
-VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
-VFL_TYPE_RADIO: radioX for radio tuners
-VFL_TYPE_SDR: swradioX for Software Defined Radio tuners
+- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices
+- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext)
+- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners
+- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners
 
 The last argument gives you a certain amount of control over the device
-device node number used (i.e. the X in videoX). Normally you will pass -1
+device node number used (i.e. the X in ``videoX``). Normally you will pass -1
 to let the v4l2 framework pick the first free number. But sometimes users
 want to select a specific node number. It is common that drivers allow
 the user to select a specific device node number through a driver module
@@ -205,85 +221,90 @@ first free number.
 
 Since in this case you do not care about a warning about not being able
 to select the specified device node number, you can call the function
-video_register_device_no_warn() instead.
+:cpp:func:`video_register_device_no_warn` instead.
 
 Whenever a device node is created some attributes are also created for you.
-If you look in /sys/class/video4linux you see the devices. Go into e.g.
-video0 and you will see 'name', 'dev_debug' and 'index' attributes. The 'name'
-attribute is the 'name' field of the video_device struct. The 'dev_debug' attribute
-can be used to enable core debugging. See the next section for more detailed
-information on this.
+If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
+``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The
+'name' attribute is the 'name' field of the video_device struct. The
+'dev_debug' attribute can be used to enable core debugging. See the next
+section for more detailed information on this.
 
 The 'index' attribute is the index of the device node: for each call to
-video_register_device() the index is just increased by 1. The first video
-device node you register always starts with index 0.
+:cpp:func:`video_register_device()` the index is just increased by 1. The
+first video device node you register always starts with index 0.
 
 Users can setup udev rules that utilize the index attribute to make fancy
-device names (e.g. 'mpegX' for MPEG video capture device nodes).
+device names (e.g. '``mpegX``' for MPEG video capture device nodes).
 
 After the device was successfully registered, then you can use these fields:
 
-- vfl_type: the device type passed to video_register_device.
-- minor: the assigned device minor number.
-- num: the device node number (i.e. the X in videoX).
-- index: the device index number.
+- :c:type:`video_device`->vfl_type: the device type passed to
+  :cpp:func:`video_register_device`.
+- :c:type:`video_device`->minor: the assigned device minor number.
+- :c:type:`video_device`->num: the device node number (i.e. the X in
+  ``videoX``).
+- :c:type:`video_device`->index: the device index number.
 
-If the registration failed, then you need to call video_device_release()
-to free the allocated video_device struct, or free your own struct if the
-video_device was embedded in it. The vdev->release() callback will never
-be called if the registration failed, nor should you ever attempt to
-unregister the device if the registration failed.
+If the registration failed, then you need to call
+:cpp:func:`video_device_release` to free the allocated :c:type:`video_device`
+struct, or free your own struct if the :c:type:`video_device` was embedded in
+it. The ``vdev->release()`` callback will never be called if the registration
+failed, nor should you ever attempt to unregister the device if the
+registration failed.
 
 video device debugging
 ----------------------
 
 The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
-device in /sys/class/video4linux/<devX>/ allows you to enable logging of
+device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of
 file operations.
 
 It is a bitmask and the following bits can be set:
 
-.. code-block:: none
 
-	0x01: Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are only logged
-	      if bit 0x08 is also set.
-	0x02: Log the ioctl name arguments and error code. VIDIOC_(D)QBUF ioctls are
-	      only logged if bit 0x08 is also set.
-	0x04: Log the file operations open, release, read, write, mmap and
-	      get_unmapped_area. The read and write operations are only logged if
-	      bit 0x08 is also set.
-	0x08: Log the read and write file operations and the VIDIOC_QBUF and
-	      VIDIOC_DQBUF ioctls.
-	0x10: Log the poll file operation.
+===== ================================================================
+Mask  Description
+===== ================================================================
+0x01  Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are
+      only logged if bit 0x08 is also set.
+0x02  Log the ioctl name arguments and error code. VIDIOC_(D)QBUF
+      ioctls are
+      only logged if bit 0x08 is also set.
+0x04  Log the file operations open, release, read, write, mmap and
+      get_unmapped_area. The read and write operations are only
+      logged if bit 0x08 is also set.
+0x08  Log the read and write file operations and the VIDIOC_QBUF and
+      VIDIOC_DQBUF ioctls.
+0x10  Log the poll file operation.
+===== ================================================================
 
-video_device cleanup
+Video device cleanup
 --------------------
 
 When the video device nodes have to be removed, either during the unload
 of the driver or because the USB device was disconnected, then you should
-unregister them:
+unregister them with:
 
-.. code-block:: none
-
-	video_unregister_device(vdev);
+	:cpp:func:`video_unregister_device`
+	(:c:type:`vdev <video_device>`);
 
 This will remove the device nodes from sysfs (causing udev to remove them
-from /dev).
+from ``/dev``).
 
-After video_unregister_device() returns no new opens can be done. However,
-in the case of USB devices some application might still have one of these
-device nodes open. So after the unregister all file operations (except
+After :cpp:func:`video_unregister_device` returns no new opens can be done.
+However, in the case of USB devices some application might still have one of
+these device nodes open. So after the unregister all file operations (except
 release, of course) will return an error as well.
 
-When the last user of the video device node exits, then the vdev->release()
+When the last user of the video device node exits, then the ``vdev->release()``
 callback is called and you can do the final cleanup there.
 
 Don't forget to cleanup the media entity associated with the video device if
 it has been initialized:
 
-.. code-block:: none
-
-	media_entity_cleanup(&vdev->entity);
+	:cpp:func:`media_entity_cleanup <media_entity_cleanup>`
+	(&vdev->entity);
 
 This can be done from the release callback.
 
@@ -293,45 +314,44 @@ video_device helper functions
 
 There are a few useful helper functions:
 
-- file/video_device private data
+- file and :c:type:`video_device` private data
 
 You can set/get driver private data in the video_device struct using:
 
-.. code-block:: none
+	:cpp:func:`video_get_drvdata <video_get_drvdata>`
+	(:c:type:`vdev <video_device>`);
 
-	void *video_get_drvdata(struct video_device *vdev);
-	void video_set_drvdata(struct video_device *vdev, void *data);
+	:cpp:func:`video_set_drvdata <video_set_drvdata>`
+	(:c:type:`vdev <video_device>`);
 
-Note that you can safely call video_set_drvdata() before calling
-video_register_device().
+Note that you can safely call :cpp:func:`video_set_drvdata` before calling
+:cpp:func:`video_register_device`.
 
 And this function:
 
-.. code-block:: none
-
-	struct video_device *video_devdata(struct file *file);
+	:cpp:func:`video_devdata <video_devdata>`
+	(struct file \*file);
 
 returns the video_device belonging to the file struct.
 
-The video_drvdata function combines video_get_drvdata with video_devdata:
+The :cpp:func:`video_devdata` function combines :cpp:func:`video_get_drvdata`
+with :cpp:func:`video_devdata`:
 
-.. code-block:: none
+	:cpp:func:`video_drvdata <video_drvdata>`
+	(struct file \*file);
 
-	void *video_drvdata(struct file *file);
+You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
 
-You can go from a video_device struct to the v4l2_device struct using:
-
-.. code-block:: none
+.. code-block:: c
 
 	struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
 
 - Device node name
 
-The video_device node kernel name can be retrieved using
+The :c:type:`video_device` node kernel name can be retrieved using:
 
-.. code-block:: none
-
-	const char *video_device_node_name(struct video_device *vdev);
+	:cpp:func:`video_device_node_name <video_device_node_name>`
+	(:c:type:`vdev <video_device>`);
 
 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
diff --git a/Documentation/media/kapi/v4l2-videobuf.rst b/Documentation/media/kapi/v4l2-videobuf.rst
index 01156728203c..54adfd772d28 100644
--- a/Documentation/media/kapi/v4l2-videobuf.rst
+++ b/Documentation/media/kapi/v4l2-videobuf.rst
@@ -1,3 +1,5 @@
+.. _vb_framework:
+
 Videobuf Framework
 ==================
 
diff --git a/Documentation/media/kapi/v4l2-videobuf2.rst b/Documentation/media/kapi/v4l2-videobuf2.rst
index b4f2d6983ef3..bdb8b83f1ea0 100644
--- a/Documentation/media/kapi/v4l2-videobuf2.rst
+++ b/Documentation/media/kapi/v4l2-videobuf2.rst
@@ -1,3 +1,5 @@
+.. _vb2_framework:
+
 V4L2 videobuf2 kAPI
 ^^^^^^^^^^^^^^^^^^^
 
-- 
2.7.4