Merge tag 'media/v4.4-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull media updates from Mauro Carvalho Chehab:
 "Media updates, including:

   - Lots of improvements at the kABI documentation
   - Split of Videobuf2 into a common part and a V4L2 specific one
   - Split of the VB2 tracing events into a separate header file
   - s5p-mfc got support for Exynos 5433
   - v4l2 fixes for 64-bits alignment when running 32 bits userspace
     on ARM
   - Added support for SDR radio transmitter at core, vivid and hackrf
     drivers
   - Some y2038 fixups
   - Some improvements at V4L2 colorspace support
   - saa7164 converted to use the V4L2 core control framework
   - several new boards additions, cleanups and fixups

  PS: There are two patches for scripts/kernel-doc that are needed by
  the documentation patches on Media.  Jon is OK on merging those via
  my tree"

* tag 'media/v4.4-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (146 commits)
  [media] c8sectpfe: Remove select on CONFIG_FW_LOADER_USER_HELPER_FALLBACK
  [media] DocBook media: update copyright/version numbers
  [media] ivtv: Convert to get_user_pages_unlocked()
  [media] media/v4l2-ctrls: fix setting autocluster to manual with VIDIOC_S_CTRL
  [media] DocBook media: Fix a typo in encoder cmd
  [media] DocBook: add SDR specific info to G_MODULATOR / S_MODULATOR
  [media] DocBook: add SDR specific info to G_TUNER / S_TUNER
  [media] hackrf: do not set human readable name for formats
  [media] hackrf: add support for transmitter
  [media] hackrf: switch to single function which configures everything
  [media] hackrf: add control for RF amplifier
  [media] DocBook: add modulator type field
  [media] v4l: add type field to v4l2_modulator struct
  [media] DocBook: document SDR transmitter
  [media] v4l2: add support for SDR transmitter
  [media] DocBook: document tuner RF gain control
  [media] v4l2: add RF gain control
  [media] v4l2: rename V4L2_TUNER_ADC to V4L2_TUNER_SDR
  [media] media/vivid-osd: fix info leak in ioctl
  [media] media: videobuf2: Move v4l2-specific stuff to videobuf2-v4l2
  ...

22 files changed, 768 insertions, 528 deletions

diff --git a/include/media/atmel-isi.h b/include/media/atmel-isi.h
deleted file mode 100644
index 6008b0985b7b..000000000000
--- a/include/media/atmel-isi.h
+++ /dev/null
@@ -1,131 +0,0 @@
-/*
- * Register definitions for the Atmel Image Sensor Interface.
- *
- * Copyright (C) 2011 Atmel Corporation
- * Josh Wu, <josh.wu@atmel.com>
- *
- * Based on previous work by Lars Haring, <lars.haring@atmel.com>
- * and Sedji Gaouaou
- *
- * 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 __ATMEL_ISI_H__
-#define __ATMEL_ISI_H__
-
-#include <linux/types.h>
-
-/* ISI_V2 register offsets */
-#define ISI_CFG1				0x0000
-#define ISI_CFG2				0x0004
-#define ISI_PSIZE				0x0008
-#define ISI_PDECF				0x000c
-#define ISI_Y2R_SET0				0x0010
-#define ISI_Y2R_SET1				0x0014
-#define ISI_R2Y_SET0				0x0018
-#define ISI_R2Y_SET1				0x001C
-#define ISI_R2Y_SET2				0x0020
-#define ISI_CTRL				0x0024
-#define ISI_STATUS				0x0028
-#define ISI_INTEN				0x002C
-#define ISI_INTDIS				0x0030
-#define ISI_INTMASK				0x0034
-#define ISI_DMA_CHER				0x0038
-#define ISI_DMA_CHDR				0x003C
-#define ISI_DMA_CHSR				0x0040
-#define ISI_DMA_P_ADDR				0x0044
-#define ISI_DMA_P_CTRL				0x0048
-#define ISI_DMA_P_DSCR				0x004C
-#define ISI_DMA_C_ADDR				0x0050
-#define ISI_DMA_C_CTRL				0x0054
-#define ISI_DMA_C_DSCR				0x0058
-
-/* Bitfields in CFG1 */
-#define ISI_CFG1_HSYNC_POL_ACTIVE_LOW		(1 << 2)
-#define ISI_CFG1_VSYNC_POL_ACTIVE_LOW		(1 << 3)
-#define ISI_CFG1_PIXCLK_POL_ACTIVE_FALLING	(1 << 4)
-#define ISI_CFG1_EMB_SYNC			(1 << 6)
-#define ISI_CFG1_CRC_SYNC			(1 << 7)
-/* Constants for FRATE(ISI_V2) */
-#define		ISI_CFG1_FRATE_CAPTURE_ALL	(0 << 8)
-#define		ISI_CFG1_FRATE_DIV_2		(1 << 8)
-#define		ISI_CFG1_FRATE_DIV_3		(2 << 8)
-#define		ISI_CFG1_FRATE_DIV_4		(3 << 8)
-#define		ISI_CFG1_FRATE_DIV_5		(4 << 8)
-#define		ISI_CFG1_FRATE_DIV_6		(5 << 8)
-#define		ISI_CFG1_FRATE_DIV_7		(6 << 8)
-#define		ISI_CFG1_FRATE_DIV_8		(7 << 8)
-#define		ISI_CFG1_FRATE_DIV_MASK		(7 << 8)
-#define ISI_CFG1_DISCR				(1 << 11)
-#define ISI_CFG1_FULL_MODE			(1 << 12)
-/* Definition for THMASK(ISI_V2) */
-#define		ISI_CFG1_THMASK_BEATS_4		(0 << 13)
-#define		ISI_CFG1_THMASK_BEATS_8		(1 << 13)
-#define		ISI_CFG1_THMASK_BEATS_16	(2 << 13)
-
-/* Bitfields in CFG2 */
-#define ISI_CFG2_GRAYSCALE			(1 << 13)
-/* Constants for YCC_SWAP(ISI_V2) */
-#define		ISI_CFG2_YCC_SWAP_DEFAULT	(0 << 28)
-#define		ISI_CFG2_YCC_SWAP_MODE_1	(1 << 28)
-#define		ISI_CFG2_YCC_SWAP_MODE_2	(2 << 28)
-#define		ISI_CFG2_YCC_SWAP_MODE_3	(3 << 28)
-#define		ISI_CFG2_YCC_SWAP_MODE_MASK	(3 << 28)
-#define ISI_CFG2_IM_VSIZE_OFFSET		0
-#define ISI_CFG2_IM_HSIZE_OFFSET		16
-#define ISI_CFG2_IM_VSIZE_MASK		(0x7FF << ISI_CFG2_IM_VSIZE_OFFSET)
-#define ISI_CFG2_IM_HSIZE_MASK		(0x7FF << ISI_CFG2_IM_HSIZE_OFFSET)
-
-/* Bitfields in CTRL */
-/* Also using in SR(ISI_V2) */
-#define ISI_CTRL_EN				(1 << 0)
-#define ISI_CTRL_CDC				(1 << 8)
-/* Also using in SR/IER/IDR/IMR(ISI_V2) */
-#define ISI_CTRL_DIS				(1 << 1)
-#define ISI_CTRL_SRST				(1 << 2)
-
-/* Bitfields in SR */
-#define ISI_SR_SIP				(1 << 19)
-/* Also using in SR/IER/IDR/IMR */
-#define ISI_SR_VSYNC				(1 << 10)
-#define ISI_SR_PXFR_DONE			(1 << 16)
-#define ISI_SR_CXFR_DONE			(1 << 17)
-#define ISI_SR_P_OVR				(1 << 24)
-#define ISI_SR_C_OVR				(1 << 25)
-#define ISI_SR_CRC_ERR				(1 << 26)
-#define ISI_SR_FR_OVR				(1 << 27)
-
-/* Bitfields in DMA_C_CTRL & in DMA_P_CTRL */
-#define ISI_DMA_CTRL_FETCH			(1 << 0)
-#define ISI_DMA_CTRL_WB				(1 << 1)
-#define ISI_DMA_CTRL_IEN			(1 << 2)
-#define ISI_DMA_CTRL_DONE			(1 << 3)
-
-/* Bitfields in DMA_CHSR/CHER/CHDR */
-#define ISI_DMA_CHSR_P_CH			(1 << 0)
-#define ISI_DMA_CHSR_C_CH			(1 << 1)
-
-/* Definition for isi_platform_data */
-#define ISI_DATAWIDTH_8				0x01
-#define ISI_DATAWIDTH_10			0x02
-
-struct v4l2_async_subdev;
-
-struct isi_platform_data {
-	u8 has_emb_sync;
-	u8 emb_crc_sync;
-	u8 hsync_act_low;
-	u8 vsync_act_low;
-	u8 pclk_act_falling;
-	u8 full_mode;
-	u32 data_width_flags;
-	/* Using for ISI_CFG1 */
-	u32 frate;
-	/* Using for ISI_MCK */
-	u32 mck_hz;
-	struct v4l2_async_subdev **asd;	/* Flat array, arranged in groups */
-	int *asd_sizes;		/* 0-terminated array of asd group sizes */
-};
-
-#endif /* __ATMEL_ISI_H__ */
diff --git a/include/media/davinci/vpbe_display.h b/include/media/davinci/vpbe_display.h
index fa0247ad815f..e14a9370b67e 100644
--- a/include/media/davinci/vpbe_display.h
+++ b/include/media/davinci/vpbe_display.h
@@ -17,6 +17,7 @@
 #include <linux/videodev2.h>
 #include <media/v4l2-common.h>
 #include <media/v4l2-fh.h>
+#include <media/videobuf2-v4l2.h>
 #include <media/videobuf2-dma-contig.h>
 #include <media/davinci/vpbe_types.h>
 #include <media/davinci/vpbe_osd.h>
@@ -64,7 +65,7 @@ struct display_layer_info {
 };
 
 struct vpbe_disp_buffer {
-	struct vb2_buffer vb;
+	struct vb2_v4l2_buffer vb;
 	struct list_head list;
 };
 
diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index 05e7ad5d2c8b..0ab59a571fee 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -118,6 +118,71 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf,
 	return ret;
 }
 
+/**
+ * struct lirc_driver - Defines the parameters on a LIRC driver
+ *
+ * @name:		this string will be used for logs
+ *
+ * @minor:		indicates minor device (/dev/lirc) number for
+ *			registered driver if caller fills it with negative
+ *			value, then the first free minor number will be used
+ *			(if available).
+ *
+ * @code_length:	length of the remote control key code expressed in bits.
+ *
+ * @buffer_size:	Number of FIFO buffers with @chunk_size size. If zero,
+ *			creates a buffer with BUFLEN size (16 bytes).
+ *
+ * @sample_rate:	if zero, the device will wait for an event with a new
+ *			code to be parsed. Otherwise, specifies the sample
+ *			rate for polling. Value should be between 0
+ *			and HZ. If equal to HZ, it would mean one polling per
+ *			second.
+ *
+ * @features:		lirc compatible hardware features, like LIRC_MODE_RAW,
+ *			LIRC_CAN_*, as defined at include/media/lirc.h.
+ *
+ * @chunk_size:		Size of each FIFO buffer.
+ *
+ * @data:		it may point to any driver data and this pointer will
+ *			be passed to all callback functions.
+ *
+ * @min_timeout:	Minimum timeout for record. Valid only if
+ *			LIRC_CAN_SET_REC_TIMEOUT is defined.
+ *
+ * @max_timeout:	Maximum timeout for record. Valid only if
+ *			LIRC_CAN_SET_REC_TIMEOUT is defined.
+ *
+ * @add_to_buf:		add_to_buf will be called after specified period of the
+ *			time or triggered by the external event, this behavior
+ *			depends on value of the sample_rate this function will
+ *			be called in user context. This routine should return
+ *			0 if data was added to the buffer and -ENODATA if none
+ *			was available. This should add some number of bits
+ *			evenly divisible by code_length to the buffer.
+ *
+ * @rbuf:		if not NULL, it will be used as a read buffer, you will
+ *			have to write to the buffer by other means, like irq's
+ *			(see also lirc_serial.c).
+ *
+ * @set_use_inc:	set_use_inc will be called after device is opened
+ *
+ * @set_use_dec:	set_use_dec will be called after device is closed
+ *
+ * @rdev:		Pointed to struct rc_dev associated with the LIRC
+ *			device.
+ *
+ * @fops:		file_operations for drivers which don't fit the current
+ *			driver model.
+ *			Some ioctl's can be directly handled by lirc_dev if the
+ *			driver's ioctl function is NULL or if it returns
+ *			-ENOIOCTLCMD (see also lirc_serial.c).
+ *
+ * @dev:		pointer to the struct device associated with the LIRC
+ *			device.
+ *
+ * @owner:		the module owning this struct
+ */
 struct lirc_driver {
 	char name[40];
 	int minor;
@@ -131,65 +196,16 @@ struct lirc_driver {
 	void *data;
 	int min_timeout;
 	int max_timeout;
-	int (*add_to_buf) (void *data, struct lirc_buffer *buf);
+	int (*add_to_buf)(void *data, struct lirc_buffer *buf);
 	struct lirc_buffer *rbuf;
-	int (*set_use_inc) (void *data);
-	void (*set_use_dec) (void *data);
+	int (*set_use_inc)(void *data);
+	void (*set_use_dec)(void *data);
 	struct rc_dev *rdev;
 	const struct file_operations *fops;
 	struct device *dev;
 	struct module *owner;
 };
 
-/* name:
- * this string will be used for logs
- *
- * minor:
- * indicates minor device (/dev/lirc) number for registered driver
- * if caller fills it with negative value, then the first free minor
- * number will be used (if available)
- *
- * code_length:
- * length of the remote control key code expressed in bits
- *
- * sample_rate:
- *
- * data:
- * it may point to any driver data and this pointer will be passed to
- * all callback functions
- *
- * add_to_buf:
- * add_to_buf will be called after specified period of the time or
- * triggered by the external event, this behavior depends on value of
- * the sample_rate this function will be called in user context. This
- * routine should return 0 if data was added to the buffer and
- * -ENODATA if none was available. This should add some number of bits
- * evenly divisible by code_length to the buffer
- *
- * rbuf:
- * if not NULL, it will be used as a read buffer, you will have to
- * write to the buffer by other means, like irq's (see also
- * lirc_serial.c).
- *
- * set_use_inc:
- * set_use_inc will be called after device is opened
- *
- * set_use_dec:
- * set_use_dec will be called after device is closed
- *
- * fops:
- * file_operations for drivers which don't fit the current driver model.
- *
- * Some ioctl's can be directly handled by lirc_dev if the driver's
- * ioctl function is NULL or if it returns -ENOIOCTLCMD (see also
- * lirc_serial.c).
- *
- * owner:
- * the module owning this struct
- *
- */
-
-
 /* following functions can be called ONLY from user context
  *
  * returns negative value on error or minor number
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index 0c003d817493..197f93799753 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -116,6 +116,13 @@ static inline u32 media_entity_subtype(struct media_entity *entity)
 #define MEDIA_ENTITY_ENUM_MAX_DEPTH	16
 #define MEDIA_ENTITY_ENUM_MAX_ID	64
 
+/*
+ * The number of pads can't be bigger than the number of entities,
+ * as the worse-case scenario is to have one entity linked up to
+ * MEDIA_ENTITY_ENUM_MAX_ID - 1 entities.
+ */
+#define MEDIA_ENTITY_MAX_PADS		(MEDIA_ENTITY_ENUM_MAX_ID - 1)
+
 struct media_entity_graph {
 	struct {
 		struct media_entity *entity;
diff --git a/include/media/soc_camera.h b/include/media/soc_camera.h
index 2f6261f3e570..97aa13314bfd 100644
--- a/include/media/soc_camera.h
+++ b/include/media/soc_camera.h
@@ -18,7 +18,7 @@
 #include <linux/pm.h>
 #include <linux/videodev2.h>
 #include <media/videobuf-core.h>
-#include <media/videobuf2-core.h>
+#include <media/videobuf2-v4l2.h>
 #include <media/v4l2-async.h>
 #include <media/v4l2-ctrls.h>
 #include <media/v4l2-device.h>
diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index ab03c5344209..094e112cc325 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -5,6 +5,15 @@
 #ifndef __TUNER_TYPES_H__
 #define __TUNER_TYPES_H__
 
+/**
+ * enum param_type - type of the tuner pameters
+ *
+ * @TUNER_PARAM_TYPE_RADIO:	Tuner params are for FM and/or AM radio
+ * @TUNER_PARAM_TYPE_PAL:	Tuner params are for PAL color TV standard
+ * @TUNER_PARAM_TYPE_SECAM:	Tuner params are for SECAM color TV standard
+ * @TUNER_PARAM_TYPE_NTSC:	Tuner params are for NTSC color TV standard
+ * @TUNER_PARAM_TYPE_DIGITAL:	Tuner params are for digital TV
+ */
 enum param_type {
 	TUNER_PARAM_TYPE_RADIO,
 	TUNER_PARAM_TYPE_PAL,
@@ -13,97 +22,142 @@ enum param_type {
 	TUNER_PARAM_TYPE_DIGITAL,
 };
 
+/**
+ * struct tuner_range - define the frequencies supported by the tuner
+ *
+ * @limit:		Max frequency supported by that range, in 62.5 kHz
+ *			(TV) or 62.5 Hz (Radio), as defined by
+ *			V4L2_TUNER_CAP_LOW.
+ * @config:		Value of the band switch byte (BB) to setup this mode.
+ * @cb:			Value of the CB byte to setup this mode.
+ *
+ * Please notice that digital tuners like xc3028/xc4000/xc5000 don't use
+ * those ranges, as they're defined inside the driver. This is used by
+ * analog tuners that are compatible with the "Philips way" to setup the
+ * tuners. On those devices, the tuner set is done via 4 bytes:
+ *	divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
+ *	band switch byte (BB).
+ * Some tuners also have an additional optional Auxiliary byte (AB).
+ */
 struct tuner_range {
 	unsigned short limit;
 	unsigned char config;
 	unsigned char cb;
 };
 
+/**
+ * struct tuner_params - Parameters to be used to setup the tuner. Those
+ *			 are used by drivers/media/tuners/tuner-types.c in
+ *			 order to specify the tuner properties. Most of
+ *			 the parameters are for tuners based on tda9887 IF-PLL
+ *			 multi-standard analog TV/Radio demodulator, with is
+ *			 very common on legacy analog tuners.
+ *
+ * @type:			Type of the tuner parameters, as defined at
+ *				enum param_type. If the tuner supports multiple
+ *				standards, an array should be used, with one
+ *				row per different standard.
+ * @cb_first_if_lower_freq:	Many Philips-based tuners have a comment in
+ *				their datasheet like
+ *				"For channel selection involving band
+ *				switching, and to ensure smooth tuning to the
+ *				desired channel without causing unnecessary
+ *				charge pump action, it is recommended to
+ *				consider the difference between wanted channel
+ *				frequency and the current channel frequency.
+ *				Unnecessary charge pump action will result
+ *				in very low tuning voltage which may drive the
+ *				oscillator to extreme conditions".
+ *				Set cb_first_if_lower_freq to 1, if this check
+ *				is required for this tuner. I tested this for
+ *				PAL by first setting the TV frequency to
+ *				203 MHz and then switching to 96.6 MHz FM
+ *				radio. The result was static unless the
+ *				control byte was sent first.
+ * @has_tda9887:		Set to 1 if this tuner uses a tda9887
+ * @port1_fm_high_sensitivity:	Many Philips tuners use tda9887 PORT1 to select
+ *				the FM radio sensitivity. If this setting is 1,
+ *				then set PORT1 to 1 to get proper FM reception.
+ * @port2_fm_high_sensitivity:	Some Philips tuners use tda9887 PORT2 to select
+ *				the FM radio sensitivity. If this setting is 1,
+ *				then set PORT2 to 1 to get proper FM reception.
+ * @fm_gain_normal:		Some Philips tuners use tda9887 cGainNormal to
+ *				select the FM radio sensitivity. If this
+ *				setting is 1, e register will use cGainNormal
+ *				instead of cGainLow.
+ * @intercarrier_mode:		Most tuners with a tda9887 use QSS mode.
+ *				Some (cheaper) tuners use Intercarrier mode.
+ *				If this setting is 1, then the tuner needs to
+ *				be set to intercarrier mode.
+ * @port1_active:		This setting sets the default value for PORT1.
+ *				0 means inactive, 1 means active. Note: the
+ *				actual bit value written to the tda9887 is
+ *				inverted. So a 0 here means a 1 in the B6 bit.
+ * @port2_active:		This setting sets the default value for PORT2.
+ *				0 means inactive, 1 means active. Note: the
+ *				actual bit value written to the tda9887 is
+ *				inverted. So a 0 here means a 1 in the B7 bit.
+ * @port1_invert_for_secam_lc:	Sometimes PORT1 is inverted when the SECAM-L'
+ *				standard is selected. Set this bit to 1 if this
+ *				is needed.
+ * @port2_invert_for_secam_lc:	Sometimes PORT2 is inverted when the SECAM-L'
+ *				standard is selected. Set this bit to 1 if this
+ *				is needed.
+ * @port1_set_for_fm_mono:	Some cards require PORT1 to be 1 for mono Radio
+ *				FM and 0 for stereo.
+ * @default_pll_gating_18:	Select 18% (or according to datasheet 0%)
+ *				L standard PLL gating, vs the driver default
+ *				of 36%.
+ * @radio_if:			IF to use in radio mode.  Tuners with a
+ *				separate radio IF filter seem to use 10.7,
+ *				while those without use 33.3 for PAL/SECAM
+ *				tuners and 41.3 for NTSC tuners.
+ *				0 = 10.7, 1 = 33.3, 2 = 41.3
+ * @default_top_low:		Default tda9887 TOP value in dB for the low
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_mid:		Default tda9887 TOP value in dB for the mid
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_high:		Default tda9887 TOP value in dB for the high
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_secam_low:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the low band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @default_top_secam_mid:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the mid band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @default_top_secam_high:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the high band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @iffreq:			Intermediate frequency (IF) used by the tuner
+ *				on digital mode.
+ * @count:			Size of the ranges array.
+ * @ranges:			Array with the frequency ranges supported by
+ *				the tuner.
+ */
 struct tuner_params {
 	enum param_type type;
 
-	/* Many Philips based tuners have a comment like this in their
-	 * datasheet:
-	 *
-	 *   For channel selection involving band switching, and to ensure
-	 *   smooth tuning to the desired channel without causing
-	 *   unnecessary charge pump action, it is recommended to consider
-	 *   the difference between wanted channel frequency and the
-	 *   current channel frequency.  Unnecessary charge pump action
-	 *   will result in very low tuning voltage which may drive the
-	 *   oscillator to extreme conditions.
-	 *
-	 * Set cb_first_if_lower_freq to 1, if this check is
-	 * required for this tuner.
-	 *
-	 * I tested this for PAL by first setting the TV frequency to
-	 * 203 MHz and then switching to 96.6 MHz FM radio. The result was
-	 * static unless the control byte was sent first.
-	 */
 	unsigned int cb_first_if_lower_freq:1;
-	/* Set to 1 if this tuner uses a tda9887 */
 	unsigned int has_tda9887:1;
-	/* Many Philips tuners use tda9887 PORT1 to select the FM radio
-	   sensitivity. If this setting is 1, then set PORT1 to 1 to
-	   get proper FM reception. */
 	unsigned int port1_fm_high_sensitivity:1;
-	/* Some Philips tuners use tda9887 PORT2 to select the FM radio
-	   sensitivity. If this setting is 1, then set PORT2 to 1 to
-	   get proper FM reception. */
 	unsigned int port2_fm_high_sensitivity:1;
-	/* Some Philips tuners use tda9887 cGainNormal to select the FM radio
-	   sensitivity. If this setting is 1, e register will use cGainNormal
-	   instead of cGainLow. */
 	unsigned int fm_gain_normal:1;
-	/* Most tuners with a tda9887 use QSS mode. Some (cheaper) tuners
-	   use Intercarrier mode. If this setting is 1, then the tuner
-	   needs to be set to intercarrier mode. */
 	unsigned int intercarrier_mode:1;
-	/* This setting sets the default value for PORT1.
-	   0 means inactive, 1 means active. Note: the actual bit
-	   value written to the tda9887 is inverted. So a 0 here
-	   means a 1 in the B6 bit. */
 	unsigned int port1_active:1;
-	/* This setting sets the default value for PORT2.
-	   0 means inactive, 1 means active. Note: the actual bit
-	   value written to the tda9887 is inverted. So a 0 here
-	   means a 1 in the B7 bit. */
 	unsigned int port2_active:1;
-	/* Sometimes PORT1 is inverted when the SECAM-L' standard is selected.
-	   Set this bit to 1 if this is needed. */
 	unsigned int port1_invert_for_secam_lc:1;
-	/* Sometimes PORT2 is inverted when the SECAM-L' standard is selected.
-	   Set this bit to 1 if this is needed. */
 	unsigned int port2_invert_for_secam_lc:1;
-	/* Some cards require PORT1 to be 1 for mono Radio FM and 0 for stereo. */
 	unsigned int port1_set_for_fm_mono:1;
-	/* Select 18% (or according to datasheet 0%) L standard PLL gating,
-	   vs the driver default of 36%. */
 	unsigned int default_pll_gating_18:1;
-	/* IF to use in radio mode.  Tuners with a separate radio IF filter
-	   seem to use 10.7, while those without use 33.3 for PAL/SECAM tuners
-	   and 41.3 for NTSC tuners. 0 = 10.7, 1 = 33.3, 2 = 41.3 */
 	unsigned int radio_if:2;
-	/* Default tda9887 TOP value in dB for the low band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_low:5;
-	/* Default tda9887 TOP value in dB for the mid band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_mid:5;
-	/* Default tda9887 TOP value in dB for the high band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_high:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the low band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_low:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the mid band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_mid:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the high band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_high:5;
 
 	u16 iffreq;
diff --git a/include/media/tuner.h b/include/media/tuner.h
index b46ebb48fe74..486b6a54363b 100644
--- a/include/media/tuner.h
+++ b/include/media/tuner.h
@@ -1,23 +1,19 @@
 /*
-    tuner.h - definition for different tuners
-
-    Copyright (C) 1997 Markus Schroeder (schroedm@uni-duesseldorf.de)
-    minor modifications by Ralph Metzler (rjkm@thp.uni-koeln.de)
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-*/
+ * tuner.h - definition for different tuners
+ *
+ * Copyright (C) 1997 Markus Schroeder (schroedm@uni-duesseldorf.de)
+ * minor modifications by Ralph Metzler (rjkm@thp.uni-koeln.de)
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
 
 #ifndef _TUNER_H
 #define _TUNER_H
@@ -83,8 +79,11 @@
 #define TUNER_PHILIPS_FM1236_MK3	43
 
 #define TUNER_PHILIPS_4IN1		44	/* ATI TV Wonder Pro - Conexant */
-/* Microtune merged with Temic 12/31/1999 partially financed by Alps - these may be similar to Temic */
-#define TUNER_MICROTUNE_4049FM5 	45
+	/*
+	 * Microtune merged with Temic 12/31/1999 partially financed by Alps.
+	 * these may be similar to Temic
+	 */
+#define TUNER_MICROTUNE_4049FM5		45
 #define TUNER_PANASONIC_VP27		46
 #define TUNER_LG_NTSC_TAPE		47
 
@@ -115,11 +114,11 @@
 
 #define TUNER_PHILIPS_TUV1236D		68	/* ATI HDTV Wonder */
 #define TUNER_TNF_5335MF                69	/* Sabrent Bt848   */
-#define TUNER_SAMSUNG_TCPN_2121P30A     70 	/* Hauppauge PVR-500MCE NTSC */
+#define TUNER_SAMSUNG_TCPN_2121P30A     70	/* Hauppauge PVR-500MCE NTSC */
 #define TUNER_XC2028			71
 
 #define TUNER_THOMSON_FE6600		72	/* DViCO FusionHDTV DVB-T Hybrid */
-#define TUNER_SAMSUNG_TCPG_6121P30A     73 	/* Hauppauge PVR-500 PAL */
+#define TUNER_SAMSUNG_TCPG_6121P30A     73	/* Hauppauge PVR-500 PAL */
 #define TUNER_TDA9887                   74      /* This tuner should be used only internally */
 #define TUNER_TEA5761			75	/* Only FM Radio Tuner */
 #define TUNER_XC5000			76	/* Xceive Silicon Tuner */
@@ -143,57 +142,92 @@
 #define TUNER_SONY_BTF_PB463Z		91	/* NTSC */
 
 /* tv card specific */
-#define TDA9887_PRESENT 		(1<<0)
-#define TDA9887_PORT1_INACTIVE 		(1<<1)
-#define TDA9887_PORT2_INACTIVE 		(1<<2)
-#define TDA9887_QSS 			(1<<3)
-#define TDA9887_INTERCARRIER 		(1<<4)
-#define TDA9887_PORT1_ACTIVE 		(1<<5)
-#define TDA9887_PORT2_ACTIVE 		(1<<6)
-#define TDA9887_INTERCARRIER_NTSC 	(1<<7)
+#define TDA9887_PRESENT			(1<<0)
+#define TDA9887_PORT1_INACTIVE		(1<<1)
+#define TDA9887_PORT2_INACTIVE		(1<<2)
+#define TDA9887_QSS			(1<<3)
+#define TDA9887_INTERCARRIER		(1<<4)
+#define TDA9887_PORT1_ACTIVE		(1<<5)
+#define TDA9887_PORT2_ACTIVE		(1<<6)
+#define TDA9887_INTERCARRIER_NTSC	(1<<7)
 /* Tuner takeover point adjustment, in dB, -16 <= top <= 15 */
-#define TDA9887_TOP_MASK 		(0x3f << 8)
-#define TDA9887_TOP_SET 		(1 << 13)
-#define TDA9887_TOP(top) 		(TDA9887_TOP_SET | (((16 + (top)) & 0x1f) << 8))
+#define TDA9887_TOP_MASK		(0x3f << 8)
+#define TDA9887_TOP_SET			(1 << 13)
+#define TDA9887_TOP(top)		(TDA9887_TOP_SET | \
+					 (((16 + (top)) & 0x1f) << 8))
 
 /* config options */
-#define TDA9887_DEEMPHASIS_MASK 	(3<<16)
-#define TDA9887_DEEMPHASIS_NONE 	(1<<16)
-#define TDA9887_DEEMPHASIS_50 		(2<<16)
-#define TDA9887_DEEMPHASIS_75 		(3<<16)
-#define TDA9887_AUTOMUTE 		(1<<18)
+#define TDA9887_DEEMPHASIS_MASK		(3<<16)
+#define TDA9887_DEEMPHASIS_NONE		(1<<16)
+#define TDA9887_DEEMPHASIS_50		(2<<16)
+#define TDA9887_DEEMPHASIS_75		(3<<16)
+#define TDA9887_AUTOMUTE		(1<<18)
 #define TDA9887_GATING_18		(1<<19)
 #define TDA9887_GAIN_NORMAL		(1<<20)
 #define TDA9887_RIF_41_3		(1<<21)  /* radio IF1 41.3 vs 33.3 */
 
+/**
+ * enum tuner_mode      - Mode of the tuner
+ *
+ * @T_RADIO:        Tuner core will work in radio mode
+ * @T_ANALOG_TV:    Tuner core will work in analog TV mode
+ *
+ * Older boards only had a single tuner device, but some devices have a
+ * separate tuner for radio. In any case, the tuner-core needs to know if
+ * the tuner chip(s) will be used in radio mode or analog TV mode, as, on
+ * radio mode, frequencies are specified on a different range than on TV
+ * mode. This enum is used by the tuner core in order to work with the
+ * proper tuner range and eventually use a different tuner chip while in
+ * radio mode.
+ */
 enum tuner_mode {
 	T_RADIO		= 1 << V4L2_TUNER_RADIO,
 	T_ANALOG_TV     = 1 << V4L2_TUNER_ANALOG_TV,
-	/* Don't need to map V4L2_TUNER_DIGITAL_TV, as tuner-core won't use it */
+	/* Don't map V4L2_TUNER_DIGITAL_TV, as tuner-core won't use it */
 };
 
-/* Older boards only had a single tuner device. Nowadays multiple tuner
-   devices may be present on a single board. Using TUNER_SET_TYPE_ADDR
-   to pass the tuner_setup structure it is possible to setup each tuner
-   device in turn.
-
-   Since multiple devices may be present it is no longer sufficient to
-   send a command to a single i2c device. Instead you should broadcast
-   the command to all i2c devices.
-
-   By setting the mode_mask correctly you can select which commands are
-   accepted by a specific tuner device. For example, set mode_mask to
-   T_RADIO if the device is a radio-only tuner. That specific tuner will
-   only accept commands when the tuner is in radio mode and ignore them
-   when the tuner is set to TV mode.
+/**
+ * struct tuner_setup   - setup the tuner chipsets
+ *
+ * @addr:		I2C address used to control the tuner device/chipset
+ * @type:		Type of the tuner, as defined at the TUNER_* macros.
+ *			Each different tuner model should have an unique
+ *			identifier.
+ * @mode_mask:		Mask with the allowed tuner modes: V4L2_TUNER_RADIO,
+ *			V4L2_TUNER_ANALOG_TV and/or V4L2_TUNER_DIGITAL_TV,
+ *			describing if the tuner should be used to support
+ *			Radio, analog TV and/or digital TV.
+ * @config:		Used to send tune