Merge branch 'synaptics-rmi4' into next

Merge updated Synaptics RMI4 support, including support for SMBus
controllers and flashing firmware.

30 files changed, 1626 insertions, 600 deletions

diff --git a/include/linux/platform_data/media/camera-pxa.h b/include/linux/platform_data/media/camera-pxa.h
index 6709b1cd7c77..ce5d90e1a6e4 100644
--- a/include/linux/platform_data/media/camera-pxa.h
+++ b/include/linux/platform_data/media/camera-pxa.h
@@ -37,6 +37,8 @@
 struct pxacamera_platform_data {
 	unsigned long flags;
 	unsigned long mclk_10khz;
+	int sensor_i2c_adapter_id;
+	int sensor_i2c_address;
 };
 
 extern void pxa_set_camera_info(struct pxacamera_platform_data *);
diff --git a/include/linux/rmi.h b/include/linux/rmi.h
index e0aca1476001..64125443f8a6 100644
--- a/include/linux/rmi.h
+++ b/include/linux/rmi.h
@@ -13,6 +13,7 @@
 #include <linux/device.h>
 #include <linux/interrupt.h>
 #include <linux/input.h>
+#include <linux/kfifo.h>
 #include <linux/list.h>
 #include <linux/module.h>
 #include <linux/types.h>
@@ -99,6 +100,8 @@ struct rmi_2d_sensor_platform_data {
 	bool topbuttonpad;
 	bool kernel_tracking;
 	int dmax;
+	int dribble;
+	int palm_detect;
 };
 
 /**
@@ -106,7 +109,7 @@ struct rmi_2d_sensor_platform_data {
  * @buttonpad - the touchpad is a buttonpad, so enable only the first actual
  * button that is found.
  * @trackstick_buttons - Set when the function 30 is handling the physical
- * buttons of the trackstick (as a PD/2 passthrough device.
+ * buttons of the trackstick (as a PS/2 passthrough device).
  * @disable - the touchpad incorrectly reports F30 and it should be ignored.
  * This is a special case which is due to misconfigured firmware.
  */
@@ -116,14 +119,17 @@ struct rmi_f30_data {
 	bool disable;
 };
 
-/**
- * struct rmi_f01_power - override default power management settings.
- *
+
+/*
+ * Set the state of a register
+ *	DEFAULT - use the default value set by the firmware config
+ *	OFF - explicitly disable the register
+ *	ON - explicitly enable the register
  */
-enum rmi_f01_nosleep {
-	RMI_F01_NOSLEEP_DEFAULT = 0,
-	RMI_F01_NOSLEEP_OFF = 1,
-	RMI_F01_NOSLEEP_ON = 2
+enum rmi_reg_state {
+	RMI_REG_STATE_DEFAULT = 0,
+	RMI_REG_STATE_OFF = 1,
+	RMI_REG_STATE_ON = 2
 };
 
 /**
@@ -143,7 +149,7 @@ enum rmi_f01_nosleep {
  * when the touch sensor is in doze mode, in units of 10ms.
  */
 struct rmi_f01_power_management {
-	enum rmi_f01_nosleep nosleep;
+	enum rmi_reg_state nosleep;
 	u8 wakeup_threshold;
 	u8 doze_holdoff;
 	u8 doze_interval;
@@ -204,16 +210,18 @@ struct rmi_device_platform_data_spi {
  * @reset_delay_ms - after issuing a reset command to the touch sensor, the
  * driver waits a few milliseconds to give the firmware a chance to
  * to re-initialize.  You can override the default wait period here.
+ * @irq: irq associated with the attn gpio line, or negative
  */
 struct rmi_device_platform_data {
 	int reset_delay_ms;
+	int irq;
 
 	struct rmi_device_platform_data_spi spi_data;
 
 	/* function handler pdata */
-	struct rmi_2d_sensor_platform_data *sensor_pdata;
+	struct rmi_2d_sensor_platform_data sensor_pdata;
 	struct rmi_f01_power_management power_management;
-	struct rmi_f30_data *f30_data;
+	struct rmi_f30_data f30_data;
 };
 
 /**
@@ -264,9 +272,6 @@ struct rmi_transport_dev {
 	struct rmi_device_platform_data pdata;
 
 	struct input_dev *input;
-
-	void *attn_data;
-	int attn_size;
 };
 
 /**
@@ -324,17 +329,24 @@ struct rmi_device {
 
 };
 
+struct rmi4_attn_data {
+	unsigned long irq_status;
+	size_t size;
+	void *data;
+};
+
 struct rmi_driver_data {
 	struct list_head function_list;
 
 	struct rmi_device *rmi_dev;
 
 	struct rmi_function *f01_container;
-	bool f01_bootloader_mode;
+	struct rmi_function *f34_container;
+	bool bootloader_mode;
 
-	u32 attn_count;
 	int num_of_irq_regs;
 	int irq_count;
+	void *irq_memory;
 	unsigned long *irq_status;
 	unsigned long *fn_irq_bits;
 	unsigned long *current_irq_mask;
@@ -343,17 +355,23 @@ struct rmi_driver_data {
 	struct input_dev *input;
 
 	u8 pdt_props;
-	u8 bsr;
+
+	u8 num_rx_electrodes;
+	u8 num_tx_electrodes;
 
 	bool enabled;
+	struct mutex enabled_mutex;
 
-	void *data;
+	struct rmi4_attn_data attn_data;
+	DECLARE_KFIFO(attn_fifo, struct rmi4_attn_data, 16);
 };
 
 int rmi_register_transport_device(struct rmi_transport_dev *xport);
 void rmi_unregister_transport_device(struct rmi_transport_dev *xport);
-int rmi_process_interrupt_requests(struct rmi_device *rmi_dev);
 
-int rmi_driver_suspend(struct rmi_device *rmi_dev);
-int rmi_driver_resume(struct rmi_device *rmi_dev);
+void rmi_set_attn_data(struct rmi_device *rmi_dev, unsigned long irq_status,
+		       void *data, size_t size);
+
+int rmi_driver_suspend(struct rmi_device *rmi_dev, bool enable_wake);
+int rmi_driver_resume(struct rmi_device *rmi_dev, bool clear_wake);
 #endif
diff --git a/include/media/drv-intf/sh_mobile_ceu.h b/include/media/drv-intf/sh_mobile_ceu.h
index 7f57056c22ba..2f43f7d9e28d 100644
--- a/include/media/drv-intf/sh_mobile_ceu.h
+++ b/include/media/drv-intf/sh_mobile_ceu.h
@@ -21,7 +21,6 @@ struct sh_mobile_ceu_info {
 	unsigned long flags;
 	int max_width;
 	int max_height;
-	struct sh_mobile_ceu_companion *csi2;
 	struct v4l2_async_subdev **asd;	/* Flat array, arranged in groups */
 	unsigned int *asd_sizes;	/* 0-terminated array pf asd group sizes */
 };
diff --git a/include/media/drv-intf/sh_mobile_csi2.h b/include/media/drv-intf/sh_mobile_csi2.h
deleted file mode 100644
index 14030db51f13..000000000000
--- a/include/media/drv-intf/sh_mobile_csi2.h
+++ /dev/null
@@ -1,48 +0,0 @@
-/*
- * Driver header for the SH-Mobile MIPI CSI-2 unit
- *
- * Copyright (C) 2010, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- */
-
-#ifndef SH_MIPI_CSI
-#define SH_MIPI_CSI
-
-#include <linux/list.h>
-
-enum sh_csi2_phy {
-	SH_CSI2_PHY_MAIN,
-	SH_CSI2_PHY_SUB,
-};
-
-enum sh_csi2_type {
-	SH_CSI2C,
-	SH_CSI2I,
-};
-
-#define SH_CSI2_CRC	(1 << 0)
-#define SH_CSI2_ECC	(1 << 1)
-
-struct platform_device;
-
-struct sh_csi2_client_config {
-	enum sh_csi2_phy phy;
-	unsigned char lanes;		/* bitmask[3:0] */
-	unsigned char channel;		/* 0..3 */
-	struct platform_device *pdev;	/* client platform device */
-	const char *name;		/* async matching: client name */
-};
-
-struct v4l2_device;
-
-struct sh_csi2_pdata {
-	enum sh_csi2_type type;
-	unsigned int flags;
-	struct sh_csi2_client_config *clients;
-	int num_clients;
-};
-
-#endif
diff --git a/include/media/i2c/smiapp.h b/include/media/i2c/smiapp.h
index 029142ddb95c..635007e7441a 100644
--- a/include/media/i2c/smiapp.h
+++ b/include/media/i2c/smiapp.h
@@ -36,8 +36,6 @@
 #define SMIAPP_CSI_SIGNALLING_MODE_CCP2_DATA_STROBE	1
 #define SMIAPP_CSI_SIGNALLING_MODE_CSI2			2
 
-#define SMIAPP_NO_XSHUTDOWN	-1
-
 /*
  * Sometimes due to board layout considerations the camera module can be
  * mounted rotated. The typical rotation used is 180 degrees which can be
@@ -57,7 +55,7 @@ struct smiapp_flash_strobe_parms {
 	u8 trigger;
 };
 
-struct smiapp_platform_data {
+struct smiapp_hwconfig {
 	/*
 	 * Change the cci address if i2c_addr_alt is set.
 	 * Both default and alternate cci addr need to be present
@@ -75,9 +73,6 @@ struct smiapp_platform_data {
 	enum smiapp_module_board_orient module_board_orient;
 
 	struct smiapp_flash_strobe_parms *strobe_setup;
-
-	int (*set_xclk)(struct v4l2_subdev *sd, int hz);
-	int32_t xshutdown;		/* gpio or SMIAPP_NO_XSHUTDOWN */
 };
 
 #endif /* __SMIAPP_H_  */
diff --git a/include/media/media-device.h b/include/media/media-device.h
index 28195242386c..ef93e21335df 100644
--- a/include/media/media-device.h
+++ b/include/media/media-device.h
@@ -49,11 +49,21 @@ struct media_entity_notify {
 };
 
 /**
+ * struct media_device_ops - Media device operations
+ * @link_notify: Link state change notification callback. This callback is
+ *		 called with the graph_mutex held.
+ */
+struct media_device_ops {
+	int (*link_notify)(struct media_link *link, u32 flags,
+			   unsigned int notification);
+};
+
+/**
  * struct media_device - Media device
  * @dev:	Parent device
  * @devnode:	Media device node
  * @driver_name: Optional device driver name. If not set, calls to
- *		%MEDIA_IOC_DEVICE_INFO will return dev->driver->name.
+ *		%MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``.
  *		This is needed for USB drivers for example, as otherwise
  *		they'll all appear as if the driver name was "usb".
  * @model:	Device model name
@@ -80,8 +90,7 @@ struct media_entity_notify {
  * @enable_source: Enable Source Handler function pointer
  * @disable_source: Disable Source Handler function pointer
  *
- * @link_notify: Link state change notification callback. This callback is
- *		 called with the graph_mutex held.
+ * @ops:	Operation handler callbacks
  *
  * This structure represents an abstract high-level media device. It allows easy
  * access to entities and provides basic media device-level support. The
@@ -102,16 +111,18 @@ struct media_entity_notify {
  * sink entity  and deactivate the link between them. Drivers
  * should call this handler to release the source.
  *
- * Note: Bridge driver is expected to implement and set the
- * handler when media_device is registered or when
- * bridge driver finds the media_device during probe.
- * Bridge driver sets source_priv with information
- * necessary to run enable/disable source handlers.
- *
  * Use-case: find tuner entity connected to the decoder
  * entity and check if it is available, and activate the
- * the link between them from enable_source and deactivate
- * from disable_source.
+ * the link between them from @enable_source and deactivate
+ * from @disable_source.
+ *
+ * .. note::
+ *
+ *    Bridge driver is expected to implement and set the
+ *    handler when &media_device is registered or when
+ *    bridge driver finds the media_device during probe.
+ *    Bridge driver sets source_priv with information
+ *    necessary to run @enable_source and @disable_source handlers.
  */
 struct media_device {
 	/* dev->driver_data points to this struct. */
@@ -148,8 +159,7 @@ struct media_device {
 			     struct media_pipeline *pipe);
 	void (*disable_source)(struct media_entity *entity);
 
-	int (*link_notify)(struct media_link *link, u32 flags,
-			   unsigned int notification);
+	const struct media_device_ops *ops;
 };
 
 /* We don't need to include pci.h or usb.h here */
@@ -168,7 +178,7 @@ struct usb_device;
  * @ent_enum: Entity enumeration to be initialised
  * @mdev: The related media device
  *
- * Returns zero on success or a negative error code.
+ * Return: zero on success or a negative error code.
  */
 static inline __must_check int media_entity_enum_init(
 	struct media_entity_enum *ent_enum, struct media_device *mdev)
@@ -211,36 +221,38 @@ void media_device_cleanup(struct media_device *mdev);
  *
  * Users, should, instead, call the media_device_register() macro.
  *
- * The caller is responsible for initializing the media_device structure before
- * registration. The following fields must be set:
+ * The caller is responsible for initializing the &media_device structure
+ * before registration. The following fields of &media_device must be set:
  *
- *  - dev must point to the parent device (usually a &pci_dev, &usb_interface or
- *    &platform_device instance).
+ *  - &media_entity.dev must point to the parent device (usually a &pci_dev,
+ *    &usb_interface or &platform_device instance).
  *
- *  - model must be filled with the device model name as a NUL-terminated UTF-8
- *    string. The device/model revision must not be stored in this field.
+ *  - &media_entity.model must be filled with the device model name as a
+ *    NUL-terminated UTF-8 string. The device/model revision must not be
+ *    stored in this field.
  *
  * The following fields are optional:
  *
- *  - serial is a unique serial number stored as a NUL-terminated ASCII string.
- *    The field is big enough to store a GUID in text form. If the hardware
- *    doesn't provide a unique serial number this field must be left empty.
+ *  - &media_entity.serial is a unique serial number stored as a
+ *    NUL-terminated ASCII string. The field is big enough to store a GUID
+ *    in text form. If the hardware doesn't provide a unique serial number
+ *    this field must be left empty.
  *
- *  - bus_info represents the location of the device in the system as a
- *    NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to
- *    "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices,
- *    the usb_make_path() function must be used. This field is used by
- *    applications to distinguish between otherwise identical devices that don't
- *    provide a serial number.
+ *  - &media_entity.bus_info represents the location of the device in the
+ *    system as a NUL-terminated ASCII string. For PCI/PCIe devices
+ *    &media_entity.bus_info must be set to "PCI:" (or "PCIe:") followed by
+ *    the value of pci_name(). For USB devices,the usb_make_path() function
+ *    must be used. This field is used by applications to distinguish between
+ *    otherwise identical devices that don't provide a serial number.
  *
- *  - hw_revision is the hardware device revision in a driver-specific format.
- *    When possible the revision should be formatted with the KERNEL_VERSION
- *    macro.
+ *  - &media_entity.hw_revision is the hardware device revision in a
+ *    driver-specific format. When possible the revision should be formatted
+ *    with the KERNEL_VERSION() macro.
  *
- *  - driver_version is formatted with the KERNEL_VERSION macro. The version
- *    minor must be incremented when new features are added to the userspace API
- *    without breaking binary compatibility. The version major must be
- *    incremented when binary compatibility is broken.
+ *  - &media_entity.driver_version is formatted with the KERNEL_VERSION()
+ *    macro. The version minor must be incremented when new features are added
+ *    to the userspace API without breaking binary compatibility. The version
+ *    major must be incremented when binary compatibility is broken.
  *
  * .. note::
  *
@@ -252,6 +264,16 @@ void media_device_cleanup(struct media_device *mdev);
  */
 int __must_check __media_device_register(struct media_device *mdev,
 					 struct module *owner);
+
+
+/**
+ * media_device_register() - Registers a media device element
+ *
+ * @mdev:	pointer to struct &media_device
+ *
+ * This macro calls __media_device_register() passing %THIS_MODULE as
+ * the __media_device_register() second argument (**owner**).
+ */
 #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE)
 
 /**
@@ -259,7 +281,6 @@ int __must_check __media_device_register(struct media_device *mdev,
  *
  * @mdev:	pointer to struct &media_device
  *
- *
  * It is safe to call this function on an unregistered (but initialised)
  * media device.
  */
@@ -285,14 +306,15 @@ void media_device_unregister(struct media_device *mdev);
  * framework.
  *
  * If the device has pads, media_entity_pads_init() should be called before
- * this function. Otherwise, the &media_entity.@pad and &media_entity.@num_pads
+ * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads
  * should be zeroed before calling this function.
  *
  * Entities have flags that describe the entity capabilities and state:
  *
- * %MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type.
- *	This can be used to report the default audio and video devices or the
- *	default camera sensor.
+ * %MEDIA_ENT_FL_DEFAULT
+ *    indicates the default entity for a given type.
+ *    This can be used to report the default audio and video devices or the
+ *    default camera sensor.
  *
  * .. note::
  *
@@ -331,8 +353,10 @@ void media_device_unregister_entity(struct media_entity *entity);
  * @mdev:      The media device
  * @nptr:      The media_entity_notify
  *
- * Note: When a new entity is registered, all the registered
- * media_entity_notify callbacks are invoked.
+ * .. note::
+ *
+ *    When a new entity is registered, all the registered
+ *    media_entity_notify callbacks are invoked.
  */
 
 int __must_check media_device_register_entity_notify(struct media_device *mdev,
@@ -410,11 +434,13 @@ void media_device_pci_init(struct media_device *mdev,
  * @board_name:	media device name. If %NULL, the routine will use the usb
  *		product name, if available.
  * @driver_name: name of the driver. if %NULL, the routine will use the name
- *		given by udev->dev->driver->name, with is usually the wrong
+ *		given by ``udev->dev->driver->name``, with is usually the wrong
  *		thing to do.
  *
- * NOTE: It is better to call media_device_usb_init() instead, as
- * such macro fills driver_name with %KBUILD_MODNAME.
+ * .. note::
+ *
+ *    It is better to call media_device_usb_init() instead, as
+ *    such macro fills driver_name with %KBUILD_MODNAME.
  */
 void __media_device_usb_init(struct media_device *mdev,
 			     struct usb_device *udev,
@@ -472,6 +498,19 @@ static inline void __media_device_usb_init(struct media_device *mdev,
 
 #endif /* CONFIG_MEDIA_CONTROLLER */
 
+/**
+ * media_device_usb_init() - create and initialize a
+ *	struct &media_device from a PCI device.
+ *
+ * @mdev:	pointer to struct &media_device
+ * @udev:	pointer to struct usb_device
+ * @name:	media device name. If %NULL, the routine will use the usb
+ *		product name, if available.
+ *
+ * This macro calls media_device_usb_init() passing the
+ * media_device_usb_init() **driver_name** parameter filled with
+ * %KBUILD_MODNAME.
+ */
 #define media_device_usb_init(mdev, udev, name) \
 	__media_device_usb_init(mdev, udev, name, KBUILD_MODNAME)
 
diff --git a/include/media/media-devnode.h b/include/media/media-devnode.h
index 37d494805944..cd23e915764c 100644
--- a/include/media/media-devnode.h
+++ b/include/media/media-devnode.h
@@ -75,8 +75,9 @@ struct media_file_operations {
  * @cdev:	struct cdev pointer character device
  * @parent:	parent device
  * @minor:	device node minor number
- * @flags:	flags, combination of the MEDIA_FLAG_* constants
- * @release:	release callback called at the end of media_devnode_release()
+ * @flags:	flags, combination of the ``MEDIA_FLAG_*`` constants
+ * @release:	release callback called at the end of ``media_devnode_release()``
+ *		routine at media-device.c.
  *
  * This structure represents a media-related device node.
  *
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index 09b03c17784d..b2203ee7a4c1 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -56,7 +56,7 @@ enum media_gobj_type {
 /**
  * struct media_gobj - Define a graph object.
  *
- * @mdev:	Pointer to the struct media_device that owns the object
+ * @mdev:	Pointer to the struct &media_device that owns the object
  * @id:		Non-zero object ID identifier. The ID should be unique
  *		inside a media_device, as it is composed by
  *		%MEDIA_BITS_PER_TYPE to store the type plus
@@ -129,7 +129,7 @@ struct media_pipeline {
  *		an interface.
  * @gobj1:	Part of a union. Used to get the pointer for the second
  *		graph_object of the link.
- * @source:	Part of a union. Used only if the second object (gobj1) is
+ * @sink:	Part of a union. Used only if the second object (gobj1) is
  *		a pad. In that case, it represents the sink pad.
  * @entity:	Part of a union. Used only if the second object (gobj1) is
  *		an entity.
@@ -162,7 +162,9 @@ struct media_link {
  * @graph_obj:	Embedded structure containing the media object common data
  * @entity:	Entity this pad belongs to
  * @index:	Pad index in the entity pads array, numbered from 0 to n
- * @flags:	Pad flags, as defined in uapi/media.h (MEDIA_PAD_FL_*)
+ * @flags:	Pad flags, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		(seek for ``MEDIA_PAD_FL_*``)
  */
 struct media_pad {
 	struct media_gobj graph_obj;	/* must be first field in struct */
@@ -182,7 +184,7 @@ struct media_pad {
  *
  * .. note::
  *
- *    Those these callbacks are called with struct media_device.@graph_mutex
+ *    Those these callbacks are called with struct &media_device.graph_mutex
  *    mutex held.
  */
 struct media_entity_operations {
@@ -210,7 +212,7 @@ struct media_entity_operations {
  * This allows runtime type identification of media entities and safe casting to
  * the correct object type. For instance, a media entity structure instance
  * embedded in a v4l2_subdev structure instance will have the type
- * MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a v4l2_subdev
+ * %MEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to a &v4l2_subdev
  * structure using the container_of() macro.
  */
 enum media_entity_type {
@@ -225,9 +227,12 @@ enum media_entity_type {
  * @graph_obj:	Embedded structure containing the media object common data.
  * @name:	Entity name.
  * @obj_type:	Type of the object that implements the media_entity.
- * @function:	Entity main function, as defined in uapi/media.h
- *		(MEDIA_ENT_F_*)
- * @flags:	Entity flags, as defined in uapi/media.h (MEDIA_ENT_FL_*)
+ * @function:	Entity main function, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		(seek for ``MEDIA_ENT_F_*``)
+ * @flags:	Entity flags, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		(seek for ``MEDIA_ENT_FL_*``)
  * @num_pads:	Number of sink and source pads.
  * @num_links:	Total number of links, forward and back, enabled and disabled.
  * @num_backlinks: Number of backlinks
@@ -246,9 +251,12 @@ enum media_entity_type {
  * @minor:	Devnode minor number (zero if not applicable). Kept just
  *		for backward compatibility.
  *
- * NOTE: @stream_count and @use_count reference counts must never be
- * negative, but are signed integers on purpose: a simple WARN_ON(<0) check
- * can be used to detect reference count bugs that would make them negative.
+ * .. note::
+ *
+ *    @stream_count and @use_count reference counts must never be
+ *    negative, but are signed integers on purpose: a simple ``WARN_ON(<0)``
+ *    check can be used to detect reference count bugs that would make them
+ *    negative.
  */
 struct media_entity {
 	struct media_gobj graph_obj;	/* must be first field in struct */
@@ -267,10 +275,6 @@ struct media_entity {
 
 	const struct media_entity_operations *ops;
 
-	/* Reference counts must never be negative, but are signed integers on
-	 * purpose: a simple WARN_ON(<0) check can be used to detect reference
-	 * count bugs that would make them negative.
-	 */
 	int stream_count;
 	int use_count;
 
@@ -289,10 +293,16 @@ struct media_entity {
  *
  * @graph_obj:		embedded graph object
  * @links:		List of links pointing to graph entities
- * @type:		Type of the interface as defined in the
- *			uapi/media/media.h header, e. g.
- *			MEDIA_INTF_T_*
- * @flags:		Interface flags as defined in uapi/media/media.h
+ * @type:		Type of the interface as defined in
+ *			:ref:`include/uapi/linux/media.h <media_header>`
+ *			(seek for ``MEDIA_INTF_T_*``)
+ * @flags:		Interface flags as defined in
+ *			:ref:`include/uapi/linux/media.h <media_header>`
+ *			(seek for ``MEDIA_INTF_FL_*``)
+ *
+ * .. note::
+ *
+ *    Currently, no flags for &media_interface is defined.
  */
 struct media_interface {
 	struct media_gobj		graph_obj;
@@ -319,7 +329,7 @@ struct media_intf_devnode {
 /**
  * media_entity_id() - return the media entity graph object id
  *
- * @entity:	pointer to entity
+ * @entity:	pointer to &media_entity
  */
 static inline u32 media_entity_id(struct media_entity *entity)
 {
@@ -329,7 +339,7 @@ static inline u32 media_entity_id(struct media_entity *entity)
 /**
  * media_type() - return the media object type
  *
- * @gobj:	pointer to the media graph object
+ * @gobj:	Pointer to the struct &media_gobj graph object
  */
 static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 {
@@ -339,7 +349,7 @@ static inline enum media_gobj_type media_type(struct media_gobj *gobj)
 /**
  * media_id() - return the media object ID
  *
- * @gobj:	pointer to the media graph object
+ * @gobj:	Pointer to the struct &media_gobj graph object
  */
 static inline u32 media_id(struct media_gobj *gobj)
 {
@@ -350,7 +360,7 @@ static inline u32 media_id(struct media_gobj *gobj)
  * media_gobj_gen_id() - encapsulates type and ID on at the object ID
  *
  * @type:	object type as define at enum &media_gobj_type.
- * @local_id:	next ID, from struct &media_device.@id.
+ * @local_id:	next ID, from struct &media_device.id.
  */
 static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id)
 {
@@ -366,9 +376,9 @@ static inline u32 media_gobj_gen_id(enum media_gobj_type type, u64 local_id)
  * is_media_entity_v4l2_video_device() - Check if the entity is a video_device
  * @entity:	pointer to entity
  *
- * Return: true if the entity is an instance of a video_device object and can
+ * Return: %true if the entity is an instance of a video_device object and can
  * safely be cast to a struct video_device using the container_of() macro, or
- * false otherwise.
+ * %false otherwise.
  */
 static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity)
 {
@@ -379,9 +389,9 @@ static inline bool is_media_entity_v4l2_video_device(struct media_entity *entity
  * is_media_entity_v4l2_subdev() - Check if the entity is a v4l2_subdev
  * @entity:	pointer to entity
  *
- * Return: true if the entity is an instance of a v4l2_subdev object and can
- * safely be cast to a struct v4l2_subdev using the container_of() macro, or
- * false otherwise.
+ * Return: %true if the entity is an instance of a &v4l2_subdev object and can
+ * safely be cast to a struct &v4l2_subdev using the container_of() macro, or
+ * %false otherwise.
  */
 static inline bool is_media_entity_v4l2_subdev(struct media_entity *entity)
 {
@@ -452,7 +462,7 @@ static inline void media_entity_enum_clear(struct media_entity_enum *ent_enum,
  * @ent_enum: Entity enumeration
  * @entity: Entity to be tested
  *
- * Returns true if the entity was marked.
+ * Returns %true if the entity was marked.
  */
 static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
 					  struct media_entity *entity)
@@ -464,12 +474,13 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
 }
 
 /**
- * media_entity_enum_test - Test whether the entity is marked, and mark it
+ * media_entity_enum_test_and_set - Test whether the entity is marked,
+ *	and mark it
  *
  * @ent_enum: Entity enumeration
  * @entity: Entity to be tested
  *
- * Returns true if the entity was marked, and mark it before doing so.
+ * Returns %true if the entity was marked, and mark it before doing so.
  */
 static inline bool
 media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
@@ -486,7 +497,7 @@ media_entity_enum_test_and_set(struct media_entity_enum *ent_enum,
  *
  * @ent_enum: Entity enumeration
  *
- * Returns true if the entity was marked.
+ * Return: %true if the entity was empty.
  */
 static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
 {
@@ -499,7 +510,8 @@ static inline bool media_entity_enum_empty(struct media_entity_enum *ent_enum)
  * @ent_enum1: First entity enumeration
  * @ent_enum2: Second entity enumeration
  *
- * Returns true if entity enumerations e and f intersect, otherwise false.
+ * Return: %true if entity enumerations @ent_enum1 and @ent_enum2 intersect,
+ * otherwise %false.
  */
 static inline bool media_entity_enum_intersects(
 	struct media_entity_enum *ent_enum1,
@@ -511,39 +523,63 @@ static inline bool media_entity_enum_intersects(
 				 min(ent_enum1->idx_max, ent_enum2->idx_max));
 }
 
+/**
+ * gobj_to_entity - returns the struct &media_entity pointer from the
+ *	@gobj contained on it.
+ *
+ * @gobj: Pointer to the struct &media_gobj graph object
+ */
 #define gobj_to_entity(gobj) \
 		container_of(gobj, struct media_entity, graph_obj)
 
+/**
+ * gobj_to_pad - returns the struct &media_pad pointer from the
+ *	@gobj contained on it.
+ *
+ * @gobj: Pointer to the struct &media_gobj graph object
+ */
 #define gobj_to_pad(gobj) \
 		container_of(gobj, struct media_pad, graph_obj)
 
+/**
+ * gobj_to_link - returns the struct &media_link pointer from the
+ *	@gobj contained on it.
+ *
+ * @gobj: Pointer to the struct &media_gobj graph object
+ */
 #define gobj_to_link(gobj) \
 		container_of(gobj, struct media_link, graph_obj)
 
-#define gobj_to_link(gobj) \
-		container_of(gobj, struct media_link, graph_obj)
-
-#define gobj_to_pad(gobj) \
-		container_of(gobj, struct media_pad, graph_obj)
-
+/**
+ * gobj_to_intf - returns the struct &media_interface pointer from the
+ *	@gobj contained on it.
+ *
+ * @gobj: Pointer to the struct &media_gobj graph object
+ */
 #define gobj_to_intf(gobj) \
 		container_of(gobj, struct media_interface, graph_obj)
 
+/**
+ * intf_to_devnode - returns the struct media_intf_devnode pointer from the
+ *	@intf contained on it.
+ *
+ * @intf: Pointer to struct &media_intf_devnode
+ */
 #define intf_to_devnode(intf) \
 		container_of(intf, struct media_intf_devnode, intf)
 
 /**
  *  media_gobj_create - Initialize a graph object
  *
- * @mdev:	Pointer to the media_device that contains the object
+ * @mdev:	Pointer to the &media_device that contains the object
  * @type:	Type of the object
- * @gobj:	Pointer to the graph object
+ * @gobj:	Pointer to the struct &media_gobj graph object
  *
- * This routine initializes the embedded struct media_gobj inside a
- * media graph object. It is called automatically if media_*_create\(\)
- * calls are used. However, if the object (entity, link, pad, interface)
- * is embedded on some other object, this function should be called before
- * registering the object at the media controller.
+ * This routine initializes the embedded struct &media_gobj inside a
+ * media graph object. It is called automatically if ``media_*_create``
+ * function calls are used. However, if the object (entity, link, pad,
+ * interface) is embedded on some other object, this function should be
+ * called before registering the object at the media controller.
  */
 void media_gobj_create(struct media_device *mdev,
 		    enum media_gobj_type type,
@@ -552,7 +588,7 @@ void media_gobj_create(struct media_device *mdev,
 /**
  *  media_gobj_destroy - Stop using a graph object on a media device
  *
- * @gobj:	Pointer to the graph object
+ * @gobj:	Pointer to the struct &media_gobj graph object
  *
  * This should be called by all routines like media_device_unregister()
  * that remove/destroy media graph objects.
@@ -567,11 +603,11 @@ void media_gobj_destroy(struct media_gobj *gobj);
  * @pads:	Array of @num_pads pads.
  *
  * The pads array is managed by the entity driver and passed to
- * media_entity_pads_init() where its pointer will be stored in the entity
- * structure.
+ * media_entity_pads_init() where its pointer will be stored in the
+ * &media_entity structure.
  *
  * If no pads are needed, drivers could either directly fill
- * &media_entity->@num_pads with 0 and &media_entity->@pads with NULL or call
+ * &media_entity->num_pads with 0 and &media_entity->pads with %NULL or call
  * this function that will do the same.
  *
  * As the number of pads is known in advance, the pads array is not allocated
@@ -601,18 +637,21 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
  * @source_pad:	number of the source pad in the pads array
  * @sink:	pointer to &media_entity of the sink pad.
  * @sink_pad:	number of the sink pad in the pads array.
- * @flags:	Link flags, as defined in include/uapi/linux/media.h.
+ * @flags:	Link flags, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		( seek for ``MEDIA_LNK_FL_*``)
  *
  * Valid values for flags:
  *
- * - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can
- *   be used to transfer media data. When two or more links target a sink pad,
- *   only one of them can be enabled at a time.
+ * %MEDIA_LNK_FL_ENABLED
+ *   Indicates that the link is enabled and can be used to transfer media data.
+ *   When two or more links target a sink pad, only one of them can be
+ *   enabled at a time.
  *
- * - A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
- *   be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
- *   %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
- *   always enabled.
+ * %MEDIA_LNK_FL_IMMUTABLE
+ *   Indicates that the link enabled state can't be modified at runtime. If
+ *   %MEDIA_LNK_FL_IMMUTABLE is set, then %MEDIA_LNK_FL_ENABLED must also be
+ *   set, since an immutable link is always enabled.
  *
  * .. note::
  *
@@ -630,17 +669,17 @@ __must_check int media_create_pad_link(struct media_entity *source,
  * @source_function: Function of the source entities. Used only if @source is
  *	NULL.
  * @source: pointer to &media_entity of the source pad. If NULL, it will use
- * 	all entities that matches the @sink_function.
+ *	all entities that matches the @sink_function.
  * @source_pad: number of the source pad in the pads array
  * @sink_function: Function of the sink entities. Used only if @sink is NULL.
  * @sink: pointer to &media_entity of the sink pad. If NULL, it will use
- * 	all entities that matches the @sink_function.
+ *	all entities that matches the @sink_function.
  * @sink_pad: number of the sink pad in the pads array.
  * @flags: Link flags, as defined in include/uapi/linux/media.h.
- * @allow_both_undefined: if true, then both @source and @sink can be NULL.
+ * @allow_both_undefined: if %true, then both @source and @sink can be NULL.
  *	In such case, it will create a crossbar between all entities that
  *	matches @source_function to all entities that matches @sink_function.
- *	If false, it will return 0 and won't create any link if both @source
+ *	If %false, it will return 0 and won't create any link if both @source
  *	and @sink are NULL.
  *
  * Valid values for flags:
@@ -660,9 +699,11 @@ __must_check int media_create_pad_link(struct media_entity *source,
  * creates link by link, this function is meant to allow 1:n, n:1 and even
  * cross-bar (n:n) links.
  *
- * NOTE: Before calling this function, media_entity_pads_init() and
- * media_device_register_entity() should be called previously for the entities
- * to be linked.
+ * .. note::
+ *
+ *    Before calling this function, media_entity_pads_init() and
+ *    media_device_register_entity() should be called previously for the
+ *    entities to be linked.
  */
 int media_create_pad_links(const struct media_device *mdev,
 			   const u32 source_function,
@@ -721,7 +762,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
  * flags.
  *
  * Media device drivers can be notified of link setup operations by setting the
- * media_device::link_notify pointer to a callback function. If provided, the
+ * &media_device.link_notify pointer to a callback function. If provided, the
  * notification callback will be called before enabling and after disabling
  * links.
  *
@@ -731,7 +772,7 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
  *
  * Link configuration must not have any side effect on other links. If an
  * enabled link at a sink pad prevents another link at the same pad from
- * being enabled, the link_setup operation must return -EBUSY and can't
+ * being enabled, the link_setup operation must return %-EBUSY and can't
  * implicitly disable the first enabled link.
  *
  * .. note::
@@ -747,8 +788,8 @@ int media_entity_setup_link(struct media_link *link, u32 flags);
  * @source: Source pad
  * @sink: Sink pad
  *
- * Return a pointer to the link between the two entities. If no such link
- * exists, return NULL.
+ * Return: returns a pointer to the link between the two entities. If no
+ * such link exists, return %NULL.
  */
 struct media_link *media_entity_find_link(struct media_pad *source,
 		struct media_pad *sink);
@@ -760,8 +801,8 @@ struct media_link *media_entity_find_link(struct media_pad *source,
  * Search for a remote pad connected to the given pad by iterating over all
  * links originating or terminating at that pad until an enabled link is found.
  *
- * Return a pointer to the pad at the remote end of the first found enabled
- * link, or NULL if no enabled link has been found.
+ * Return: returns a pointer to the pad at the remote end of the first found
+ * enabled link, or %NULL if no enabled link has been found.
  */
 struct media_pad *media_entity_remote_pad(struct media_pad *pad);
 
@@ -772,12 +813,18 @@ struct media_pad *media_entity_remote_pad(struct media_pad *pad);
  *
  * Get a reference to the parent media device module.
  *
- * The function will return immediately if @entity is NULL.
+ * The function will return immediately if @entity is %NULL.
  *
- * Return a pointer to the entity on success or NULL on failure.
+ * Return: returns a pointer to the entity on success or %NULL on failure.
  */
 struct media_entity *media_entity_get(struct media_entity *entity);
 
+/**
+ * media_entity_graph_walk_init - Allocate resources used by graph walk.
+ *
+ * @graph: Media graph structure that will be used to walk the graph
+ * @mdev: Pointer to the &media_device that contains the object
+ */
 __must_check int media_entity_graph_walk_init(
 	struct media_entity_graph *graph, struct media_device *mdev);
 
@@ -795,12 +842,14 @@ void media_entity_graph_walk_cleanup(struct media_entity_graph *graph);
  *
  * Release the reference count acquired by media_entity_get().
  *
- * The function will return immediately if @entity is NULL.
+ * The function will return immediately if @entity is %NULL.
  */
 void media_entity_put(struct media_entity *entity);
 
 /**
- * media_entity_graph_walk_start - Start walking the media graph at a given entity
+ * media_entity_graph_walk_start - Start walking the media graph at a
+ *	given entity
+ *
  * @graph: Media graph structure that will be used to walk the graph
  * @entity: Starting entity
  *
@@ -824,8 +873,8 @@ void media_entity_graph_walk_start(struct media_entity_graph *graph,
  * The graph structure must have been previously initialized with a call to
  * media_entity_graph_walk_start().
  *
- * Return the next entity in the graph or NULL if the whole graph have been
- * traversed.
+ * Return: returns the next entity in the graph or %NULL if the whole graph
+ * have been traversed.
  */
 struct media_entity *
 media_entity_graph_walk_next(struct media_entity_graph *graph);
@@ -836,8 +885,8 @@ media_entity_graph_walk_next(struct media_entity_graph *graph);
  * @pipe: Media pipeline to be assigned to all entities in the pipeline.
  *
  * Mark all entities connected to a given entity through enabled links, either
- * directly or indirectly, as streaming. The given pipeline object is assigned to
- * every entity in the pipeline and stored in the media_entity pipe field.
+ * directly or indirectly, as streaming. The given pipeline object is assigned
+ * to every entity in the pipeline and stored in the media_entity pipe field.
  *
  * Calls to this function can be nested, in which case the same number of
  * media_entity_pipeline_stop() calls will be required to stop streaming. The
@@ -863,7 +912,7 @@ __must_check int __media_entity_pipeline_start(struct media_entity *entity,
  *
  * Mark all entities connected to a given entity through enabled links, either
  * directly or indirectly, as not streaming. The media_entity pipe field is
- * reset to NULL.
+ * reset to %NULL.
  *
  * If multiple calls to media_entity_pipeline_start() have been made, the same
  * number of calls to this function are required to mark the pipeline as not
@@ -884,14 +933,21 @@ void __media_entity_pipeline_stop(struct media_entity *entity);
  * media_devnode_create() - creates and initializes a device node interface
  *
  * @mdev:	pointer to struct &media_device
- * @type:	type of the interface, as given by MEDIA_INTF_T_* macros
- *		as defined in the uapi/media/media.h header.
- * @flags:	Interface flags as defined in uapi/media/media.h.
+ * @type:	type of the interface, as given by
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		( seek for ``MEDIA_INTF_T_*``) macros.
+ * @flags:	Interface flags, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		( seek for ``MEDIA_INTF_FL_*``)
  * @major:	Device node major number.
  * @minor:	Device node minor number.
  *
  * Return: if succeeded, returns a pointer to the newly allocated
  *	&media_intf_devnode pointer.
+ *
+ * .. note::
+ *
+ *    Currently, no flags for &media_interface is defined.
  */
 struct media_intf_devnode *
 __must_check media_devnode_create(struct media_device *mdev,
@@ -913,15 +969,19 @@ struct media_link *
  *
  * @entity:	pointer to %media_entity
  * @intf:	pointer to %media_interface
- * @flags:	Link flags, as defined in include/uapi/linux/media.h.
+ * @flags:	Link flags, as defined in
+ *		:ref:`include/uapi/linux/media.h <media_header>`
+ *		( seek for ``MEDIA_LNK_FL_*``)
  *
  *
  * Valid values for flags:
  *
- * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
- *   the entity hardware. That's the default value for interfaces. An
- *   interface may be disabled if the hardware is busy due to the usage
- *   of some other interface that it is currently controlling the hardware.
+ * %MEDIA_LNK_FL_ENABLED
+ *   Indicates that the interface is connected to the entity hardware.
+ *   That's the default value for interfaces. An interface may be disabled if
+ *   the hardware is busy due to the usage of some other interface that it is
+ *   currently controlling the hardware.
+ *
  *   A typical example is an hybrid TV device that handle only one type of
  *   stream on a given time. So, when the digital TV is streaming,
  *   the V4L2 interfaces won't be enabled, as such device is not able to
@@ -977,6 +1037,18 @@ void __media_remove_intf_links(struct media_interface *intf);
  */
 void media_remove_intf_links(struct media_interface *intf);
 
+/**
+ * media_entity_call - Calls a struct media_entity_operations operation on
+ *	an entity
+ *
+ * @entity: entity where the @operation will be called
+ * @operation: type of the operation. Should be the name of a member of
+ *	struct &media_entity_operations.
+ *
+ * This helper function will check if @operation is not %NULL. On such case,
+ * it will issue a call to @operation\(@entity, @args\).
+ */
+
 #define media_entity_call(entity, operation, args...)			\
 	(((entity)->ops && (entity)->ops->operation) ?			\
 	 (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD)
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index 10908e356b23..40188d362486 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -231,7 +231,7 @@ void rc_unregister_device(struct rc_dev *dev);
 int rc_open(struct rc_dev *rdev);
 
 /**
- * rc_open - Closes a RC device
+ * rc_close - Closes a RC device
  *
  * @rdev: pointer to struct rc_dev.
  */
diff --git a/include/media/rc-map.h b/include/media/rc-map.h
index daa75fcc1ff1..e1cc14cba391 100644
--- a/include/media/rc-map.h
+++ b/include/media/rc-map.h
@@ -11,27 +11,55 @@
 
 #include <linux/input.h>
 
+/**
+ * enum rc_type - type of the Remote Controller protocol
+ *
+ * @RC_TYPE_UNKNOWN: Protocol not known
+ * @RC_TYPE_OTHER: Protocol known but proprietary
+ * @RC_TYPE_RC5: Philips RC5 protocol
+ * @RC_TYPE_RC5X: Philips RC5x protocol
+ * @RC_TYPE_RC5_SZ: StreamZap variant of RC5
+ * @RC_TYPE_JVC: JVC protocol
+ * @RC_TYPE_SONY12: Sony 12 bit protocol
+ * @RC_TYPE_SONY15: Sony 15 bit protocol
+ * @RC_TYPE_SONY20: Sony 20 bit protocol
+ * @RC_TYPE_NEC: NEC protocol
+ * @RC_TYPE_NECX: Extended NEC protocol
+ * @RC_TYPE_NEC32: NEC 32 bit protocol
+ * @RC_TYPE_SANYO: Sanyo protocol
+ * @RC_TYPE_MCE_KBD: RC6-ish MCE keyboard/mouse
+ * @RC_TYPE_RC6_0: Philips RC6-0-16 protocol
+ * @RC_TYPE_RC6_6A_20: Philips RC6-6A-20 protocol
+ * @RC_TYPE_RC6_6A_24: Philips RC6-6A-24 protocol
+ * @RC_TYPE_RC6_6A_32: Philips RC6-6A-32 protocol
+ * @RC_TYPE_RC6_MCE: MCE (Philips RC6-6A-32 subtype) protocol
+ * @RC_TYPE_SHARP: Sharp protocol
+ * @RC_TYPE_XMP: XMP protocol
+ * @RC_TYPE_CEC: CEC protocol
+ */
 enum rc_type {
-	RC_TYPE_UNKNOWN		= 0,	/* Protocol not known */
-	RC_TYPE_OTHER		= 1,	/* Protocol known but proprietary */
-	RC_TYPE_RC5		= 2,	/* Philips RC5 protocol */
-	RC_TYPE_RC5X		= 3,	/* Philips RC5x protocol */
-	RC_TYPE_RC5_SZ		= 4,	/* StreamZap variant of RC5 */
-	RC_TYPE_JVC		= 5,	/* JVC protocol */
-	RC_TYPE_SONY12		= 6,	/* Sony 12 bit protocol */
-	RC_TYPE_SONY15		= 7,	/* Sony 15 bit protocol */
-	RC_TYPE_SONY20		= 8,	/* Sony 20 bit protocol */
-	RC_TYPE_NEC		= 9,	/* NEC protocol */
-	RC_TYPE_SANYO		= 10,	/* Sanyo protocol */
-	RC_TYPE_MCE_KBD		= 11,	/* RC6-ish MCE keyboard/mouse */
-	RC_TYPE_RC6_0		= 12,	/* Philips RC6-0-16 protocol */
-	RC_TYPE_RC6_6A_20	= 13,	/* Philips RC6-6A-20 protocol */
-	RC_TYPE_RC6_6A_24	= 14,	/* Philips RC6-6A-24 protocol */
-	RC_TYPE_RC6_6A_32	= 15,	/* Philips RC6-6A-32 protocol */
-	RC_TYPE_RC6_MCE		= 16,	/* MCE (Philips RC6-6A-32 subtype) protocol */
-	RC_TYPE_SHARP		= 17,	/* Sharp protocol */
-	RC_TYPE_XMP		= 18,	/* XMP protocol */
-	RC_TYPE_CEC		= 19,	/* CEC protocol */
+	RC_TYPE_UNKNOWN		= 0,
+	RC_TYPE_OTHER		= 1,
+	RC_TYPE_RC5		= 2,
+	RC_TYPE_RC5X		= 3,
+	RC_TYPE_RC5_SZ		= 4,
+	RC_TYPE_JVC		= 5,
+	RC_TYPE_SONY12		= 6,
+	RC_TYPE_SONY15		= 7,
+	RC_TYPE_SONY20		= 8,
+	RC_TYPE_NEC		= 9,
+	RC_TYPE_NECX		= 10,
+	RC_TYPE_NEC32		= 11,
+	RC_TYPE_SANYO		= 12,
+	RC_TYPE_MCE_KBD		= 13,
+	RC_TYPE_RC6_0		= 14,
+	RC_TYPE_RC6_6A_20	= 15,
+	RC_TYPE_RC6_6A_24	= 16,
+	RC_TYPE_RC6_6A_32	= 17,
+	RC_TYPE_RC6_MCE		= 18,
+	RC_TYPE_SHARP		= 19,
+	RC_TYPE_XMP		= 20,
+	RC_TYPE_CEC		= 21,
 };
 
 #define RC_BIT_NONE		0ULL
@@ -45,6 +73,8 @@ enum rc_type {
 #define RC_BIT_SONY15		(1ULL << RC_TYPE_SONY15)
 #define RC_BIT_SONY20		(1ULL << RC_TYPE_SONY20)
 #define RC_BIT_NEC		(1ULL << RC_TYPE_NEC)
+#define RC_BIT_NECX		(1ULL << RC_TYPE_NECX)
+#define RC_BIT_NEC32		(1ULL << RC_TYPE_NEC32)
 #define RC_BIT_SANYO		(1ULL << RC_TYPE_SANYO)
 #define RC_BIT_MCE_KBD		(1ULL << RC_TYPE_MCE_KBD)
 #define RC_BIT_RC6_0		(1ULL << RC_TYPE_RC6_0)
@@ -60,8 +90,9 @@ enum rc_type {
 			 RC_BIT_RC5 | RC_BIT_RC5X | RC_BIT_RC5_SZ | \
 			 RC_BIT_JVC | \
 			 RC_BIT_SONY12 | RC_BIT_SONY15 | RC_BIT_SONY20 | \
-			 RC_BIT_NEC | RC_BIT_SANYO | RC_BIT_MCE_KBD | \
-			 RC_BIT_RC6_0 | RC_BIT_RC6_6A_20 | RC_BIT_RC6_6A_24 | \
+			 RC_BIT_NEC | RC_BIT_NECX | RC_BIT_NEC32 | \
+			 RC_BIT_SANYO | RC_BIT_MCE_KBD | RC_BIT_RC6_0 | \
+			 RC_BIT_RC6_6A_20 | RC_BIT_RC6_6A_24 | \
 			 RC_BIT_RC6_6A_32 | RC_BIT_RC6_MCE | RC_BIT_SHARP | \
 			 RC_BIT_XMP | RC_BIT_CEC)
 
@@ -76,21 +107,45 @@ enum rc_type {
 #define RC_SCANCODE_RC6_0(sys, cmd)		(((sys) << 8) | (cmd))
 #define RC_SCANCODE_RC6_6A(vendor, sys, cmd)	(((vendor) << 16) | ((sys) << 8) | (cmd))
 
+/**
+ * struct rc_map_table - represents a scancode/keycode pair
+ *
+ * @scancode: scan code (u32)
+ * @keycode: Linux input keycode
+ */
 struct rc_map_table {
 	u32	scancode;
 	u32	keycode;
 };
 
+/**
+ * struct rc_map - represents a keycode map table
+ *
+ * @scan: pointer to struct &rc_map_table
+ * @size: Max number of entries
+ * @len: Number of entries that are in use
+ * @alloc: size of \*scan, in bytes
+ * @rc_type: type of the remote controller protocol, as defined at
+ *	     enum &rc_type
+ * @name: name of the key map table
+ * @lock: lock to protect access to this structure
+ */
 struct rc_map {
 	struct rc_map_table	*scan;
-	unsigned int		size;	/* Max number of entries */
-	unsigned int		len;	/* Used number of entries */
-	unsigned int		alloc;	/* Size of *scan in bytes */
+	unsigned int		size;
+	unsigned int		len;
+	unsigned int		alloc;
 	enum rc_type		rc_type;
 	const char		*name;
 	spinlock_t		lock;
 };
 
+/**
+ * struct rc_map_list - list of the registered &rc_map maps
+ *
+ * @list: pointer to struct &list_head
+ * @map: pointer to struct &rc_map
+ */
 struct rc_map_list {
 	struct list_head	 list;
 	struct rc_map map;
diff --git a/include/media/rcar-fcp.h b/include/media/rcar-fcp.h
index 4c7fc77eaf29..8723f05c6321 100644
--- a/include/media/rcar-fcp.h
+++ b/include/media/rcar-fcp.h
@@ -29,7 +29,7 @@ static inline struct rcar_fcp_device *rcar_fcp_get(const struct device_node *np)
 static inline void rcar_fcp_put(struct rcar_fcp_device *fcp) { }
 static inline int rcar_fcp_enable(struct rcar_fcp_device *fcp)
 {
-	return -ENOSYS;
+	return 0;
 }
 static inline void rcar_fcp_disable(struct rcar_fcp_device *fcp) { }
 #endif
diff --git a/include/media/soc_camera.h b/include/media/soc_camera.h
index 97aa13314bfd..1a15c3e4efd3 100644
--- a/include/media/soc_camera.h
+++ b/include/media/soc_camera.h
@@ -105,16 +105,13 @@ struct soc_camera_host_ops {
 	int (*get_formats)(struct soc_camera_device *, unsigned int,
 			   struct soc_camera_format_xlate *);
 	void (*put_formats)(struct soc_camera_device *);
-	int (*cropcap)(struct soc_camera_device *, struct v4l2_cropcap *);
-	int (*get_crop)(struct soc_camera_device *, struct v4l2_crop *);
-	int (*set_crop)(struct soc_camera_device *, const struct v4l2_crop *);
 	int (*get_selection)(struct soc_camera_device *, struct v4l2_selection *);
 	int (*set_selection)(struct soc_camera_device *, struct v4l2_selection *);
 	/*
-	 * The difference to .set_crop() is, that .set_livecrop is not allowed
+	 * The difference to .set_selection() is, that .set_liveselection is not allowed
 	 * to change the output sizes
 	 */
-	int (*set_livecrop)(struct soc_camera_device *, const struct v4l2_crop *);
+	int (*set_liveselection)(struct soc_camera_device *, struct v4l2_selection *);
 	int (*set_fmt)(struct soc_camera_device *, struct v4l2_format *);
 	int (*try_fmt)(struct soc_camera_device *, struct v4l2_format *);
 	void (*init_videobuf)(struct videobuf_queue *,
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 178a88d45aea..e1006b391cdc 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -93,6 +93,16 @@ struct v4l2_ctrl_type_ops {
 			union v4l2_ctrl_ptr ptr);
 };
 
+/**
+ * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
+ *	that should be called when a control value has changed.
+ *
+ * @ctrl: pointer to struct &v4l2_ctrl
+ * @priv: control private data
+ *
+ * This typedef definition is used as an argument to v4l2_ctrl_notify()
+ * and as an argument at struct &v4l2_ctrl_handler.
+ */
 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
 
 /**
@@ -229,7 +239,7 @@ struct v4l2_ctrl {
  * @next:	Single-link list node for the hash.
  * @ctrl:	The actual control information.
  * @helper:	Pointer to helper struct. Used internally in
- *		prepare_ext_ctrls().
+ *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
  *
  * Each control handler has a list of these refs. The list_head is used to
  * keep a sorted-by-control-ID list of all controls, while the next pointer
@@ -369,17 +379,39 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
  * @key:	Used by the lock validator if CONFIG_LOCKDEP is set.
  * @name:	Used by the lock validator if CONFIG_LOCKDEP is set.
  *
- * Returns an error if the buckets could not be allocated. This error will
- * also be stored in @hdl->error.
+ * .. attention::
+ *
+ *    Never use this call directly, always use the v4l2_ctrl_handler_init()
+ *    macro that hides the @key and @name arguments.
  *
- * Never use this call directly, always use the v4l2_ctrl_handler_init
- * macro that hides the @key and @name arguments.
+ * Return: returns an error if the buckets could not be allocated. This
+ * error will also be stored in @hdl->error.
  */
 int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
 				 unsigned int nr_of_controls_hint,
 				 struct lock_class_key *key, const char *name);
 
 #ifdef CONFIG_LOCKDEP
+
+/**
+ * v4l2_ctrl_handler_init - helper function to create a static struct
+ *	 &lock_class_key and calls v4l2_ctrl_handler_init_class()
+ *
+ * @hdl:	The control handler.
+ * @nr_of_controls_hint: A hint of how many controls this handler is
+ *		expected to refer to. This is the total number, so including
+ *		any inherited controls. It doesn't have to be precise, but if
+ *		it is way off, then you either waste memory (too many buckets
+ *		are allocated) or the control lookup becomes slower (not enough
+ *		buckets are allocated, so there are more slow list lookups).
+ *		It will always work, though.
+ *
+ * This helper function creates a static struct &lock_class_key and
+ * calls v4l2_ctrl_handler_init_class(), providing a proper name for the lock
+ * validador.
+ *
+ * Use this helper function to initialize a control handler.
+ */
 #define v4l2_ctrl_handler_init(hdl, nr_of_controls_hint)		\
 (									\
 	({								\
@@ -564,6 +596,13 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
 					 u32 id, u8 max, u8 def,
 					 const s64 *qmenu_int);
 
+/**
+ * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
+ *	used when adding a control handler.
+ *
+ * @ctrl: pointer to struct &v4l2_ctrl.
+ */
+
 typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
 
 /**
@@ -635,8 +674,8 @@ void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
  * be marked active, and any reads will just return the current value without
  * going through g_volatile_ctrl.
  *
- * In addition, this function will set the V4L2_CTRL_FLAG_UPDATE flag
- * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
+ * In addition, this function will set the %V4L2_CTRL_FLAG_UPDATE flag
+ * on the autofoo control and %V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
  * if autofoo is in auto mode.
  */
 void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
@@ -686,7 +725,6 @@ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
  */
 void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
 
-
 /**
  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
  *
@@ -936,9 +974,9 @@ extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
  * v4l2_ctrl_replace - Function to be used as a callback to
  *	&struct v4l2_subscribed_event_ops replace\(\)
  *
- * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ * @old: pointer to struct &v4l2_event with the reported
  *	 event;
- * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the modified
+ * @new: pointer to struct &v4l2_event with the modified
  *	 event;
  */
 void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
@@ -947,9 +985,9 @@ void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
  * v4l2_ctrl_merge - Function to be used as a callback to
  *	&struct v4l2_subscribed_event_ops merge(\)
  *
- * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ * @old: pointer to struct &v4l2_event with the reported
  *	 event;
- * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the merged
+ * @new: pointer to struct &v4l2_event with the merged
  *	 event;
  */
 void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index a122b1bd40f9..e657614521e3 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -25,7 +25,8 @@
 #define VFL_TYPE_RADIO		2
 #define VFL_TYPE_SUBDEV		3
 #define VFL_TYPE_SDR		4
-#define VFL_TYPE_MAX		5
+#define VFL_TYPE_TOUCH		5
+#define VFL_TYPE_MAX		6
 
 /* Is this a receiver, transmitter or mem-to-mem? */
 /* Ignored for VFL_TYPE_SUBDEV. */
@@ -55,7 +56,7 @@ struct v4l2_ctrl_handler;
  *
  * .. note::
  *    The size of @prios array matches the number of priority types defined
- *    by :ref:`enum v4l2_priority <v4l2-priority>`.
+ *    by enum &v4l2_priority.
  */
 struct v4l2_prio_state {
 	atomic_t prios[4];
@@ -72,8 +73,8 @@ 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>`.
+ * @local: pointer to the desired priority, as defined by enum &v4l2_priority
+ * @new: Priority type requested, as defined by enum &v4l2_priority.
  *
  * .. note::
  *	This function should be used only by the V4L2 core.
@@ -85,7 +86,7 @@ int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
  * 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>`
+ * @local: pointer to the desired priority, as defined by enum &v4l2_priority
  *
  * .. note::
  *	This function should be used only by the V4L2 core.
@@ -96,7 +97,7 @@ 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>`
+ * @local: priority to be released, as defined by enum &v4l2_priority
  *
  * .. note::
  *	This function should be used only by the V4L2 core.
@@ -114,10 +115,10 @@ void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
 
 /**
- * v4l2_prio_close - Implements the priority logic for a file handler close
+ * v4l2_prio_check - 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
+ * @local: desired priority, as defined by enum &v4l2_priority local
  *
  * .. note::
  *	This function should be used only by the V4L2 core.
@@ -294,6 +295,7 @@ struct video_device
  *	- %VFL_TYPE_RADIO - A radio card
  *	- %VFL_TYPE_SUBDEV - A subdevice
  *	- %VFL_TYPE_SDR - Software Defined Radio
+ *	- %VFL_TYPE_TOUCH - A touch sensor
  *
  * .. note::
  *
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index a9d6aa41790e..8ffa94009d1a 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -39,7 +39,7 @@ struct v4l2_ctrl_handler;
  *	if this struct is embedded into a larger struct.
  * @name: unique device name, by default the driver name + bus ID
  * @notify: notify callback called by some sub-devices.
- * @ctrl_handler: The control handler. May be NULL.
+ * @ctrl_handler: The control handler. May be %NULL.
  * @prio: Device's priority state
  * @ref: Keep track of the references to this struct.
  * @release: Release function that is called when the ref count
@@ -53,8 +53,8 @@ struct v4l2_ctrl_handler;
  *
  * .. note::
  *
- *    #) dev->driver_data points to this struct.
- *    #) dev might be NULL if there is no parent device
+ *    #) @dev->driver_data points to this struct.
+ *    #) @dev might be %NULL if there is no parent device
  */
 
 struct v4l2_device {
@@ -76,10 +76,10 @@ struct v4l2_device {
 /**
  * v4l2_device_get - gets a V4L2 device reference
  *
- * @v4l2_dev: pointer to struct v4l2_device
+ * @v4l2_dev: pointer to struct &v4l2_device
  *
  * This is an ancillary routine meant to increment the usage for the
- * struct v4l2_device pointed by @v4l2_dev.
+ * struct &v4l2_device pointed by @v4l2_dev.
  */
 static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
 {
@@ -89,23 +89,23 @@ static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
 /**
  * v4l2_device_put - putss a V4L2 device reference
  *
- * @v4l2_dev: pointer to struct v4l2_device
+ * @v4l2_dev: pointer to struct &v4l2_device
  *
  * This is an ancillary routine meant to decrement the usage for the
- * struct v4l2_device pointed by @v4l2_dev.
+ * struct &v4l2_device pointed by @v4l2_dev.
  */
 int v4l2_device_put(struct v4l2_device *v4l2_dev);
 
 /**
- * v4l2_device_register -Initialize v4l2_dev and make dev->driver_data
- * 	point to v4l2_dev.
+ * v4l2_device_register - Initialize v4l2_dev and make @dev->driver_data
+ *	point to @v4l2_dev.
  *
- * @dev: pointer to struct device
- * @v4l2_dev: pointer to struct v4l2_device
+ * @dev: pointer to struct &device
+ * @v4l2_dev: pointer to struct &v4l2_device
  *
  * .. note::
- *	dev may be NULL in rare cases (ISA devices).
- *	In such case the caller must fill in the v4l2_dev->name field
+ *	@dev may be %NULL in rare cases (ISA devices).
+ *	In such case the caller must fill in the @v4l2_dev->name field
  *	before calling this function.
  */
 int __must_check v4l2_device_register(struct device *dev,
@@ -113,14 +113,14 @@ int __must_check v4l2_device_register(struct device *dev,
 
 /**
  * v4l2_device_set_name - Optional function to initialize the
- * 	name field of struct v4l2_device
+ *	name field of struct &v4l2_device
  *
- * @v4l2_dev: pointer to struct v4l2_device
+ * @v4l2_dev: pointer to struct &v4l2_device
  * @basename: base name for the device name
  * @instance: pointer to a static atomic_t var with the instance usage for
- * 	the device driver.
+ *	the device driver.
  *
- * v4l2_device_set_name() initializes the name field of struct v4l2_device
+ * v4l2_device_set_name() initializes the name field of struct &v4l2_device
  * using the driver name and a driver-global atomic_t instance.
  *
  * This function will increment the instance counter and returns the
@@ -132,7 +132,7 @@ int __must_check v4l2_device_register(struct device *dev,
  *
  *   ...
  *
- *   instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
+ *   instance = v4l2_device_set_name(&\ v4l2_dev, "foo", &\ drv_instance);
  *
  * The first time this is called the name field will be set to foo0 and
  * this function returns 0. If the name ends with a digit (e.g. cx18),
@@ -147,16 +147,16 @@ int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
  * @v4l2_dev: pointer to struct v4l2_device
  *
  * Should be called when the USB parent disconnects.
- * Since the parent disappears, this ensures that v4l2_dev doesn't have
+ * Since the parent disappears, this ensures that @v4l2_dev doesn't have
  * an invalid parent pointer.
  *
- * .. note:: This function sets v4l2_dev->dev to NULL.
+ * .. note:: This function sets @v4l2_dev->dev to NULL.
  */
 void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
 
 /**
  *  v4l2_device_unregister - Unregister all sub-devices and any other
- *	 resources related to v4l2_dev.
+ *	 resources related to @v4l2_dev.
  *
  * @v4l2_dev: pointer to struct v4l2_device
  */
@@ -165,8 +165,8 @@ void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
 /**
  * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
  *
- * @v4l2_dev: pointer to struct v4l2_device
- * @sd: pointer to struct v4l2_subdev
+ * @v4l2_dev: pointer to struct &v4l2_device
+ * @sd: pointer to struct &v4l2_subdev
  *
  * While registered, the subdev module is marked as in-use.
  *
@@ -179,7 +179,7 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
 /**
  * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
  *
- * @sd: pointer to struct v4l2_subdev
+ * @sd: pointer to struct &v4l2_subdev
  *
  * .. note ::
  *
@@ -191,7 +191,7 @@ void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
 /**
  * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
  *	of the v4l2 device that are marked with
- * 	the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+ *	the %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
  *
  * @v4l2_dev: pointer to struct v4l2_device
  */
@@ -201,9 +201,9 @@ v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
 /**
  * v4l2_subdev_notify - Sends a notification to v4l2_device.
  *
- * @sd: pointer to struct v4l2_subdev
+ * @sd: pointer to struct &v4l2_subdev
  * @notification: type of notification. Please notice that the notification
- * 	type is driver-specific.
+ *	type is driver-specific.
  * @arg: arguments for the notification. Those are specific to each
  *	notification type.
  */
@@ -222,7 +222,7 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
    Ignore any errors. Note that you cannot add or delete a subdev
    while walking the subdevs list. */
 #define __v4l2_device_call_subdevs_p(v4l2_dev, sd, cond, o, f, args...)	\
-	do { 								\
+	do {								\
 		list_for_each_entry((sd), &(v4l2_dev)->subdevs, list)	\
 			if ((cond) && (sd)->ops->o && (sd)->ops->o->f)	\
 				(sd)->ops->o->f((sd) , ##args);		\
@@ -241,15 +241,15 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
    return with that error code. Note that you cannot add or delete a
    subdev while walking the subdevs list. */
 #define __v4l2_device_call_subdevs_until_err_p(v4l2_dev, sd, cond, o, f, args...) \
-({ 									\
+({									\
 	long __err = 0;							\
 									\
 	list_for_each_entry((sd), &(v4l2_dev)->subdevs, list) {		\
 		if ((cond) && (sd)->ops->o && (sd)->ops->o->f)		\
 			__err = (sd)->ops->o->f((sd) , ##args);		\
 		if (__err && __err != -ENOIOCTLCMD)			\
-			break; 						\
-	} 								\
+			break;						\
+	}								\
 	(__err == -ENOIOCTLCMD) ? 0 : __err;				\
 })
 
@@ -276,7 +276,7 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
    match them all). If the callback returns an error other than 0 or
    -ENOIOCTLCMD, then return with that error code. Note that you cannot
    add or delete a subdev while walking the subdevs list. */
-#define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...) 	\
+#define v4l2_device_call_until_err(v4l2_dev, grpid, o, f, args...)	\
 ({									\
 	struct v4l2_subdev *__sd;					\
 	__v4l2_device_call_subdevs_until_err_p(v4l2_dev, __sd,		\
@@ -300,8 +300,8 @@ static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
 
 /*
  * Call the specified callback for all subdevs where grp_id & grpmsk != 0
- * (if grpmsk == `0, then match them all). If the callback returns an error
- * other than 0 or -ENOIOCTLCMD, then return with that error code. Note that
+ * (if grpmsk == 0, then match them all). If the callback returns an error
+ * other than 0 or %-ENOIOCTLCMD, then return with that error code. Note that
  * you cannot add or delete a subdev while walking the subdevs list.
  */
 #define v4l2_device_mask_call_until_err(v4l2_dev, grpmsk, o, f, args...) \
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 65caadf13eec..0a7d9e1fc8c8 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -28,8 +28,8 @@
  */
 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
 
-/*
- * v4l2_check_dv_timings_fnc - timings check callback
+/**
+ * typedef v4l2_check_dv_timings_fnc - timings check callback
  *
  * @t: the v4l2_dv_timings struct.
  * @handle: a handle from the driver.
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index ca854203b8b9..a700285c64a9 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -222,7 +222,8 @@ int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
 				  struct v4l2_fh *fh,
 				  struct v4l2_event_subscription *sub);
 /**
- * v4l2_src_change_event_subscribe -
+ * v4l2_src_change_event_subscribe - helper function that calls
+ * 	v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
  *
  * @fh: pointer to struct v4l2_fh
  * @sub: pointer to &struct v4l2_event_subscription
diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h
index 3d184ab52274..b0fe4d6f4a5f 100644
--- a/include/media/v4l2-flash-led-class.h
+++ b/include/media/v4l2-flash-led-class.h
@@ -20,7 +20,7 @@ struct led_classdev;
 struct v4l2_flash;
 enum led_brightness;
 
-/*
+/**
  * struct v4l2_flash_ctrl_data - flash control initialization data, filled
  *				basing on the features declared by the LED flash
  *				class driver in the v4l2_flash_config
@@ -33,14 +33,21 @@ struct v4l2_flash_ctrl_data {
 	u32 cid;
 };
 
+/**
+ * struct v4l2_flash_ops - V4L2 flash operations
+ *
+ * @external_strobe_set: Setup strobing the flash by hardware pin state
+ *	assertion.
+ * @intensity_to_led_brightness: Convert intensity to brightness in a device
+ *	specific manner
+ * @led_brightness_to_intensity: convert brightness to intensity in a device
+ *	specific manner.
+ */
 struct v4l2_flash_ops {
-	/* setup strobing the flash by hardware pin state assertion */
 	int (*external_strobe_set)(struct v4l2_flash *v4l2_flash,
 					bool enable);
-	/* convert intensity to brightness in a device specific manner */
 	enum led_brightness (*intensity_to_led_brightness)
 		(struct v4l2_flash *v4l2_flash, s32 intensity);
-	/* convert brightness to intensity in a device specific manner */
 	s32 (*led_brightness_to_intensity)
 		(struct v4l2_flash *v4l2_flash, enum led_brightness);
 };
diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h
index 8b1d19bc9b0e..574ff2ae94be 100644
--- a/include/media/v4l2-ioctl.h
+++ b/include/media/v4l2-ioctl.h
@@ -287,273 +287,286 @@ struct v4l2_ioctl_ops {
 	/* ioctl callbacks */
 
 	/* VIDIOC_QUERYCAP handler */
-	int (*vidioc_querycap)(struct file *file, void *fh, struct v4l2_capability *cap);
+	int (*vidioc_querycap)(struct file *file, void *fh,
+			       struct v4l2_capability *cap);
 
 	/* VIDIOC_ENUM_FMT handlers */
-	int (*vidioc_enum_fmt_vid_cap)     (struct file *file, void *fh,
-					    struct v4l2_fmtdesc *f);
-	int (*vidioc_enum_fmt_vid_overlay) (struct file *file, void *fh,
-					    struct v4l2_fmtdesc *f);
-	int (*vidioc_enum_fmt_vid_out)     (struct file *file, void *fh,
-					    struct v4l2_fmtdesc *f);
+	int (*vidioc_enum_fmt_vid_cap)(struct file *file, void *fh,
+				       struct v4l2_fmtdesc *f);
+	int (*vidioc_enum_fmt_vid_overlay)(struct file *file, void *fh,
+					   struct v4l2_fmtdesc *f);
+	int (*vidioc_enum_fmt_vid_out)(struct file *file, void *fh,
+				       struct v4l2_fmtdesc *f);
 	int (*vidioc_enum_fmt_vid_cap_mplane)(struct file *file, void *fh,
 					      struct v4l2_fmtdesc *f);
 	int (*vidioc_enum_fmt_vid_out_mplane)(struct file *file, void *fh,
 					      struct v4l2_fmtdesc *f);
-	int (*vidioc_enum_fmt_sdr_cap)     (struct file *file, void *fh,
-					    struct v4l2_fmtdesc *f);
-	int (*vidioc_enum_fmt_sdr_out)     (struct file *file, void *fh,
-					    struct v4l2_fmtdesc *f);
+	int (*vidioc_enum_fmt_sdr_cap)(struct file *file, void *fh,
+				       struct v4l2_fmtdesc *f);
+	int (*vidioc_enum_fmt_sdr_out)(struct file *file, void *fh,
+				       struct v4l2_fmtdesc *f);
 
 	/* VIDIOC_G_FMT handlers */
-	int (*vidioc_g_fmt_vid_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_g_fmt_vid_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_g_fmt_vid_overlay)(struct file *file, void *fh,
 					struct v4l2_format *f);
-	int (*vidioc_g_fmt_vid_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_g_fmt_vid_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_g_fmt_vid_out_overlay)(struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_g_fmt_vbi_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_g_fmt_vbi_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+					    struct v4l2_format *f);
+	int (*vidioc_g_fmt_vbi_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
+	int (*vidioc_g_fmt_vbi_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_g_fmt_sliced_vbi_cap)(struct file *file, void *fh,
-					struct v4l2_format *f);
+					   struct v4l2_format *f);
 	int (*vidioc_g_fmt_sliced_vbi_out)(struct file *file, void *fh,
-					struct v4l2_format *f);
+					   struct v4l2_format *f);
 	int (*vidioc_g_fmt_vid_cap_mplane)(struct file *file, void *fh,
 					   struct v4l2_format *f);
 	int (*vidioc_g_fmt_vid_out_mplane)(struct file *file, void *fh,
 					   struct v4l2_format *f);
-	int (*vidioc_g_fmt_sdr_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_g_fmt_sdr_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_g_fmt_sdr_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
+	int (*vidioc_g_fmt_sdr_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 
 	/* VIDIOC_S_FMT handlers */
-	int (*vidioc_s_fmt_vid_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_s_fmt_vid_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_s_fmt_vid_overlay)(struct file *file, void *fh,
 					struct v4l2_format *f);
-	int (*vidioc_s_fmt_vid_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_s_fmt_vid_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_s_fmt_vid_out_overlay)(struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_s_fmt_vbi_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_s_fmt_vbi_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+					    struct v4l2_format *f);
+	int (*vidioc_s_fmt_vbi_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
+	int (*vidioc_s_fmt_vbi_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 	int (*vidioc_s_fmt_sliced_vbi_cap)(struct file *file, void *fh,
-					struct v4l2_format *f);
+					   struct v4l2_format *f);
 	int (*vidioc_s_fmt_sliced_vbi_out)(struct file *file, void *fh,
-					struct v4l2_format *f);
+					   struct v4l2_format *f);
 	int (*vidioc_s_fmt_vid_cap_mplane)(struct file *file, void *fh,
 					   struct v4l2_format *f);
 	int (*vidioc_s_fmt_vid_out_mplane)(struct file *file, void *fh,
 					   struct v4l2_format *f);
-	int (*vidioc_s_fmt_sdr_cap)    (struct file *file, void *fh,
-					struct v4l2_format *f);
-	int (*vidioc_s_fmt_sdr_out)    (struct file *file, void *fh,
-					struct v4l2_format *f);
+	int (*vidioc_s_fmt_sdr_cap)(struct file *file, void *fh,
+				    struct v4l2_format *f);
+	int (*vidioc_s_fmt_sdr_out)(struct file *file, void *fh,
+				    struct v4l2_format *f);
 
 	/* VIDIOC_TRY_FMT handlers */
-	int (*vidioc_try_fmt_vid_cap)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
+	int (*vidioc_try_fmt_vid_cap)(struct file *file, void *fh,
+				      struct v4l2_format *f);
 	int (*vidioc_try_fmt_vid_overlay)(struct file *file, void *fh,
 					  struct v4l2_format *f);
-	int (*vidioc_try_fmt_vid_out)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
+	int (*vidioc_try_fmt_vid_out)(struct file *file, void *fh,
+				      struct v4l2_format *f);
 	int (*vidioc_try_fmt_vid_out_overlay)(struct file *file, void *fh,
-					  struct v4l2_format *f);
-	int (*vidioc_try_fmt_vbi_cap)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
-	int (*vidioc_try_fmt_vbi_out)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
+					     struct v4l2_format *f);
+	int (*vidioc_try_fmt_vbi_cap)(struct file *file, void *fh,
+				      struct v4l2_format *f);
+	int (*vidioc_try_fmt_vbi_out)(struct file *file, void *fh,
+				      struct v4l2_format *f);
 	int (*vidioc_try_fmt_sliced_vbi_cap)(struct file *file, void *fh,
-					  struct v4l2_format *f);
+					     struct v4l2_format *f);
 	int (*vidioc_try_fmt_sliced_vbi_out)(struct file *file, void *fh,
-					  struct v4l2_format *f);
+					     struct v4l2_format *f);
 	int (*vidioc_try_fmt_vid_cap_mplane)(struct file *file, void *fh,
 					     struct v4l2_format *f);
 	int (*vidioc_try_fmt_vid_out_mplane)(struct file *file, void *fh,
 					     struct v4l2_format *f);
-	int (*vidioc_try_fmt_sdr_cap)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
-	int (*vidioc_try_fmt_sdr_out)    (struct file *file, void *fh,
-					  struct v4l2_format *f);
+	int (*vidioc_try_fmt_sdr_cap)(struct file *file, void *fh,
+				      struct v4l2_format *f);
+	int (*vidioc_try_fmt_sdr_out)(struct file *file, void *fh,
+				      struct v4l2_format *f);
 
 	/* Buffer handlers */
-	int (*vidioc_reqbufs) (struct file *file, void *fh, struct v4l2_requestbuffers *b);
-	int (*vidioc_querybuf)(struct file *file, void *fh, struct v4l2_buffer *b);
-	int (*vidioc_qbuf)    (struct file *file, void *fh, struct v4l2_buffer *b);
-	int (*vidioc_expbuf)  (struct file *file, void *fh,
-				struct v4l2_exportbuffer *e);
-	int (*vidioc_dqbuf)   (struct file *file, void *fh, struct v4l2_buffer *b);
-
-	int (*vidioc_create_bufs)(struct file *file, void *fh, struct v4l2_create_buffers *b);
-	int (*vidioc_prepare_buf)(struct file *file, void *fh, struct v4l2_buffer *b);
-
-	int (*vidioc_overlay) (struct file *file, void *fh, unsigned int i);
-	int (*vidioc_g_fbuf)   (struct file *file, void *fh,
-				struct v4l2_framebuffer *a);
-	int (*vidioc_s_fbuf)   (struct file *file, void *fh,
-				const struct v4l2_framebuffer *a);
+	int (*vidioc_reqbufs)(struct file *file, void *fh,
+			      struct v4l2_requestbuffers *b);
+	int (*vidioc_querybuf)(struct file *file, void *fh,
+			       struct v4l2_buffer *b);
+	int (*vidioc_qbuf)(struct file *file, void *fh,
+			   struct v4l2_buffer *b);
+	int (*vidioc_expbuf)(struct file *file, void *fh,
+			     struct v4l2_exportbuffer *e);
+	int (*vidioc_dqbuf)(struct file *file, void *fh,
+			    struct v4l2_buffer *b);
+
+	int (*vidioc_create_bufs)(struct file *file, void *fh,
+				  struct v4l2_create_buffers *b);
+	int (*vidioc_prepare_buf)(struct file *file, void *fh,
+				  struct v4l2_buffer *b);
+
+	int (*vidioc_overlay)(struct file *file, void *fh, unsigned int i);
+	int (*vidioc_g_fbuf)(struct file *file, void *fh,
+			     struct v4l2_framebuffer *a);
+	int (*vidioc_s_fbuf)(struct file *file, void *fh,
+			     const struct v4l2_framebuffer *a);
 
 		/* Stream on/off */
-	int (*vidioc_streamon) (struct file *file, void *fh, enum v4l2_buf_type i);
-	int (*vidioc_streamoff)(struct file *file, void *fh, enum v4l2_buf_type i);
-
-		/* Standard handling
-			ENUMSTD is handled by videodev.c
+	int (*vidioc_streamon)(struct file *file, void *fh,
+			       enum v4l2_buf_type i);
+	int (*vidioc_streamoff)(struct file *file, void *fh,
+				enum v4l2_buf_type i);
+
+		/*
+		 * Standard handling
+		 *
+		 * Note: ENUMSTD is handled by videodev.c
 		 */
-	int (*vidioc_g_std) (struct file *file, void *fh, v4l2_std_id *norm);
-	int (*vidioc_s_std) (struct file *file, void *fh, v4l2_std_id norm);
-	int (*vidioc_querystd) (struct file *file, void *fh, v4l2_std_id *a);
+	int (*vidioc_g_std)(struct file *file, void *fh, v4l2_std_id *norm);
+	int (*vidioc_s_std)(struct file *file, void *fh, v4l2_std_id norm);
+	int (*vidioc_querystd)(struct file *file, void *fh, v4l2_std_id *a);
 
 		/* Input handling */
 	int (*vidioc_enum_input)(struct file *file, void *fh,
 				 struct v4l2_input *inp);
-	int (*vidioc_g_input)   (struct file *file, void *fh, unsigned int *i);
-	int (*vidioc_s_input)   (struct file *file, void *fh, unsigned int i);
+	int (*vidioc_g_input)(struct file *file, void *fh, unsigned int *i);
+	int (*vidioc_s_input)(struct file *file, void *fh, unsigned int i);
 
 		/* Output handling */
-	int (*vidioc_enum_output) (struct file *file, void *fh,
+	int (*vidioc_enum_output)(struct file *file, void *fh,
 				  struct v4l2_output *a);
-	int (*vidioc_g_output)   (struct file *file, void *fh, unsigned int *i);
-	int (*vidioc_s_output)   (struct file *file, void *fh, unsigned int i);
+	int (*vidioc_g_output)(struct file *file, void *fh, unsigned int *i);
+	int (*vidioc_s_output)(struct file *file, void *fh, unsigned int i);
 
 		/* Control handling */
-	int (*vidioc_queryctrl)        (struct file *file, void *fh,
-					struct v4l2_queryctrl *a);
-	int (*vidioc_query_ext_ctrl)   (struct file *file, void *fh,
-					struct v4l2_query_ext_ctrl *a);
-	int (*vidioc_g_ctrl)           (struct file *file, void *fh,
-					struct v4l2_control *a);
-	int (*vidioc_s_ctrl)           (struct file *file, void *fh,
-					struct v4l2_control *a);
-	int (*vidioc_g_ext_ctrls)      (struct file *file, void *fh,
-					struct v4l2_ext_controls *a);
-	int (*vidioc_s_ext_ctrls)      (struct file *file, void *fh,
-					struct v4l2_ext_controls *a);
-	int (*vidioc_try_ext_ctrls)    (struct file *file, void *fh,
-					struct v4l2_ext_controls *a);
-	int (*vidioc_querymenu)        (struct file *file, void *fh,
-					struct v4l2_querymenu *a);
+	int (*vidioc_queryctrl)(struct file *file, void *fh,
+				struct v4l2_queryctrl *a);
+	int (*vidioc_query_ext_ctrl)(struct file *file, void *fh,
+				     struct v4l2_query_ext_ctrl *a);
+	int (*vidioc_g_ctrl)(struct file *file, void *fh,
+			     struct v4l2_control *a);
+	int (*vidioc_s_ctrl)(struct file *file, void *fh,
+			     struct v4l2_control *a);
+	int (*vidioc_g_ext_ctrls)(struct file *file, void *fh,
+				  struct v4l2_ext_controls *a);
+	int (*vidioc_s_ext_ctrls)(struct file *file, void *fh,
+				  struct v4l2_ext_controls *a);
+	int (*vidioc_try_ext_ctrls)(struct file *file, void *fh,
+				    struct v4l2_ext_controls *a);
+	int (*vidioc_querymenu)(struct file *file, void *fh,
+				struct v4l2_querymenu *a);
 
 	/* Audio ioctls */
-	int (*vidioc_enumaudio)        (struct file *file, void *fh,
-					struct v4l2_audio *a);
-	int (*vidioc_g_audio)          (struct file *file, void *fh,
-					struct v4l2_audio *a);
-	int (*vidioc_s_audio)          (struct file *file, void *fh,
-					const struct v4l2_audio *a);
+	int (*vidioc_enumaudio)(struct file *file, void *fh,
+				struct v4l2_audio *a);
+	int (*vidioc_g_audio)(struct file *file, void *fh,
+			      struct v4l2_audio *a);
+	int (*vidioc_s_audio)(struct file *file, void *fh,
+			      const struct v4l2_audio *a);
 
 	/* Audio out ioctls */
-	int (*vidioc_enumaudout)       (struct file *file, void *fh,
-					struct v4l2_audioout *a);
-	int (*vidioc_g_audout)         (struct file *file, void *fh,
-					struct v4l2_audioout *a);
-	int (*vidioc_s_audout)         (struct file *file, void *fh,
-					const struct v4l2_audioout *a);
-	int (*vidioc_g_modulator)      (struct file *file, void *fh,
-					struct v4l2_modulator *a);
-	int (*vidioc_s_modulator)      (struct file *file, void *fh,
-					const struct v4l2_modulator *a);
+	int (*vidioc_enumaudout)(struct file *file, void *fh,
+				 struct v4l2_audioout *a);
+	int (*vidioc_g_audout)(struct file *file, void *fh,
+			       struct v4l2_audioout *a);
+	int (*vidioc_s_audout)(struct file *file, void *fh,
+			       const struct v4l2_audioout *a);
+	int (*vidioc_g_modulator)(struct file *file, void *fh,
+				  struct v4l2_modulator *a);
+	int (*vidioc_s_modulator)(struct file *file, void *fh,
+				  const struct v4l2_modulator *a);
 	/* Crop ioctls */
-	int (*vidioc_cropcap)          (struct file *file, void *fh,
-					struct v4l2_cropcap *a);
-	int (*vidioc_g_crop)           (struct file *file, void *fh,
-					struct v4l2_crop *a);
-	int (*vidioc_s_crop)           (struct file *file, void *fh,
-					const struct v4l2_crop *a);
-	int (*vidioc_g_selection)      (struct file *file, void *fh,
-					struct v4l2_selection *s);
-	int (*vidioc_s_selection)      (struct file *file, void *fh,
-					struct v4l2_selection *s);
+	int (*vidioc_cropcap)(struct file *file, void *fh,
+			      struct v4l2_cropcap *a);
+	int (*vidioc_g_crop)(struct file *file, void *fh,
+			     struct v4l2_crop *a);
+	int (*vidioc_s_crop)(struct file *file, void *fh,
+			     const struct v4l2_crop *a);
+	int (*vidioc_g_selection)(struct file *file, void *fh,
+				  struct v4l2_selection *s);
+	int (*vidioc_s_selection)(struct file *file, void *fh,
+				  struct v4l2_selection *s);
 	/* Compression ioctls */
-	int (*vidioc_g_jpegcomp)       (struct file *file, void *fh,
-					struct v4l2_jpegcompression *a);
-	int (*vidioc_s_jpegcomp)       (struct file *file, void *fh,
-					const struct v4l2_jpegcompression *a);
-	int (*vidioc_g_enc_index)      (struct file *file, void *fh,
-					struct v4l2_enc_idx *a);
-	int (*vidioc_encoder_cmd)      (struct file *file, void *fh,
-					struct v4l2_encoder_cmd *a);
-	int (*vidioc_try_encoder_cmd)  (struct file *file, void *fh,
-					struct v4l2_encoder_cmd *a);
-	int (*vidioc_decoder_cmd)      (struct file *file, void *fh,
-					struct v4l2_decoder_cmd *a);
-	int (*vidioc_try_decoder_cmd)  (struct file *file, void *fh,
-					struct v4l2_decoder_cmd *a);
+	int (*vidioc_g_jpegcomp)(struct file *file, void *fh,
+				 struct v4l2_jpegcompression *a);
+	int (*vidioc_s_jpegcomp)(struct file *file, void *fh,
+				 const struct v4l2_jpegcompression *a);
+	int (*vidioc_g_enc_index)(struct file *file, void *fh,
+				  struct v4l2_enc_idx *a);
+	int (*vidioc_encoder_cmd)(struct file *file, void *fh,
+				  struct v4l2_encoder_cmd *a);
+	int (*vidioc_try_encoder_cmd)(struct file *file, void *fh,
+				      struct v4l2_encoder_cmd *a);
+	int (*vidioc_decoder_cmd)(struct file *file, void *fh,
+				  struct v4l2_decoder_cmd *a);
+	int (*vidioc_try_decoder_cmd)(struct file *file, void *fh,
+				      struct v4l2_decoder_cmd *a);
 
 	/* Stream type-dependent parameter ioctls */
-	int (*vidioc_g_parm)           (struct file *file, void *fh,
-					struct v4l2_streamparm *a);
-	int (*vidioc_s_parm)           (struct file *file, void *fh,
-					struct v4l2_streamparm *a);
+	int (*vidioc_g_parm)(struct file *file, void *fh,
+			     struct v4l2_streamparm *a);
+	int (*vidioc_s_parm)(struct file *file, void *fh,
+			     struct v4l2_streamparm *a);
 
 	/* Tuner ioctls */
-	int (*vidioc_g_tuner)          (struct file *file, void *fh,
-					struct v4l2_tuner *a);
-	int (*vidioc_s_tuner)          (struct file *file, void *fh,
-					const struct v4l2_tuner *a);
-	int (*vidioc_g_frequency)      (struct file *file, void *fh,
-					struct v4l2_frequency *a);
-	int (*vidioc_s_frequency)      (struct file *file, void *fh,
-					const struct v4l2_frequency *a);
-	int (*vidioc_enum_freq_bands) (struct file *file, void *fh,
-				    struct v4l2_frequency_band *band);
+	int (*vidioc_g_tuner)(struct file *file, void *fh,
+			      struct v4l2_tuner *a);
+	int (*vidioc_s_tuner)(struct file *file, void *fh,
+			      const struct v4l2_tuner *a);
+	int (*vidioc_g_frequency)(struct file *file, void *fh,
+				  struct v4l2_frequency *a);
+	int (*vidioc_s_frequency)(struct file *file, void *fh,
+				  const struct v4l2_frequency *a);
+	int (*vidioc_enum_freq_bands)(struct file *file, void *fh,
+				      struct v4l2_frequency_band *band);
 
 	/* Sliced VBI cap */
-	int (*vidioc_g_sliced_vbi_cap) (struct file *file, void *fh,
-					struct v4l2_sliced_vbi_cap *a);
+	int (*vidioc_g_sliced_vbi_cap)(struct file *file, void *fh,
+				       struct v4l2_sliced_vbi_cap *a);
 
 	/* Log status ioctl */
-	int (*vidioc_log_status)       (struct file *file, void *fh);
+	int (*vidioc_log_status)(struct file *file, void *fh);
 
-	int (*vidioc_s_hw_freq_seek)   (struct file *file, void *fh,
-					const struct v4l2_hw_freq_seek *a);
+	int (*vidioc_s_hw_freq_seek)(struct file *file, void *fh,
+				     const struct v4l2_hw_freq_seek *a);
 
 	/* Debugging ioctls */
 #ifdef CONFIG_VIDEO_ADV_DEBUG
-	int (*vidioc_g_register)       (struct file *file, void *fh,
-					struct v4l2_dbg_register *reg);
-	int (*vidioc_s_register)       (struct file *file, void *fh,
-					const struct v4l2_dbg_register *reg);
+	int (*vidioc_g_register)(struct file *file, void *fh,
+				 struct v4l2_dbg_register *reg);
+	int (*vidioc_s_register)(struct file *file, void *fh,
+				 const struct v4l2_dbg_register *reg);
 
-	int (*vidioc_g_chip_info)      (struct file *file, void *fh,
-					struct v4l2_dbg_chip_info *chip);
+	int (*vidioc_g_chip_info)(struct file *file, void *fh,
+				  struct v4l2_dbg_chip_info *chip);
 #endif
 
-	int (*vidioc_enum_framesizes)   (struct file *file, void *fh,
-					 struct v4l2_frmsizeenum *fsize);
+	int (*vidioc_enum_framesizes)(struct file *file, void *fh,
+				      struct v4l2_frmsizeenum *fsize);
 
-	int (*vidioc_enum_frameintervals) (struct file *file, void *fh,
-					   struct v4l2_frmivalenum *fival);
+	int (*vidioc_enum_frameintervals)(struct file *file, void *fh,
+					  struct v4l2_frmivalenum *fival);
 
 	/* DV Timings IOCTLs */
-	int (*vidioc_s_dv_timings) (struct file *file, void *fh,
-				    struct v4l2_dv_timings *timings);
-	int (*vidioc_g_dv_timings) (struct file *file, void *fh,
-				    struct v4l2_dv_timings *timings);
-	int (*vidioc_query_dv_timings) (struct file *file, void *fh,
-				    struct v4l2_dv_timings *timings);
-	int (*vidioc_enum_dv_timings) (struct file *file, void *fh,
-				    struct v4l2_enum_dv_timings *timings);
-	int (*vidioc_dv_timings_cap) (struct file *file, void *fh,
-				    struct v4l2_dv_timings_cap *cap);
-	int (*vidioc_g_edid) (struct file *file, void *fh, struct v4l2_edid *edid);
-	int (*vidioc_s_edid) (struct file *file, void *fh, struct v4l2_edid *edid);
-
-	int (*vidioc_subscribe_event)  (struct v4l2_fh *fh,
-					const struct v4l2_event_subscription *sub);
+	int (*vidioc_s_dv_timings)(struct file *file, void *fh,
+				   struct v4l2_dv_timings *timings);
+	int (*vidioc_g_dv_timings)(struct file *file, void *fh,
+				   struct v4l2_dv_timings *timings);
+	int (*vidioc_query_dv_timings)(struct file *file, void *fh,
+				       struct v4l2_dv_timings *timings);
+	int (*vidioc_enum_dv_timings)(struct file *file, void *fh,
+				      struct v4l2_enum_dv_timings *timings);
+	int (*vidioc_dv_timings_cap)(struct file *file, void *fh,
+				     struct v4l2_dv_timings_cap *cap);
+	int (*vidioc_g_edid)(struct file *file, void *fh,
+			     struct v4l2_edid *edid);
+	int (*vidioc_s_edid)(struct file *file, void *fh,
+			     struct v4l2_edid *edid);
+
+	int (*vidioc_subscribe_event)(struct v4l2_fh *fh,
+				      const struct v4l2_event_subscription *sub);
 	int (*vidioc_unsubscribe_event)(struct v4l2_fh *fh,
 					const struct v4l2_event_subscription *sub);
 
 	/* For other private ioctls */
-	long (*vidioc_default)	       (struct file *file, void *fh,
-					bool valid_prio, unsigned int cmd, void *arg);
+	long (*vidioc_default)(struct file *file, void *fh,
+			       bool valid_prio, unsigned int cmd, void *arg);
 };
 
 
@@ -573,38 +586,123 @@ struct v4l2_ioctl_ops {
 #define V4L2_DEV_DEBUG_POLL		0x10
 
 /*  Video standard functions  */
-extern const char *v4l2_norm_to_name(v4l2_std_id id);
-extern void v4l2_video_std_frame_period(int id, struct v4l2_fract *frameperiod);
-extern int v4l2_video_std_construct(struct v4l2_standard *vs,
+
+/**
+ * v4l2_norm_to_name - Ancillary routine to analog TV standard name from its ID.
+ *
+ * @id:	analog TV standard ID.
+ *
+ * Return: returns a string with the name of the analog TV standard.
+ * If the standard is not found or if @id points to multiple standard,
+ * it returns "Unknown".
+ */
+const char *v4l2_norm_to_name(v4l2_std_id id);
+
+/**
+ * v4l2_video_std_frame_period - Ancillary routine that fills a
+ *	struct &v4l2_fract pointer with the default framerate fraction.
+ *
+ * @id: analog TV sdandard ID.
+ * @frameperiod: struct &v4l2_fract pointer to be filled
+ *
+ */
+void v4l2_video_std_frame_period(int id, struct v4l2_fract *frameperiod);
+
+/**
+ * v4l2_video_std_construct - Ancillary routine that fills in the fields of
+ *	a &v4l2_standard structure according to the @id parameter.
+ *
+ * @vs: struct &v4l2_standard pointer to be filled
+ * @id: analog TV sdandard ID.
+ * @name: name of the standard to be used
+ *
+ * .. note::
+ *
+ *    This ancillary routine is obsolete. Shouldn't be used on newer drivers.
+ */
+int v4l2_video_std_construct(struct v4l2_standard *vs,
 				    int id, const char *name);
-/* Prints the ioctl in a human-readable format. If prefix != NULL,
-   then do printk(KERN_DEBUG "%s: ", prefix) first. */
-extern void v4l_printk_ioctl(const char *prefix, unsigned int cmd);
 
-/* Internal use only: get the mutex (if any) that we need to lock for the
-   given command. */
+/**
+ * v4l_printk_ioctl - Ancillary routine that prints the ioctl in a
+ *	human-readable format.
+ *
+ * @prefix: prefix to be added at the ioctl prints.
+ * @cmd: ioctl name
+ *
+ * .. note::
+ *
+ *    If prefix != %NULL, then it will issue a
+ *    ``printk(KERN_DEBUG "%s: ", prefix)`` first.
+ */
+void v4l_printk_ioctl(const char *prefix, unsigned int cmd);
+
 struct video_device;
-extern struct mutex *v4l2_ioctl_get_lock(struct video_device *vdev, unsigned cmd);
+
+
+/**
+ * v4l2_ioctl_get_lock - get the mutex (if any) that it is need to lock for
+ *	a given command.
+ *
+ * @vdev: Pointer to struct &video_device.
+ * @cmd: Ioctl name.
+ *
+ * .. note:: Internal use only. Should not be used outside V4L2 core.
+ */
+struct mutex *v4l2_ioctl_get_lock(struct video_device *vdev, unsigned int cmd);
 
 /* names for fancy debug output */
 extern const char *v4l2_field_names[];
 extern const char *v4l2_type_names[];
 
 #ifdef CONFIG_COMPAT
-/* 32 Bits compatibility layer for 64 bits processors */
-extern long v4l2_compat_ioctl32(struct file *file, unsigned int cmd,
-				unsigned long arg);
+/**
+ * v4l2_compat_ioctl32 -32 Bits compatibility layer for 64 bits processors
+ *
+ * @file: Pointer to struct &file.
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ */
+long int v4l2_compat_ioctl32(struct file *file, unsigned int cmd,
+			     unsigned long arg);
 #endif
 
-typedef long (*v4l2_kioctl)(struct file *file,
-		unsigned int cmd, void *arg);
+/**
+ * typedef v4l2_kioctl - Typedef used to pass an ioctl handler.
+ *
+ * @file: Pointer to struct &file.
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ */
+typedef long (*v4l2_kioctl)(struct file *file, unsigned int cmd, void *arg);
 
-/* Include support for obsoleted stuff */
-extern long video_usercopy(struct file *file, unsigned int cmd,
-				unsigned long arg, v4l2_kioctl func);
+/**
+ * video_usercopy - copies data from/to userspace memory when an ioctl is
+ *	issued.
+ *
+ * @file: Pointer to struct &file.
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ * @func: function that will handle the ioctl
+ *
+ * .. note::
+ *
+ *    This routine should be used only inside the V4L2 core.
+ */
+long int video_usercopy(struct file *file, unsigned int cmd,
+			unsigned long int arg, v4l2_kioctl func);
 
-/* Standard handlers for V4L ioctl's */
-extern long video_ioctl2(struct file *file,
-			unsigned int cmd, unsigned long arg);
+/**
+ * video_ioctl2 - Handles a V4L2 ioctl.
+ *
+ * @file: Pointer to struct &file.
+ * @cmd: Ioctl name.
+ * @arg: Ioctl argument.
+ *
+ * Method used to hancle an ioctl. Should be used to fill the
+ * &v4l2_ioctl_ops.unlocked_ioctl on all V4L2 drivers.
+ */
+long int video_ioctl2(struct file *file,
+		      unsigned int cmd, unsigned long int arg);
 
 #endif /* _V4L2_IOCTL_H */
diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h
index 28c3f9d9c209..2634d9dc9916 100644
--- a/include/media/v4l2-mc.h
+++ b/include/media/v4l2-mc.h
@@ -53,7 +53,7 @@ enum tuner_pad_index {
 };
 
 /**
- * enum if_vid_dec_index - video IF-PLL pad index for
+ * enum if_vid_dec_pad_index - video IF-PLL pad index for
  *			   MEDIA_ENT_F_IF_VID_DECODER
  *
  * @IF_VID_DEC_PAD_IF_INPUT:	video Intermediate Frequency (IF) sink pad
@@ -68,7 +68,7 @@ enum if_vid_dec_pad_index {
 };
 
 /**
- * enum if_aud_dec_index - audio/sound IF-PLL pad index for
+ * enum if_aud_dec_pad_index - audio/sound IF-PLL pad index for
  *			   MEDIA_ENT_F_IF_AUD_DECODER
  *
  * @IF_AUD_DEC_PAD_IF_INPUT:	audio Intermediate Frequency (IF) sink pad
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index 5a9597dd1ee0..1b355344c804 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -41,9 +41,9 @@
  *		This function does not have to (and will usually not) wait
  *		until the device enters a state when it can be stopped.
  * @lock:	optional. Define a driver's own lock callback, instead of using
- *		m2m_ctx->q_lock.
+ *		&v4l2_m2m_ctx->q_lock.
  * @unlock:	optional. Define a driver's own unlock callback, instead of
- *		using m2m_ctx->q_lock.
+ *		using &v4l2_m2m_ctx->q_lock.
  */
 struct v4l2_m2m_ops {
 	void (*device_run)(void *priv);
@@ -55,29 +55,51 @@ struct v4l2_m2m_ops {
 
 struct v4l2_m2m_dev;
 
+/**
+ * struct v4l2_m2m_queue_ctx - represents a queue for buffers ready to be
+ *	processed
+ *
+ * @q:		pointer to struct &vb2_queue
+ * @rdy_queue:	List of V4L2 mem-to-mem queues
+ * @rdy_spinlock: spin lock to protect the struct usage
+ * @num_rdy:	number of buffers ready to be processed
+ * @buffered:	is the queue buffered?
+ *
+ * Queue for buffers ready to be processed as soon as this
+ * instance receives access to the device.
+ */
+
 struct v4l2_m2m_queue_ctx {
-/* private: internal use only */
 	struct vb2_queue	q;
 
-	/* Queue for buffers ready to be processed as soon as this
-	 * instance receives access to the device */
 	struct list_head	rdy_queue;
 	spinlock_t		rdy_spinlock;
 	u8			num_rdy;
 	bool			buffered;
 };
 
+/**
+ * struct v4l2_m2m_ctx - Memory to memory context structure
+ *
+ * @q_lock: struct &mutex lock
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
+ * @cap_q_ctx: Capture (output to memory) queue context
+ * @out_q_ctx: Output (input from memory) queue context
+ * @queue: List of memory to memory contexts
+ * @job_flags: Job queue flags, used internally by v4l2-mem2mem.c:
+ *		%TRANS_QUEUED, %TRANS_RUNNING and %TRANS_ABORT.
+ * @finished: Wait queue used to signalize when a job queue finished.
+ * @priv: Instance private data
+ */
 struct v4l2_m2m_ctx {
 	/* optional cap/out vb2 queues lock */
 	struct mutex			*q_lock;
 
-/* private: internal use only */
+	/* internal use only */
 	struct v4l2_m2m_dev		*m2m_dev;
 
-	/* Capture (output to memory) queue context */
 	struct v4l2_m2m_queue_ctx	cap_q_ctx;
 
-	/* Output (input from memory) queue context */
 	struct v4l2_m2m_queue_ctx	out_q_ctx;
 
 	/* For device job queue */
@@ -85,22 +107,75 @@ struct v4l2_m2m_ctx {
 	unsigned long			job_flags;
 	wait_queue_head_t		finished;
 
-	/* Instance private data */
 	void				*priv;
 };
 
+/**
+ * struct v4l2_m2m_buffer - Memory to memory buffer
+ *
+ * @vb: pointer to struct &vb2_v4l2_buffer
+ * @list: list of m2m buffers
+ */
 struct v4l2_m2m_buffer {
 	struct vb2_v4l2_buffer	vb;
 	struct list_head	list;
 };
 
+/**
+ * v4l2_m2m_get_curr_priv() - return driver private data for the currently
+ * running instance or NULL if no instance is running
+ *
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
+ */
 void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev);
 
+/**
+ * v4l2_m2m_get_vq() - return vb2_queue for the given type
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
+ */
 struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx,
 				       enum v4l2_buf_type type);
 
+/**
+ * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to
+ * the pending job queue and add it if so.
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ *
+ * There are three basic requirements an instance has to meet to be able to run:
+ * 1) at least one source buffer has to be queued,
+ * 2) at least one destination buffer has to be queued,
+ * 3) streaming has to be on.
+ *
+ * If a queue is buffered (for example a decoder hardware ringbuffer that has
+ * to be drained before doing streamoff), allow scheduling without v4l2 buffers
+ * on that queue.
+ *
+ * There may also be additional, custom requirements. In such case the driver
+ * should supply a custom callback (job_ready in v4l2_m2m_ops) that should
+ * return 1 if the instance is ready.
+ * An example of the above could be an instance that requires more than one
+ * src/dst buffer per transaction.
+ */
 void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx);
 
+/**
+ * v4l2_m2m_job_finish() - inform the framework that a job has been finished
+ * and have it clean up
+ *
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ *
+ * Called by a driver to yield back the device after it has finished with it.
+ * Should be called as soon as possible after reaching a state which allows
+ * other instances to take control of the device.
+ *
+ * This function has to be called only after &v4l2_m2m_ops->device_run
+ * callback has been called on the driver. To prevent recursion, it should
+ * not be called directly from the &v4l2_m2m_ops->device_run callback though.
+ */
 void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev,
 			 struct v4l2_m2m_ctx *m2m_ctx);
 
@@ -110,38 +185,165 @@ v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state)
 	vb2_buffer_done(&buf->vb2_buf, state);
 }
 
+/**
+ * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @reqbufs: pointer to struct &v4l2_requestbuffers
+ */
 int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		     struct v4l2_requestbuffers *reqbufs);
 
+/**
+ * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
+ *
+ * See v4l2_m2m_mmap() documentation for details.
+ */
 int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		      struct v4l2_buffer *buf);
 
+/**
+ * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on
+ * the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
+ */
 int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		  struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on
+ * the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
+ */
 int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		   struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on
+ * the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @buf: pointer to struct &v4l2_buffer
+ */
 int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 			 struct v4l2_buffer *buf);
+
+/**
+ * v4l2_m2m_create_bufs() - create a source or destination buffer, depending
+ * on the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @create: pointer to struct &v4l2_create_buffers
+ */
 int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 			 struct v4l2_create_buffers *create);
 
+/**
+ * v4l2_m2m_expbuf() - export a source or destination buffer, depending on
+ * the type
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @eb: pointer to struct &v4l2_exportbuffer
+ */
 int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		   struct v4l2_exportbuffer *eb);
 
+/**
+ * v4l2_m2m_streamon() - turn on streaming for a video queue
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
+ */
 int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		      enum v4l2_buf_type type);
+
+/**
+ * v4l2_m2m_streamoff() - turn off streaming for a video queue
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type
+ */
 int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		       enum v4l2_buf_type type);
 
+/**
+ * v4l2_m2m_poll() - poll replacement, for destination buffers only
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @wait: pointer to struct &poll_table_struct
+ *
+ * Call from the driver's poll() function. Will poll both queues. If a buffer
+ * is available to dequeue (with dqbuf) from the source queue, this will
+ * indicate that a non-blocking write can be performed, while read will be
+ * returned in case of the destination queue.
+ */
 unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 			   struct poll_table_struct *wait);
 
+/**
+ * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer
+ *
+ * @file: pointer to struct &file
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @vma: pointer to struct &vm_area_struct
+ *
+ * Call from driver's mmap() function. Will handle mmap() for both queues
+ * seamlessly for videobuffer, which will receive normal per-queue offsets and
+ * proper videobuf queue pointers. The differentiation is made outside videobuf
+ * by adding a predefined offset to buffers from one of the queues and
+ * subtracting it before passing it back to videobuf. Only drivers (and
+ * thus applications) receive modified offsets.
+ */
 int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx,
 		  struct vm_area_struct *vma);
 
+/**
+ * v4l2_m2m_init() - initialize per-driver m2m data
+ *
+ * @m2m_ops: pointer to struct v4l2_m2m_ops
+ *
+ * Usually called from driver's ``probe()`` function.
+ *
+ * Return: returns an opaque pointer to the internal data to handle M2M context
+ */
 struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops);
+
+/**
+ * v4l2_m2m_release() - cleans up and frees a m2m_dev structure
+ *
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
+ *
+ * Usually called from driver's ``remove()`` function.
+ */
 void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev);
 
+/**
+ * v4l2_m2m_ctx_init() - allocate and initialize a m2m context
+ *
+ * @m2m_dev: opaque pointer to the internal data to handle M2M context
+ * @drv_priv: driver's instance private data
+ * @queue_init: a callback for queue type-specific initialization function
+ *	to be used for initializing videobuf_queues
+ *
+ * Usually called from driver's ``open()`` function.
+ */
 struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev,
 		void *drv_priv,
 		int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq));
@@ -158,8 +360,23 @@ static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx,
 	m2m_ctx->cap_q_ctx.buffered = buffered;
 }
 
+/**
+ * v4l2_m2m_ctx_release() - release m2m context
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ *
+ * Usually called from driver's release() function.
+ */
 void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx);
 
+/**
+ * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list.
+ *
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
+ * @vbuf: pointer to struct &vb2_v4l2_buffer
+ *
+ * Call from videobuf_queue_ops->ops->buf_queue, videobuf_queue_ops callback.
+ */
 void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
 			struct vb2_v4l2_buffer *vbuf);
 
@@ -167,7 +384,7 @@ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx,
  * v4l2_m2m_num_src_bufs_ready() - return the number of source buffers ready for
  * use
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline
 unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -176,10 +393,10 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
 }
 
 /**
- * v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers
+ * v4l2_m2m_num_dst_bufs_ready() - return the number of destination buffers
  * ready for use
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline
 unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -187,13 +404,18 @@ unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
 	return m2m_ctx->cap_q_ctx.num_rdy;
 }
 
+/**
+ * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers
+ *
+ * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx
+ */
 void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx);
 
 /**
  * v4l2_m2m_next_src_buf() - return next source buffer from the list of ready
  * buffers
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -204,7 +426,7 @@ static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx)
  * v4l2_m2m_next_dst_buf() - return next destination buffer from the list of
  * ready buffers
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -214,7 +436,7 @@ static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx)
 /**
  * v4l2_m2m_get_src_vq() - return vb2_queue for source buffers
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline
 struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -225,7 +447,7 @@ struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx)
 /**
  * v4l2_m2m_get_dst_vq() - return vb2_queue for destination buffers
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline
 struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -233,13 +455,19 @@ struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
 	return &m2m_ctx->cap_q_ctx.q;
 }
 
+/**
+ * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and
+ * return it
+ *
+ * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx
+ */
 void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx);
 
 /**
  * v4l2_m2m_src_buf_remove() - take off a source buffer from the list of ready
  * buffers and return it
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -250,7 +478,7 @@ static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
  * v4l2_m2m_dst_buf_remove() - take off a destination buffer from the list of
  * ready buffers and return it
  *
- * @m2m_ctx: pointer to struct v4l2_m2m_ctx
+ * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
  */
 static inline void *v4l2_m2m_dst_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
 {
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 2a2240c99b30..cf778c5dca18 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -184,8 +184,6 @@ struct v4l2_subdev_io_pin_config {
  *		     for it to be warned when the value of a control changes.
  *
  * @unsubscribe_event: remove event subscription from the control framework.
- *
- * @registered_async: the subdevice has been registered async.
  */
 struct v4l2_subdev_core_ops {
 	int (*log_status)(struct v4l2_subdev *sd);
@@ -211,11 +209,11 @@ struct v4l2_subdev_core_ops {
 			       struct v4l2_event_subscription *sub);
 	int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
 				 struct v4l2_event_subscription *sub);
-	int (*registered_async)(struct v4l2_subdev *sd);
 };
 
 /**
- * struct s_radio - Callbacks used when v4l device was opened in radio mode.
+ * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
+ *	in radio mode.
  *
  * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
  *
@@ -229,7 +227,7 @@ struct v4l2_subdev_core_ops {
  *
  * @g_tuner: callback for %VIDIOC_G_TUNER ioctl handler code.
  *
- * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. &vt->type must be
+ * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. @vt->type must be
  *	     filled in. Normally done by video_ioctl2 or the
  *	     bridge driver.
  *
@@ -358,11 +356,7 @@ struct v4l2_mbus_frame_desc {
  * @s_stream: used to notify the driver that a video stream will start or has
  *	stopped.
  *
- * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code.
- *
- * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code.
- *
- * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code.
+ * @g_pixelaspect: callback to return the pixelaspect ratio.
  *
  * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code.
  *
@@ -402,9 +396,7 @@ struct v4l2_subdev_video_ops {
 	int (*g_tvnorms_output)(struct v4l2_subdev *sd, v4l2_std_id *std);
 	int (*g_input_status)(struct v4l2_subdev *sd, u32 *status);
 	int (*s_stream)(struct v4l2_subdev *sd, int enable);
-	int (*cropcap)(struct v4l2_subdev *sd, struct v4l2_cropcap *cc);
-	int (*g_crop)(struct v4l2_subdev *sd, struct v4l2_crop *crop);
-	int (*s_crop)(struct v4l2_subdev *sd, const struct v4l2_crop *crop);
+	int (*g_pixelaspect)(struct v4l2_subdev *sd, struct v4l2_fract *aspect);
 	int (*g_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
 	int (*s_parm)(struct v4l2_subdev *sd, struct v4l2_streamparm *param);
 	int (*g_frame_interval)(struct v4l2_subdev *sd,
@@ -430,7 +422,7 @@ struct v4l2_subdev_video_ops {
  *				  in video mode via the vbi device node.
  *
  *  @decode_vbi_line: video decoders that support sliced VBI need to implement
- *	this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the
+ *	this ioctl. Field p of the &struct v4l2_decode_vbi_line is set to the
  *	start of the VBI data that was generated by the decoder. The driver
  *	then parses the sliced VBI data and sets the other fields in the
  *	struct accordingly. The pointer p is updated to point to the start of
@@ -773,7 +765,7 @@ struct v4l2_subdev_platform_data {
  * @entity: pointer to &struct media_entity
  * @list: List of sub-devices
  * @owner: The owner is the same as the driver's &struct device owner.
- * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev
+ * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
  *	ownner. Initialized by v4l2_device_register_subdev().
  * @flags: subdev flags. Can be:
  *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
@@ -783,9 +775,9 @@ struct v4l2_subdev_platform_data {
  *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
  *   events.
  *
- * @v4l2_dev: pointer to &struct v4l2_device
- * @ops: pointer to &struct v4l2_subdev_ops
- * @internal_ops: pointer to &struct v4l2_subdev_internal_ops.
+ * @v4l2_dev: pointer to struct &v4l2_device
+ * @ops: pointer to struct &v4l2_subdev_ops
+ * @internal_ops: pointer to struct &v4l2_subdev_internal_ops.
  *	Never call these internal ops from within a driver!
  * @ctrl_handler: The control handler of this subdev. May be NULL.
  * @name: Name of the sub-device. Please notice that the name must be unique.
@@ -896,7 +888,7 @@ static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
 }
 
 /**
- * v4l2_set_subdevdata - Sets V4L2 dev private host data
+ * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data
  *
  * @sd: pointer to &struct v4l2_subdev
  * @p: pointer to the private data to be stored.
@@ -907,7 +899,7 @@ static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
 }
 
 /**
- * v4l2_get_subdevdata - Gets V4L2 dev private data
+ * v4l2_get_subdev_hostdata - Gets V4L2 dev private data
  *
  * @sd: pointer to &struct v4l2_subdev
  *
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index a4a9a55a0c42..ac5898a55fd9 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -20,6 +20,20 @@
 #define VB2_MAX_FRAME	(32)
 #define VB2_MAX_PLANES	(8)
 
+/**
+ * enum vb2_memory - type of memory model used to make the buffers visible
+ *	on userspace.
+ *
+ * @VB2_MEMORY_UNKNOWN:	Buffer status is unknown or it is not used yet on
+ *			userspace.
+ * @VB2_MEMORY_MMAP:	The buffers are allocated by the Kernel and it is
+ *			memory mapped via mmap() ioctl. This model is
+ *			also used when the user is using the buffers via
+ *			read() or write() system calls.
+ * @VB2_MEMORY_USERPTR:	The buffers was allocated in userspace and it is
+ *			memory mapped via mmap() ioctl.
+ * @VB2_MEMORY_DMABUF:	The buffers are passed to userspace via DMA buffer.
+ */
 enum vb2_memory {
 	VB2_MEMORY_UNKNOWN	= 0,
 	VB2_MEMORY_MMAP		= 1,
@@ -33,15 +47,15 @@ struct vb2_threadio_data;
 /**
  * struct vb2_mem_ops - memory handling/memory allocator operations
  * @alloc:	allocate video memory and, optionally, allocator private data,
- *		return NULL on failure or a pointer to allocator private,
+ *		return ERR_PTR() on failure or a pointer to allocator private,
  *		per-buffer data on success; the returned private structure
- *		will then be passed as buf_priv argument to other ops in this
+ *		will then be passed as @buf_priv argument to other ops in this
  *		structure. Additional gfp_flags to use when allocating the
  *		are also passed to this operation. These flags are from the
  *		gfp_flags field of vb2_queue.
  * @put:	inform the allocator that the buffer will no longer be used;
  *		usually will result in the allocator freeing the buffer (if
- *		no other users of this buffer are present); the buf_priv
+ *		no other users of this buffer are present); the @buf_priv
  *		argument is the allocator private per-buffer structure
  *		previously returned from the alloc callback.
  * @get_dmabuf: acquire userspace memory for a hardware operation; used for
@@ -50,18 +64,18 @@ struct vb2_threadio_data;
  *		 USERPTR memory types; vaddr is the address passed to the
  *		 videobuf layer when queuing a video buffer of USERPTR type;
  *		 should return an allocator private per-buffer structure
- *		 associated with the buffer on success, NULL on failure;
- *		 the returned private structure will then be passed as buf_priv
+ *		 associated with the buffer on success, ERR_PTR() on failure;
+ *		 the returned private structure will then be passed as @buf_priv
  *		 argument to other ops in this structure.
  * @put_userptr: inform the allocator that a USERPTR buffer will no longer
  *		 be used.
  * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
  *		   used for DMABUF memory types; dev is the alloc device
- *		   dbuf is the shared dma_buf; returns NULL on failure;
+ *		   dbuf is the shared dma_buf; returns ERR_PTR() on failure;
  *		   allocator private per-buffer structure on success;
  *		   this needs to be used for further accesses to the buffer.
  * @detach_dmabuf: inform the exporter of the buffer that the current DMABUF
- *		   buffer is no longer used; the buf_priv argument is the
+ *		   buffer is no longer used; the @buf_priv argument is the
  *		   allocator private per-buffer structure previously returned
  *		   from the attach_dmabuf callback.
  * @map_dmabuf: request for access to the dmabuf from allocator; the allocator
@@ -95,11 +109,13 @@ struct vb2_threadio_data;
  *
  *    #) Required ops for read/write access types: alloc, put, num_users, vaddr.
  *
- *    #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
+ *    #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf,
+ *       map_dmabuf, unmap_dmabuf.
  */
 struct vb2_mem_ops {
 	void		*(*alloc)(struct device *dev, unsigned long attrs,
-				  unsigned long size, enum dma_data_direction dma_dir,
+				  unsigned long size,
+				  enum dma_data_direction dma_dir,
 				  gfp_t gfp_flags);
 	void		(*put)(void *buf_priv);
 	struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags);
@@ -112,7 +128,8 @@ struct vb2_mem_ops {
 	void		(*prepare)(void *buf_priv);
 	void		(*finish)(void *buf_priv);
 
-	void		*(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf,
+	void		*(*attach_dmabuf)(struct device *dev,
+					  struct dma_buf *dbuf,
 					  unsigned long size,
 					  enum dma_data_direction dma_dir);
 	void		(*detach_dmabuf)(void *buf_priv);
@@ -277,7 +294,7 @@ struct vb2_buffer {
 /**
  * struct vb2_ops - driver-specific callbacks
  *
- * @queue_setup:	called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS
+ * @queue_setup:	called from VIDIOC_REQBUFS() and VIDIOC_CREATE_BUFS()
  *			handlers before memory allocation. It can be called
  *			twice: if the original number of requested buffers
  *			could not be allocated, then it will be called a
@@ -288,11 +305,11 @@ struct vb2_buffer {
  *			buffer in \*num_planes, the size of each plane should be
  *			set in the sizes\[\] array and optional per-plane
  *			allocator specific device in the alloc_devs\[\] array.
- *			When called from %VIDIOC_REQBUFS, \*num_planes == 0, the
- *			driver has to use the currently configured format to
+ *			When called from VIDIOC_REQBUFS,() \*num_planes == 0,
+ *			the driver has to use the currently configured format to
  *			determine the plane sizes and \*num_buffers is the total
  *			number of buffers that are being allocated. When called
- *			from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
+ *			from VIDIOC_CREATE_BUFS,() \*num_planes != 0 and it
  *			describes the requested number of planes and sizes\[\]
  *			contains the requested plane sizes. If either
  *			\*num_planes or the requested sizes are invalid callback
@@ -311,11 +328,11 @@ struct vb2_buffer {
  *			initialization failure (return != 0) will prevent
  *			queue setup from completing successfully; optional.
  * @buf_prepare:	called every time the buffer is queued from userspace
- *			and from the %VIDIOC_PREPARE_BUF ioctl; drivers may
+ *			and from the VIDIOC_PREPARE_BUF() ioctl; drivers may
  *			perform any initialization required before each
  *			hardware operation in this callback; drivers can
  *			access/modify the buffer here as it is still synced for
- *			the CPU; drivers that support %VIDIOC_CREATE_BUFS must
+ *			the CPU; drivers that support VIDIOC_CREATE_BUFS() must
  *			also validate the buffer size; if an error is returned,
  *			the buffer will not be queued in driver; optional.
  * @buf_finish:		called before every dequeue of the buffer back to
@@ -339,24 +356,25 @@ struct vb2_buffer {
  *			driver can return an error if hardware fails, in that
  *			case all buffers that have been already given by
  *			the @buf_queue callback are to be returned by the driver
- *			by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\).
+ *			by calling vb2_buffer_done() with %VB2_BUF_STATE_QUEUED.
  *			If you need a minimum number of buffers before you can
  *			start streaming, then set @min_buffers_needed in the
  *			vb2_queue structure. If that is non-zero then
- *			start_streaming won't be called until at least that
+ *			@start_streaming won't be called until at least that
  *			many buffers have been queued up by userspace.
  * @stop_streaming:	called when 'streaming' state must be disabled; driver
  *			should stop any DMA transactions or wait until they
  *			finish and give back all buffers it got from &buf_queue
- *			callback by calling @vb2_buffer_done\(\) with either
+ *			callback by calling vb2_buffer_done() with either
  *			%VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
  *			vb2_wait_for_all_buffers() function
  * @buf_queue:		passes buffer vb to the driver; driver may start
  *			hardware operation on this buffer; driver should give
  *			the buffer back by calling vb2_buffer_done() function;
- *			it is allways called after calling %VIDIOC_STREAMON ioctl;
- *			might be called before start_streaming callback if user
- *			pre-queued buffers before calling %VIDIOC_STREAMON.
+ *			it is allways called after calling VIDIOC_STREAMON()
+ *			ioctl; might be called before @start_streaming callback
+ *			if user pre-queued buffers before calling
+ *			VIDIOC_STREAMON().
  */
 struct vb2_ops {
 	int (*queue_setup)(struct vb2_queue *q,
@@ -378,7 +396,7 @@ struct vb2_ops {
 };
 
 /**
- * struct vb2_ops - driver-specific callbacks
+ * struct vb2_buf_ops - driver-specific callbacks
  *
  * @verify_planes_array: Verify that a given user space structure contains
  *			enough planes for the buffer. This is called
@@ -404,7 +422,7 @@ struct vb2_buf_ops {
  *
  * @type:	private buffer type whose content is defined by the vb2-core
  *		caller. For example, for V4L2, it should match
- *		the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h
+ *		the types defined on enum &v4l2_buf_type
  * @io_modes:	supported io methods (see vb2_io_modes enum)
  * @dev:	device to use for the default allocation context if the driver
  *		doesn't fill in the @alloc_devs array.
@@ -439,12 +457,12 @@ struct vb2_buf_ops {
  *		Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32
  *		to force the buffer allocation to a specific memory zone.
  * @min_buffers_needed: the minimum number of buffers needed before
- *		start_streaming() can be called. Used when a DMA engine
+ *		@start_streaming can be called. Used when a DMA engine
  *		cannot be started unless at least this number of buffers
  *		have been queued into the driver.
  */
 /*
- * Private elements (won't appear at the DocBook):
+ * Private elements (won't appear at the uAPI book):
  * @mmap_lock:	private mutex used when buffers are allocated/freed/mmapped
  * @memory:	current memory type used
  * @bufs:	videobuf buffer structures
@@ -457,7 +475,7 @@ struct vb2_buf_ops {
  * @done_wq:	waitqueue for processes waiting for buffers ready to be dequeued
  * @alloc_devs:	memory type/allocator-specific per-plane device
  * @streaming:	current streaming state
- * @start_streaming_called: start_streaming() was called successfully and we
+ * @start_streaming_called: @start_streaming was called successfully and we
  *		started streaming.
  * @error:	a fatal error occurred on the queue
  * @waiting_for_buffers: used in poll() to check if vb2 is still waiting for
@@ -536,36 +554,286 @@ struct vb2_queue {
 #endif
 };
 
+/**
+ * vb2_plane_vaddr() - Return a kernel virtual address of a given plane
+ * @vb:		vb2_buffer to which the plane in question belongs to
+ * @plane_no:	plane number for which the address is to be returned
+ *
+ * This function returns a kernel virtual address of a given plane if
+ * such a mapping exist, NULL otherwise.
+ */
 void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
+
+/**
+ * vb2_plane_cookie() - Return allocator specific cookie for the given plane
+ * @vb:		vb2_buffer to which the plane in question belongs to
+ * @plane_no:	plane number for which the cookie is to be returned
+ *
+ * This function returns an allocator specific cookie for a given plane if
+ * available, NULL otherwise. The allocator should provide some simple static
+ * inline function, which would convert this cookie to the allocator specific
+ * type that can be used directly by the driver to access the buffer. This can
+ * be for example physical address, pointer to scatter list or IOMMU mapping.
+ */
 void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
 
+/**
+ * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished
+ * @vb:		vb2_buffer returned from the driver
+ * @state:	either %VB2_BUF_STATE_DONE if the operation finished
+ *		successfully, %VB2_BUF_STATE_ERROR if the operation finished
+ *		with an error or %VB2_BUF_STATE_QUEUED if the driver wants to
+ *		requeue buffers. If start_streaming fails then it should return
+ *		buffers with state %VB2_BUF_STATE_QUEUED to put them back into
+ *		the queue.
+ *
+ * This function should be called by the driver after a hardware operation on
+ * a buffer is finished and the buffer may be returned to userspace. The driver
+ * cannot use this buffer anymore until it is queued back to it by videobuf
+ * by the means of &vb2_ops->buf_queue callback. Only buffers previously queued
+ * to the driver by &vb2_ops->buf_queue can be passed to this function.
+ *
+ * While streaming a buffer can only be returned in state DONE or ERROR.
+ * The start_streaming op can also return them in case the DMA engine cannot
+ * be started for some reason. In that case the buffers should be returned with
+ * state QUEUED.
+ */
 void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
+
+/**
+ * vb2_discard_done() - discard all buffers marked as DONE
+ * @q:		videobuf2 queue
+ *
+ * This function is intended to be used with suspend/resume operations. It
+ * discards all 'done' buffers as they would be too old to be requested after
+ * resume.
+ *
+ * Drivers must stop the hardware and synchronize with interrupt handlers and/or
+ * delayed works before calling this function to make sure no buffer will be
+ * touched by the driver and/or hardware.
+ */
 void vb2_discard_done(struct vb2_queue *q);
+
+/**
+ * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2
+ * @q:		videobuf2 queue
+ *
+ * This function will wait until all buffers that have been given to the driver
+ * by &vb2_ops->buf_queue are given back to vb2 with vb2_buffer_done(). It
+ * doesn't call wait_prepare()/wait_finish() pair. It is intended to be called
+ * with all locks taken, for example from &vb2_ops->stop_streaming callback.
+ */
 int vb2_wait_for_all_buffers(struct vb2_queue *q);
 
+/**
+ * vb2_core_querybuf() - query video buffer information
+ * @q:		videobuf queue
+ * @index:	id number of the buffer
+ * @pb:		buffer struct passed from userspace
+ *
+ * Should be called from vidioc_querybuf ioctl handler in driver.
+ * The passed buffer should have been verified.
+ * This function fills the relevant information for the userspace.
+ */
 void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_reqbufs() - Initiate streaming
+ * @q:		videobuf2 queue
+ * @memory: memory type
+ * @count: requested buffer count
+ *
+ * Should be called from vidioc_reqbufs ioctl handler of a driver.
+ *
+ * This function:
+ *
+ * #) verifies streaming parameters passed from the userspace,
+ * #) sets up the queue,
+ * #) negotiates number of buffers and planes per buffer with the driver
+ *    to be used during streaming,
+ * #) allocates internal buffer structures (struct vb2_buffer), according to
+ *    the agreed parameters,
+ * #) for MMAP memory type, allocates actual video memory, using the
+ *    memory handling/allocation routines provided during queue initialization
+ *
+ * If req->count is 0, all the memory will be freed instead.
+ * If the queue has been allocated previously (by a previous vb2_reqbufs) call
+ * and the queue is not busy, memory will be reallocated.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_reqbufs handler in driver.
+ */
 int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
 		unsigned int *count);
+
+/**
+ * vb2_core_create_bufs() - Allocate buffers and any required auxiliary structs
+ * @q:		videobuf2 queue
+ * @memory: memory type
+ * @count: requested buffer count
+ * @requested_planes: number of planes requested
+ * @requested_sizes: array with the size of the planes
+ *
+ * Should be called from VIDIOC_CREATE_BUFS() ioctl handler of a driver.
+ * This function:
+ *
+ * #) verifies parameter sanity
+ * #) calls the .queue_setup() queue operation
+ * #) performs any necessary memory allocations
+ *
+ * Return: the return values from this function are intended to be directly
+ * returned from VIDIOC_CREATE_BUFS() handler in driver.
+ */
 int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
-		unsigned int *count, unsigned requested_planes,
-		const unsigned int requested_sizes[]);
+			 unsigned int *count, unsigned int requested_planes,
+			 const unsigned int requested_sizes[]);
+
+/**
+ * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace
+ *			to the kernel
+ * @q:		videobuf2 queue
+ * @index:	id number of the buffer
+ * @pb:		buffer structure passed from userspace to vidioc_prepare_buf
+ *		handler in driver
+ *
+ * Should be called from vidioc_prepare_buf ioctl handler of a driver.
+ * The passed buffer should have been verified.
+ * This function calls buf_prepare callback in the driver (if provided),
+ * in which driver-specific buffer initialization can be performed,
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_prepare_buf handler in driver.
+ */
 int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_qbuf() - Queue a buffer from userspace
+ *
+ * @q:		videobuf2 queue
+ * @index:	id number of the buffer
+ * @pb:		buffer structure passed from userspace to vidioc_qbuf handler
+ *		in driver
+ *
+ * Should be called from vidioc_qbuf ioctl handler of a driver.
+ * The passed buffer should have been verified.
+ *
+ * This function:
+ *
+ * #) if necessary, calls buf_prepare callback in the driver (if provided), in
+ *    which driver-specific buffer initialization can be performed,
+ * #) if streaming is on, queues the buffer in driver by the means of
+ *    &vb2_ops->buf_queue callback for processing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_qbuf handler in driver.
+ */
 int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
+
+/**
+ * vb2_core_dqbuf() - Dequeue a buffer to the userspace
+ * @q:		videobuf2 queue
+ * @pindex:	pointer to the buffer index. May be NULL
+ * @pb:		buffer structure passed from userspace to vidioc_dqbuf handler
+ *		in driver
+ * @nonblocking: if true, this call will not sleep waiting for a buffer if no
+ *		 buffers ready for dequeuing are present. Normally the driver
+ *		 would be passing (file->f_flags & O_NONBLOCK) here
+ *
+ * Should be called from vidioc_dqbuf ioctl handler of a driver.
+ * The passed buffer should have been verified.
+ *
+ * This function:
+ *
+ * #) calls buf_finish callback in the driver (if provided), in which
+ *    driver can perform any additional operations that may be required before
+ *    returning the buffer to userspace, such as cache sync,
+ * #) the buffer struct members are filled with relevant information for
+ *    the userspace.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_dqbuf handler in driver.
+ */
 int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
 		   bool nonblocking);
 
 int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
 int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
 
+/**
+ * vb2_core_expbuf() - Export a buffer as a file descriptor
+ * @q:		videobuf2 queue
+ * @fd:		file descriptor associated with DMABUF (set by driver) *
+ * @type:	buffer type
+ * @index:	id number of the buffer
+ * @plane:	index of the plane to be exported, 0 for single plane queues
+ * @flags:	flags for newly created file, currently only O_CLOEXEC is
+ *		supported, refer to manual of open syscall for more details
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_expbuf handler in driver.
+ */
 int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
 		unsigned int index, unsigned int plane, unsigned int flags);
 
+/**
+ * vb2_core_queue_init() - initialize a videobuf2 queue
+ * @q:		videobuf2 queue; this structure should be allocated in driver
+ *
+ * The vb2_queue structure should be allocated by the driver. The driver is
+ * responsible of clearing it's content and setting initial values for some
+ * required entries before calling this function.
+ * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
+ * to the struct vb2_queue description in include/media/videobuf2-core.h
+ * for more information.
+ */
 int vb2_core_queue_init(struct vb2_queue *q);
+
+/**
+ * vb2_core_queue_release() - stop streaming, release the queue and free memory
+ * @q:		videobuf2 queue
+ *
+ * This function stops streaming and performs necessary clean ups, including
+ * freeing video buffer memory. The driver is responsible for freeing
+ * the vb2_queue structure itself.
+ */
 void vb2_core_queue_release(struct vb2_queue *q);
 
+/**
+ * vb2_queue_error() - signal a fatal error on the queue
+ * @q:		videobuf2 queue
+ *
+ * Flag that a fatal unrecoverable error has occurred and wake up all processes
+ * waiting on the queue. Polling will now set POLLERR and queuing and dequeuing
+ * buffers will return -EIO.
+ *
+ * The error flag will be cleared when cancelling the queue, either from
+ * vb2_streamoff or vb2_queue_release. Drivers should thus not call this
+ * function before starting the stream, otherwise the error flag will remain set
+ * until the queue is released when closing the device node.
+ */
 void vb2_queue_error(struct vb2_queue *q);
 
+/**
+ * vb2_mmap() - map video buffers into application address space
+ * @q:		videobuf2 queue
+ * @vma:	vma passed to the mmap file operation handler in the driver
+ *
+ * Should be called from mmap file operation handler of a driver.
+ * This function maps one plane of one of the available video buffers to
+ * userspace. To map whole video memory allocated on reqbufs, this function
+ * has to be called once per each plane per each buffer previously allocated.
+ *
+ * When the userspace application calls mmap, it passes to it an offset returned
+ * to it earlier by the means of vidioc_querybuf handler. That offset acts as
+ * a "cookie", which is then used to identify the plane to be mapped.
+ * This function finds a plane with a matching offset and a mapping is performed
+ * by the means of a provided memory operation.
+ *
+ * The return values from this function are intended to be directly returned
+ * from the mmap handler in driver.
+ */
 int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
+
 #ifndef CONFIG_MMU
 unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 				    unsigned long addr,
@@ -573,15 +841,36 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 				    unsigned long pgoff,
 				    unsigned long flags);
 #endif
+
+/**
+ * vb2_core_poll() - implements poll userspace operation
+ * @q:		videobuf2 queue
+ * @file:	file argument passed to the poll file operation handler
+ * @wait:	wait argument passed to the poll file operation handler
+ *
+ * This function implements poll file operation handler for a driver.
+ * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
+ * be informed that the file descriptor of a video device is available for
+ * reading.
+ * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
+ * will be reported as available for writing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from poll handler in driver.
+ */
 unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
-		poll_table *wait);
+			   poll_table *wait);
+
 size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
 size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
 
-/*
- * vb2_thread_fnc - callback function for use with vb2_thread
+/**
+ * typedef vb2_thread_fnc - callback function for use with vb2_thread
+ *
+ * @vb: pointer to struct &vb2_buffer
+ * @priv: pointer to a private pointer
  *
  * This is called whenever a buffer is dequeued in the thread.
  */
@@ -597,9 +886,11 @@ typedef int (*vb2_thread_fnc)(struct vb2_buffer *vb, void *priv);
  * This starts a thread that will queue and dequeue until an error occurs
  * or @vb2_thread_stop is called.
  *
- * This function should not be used for anything else but the videobuf2-dvb
- * support. If you think you have another good use-case for this, then please
- * contact the linux-media mailinglist first.
+ * .. attention::
+ *
+ *   This function should not be used for anything else but the videobuf2-dvb
+ *   support. If you think you have another good use-case for this, then please
+ *   contact the linux-media mailing list first.
  */
 int vb2_thread_start(struct vb2_queue *q, vb2_thread_fnc fnc, void *priv,
 		     const char *thread_name);
@@ -717,7 +1008,26 @@ static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q)
  * The following functions are not part of the vb2 core API, but are useful
  * functions for videobuf2-*.
  */
+
+/**
+ * vb2_buffer_in_use() - return true if the buffer is in use and
+ * the queue cannot be freed (by the means of REQBUFS(0)) call
+ *
+ * @vb:		buffer for which plane size should be returned
+ * @q:		videobuf queue
+ */
 bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
+
+/**
+ * vb2_verify_memory_type() - Check whether the memory type and buffer type
+ * passed to a buffer operation are compatible with the queue.
+ *
+ * @q:		videobuf queue
+ * @memory:	memory model, as defined by enum &vb2_memory.
+ * @type:	private buffer type whose content is defined by the vb2-core
+ *		caller. For example, for V4L2, it should match
+ *		the types defined on enum &v4l2_buf_type
+ */
 int vb2_verify_memory_type(struct vb2_queue *q,
 		enum vb2_memory memory, unsigned int type);
 #endif /* _MEDIA_VIDEOBUF2_CORE_H */
diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h
index 3cc836f76675..036127c54bbf 100644
--- a/include/media/videobuf2-v4l2.h
+++ b/include/media/videobuf2-v4l2.h
@@ -25,11 +25,13 @@
 
 /**
  * struct vb2_v4l2_buffer - video buffer information for v4l2
+ *
  * @vb2_buf:	video buffer 2
  * @flags:	buffer informational flags
  * @field:	enum v4l2_field; field order of the image in the buffer
  * @timecode:	frame timecode
  * @sequence:	sequence count of this frame
+ *
  * Should contain enough information to be able to cover all the fields
  * of struct v4l2_buffer at videodev2.h
  */
@@ -49,22 +51,183 @@ struct vb2_v4l2_buffer {
 	container_of(vb, struct vb2_v4l2_buffer, vb2_buf)
 
 int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
+
+/**
+ * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
+ * the memory and type values.
+ *
+ * @q:		videobuf2 queue
+ * @req:	struct passed from userspace to vidioc_reqbufs handler
+ *		in driver
+ */
 int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
 
+/**
+ * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
+ * the memory and type values.
+ *
+ * @q:		videobuf2 queue
+ * @create:	creation parameters, passed from userspace to vidioc_create_bufs
+ *		handler in driver
+ */
 int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
+
+/**
+ * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
+ *
+ * @q:		videobuf2 queue
+ * @b:		buffer structure passed from userspace to vidioc_prepare_buf
+ *		handler in driver
+ *
+ * Should be called from vidioc_prepare_buf ioctl handler of a driver.
+ * This function:
+ *
+ * #) verifies the passed buffer,
+ * #) calls buf_prepare callback in the driver (if provided), in which
+ *    driver-specific buffer initialization can be performed.
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_prepare_buf handler in driver.
+ */
 int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b);
 
+/**
+ * vb2_qbuf() - Queue a buffer from userspace
+ * @q:		videobuf2 queue
+ * @b:		buffer structure passed from userspace to VIDIOC_QBUF() handler
+ *		in driver
+ *
+ * Should be called from VIDIOC_QBUF() ioctl handler of a driver.
+ *
+ * This function:
+ *
+ * #) verifies the passed buffer,
+ * #) if necessary, calls buf_prepare callback in the driver (if provided), in
+ *    which driver-specific buffer initialization can be performed,
+ * #) if streaming is on, queues the buffer in driver by the means of buf_queue
+ *    callback for processing.
+ *
+ * The return values from this function are intended to be directly returned
+ * from VIDIOC_QBUF() handler in driver.
+ */
 int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b);
+
+/**
+ * vb2_expbuf() - Export a buffer as a file descriptor
+ * @q:		videobuf2 queue
+ * @eb:		export buffer structure passed from userspace to VIDIOC_EXPBUF()
+ *		handler in driver
+ *
+ * The return values from this function are intended to be directly returned
+ * from VIDIOC_EXPBUF() handler in driver.
+ */
 int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
+
+/**
+ * vb2_dqbuf() - Dequeue a buffer to the userspace
+ * @q:		videobuf2 queue
+ * @b:		buffer structure passed from userspace to VIDIOC_DQBUF() handler
+ *		in driver
+ * @nonblocking: if true, this call will not sleep waiting for a buffer if no
+ *		 buffers ready for dequeuing are present. Normally the driver
+ *		 would be passing (file->f_flags & O_NONBLOCK) here
+ *
+ * Should be called from VIDIOC_DQBUF() ioctl handler of a driver.
+ *
+ * This function:
+ *
+ * #) verifies the passed buffer,
+ * #) calls buf_finish callback in the driver (if provided), in which
+ *    driver can perform any additional operations that may be required before
+ *    returning the buffer to userspace, such as cache sync,
+ * #) the buffer struct members are filled with relevant information for
+ *    the userspace.
+ *
+ * The return values from this function are intended to be directly returned
+ * from VIDIOC_DQBUF() handler in driver.
+ */
 int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
 
+/**
+ * vb2_streamon - start streaming
+ * @q:		videobuf2 queue
+ * @type:	type argument passed from userspace to vidioc_streamon handler
+ *
+ * Should be called from vidioc_streamon handler of a driver.
+ *
+ * This function:
+ *
+ * 1) verifies current state
+ * 2) passes any previously queued buffers to the driver and starts streaming
+ *
+ * The return values from this function are intended to be directly returned
+ * from vidioc_streamon handler in the driver.
+ */
 int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
+
+/**
+ * vb2_streamoff - stop streaming
+ * @q:		videobuf2 queue
+ * @type:	type argument passed from userspace to vidioc_streamoff handler
+ *
+ * Should be called from vidioc_streamoff handler of a driver.
+ *
+ * This function:
+ *
+ * #) verifies current state,
+ * #) stop streaming and dequeues any queued buffers, including those previously
+ *    passed to the driver (after waiting for the driver to finish).
+ *
+ * This call can be used for pausing playback.
+ * The return values from this function are intended to be directly returned
+ * from vidioc_streamoff handler in the driver
+ */
 int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type);
 
+/**
+ * vb2_queue_init() - initialize a videobuf2 queue
+ * @q:		videobuf2 queue; this structure should be allocated in driver
+ *
+ * The vb2_queue structure should be allocated by the driver. The driver is
+ * responsible of clearing it's content and setting initial values for some
+ * required entries before calling this function.
+ * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
+ * to the struct vb2_queue description in include/media/videobuf2-core.h
+ * for more information.
+ */
 int __must_check vb2_queue_init(struct vb2_queue *q);
+
+/**
+ * vb2_queue_release() - stop streaming, release the queue and free memory
+ * @q:		videobuf2 queue
+ *
+ * This function stops streaming and performs necessary clean ups, including
+ * freeing video buffer memory. The driver is responsible for freeing
+ * the vb2_queue structure itself.
+ */
 void vb2_queue_release(struct vb2_queue *q);
+
+/**
+ * vb2_poll() - implements poll userspace operation
+ * @q:		videobuf2 queue
+ * @file:	file argument passed to the poll file operation handler
+ * @wait:	wait argument passed to the poll file operation handler
+ *
+ * This function implements poll file operation handler for a driver.
+ * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
+ * be informed that the file descriptor of a video device is available for
+ * reading.
+ * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
+ * will be reported as available for writing.
+ *
+ * If the driver uses struct v4l2_fh, then vb2_poll() will also check for any
+ * pending events.
+ *
+ * The return values from this function are intended to be directly returned
+ * from poll handler in driver.
+ */
 unsigned int vb2_poll(struct vb2_queue *q, struct file *file,
-		poll_table *wait);
+		      poll_table *wait);
 
 /*
  * The following functions are not part of the vb2 core API, but are simple
@@ -105,9 +268,22 @@ unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr,
 		unsigned long len, unsigned long pgoff, unsigned long flags);
 #endif
 
-/* struct vb2_ops helpers, only use if vq->lock is non-NULL. */
-
+/**
+ * vb2_ops_wait_prepare - helper function to lock a struct &vb2_queue
+ *
+ * @vq: pointer to struct vb2_queue
+ *
+ * ..note:: only use if vq->lock is non-NULL.
+ */
 void vb2_ops_wait_prepare(struct vb2_queue *vq);
+
+/**
+ * vb2_ops_wait_finish - helper function to unlock a struct &vb2_queue
+ *
+ * @vq: pointer to struct vb2_queue
+ *
+ * ..note:: only use if vq->lock is non-NULL.
+ */
 void vb2_ops_wait_finish(struct vb2_queue *vq);
 
 #endif /* _MEDIA_VIDEOBUF2_V4L2_H */
diff --git a/include/media/vsp1.h b/include/media/vsp1.h
index 9322d9775fb7..458b400373d4 100644
--- a/include/media/vsp1.h
+++ b/include/media/vsp1.h
@@ -26,7 +26,7 @@ int vsp1_du_setup_lif(struct device *dev, unsigned int width,
 struct vsp1_du_atomic_config {
 	u32 pixelformat;
 	unsigned int pitch;
-	dma_addr_t mem[2];
+	dma_addr_t mem[3];
 	struct v4l2_rect src;
 	struct v4l2_rect dst;
 	unsigned int alpha;
diff --git a/include/uapi/linux/dvb/video.h b/include/uapi/linux/dvb/video.h
index 49392564f9d6..260f033a5b54 100644
--- a/include/uapi/linux/dvb/video.h
+++ b/include/uapi/linux/dvb/video.h
@@ -206,7 +206,8 @@ typedef __u16 video_attributes_t;
 /*    6    line 21-2 data present in GOP (1=yes, 0=no) */
 /*    5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
 /*    2    source letterboxed (1=yes, 0=no) */
-/*    0    film/camera mode (0=camera, 1=film (625/50 only)) */
+/*    0    film/camera mode (0=
+ *camera, 1=film (625/50 only)) */
 
 
 /* bit definitions for capabilities: */
diff --git a/include/uapi/linux/media-bus-format.h b/include/uapi/linux/media-bus-format.h
index 190d491d5b13..2168759c1287 100644
--- a/include/uapi/linux/media-bus-format.h
+++ b/include/uapi/linux/media-bus-format.h
@@ -97,7 +97,7 @@
 #define MEDIA_BUS_FMT_YUV10_1X30		0x2016
 #define MEDIA_BUS_FMT_AYUV8_1X32		0x2017
 
-/* Bayer - next is	0x3019 */
+/* Bayer - next is	0x3021 */
 #define MEDIA_BUS_FMT_SBGGR8_1X8		0x3001
 #define MEDIA_BUS_FMT_SGBRG8_1X8		0x3013
 #define MEDIA_BUS_FMT_SGRBG8_1X8		0x3002
@@ -122,6 +122,14 @@
 #define MEDIA_BUS_FMT_SGBRG12_1X12		0x3010
 #define MEDIA_BUS_FMT_SGRBG12_1X12		0x3011
 #define MEDIA_BUS_FMT_SRGGB12_1X12		0x3012
+#define MEDIA_BUS_FMT_SBGGR14_1X14		0x3019
+#define MEDIA_BUS_FMT_SGBRG14_1X14		0x301a
+#define MEDIA_BUS_FMT_SGRBG14_1X14		0x301b
+#define MEDIA_BUS_FMT_SRGGB14_1X14		0x301c
+#define MEDIA_BUS_FMT_SBGGR16_1X16		0x301d
+#define MEDIA_BUS_FMT_SGBRG16_1X16		0x301e
+#define MEDIA_BUS_FMT_SGRBG16_1X16		0x301f
+#define MEDIA_BUS_FMT_SRGGB16_1X16		0x3020
 
 /* JPEG compressed formats - next is	0x4002 */
 #define MEDIA_BUS_FMT_JPEG_1X8			0x4001
diff --git a/include/uapi/linux/media.h b/include/uapi/linux/media.h
index 7acf0f634f70..4890787731b8 100644
--- a/include/uapi/linux/media.h
+++ b/include/uapi/linux/media.h
@@ -307,6 +307,7 @@ struct media_links_enum {
 #define MEDIA_INTF_T_V4L_RADIO  (MEDIA_INTF_T_V4L_BASE + 2)
 #define MEDIA_INTF_T_V4L_SUBDEV (MEDIA_INTF_T_V4L_BASE + 3)
 #define MEDIA_INTF_T_V4L_SWRADIO (MEDIA_INTF_T_V4L_BASE + 4)
+#define MEDIA_INTF_T_V4L_TOUCH	(MEDIA_INTF_T_V4L_BASE + 5)
 
 #define MEDIA_INTF_T_ALSA_PCM_CAPTURE   (MEDIA_INTF_T_ALSA_BASE)
 #define MEDIA_INTF_T_ALSA_PCM_PLAYBACK  (MEDIA_INTF_T_ALSA_BASE + 1)
diff --git a/include/uapi/linux/v4l2-dv-timings.h b/include/uapi/linux/v4l2-dv-timings.h
index 086168e18ca8..f31957166337 100644
--- a/include/uapi/linux/v4l2-dv-timings.h
+++ b/include/uapi/linux/v4l2-dv-timings.h
@@ -934,4 +934,16 @@
 		V4L2_DV_FL_REDUCED_BLANKING) \
 }
 
+/* SDI timings definitions */
+
+/* SMPTE-125M */
+#define V4L2_DV_BT_SDI_720X487I60 { \
+	.type = V4L2_DV_BT_656_1120, \
+	V4L2_INIT_BT_TIMINGS(720, 487, 1, \
+		V4L2_DV_HSYNC_POS_POL, \
+		13500000, 16, 121, 0, 0, 19, 0, 0, 19, 0, \
+		V4L2_DV_BT_STD_SDI, \
+		V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE) \
+}
+
 #endif
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 724f43e69d03..94f123f3e04e 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -292,13 +292,11 @@ enum v4l2_ycbcr_encoding {
 	 * various colorspaces:
 	 *
 	 * V4L2_COLORSPACE_SMPTE170M, V4L2_COLORSPACE_470_SYSTEM_M,
-	 * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_ADOBERGB and
-	 * V4L2_COLORSPACE_JPEG: V4L2_YCBCR_ENC_601
+	 * V4L2_COLORSPACE_470_SYSTEM_BG, V4L2_COLORSPACE_SRGB,
+	 * V4L2_COLORSPACE_ADOBERGB and V4L2_COLORSPACE_JPEG: V4L2_YCBCR_ENC_601
 	 *
 	 * V4L2_COLORSPACE_REC709 and V4L2_COLORSPACE_DCI_P3: V4L2_YCBCR_ENC_709
 	 *
-	 * V4L2_COLORSPACE_SRGB: V4L2_YCBCR_ENC_SYCC
-	 *
 	 * V4L2_COLORSPACE_BT2020: V4L2_YCBCR_ENC_BT2020
 	 *
 	 * V4L2_COLORSPACE_SMPTE240M: V4L2_YCBCR_ENC_SMPTE240M
@@ -317,8 +315,14 @@ enum v4l2_ycbcr_encoding {
 	/* Rec. 709/EN 61966-2-4 Extended Gamut -- HDTV */
 	V4L2_YCBCR_ENC_XV709          = 4,
 
-	/* sYCC (Y'CbCr encoding of sRGB) */
+#ifndef __KERNEL__
+	/*
+	 * sYCC (Y'CbCr encoding of sRGB), identical to ENC_601. It was added
+	 * originally due to a misunderstanding of the sYCC standard. It should
+	 * not be used, instead use V4L2_YCBCR_ENC_601.
+	 */
 	V4L2_YCBCR_ENC_SYCC           = 5,
+#endif
 
 	/* BT.2020 Non-constant Luminance Y'CbCr */
 	V4L2_YCBCR_ENC_BT2020         = 6,
@@ -345,8 +349,8 @@ enum v4l2_quantization {
 	/*
 	 * The default for R'G'B' quantization is always full range, except
 	 * for the BT2020 colorspace. For Y'CbCr the quantization is always
-	 * limited range, except for COLORSPACE_JPEG, SYCC, XV601 or XV709:
-	 * those are full range.
+	 * limited range, except for COLORSPACE_JPEG, SRGB, ADOBERGB,
+	 * XV601 or XV709: those are full range.
 	 */
 	V4L2_QUANTIZATION_DEFAULT     = 0,
 	V4L2_QUANTIZATION_FULL_RANGE  = 1,
@@ -361,7 +365,8 @@ enum v4l2_quantization {
 #define V4L2_MAP_QUANTIZATION_DEFAULT(is_rgb, colsp, ycbcr_enc) \
 	(((is_rgb) && (colsp) == V4L2_COLORSPACE_BT2020) ? V4L2_QUANTIZATION_LIM_RANGE : \
 	 (((is_rgb) || (ycbcr_enc) == V4L2_YCBCR_ENC_XV601 || \
-	  (ycbcr_enc) == V4L2_YCBCR_ENC_XV709 || (colsp) == V4L2_COLORSPACE_JPEG) ? \
+	  (ycbcr_enc) == V4L2_YCBCR_ENC_XV709 || (colsp) == V4L2_COLORSPACE_JPEG) || \
+	  (colsp) == V4L2_COLORSPACE_ADOBERGB || (colsp) == V4L2_COLORSPACE_SRGB ? \
 	 V4L2_QUANTIZATION_FULL_RANGE : V4L2_QUANTIZATION_LIM_RANGE))
 
 enum v4l2_priority {
@@ -440,6 +445,8 @@ struct v4l2_capability {
 #define V4L2_CAP_ASYNCIO                0x02000000  /* async I/O */
 #define V4L2_CAP_STREAMING              0x04000000  /* streaming I/O ioctls */
 
+#define V4L2_CAP_TOUCH                  0x10000000  /* Is a touch device */
+
 #define V4L2_CAP_DEVICE_CAPS            0x80000000  /* sets device capabilities field */
 
 /*
@@ -635,6 +642,12 @@ struct v4l2_pix_format {
 #define V4L2_SDR_FMT_CS14LE       v4l2_fourcc('C', 'S', '1', '4') /* complex s14le */
 #define V4L2_SDR_FMT_RU12LE       v4l2_fourcc('R', 'U', '1', '2') /* real u12le */
 
+/* Touch formats - used for Touch devices */
+#define V4L2_TCH_FMT_DELTA_TD16	v4l2_fourcc('T', 'D', '1', '6') /* 16-bit signed deltas */
+#define V4L2_TCH_FMT_DELTA_TD08	v4l2_fourcc('T', 'D', '0', '8') /* 8-bit signed deltas */
+#define V4L2_TCH_FMT_TU16	v4l2_fourcc('T', 'U', '1', '6') /* 16-bit unsigned touch data */
+#define V4L2_TCH_FMT_TU08	v4l2_fourcc('T', 'U', '0', '8') /* 8-bit unsigned touch data */
+
 /* priv field value to indicates that subsequent fields are valid. */
 #define V4L2_PIX_FMT_PRIV_MAGIC		0xfeedcafe
 
@@ -1261,6 +1274,7 @@ struct v4l2_bt_timings {
 #define V4L2_DV_BT_STD_DMT	(1 << 1)  /* VESA Discrete Monitor Timings */
 #define V4L2_DV_BT_STD_CVT	(1 << 2)  /* VESA Coordinated Video Timings */
 #define V4L2_DV_BT_STD_GTF	(1 << 3)  /* VESA Generalized Timings Formula */
+#define V4L2_DV_BT_STD_SDI	(1 << 4)  /* SDI Timings */
 
 /* Flags */
 
@@ -1292,6 +1306,11 @@ struct v4l2_bt_timings {
  * use the range 16-235) as opposed to 0-255. All formats defined in CEA-861
  * except for the 640x480 format are CE formats. */
 #define V4L2_DV_FL_IS_CE_VIDEO			(1 << 4)
+/* Some formats like SMPTE-125M have an interlaced signal with a odd
+ * total height. For these formats, if this flag is set, the first
+ * field has the extra line. If not, it is the second field.
+ */
+#define V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE		(1 << 5)
 
 /* A few useful defines to calculate the total blanking and frame sizes */
 #define V4L2_DV_BT_BLANKING_WIDTH(bt) \
@@ -1401,6 +1420,7 @@ struct v4l2_input {
 /*  Values for the 'type' field */
 #define V4L2_INPUT_TYPE_TUNER		1
 #define V4L2_INPUT_TYPE_CAMERA		2
+#define V4L2_INPUT_TYPE_TOUCH		3
 
 /* field 'status' - general */
 #define V4L2_IN_ST_NO_POWER    0x00000001  /* Attached device is off */
@@ -1415,6 +1435,8 @@ struct v4l2_input {
 /* field 'status' - analog */
 #define V4L2_IN_ST_NO_H_LOCK   0x00000100  /* No horizontal sync lock */
 #define V4L2_IN_ST_COLOR_KILL  0x00000200  /* Color killer is active */
+#define V4L2_IN_ST_NO_V_LOCK   0x00000400  /* No vertical sync lock */
+#define V4L2_IN_ST_NO_STD_LOCK 0x00000800  /* No standard format lock */
 
 /* field 'status' - digital */
 #define V4L2_IN_ST_NO_SYNC     0x00010000  /* No synchronization lock */