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

Pull media updates from Mauro Carvalho Chehab:
 - new DVB frontend drivers: ascot2e, cxd2841er, horus3a, lnbh25
 - new HDMI capture driver: tc358743
 - new driver for NetUP DVB new boards (netup_unidvb)
 - IR support for DVBSky cards (smipcie-ir)
 - Coda driver has gain macroblock tiling support
 - Renesas R-Car gains JPEG codec driver
 - new DVB platform driver for STi boards: c8sectpfe
 - added documentation for the media core kABI to device-drivers DocBook
 - lots of driver fixups, cleanups and improvements

* tag 'media/v4.3-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (297 commits)
  [media] c8sectpfe: Remove select on undefined LIBELF_32
  [media] i2c: fix platform_no_drv_owner.cocci warnings
  [media] cx231xx: Use wake_up_interruptible() instead of wake_up_interruptible_nr()
  [media] tc358743: only queue subdev notifications if devnode is set
  [media] tc358743: add missing Kconfig dependency/select
  [media] c8sectpfe: Use %pad to print 'dma_addr_t'
  [media] DocBook media: Fix typo "the the" in xml files
  [media] tc358743: make reset gpio optional
  [media] tc358743: set direction of reset gpio using devm_gpiod_get
  [media] dvbdev: document most of the functions/data structs
  [media] dvb_frontend.h: document the struct dvb_frontend
  [media] dvb-frontend.h: document struct dtv_frontend_properties
  [media] dvb-frontend.h: document struct dvb_frontend_ops
  [media] dvb: Use DVBFE_ALGO_HW where applicable
  [media] dvb_frontend.h: document struct analog_demod_ops
  [media] dvb_frontend.h: Document struct dvb_tuner_ops
  [media] Docbook: Document struct analog_parameters
  [media] dvb_frontend.h: get rid of dvbfe_modcod
  [media] add documentation for struct dvb_tuner_info
  [media] dvb_frontend: document dvb_frontend_tune_settings
  ...

15 files changed, 1111 insertions, 865 deletions

diff --git a/include/media/media-devnode.h b/include/media/media-devnode.h
index 0dc7060f9625..17ddae32060d 100644
--- a/include/media/media-devnode.h
+++ b/include/media/media-devnode.h
@@ -53,9 +53,13 @@ struct media_file_operations {
 
 /**
  * struct media_devnode - Media device node
+ * @fops:       pointer to struct media_file_operations with media device ops
+ * @dev:        struct device pointer for the media controller device
+ * @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()
  *
  * This structure represents a media-related device node.
  *
diff --git a/include/media/omap3isp.h b/include/media/omap3isp.h
deleted file mode 100644
index 048f8f9117ef..000000000000
--- a/include/media/omap3isp.h
+++ /dev/null
@@ -1,158 +0,0 @@
-/*
- * omap3isp.h
- *
- * TI OMAP3 ISP - Platform data
- *
- * Copyright (C) 2011 Nokia Corporation
- *
- * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
- *           Sakari Ailus <sakari.ailus@iki.fi>
- *
- * 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.
- *
- * 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., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA
- */
-
-#ifndef __MEDIA_OMAP3ISP_H__
-#define __MEDIA_OMAP3ISP_H__
-
-struct i2c_board_info;
-struct isp_device;
-
-enum isp_interface_type {
-        ISP_INTERFACE_PARALLEL,
-        ISP_INTERFACE_CSI2A_PHY2,
-        ISP_INTERFACE_CCP2B_PHY1,
-        ISP_INTERFACE_CCP2B_PHY2,
-        ISP_INTERFACE_CSI2C_PHY1,
-};
-
-enum {
-        ISP_LANE_SHIFT_0 = 0,
-        ISP_LANE_SHIFT_2 = 1,
-        ISP_LANE_SHIFT_4 = 2,
-        ISP_LANE_SHIFT_6 = 3,
-};
-
-/**
- * struct isp_parallel_cfg - Parallel interface configuration
- * @data_lane_shift: Data lane shifter
- *              ISP_LANE_SHIFT_0 - CAMEXT[13:0] -> CAM[13:0]
- *              ISP_LANE_SHIFT_2 - CAMEXT[13:2] -> CAM[11:0]
- *              ISP_LANE_SHIFT_4 - CAMEXT[13:4] -> CAM[9:0]
- *              ISP_LANE_SHIFT_6 - CAMEXT[13:6] -> CAM[7:0]
- * @clk_pol: Pixel clock polarity
- *              0 - Sample on rising edge, 1 - Sample on falling edge
- * @hs_pol: Horizontal synchronization polarity
- *              0 - Active high, 1 - Active low
- * @vs_pol: Vertical synchronization polarity
- *              0 - Active high, 1 - Active low
- * @fld_pol: Field signal polarity
- *              0 - Positive, 1 - Negative
- * @data_pol: Data polarity
- *              0 - Normal, 1 - One's complement
- */
-struct isp_parallel_cfg {
-        unsigned int data_lane_shift:2;
-        unsigned int clk_pol:1;
-        unsigned int hs_pol:1;
-        unsigned int vs_pol:1;
-        unsigned int fld_pol:1;
-        unsigned int data_pol:1;
-};
-
-enum {
-        ISP_CCP2_PHY_DATA_CLOCK = 0,
-        ISP_CCP2_PHY_DATA_STROBE = 1,
-};
-
-enum {
-        ISP_CCP2_MODE_MIPI = 0,
-        ISP_CCP2_MODE_CCP2 = 1,
-};
-
-/**
- * struct isp_csiphy_lane: CCP2/CSI2 lane position and polarity
- * @pos: position of the lane
- * @pol: polarity of the lane
- */
-struct isp_csiphy_lane {
-        u8 pos;
-        u8 pol;
-};
-
-#define ISP_CSIPHY1_NUM_DATA_LANES      1
-#define ISP_CSIPHY2_NUM_DATA_LANES      2
-
-/**
- * struct isp_csiphy_lanes_cfg - CCP2/CSI2 lane configuration
- * @data: Configuration of one or two data lanes
- * @clk: Clock lane configuration
- */
-struct isp_csiphy_lanes_cfg {
-        struct isp_csiphy_lane data[ISP_CSIPHY2_NUM_DATA_LANES];
-        struct isp_csiphy_lane clk;
-};
-
-/**
- * struct isp_ccp2_cfg - CCP2 interface configuration
- * @strobe_clk_pol: Strobe/clock polarity
- *              0 - Non Inverted, 1 - Inverted
- * @crc: Enable the cyclic redundancy check
- * @ccp2_mode: Enable CCP2 compatibility mode
- *              ISP_CCP2_MODE_MIPI - MIPI-CSI1 mode
- *              ISP_CCP2_MODE_CCP2 - CCP2 mode
- * @phy_layer: Physical layer selection
- *              ISP_CCP2_PHY_DATA_CLOCK - Data/clock physical layer
- *              ISP_CCP2_PHY_DATA_STROBE - Data/strobe physical layer
- * @vpclk_div: Video port output clock control
- */
-struct isp_ccp2_cfg {
-        unsigned int strobe_clk_pol:1;
-        unsigned int crc:1;
-        unsigned int ccp2_mode:1;
-        unsigned int phy_layer:1;
-        unsigned int vpclk_div:2;
-        struct isp_csiphy_lanes_cfg lanecfg;
-};
-
-/**
- * struct isp_csi2_cfg - CSI2 interface configuration
- * @crc: Enable the cyclic redundancy check
- */
-struct isp_csi2_cfg {
-        unsigned crc:1;
-        struct isp_csiphy_lanes_cfg lanecfg;
-};
-
-struct isp_bus_cfg {
-        enum isp_interface_type interface;
-        union {
-                struct isp_parallel_cfg parallel;
-                struct isp_ccp2_cfg ccp2;
-                struct isp_csi2_cfg csi2;
-        } bus; /* gcc < 4.6.0 chokes on anonymous union initializers */
-};
-
-struct isp_platform_subdev {
-        struct i2c_board_info *board_info;
-        int i2c_adapter_id;
-        struct isp_bus_cfg *bus;
-};
-
-struct isp_platform_data {
-        struct isp_platform_subdev *subdevs;
-        void (*set_constraints)(struct isp_device *isp, bool enable);
-};
-
-#endif  /* __MEDIA_OMAP3ISP_H__ */
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index 644bdc61c387..ec921f6538c7 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -69,7 +69,7 @@ enum rc_filter_type {
  * @rc_map: current scan/key table
  * @lock: used to ensure we've filled in all protocol details before
  *      anyone can call show_protocols or store_protocols
- * @devno: unique remote control device number
+ * @minor: unique minor remote control device number
  * @raw: additional data for raw pulse/space devices
  * @input_dev: the input child device used to communicate events to userspace
  * @driver_type: specifies if protocol decoding is done in hardware or software
@@ -110,7 +110,7 @@ enum rc_filter_type {
  * @s_tx_mask: set transmitter mask (for devices with multiple tx outputs)
  * @s_tx_carrier: set transmit carrier frequency
  * @s_tx_duty_cycle: set transmit duty cycle (0% - 100%)
- * @s_rx_carrier: inform driver about carrier it is expected to handle
+ * @s_rx_carrier_range: inform driver about carrier it is expected to handle
  * @tx_ir: transmit IR
  * @s_idle: enable/disable hardware idle mode, upon which,
  *      device doesn't interrupt host until it sees IR pulses
@@ -129,7 +129,7 @@ struct rc_dev {
         const char                      *map_name;
         struct rc_map                   rc_map;
         struct mutex                    lock;
-        unsigned long                   devno;
+        unsigned int                    minor;
         struct ir_raw_event_ctrl        *raw;
         struct input_dev                *input_dev;
         enum rc_driver_type             driver_type;
diff --git a/include/media/rc-map.h b/include/media/rc-map.h
index 27763d5bd261..7c4bbc4dfab4 100644
--- a/include/media/rc-map.h
+++ b/include/media/rc-map.h
@@ -14,30 +14,28 @@
 enum rc_type {
         RC_TYPE_UNKNOWN         = 0,    /* Protocol not known */
         RC_TYPE_OTHER           = 1,    /* Protocol known but proprietary */
-        RC_TYPE_LIRC            = 2,    /* Pass raw IR to lirc userspace */
-        RC_TYPE_RC5             = 3,    /* Philips RC5 protocol */
-        RC_TYPE_RC5X            = 4,    /* Philips RC5x protocol */
-        RC_TYPE_RC5_SZ          = 5,    /* StreamZap variant of RC5 */
-        RC_TYPE_JVC             = 6,    /* JVC protocol */
-        RC_TYPE_SONY12          = 7,    /* Sony 12 bit protocol */
-        RC_TYPE_SONY15          = 8,    /* Sony 15 bit protocol */
-        RC_TYPE_SONY20          = 9,    /* Sony 20 bit protocol */
-        RC_TYPE_NEC             = 10,   /* NEC protocol */
-        RC_TYPE_SANYO           = 11,   /* Sanyo protocol */
-        RC_TYPE_MCE_KBD         = 12,   /* RC6-ish MCE keyboard/mouse */
-        RC_TYPE_RC6_0           = 13,   /* Philips RC6-0-16 protocol */
-        RC_TYPE_RC6_6A_20       = 14,   /* Philips RC6-6A-20 protocol */
-        RC_TYPE_RC6_6A_24       = 15,   /* Philips RC6-6A-24 protocol */
-        RC_TYPE_RC6_6A_32       = 16,   /* Philips RC6-6A-32 protocol */
-        RC_TYPE_RC6_MCE         = 17,   /* MCE (Philips RC6-6A-32 subtype) protocol */
-        RC_TYPE_SHARP           = 18,   /* Sharp protocol */
-        RC_TYPE_XMP             = 19,   /* XMP protocol */
+        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 */
 };
 
 #define RC_BIT_NONE             0
 #define RC_BIT_UNKNOWN          (1 << RC_TYPE_UNKNOWN)
 #define RC_BIT_OTHER            (1 << RC_TYPE_OTHER)
-#define RC_BIT_LIRC             (1 << RC_TYPE_LIRC)
 #define RC_BIT_RC5              (1 << RC_TYPE_RC5)
 #define RC_BIT_RC5X             (1 << RC_TYPE_RC5X)
 #define RC_BIT_RC5_SZ           (1 << RC_TYPE_RC5_SZ)
@@ -56,7 +54,7 @@ enum rc_type {
 #define RC_BIT_SHARP            (1 << RC_TYPE_SHARP)
 #define RC_BIT_XMP              (1 << RC_TYPE_XMP)
 
-#define RC_BIT_ALL      (RC_BIT_UNKNOWN | RC_BIT_OTHER | RC_BIT_LIRC | \
+#define RC_BIT_ALL      (RC_BIT_UNKNOWN | RC_BIT_OTHER | \
                          RC_BIT_RC5 | RC_BIT_RC5X | RC_BIT_RC5_SZ | \
                          RC_BIT_JVC | \
                          RC_BIT_SONY12 | RC_BIT_SONY15 | RC_BIT_SONY20 | \
diff --git a/include/media/tc358743.h b/include/media/tc358743.h
new file mode 100644
index 000000000000..4513f2f9cfbc
--- /dev/null
+++ b/include/media/tc358743.h
@@ -0,0 +1,131 @@
+/*
+ * tc358743 - Toshiba HDMI to CSI-2 bridge
+ *
+ * Copyright 2015 Cisco Systems, Inc. and/or its affiliates. All rights
+ * reserved.
+ *
+ * This program is free software; you may redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+/*
+ * References (c = chapter, p = page):
+ * REF_01 - Toshiba, TC358743XBG (H2C), Functional Specification, Rev 0.60
+ * REF_02 - Toshiba, TC358743XBG_HDMI-CSI_Tv11p_nm.xls
+ */
+
+#ifndef _TC358743_
+#define _TC358743_
+
+enum tc358743_ddc5v_delays {
+        DDC5V_DELAY_0_MS,
+        DDC5V_DELAY_50_MS,
+        DDC5V_DELAY_100_MS,
+        DDC5V_DELAY_200_MS,
+};
+
+enum tc358743_hdmi_detection_delay {
+        HDMI_MODE_DELAY_0_MS,
+        HDMI_MODE_DELAY_25_MS,
+        HDMI_MODE_DELAY_50_MS,
+        HDMI_MODE_DELAY_100_MS,
+};
+
+struct tc358743_platform_data {
+        /* System clock connected to REFCLK (pin H5) */
+        u32 refclk_hz; /* 26 MHz, 27 MHz or 42 MHz */
+
+        /* DDC +5V debounce delay to avoid spurious interrupts when the cable
+         * is connected.
+         * Sets DDC5V_MODE in register DDC_CTL.
+         * Default: DDC5V_DELAY_0_MS
+         */
+        enum tc358743_ddc5v_delays ddc5v_delay;
+
+        bool enable_hdcp;
+
+        /*
+         * The FIFO size is 512x32, so Toshiba recommend to set the default FIFO
+         * level to somewhere in the middle (e.g. 300), so it can cover speed
+         * mismatches in input and output ports.
+         */
+        u16 fifo_level;
+
+        /* Bps pr lane is (refclk_hz / pll_prd) * pll_fbd */
+        u16 pll_prd;
+        u16 pll_fbd;
+
+        /* CSI
+         * Calculate CSI parameters with REF_02 for the highest resolution your
+         * CSI interface can handle. The driver will adjust the number of CSI
+         * lanes in use according to the pixel clock.
+         *
+         * The values in brackets are calculated with REF_02 when the number of
+         * bps pr lane is 823.5 MHz, and can serve as a starting point.
+         */
+        u32 lineinitcnt;        /* (0x00001770) */
+        u32 lptxtimecnt;        /* (0x00000005) */
+        u32 tclk_headercnt;     /* (0x00001d04) */
+        u32 tclk_trailcnt;      /* (0x00000000) */
+        u32 ths_headercnt;      /* (0x00000505) */
+        u32 twakeup;            /* (0x00004650) */
+        u32 tclk_postcnt;       /* (0x00000000) */
+        u32 ths_trailcnt;       /* (0x00000004) */
+        u32 hstxvregcnt;        /* (0x00000005) */
+
+        /* DVI->HDMI detection delay to avoid unnecessary switching between DVI
+         * and HDMI mode.
+         * Sets HDMI_DET_V in register HDMI_DET.
+         * Default: HDMI_MODE_DELAY_0_MS
+         */
+        enum tc358743_hdmi_detection_delay hdmi_detection_delay;
+
+        /* Reset PHY automatically when TMDS clock goes from DC to AC.
+         * Sets PHY_AUTO_RST2 in register PHY_CTL2.
+         * Default: false
+         */
+        bool hdmi_phy_auto_reset_tmds_detected;
+
+        /* Reset PHY automatically when TMDS clock passes 21 MHz.
+         * Sets PHY_AUTO_RST3 in register PHY_CTL2.
+         * Default: false
+         */
+        bool hdmi_phy_auto_reset_tmds_in_range;
+
+        /* Reset PHY automatically when TMDS clock is detected.
+         * Sets PHY_AUTO_RST4 in register PHY_CTL2.
+         * Default: false
+         */
+        bool hdmi_phy_auto_reset_tmds_valid;
+
+        /* Reset HDMI PHY automatically when hsync period is out of range.
+         * Sets H_PI_RST in register HV_RST.
+         * Default: false
+         */
+        bool hdmi_phy_auto_reset_hsync_out_of_range;
+
+        /* Reset HDMI PHY automatically when vsync period is out of range.
+         * Sets V_PI_RST in register HV_RST.
+         * Default: false
+         */
+        bool hdmi_phy_auto_reset_vsync_out_of_range;
+};
+
+/* custom controls */
+/* Audio sample rate in Hz */
+#define TC358743_CID_AUDIO_SAMPLING_RATE (V4L2_CID_USER_TC358743_BASE + 0)
+/* Audio present status */
+#define TC358743_CID_AUDIO_PRESENT       (V4L2_CID_USER_TC358743_BASE + 1)
+
+#endif
diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h
index 768356917bea..1d6d7da4c45d 100644
--- a/include/media/v4l2-async.h
+++ b/include/media/v4l2-async.h
@@ -32,7 +32,8 @@ enum v4l2_async_match_type {
 
 /**
  * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
- * @bus_type:   subdevice bus type to select the appropriate matching method
+ *
+ * @match_type: type of match that will be used
  * @match:      union of per-bus type matching data sets
  * @list:       used to link struct v4l2_async_subdev objects, waiting to be
  *              probed, to a notifier->waiting list
@@ -62,8 +63,9 @@ struct v4l2_async_subdev {
 };
 
 /**
- * v4l2_async_notifier - v4l2_device notifier data
- * @num_subdevs:number of subdevices
+ * struct v4l2_async_notifier - v4l2_device notifier data
+ *
+ * @num_subdevs: number of subdevices
  * @subdevs:    array of pointers to subdevice descriptors
  * @v4l2_dev:   pointer to struct v4l2_device
  * @waiting:    list of struct v4l2_async_subdev, waiting for their drivers
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 911f3e542834..da6fe9802fee 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -36,7 +36,8 @@ struct v4l2_subscribed_event;
 struct v4l2_fh;
 struct poll_table_struct;
 
-/** union v4l2_ctrl_ptr - A pointer to a control value.
+/**
+ * union v4l2_ctrl_ptr - A pointer to a control value.
  * @p_s32:      Pointer to a 32-bit signed value.
  * @p_s64:      Pointer to a 64-bit signed value.
  * @p_u8:       Pointer to a 8-bit unsigned value.
@@ -55,30 +56,34 @@ union v4l2_ctrl_ptr {
         void *p;
 };
 
-/** struct v4l2_ctrl_ops - The control operations that the driver has to provide.
-  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
-  *             for volatile (and usually read-only) controls such as a control
-  *             that returns the current signal strength which changes
-  *             continuously.
-  *             If not set, then the currently cached value will be returned.
-  * @try_ctrl:  Test whether the control's value is valid. Only relevant when
-  *             the usual min/max/step checks are not sufficient.
-  * @s_ctrl:    Actually set the new control value. s_ctrl is compulsory. The
-  *             ctrl->handler->lock is held when these ops are called, so no
-  *             one else can access controls owned by that handler.
-  */
+/**
+ * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
+ * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
+ *              for volatile (and usually read-only) controls such as a control
+ *              that returns the current signal strength which changes
+ *              continuously.
+ *              If not set, then the currently cached value will be returned.
+ * @try_ctrl:   Test whether the control's value is valid. Only relevant when
+ *              the usual min/max/step checks are not sufficient.
+ * @s_ctrl:     Actually set the new control value. s_ctrl is compulsory. The
+ *              ctrl->handler->lock is held when these ops are called, so no
+ *              one else can access controls owned by that handler.
+ */
 struct v4l2_ctrl_ops {
         int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
         int (*try_ctrl)(struct v4l2_ctrl *ctrl);
         int (*s_ctrl)(struct v4l2_ctrl *ctrl);
 };
 
-/** struct v4l2_ctrl_type_ops - The control type operations that the driver has to provide.
-  * @equal: return true if both values are equal.
-  * @init: initialize the value.
-  * @log: log the value.
-  * @validate: validate the value. Return 0 on success and a negative value otherwise.
-  */
+/**
+ * struct v4l2_ctrl_type_ops - The control type operations that the driver
+ *                             has to provide.
+ *
+ * @equal: return true if both values are equal.
+ * @init: initialize the value.
+ * @log: log the value.
+ * @validate: validate the value. Return 0 on success and a negative value otherwise.
+ */
 struct v4l2_ctrl_type_ops {
         bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
                       union v4l2_ctrl_ptr ptr1,
@@ -92,74 +97,80 @@ struct v4l2_ctrl_type_ops {
 
 typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
 
-/** struct v4l2_ctrl - The control structure.
-  * @node:      The list node.
-  * @ev_subs:   The list of control event subscriptions.
-  * @handler:   The handler that owns the control.
-  * @cluster:   Point to start of cluster array.
-  * @ncontrols: Number of controls in cluster array.
-  * @done:      Internal flag: set for each processed control.
-  * @is_new:    Set when the user specified a new value for this control. It
-  *             is also set when called from v4l2_ctrl_handler_setup. Drivers
-  *             should never set this flag.
-  * @has_changed: Set when the current value differs from the new value. Drivers
-  *             should never use this flag.
-  * @is_private: If set, then this control is private to its handler and it
-  *             will not be added to any other handlers. Drivers can set
-  *             this flag.
-  * @is_auto:   If set, then this control selects whether the other cluster
-  *             members are in 'automatic' mode or 'manual' mode. This is
-  *             used for autogain/gain type clusters. Drivers should never
-  *             set this flag directly.
-  * @is_int:    If set, then this control has a simple integer value (i.e. it
-  *             uses ctrl->val).
-  * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING.
-  * @is_ptr:    If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES
-  *             and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct
-  *             v4l2_ext_control uses field p to point to the data.
-  * @is_array: If set, then this control contains an N-dimensional array.
-  * @has_volatiles: If set, then one or more members of the cluster are volatile.
-  *             Drivers should never touch this flag.
-  * @call_notify: If set, then call the handler's notify function whenever the
-  *             control's value changes.
-  * @manual_mode_value: If the is_auto flag is set, then this is the value
-  *             of the auto control that determines if that control is in
-  *             manual mode. So if the value of the auto control equals this
-  *             value, then the whole cluster is in manual mode. Drivers should
-  *             never set this flag directly.
-  * @ops:       The control ops.
-  * @type_ops:  The control type ops.
-  * @id:        The control ID.
-  * @name:      The control name.
-  * @type:      The control type.
-  * @minimum:   The control's minimum value.
-  * @maximum:   The control's maximum value.
-  * @default_value: The control's default value.
-  * @step:      The control's step value for non-menu controls.
-  * @elems:     The number of elements in the N-dimensional array.
-  * @elem_size: The size in bytes of the control.
-  * @dims:      The size of each dimension.
-  * @nr_of_dims:The number of dimensions in @dims.
-  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
-  *             easy to skip menu items that are not valid. If bit X is set,
-  *             then menu item X is skipped. Of course, this only works for
-  *             menus with <= 32 menu items. There are no menus that come
-  *             close to that number, so this is OK. Should we ever need more,
-  *             then this will have to be extended to a u64 or a bit array.
-  * @qmenu:     A const char * array for all menu items. Array entries that are
-  *             empty strings ("") correspond to non-existing menu items (this
-  *             is in addition to the menu_skip_mask above). The last entry
-  *             must be NULL.
-  * @flags:     The control's flags.
-  * @cur:       The control's current value.
-  * @val:       The control's new s32 value.
-  * @val64:     The control's new s64 value.
-  * @priv:      The control's private pointer. For use by the driver. It is
-  *             untouched by the control framework. Note that this pointer is
-  *             not freed when the control is deleted. Should this be needed
-  *             then a new internal bitfield can be added to tell the framework
-  *             to free this pointer.
-  */
+/**
+ * struct v4l2_ctrl - The control structure.
+ * @node:       The list node.
+ * @ev_subs:    The list of control event subscriptions.
+ * @handler:    The handler that owns the control.
+ * @cluster:    Point to start of cluster array.
+ * @ncontrols:  Number of controls in cluster array.
+ * @done:       Internal flag: set for each processed control.
+ * @is_new:     Set when the user specified a new value for this control. It
+ *              is also set when called from v4l2_ctrl_handler_setup. Drivers
+ *              should never set this flag.
+ * @has_changed: Set when the current value differs from the new value. Drivers
+ *              should never use this flag.
+ * @is_private: If set, then this control is private to its handler and it
+ *              will not be added to any other handlers. Drivers can set
+ *              this flag.
+ * @is_auto:   If set, then this control selects whether the other cluster
+ *              members are in 'automatic' mode or 'manual' mode. This is
+ *              used for autogain/gain type clusters. Drivers should never
+ *              set this flag directly.
+ * @is_int:    If set, then this control has a simple integer value (i.e. it
+ *              uses ctrl->val).
+ * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING.
+ * @is_ptr:     If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES
+ *              and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct
+ *              v4l2_ext_control uses field p to point to the data.
+ * @is_array: If set, then this control contains an N-dimensional array.
+ * @has_volatiles: If set, then one or more members of the cluster are volatile.
+ *              Drivers should never touch this flag.
+ * @call_notify: If set, then call the handler's notify function whenever the
+ *              control's value changes.
+ * @manual_mode_value: If the is_auto flag is set, then this is the value
+ *              of the auto control that determines if that control is in
+ *              manual mode. So if the value of the auto control equals this
+ *              value, then the whole cluster is in manual mode. Drivers should
+ *              never set this flag directly.
+ * @ops:        The control ops.
+ * @type_ops:   The control type ops.
+ * @id: The control ID.
+ * @name:       The control name.
+ * @type:       The control type.
+ * @minimum:    The control's minimum value.
+ * @maximum:    The control's maximum value.
+ * @default_value: The control's default value.
+ * @step:       The control's step value for non-menu controls.
+ * @elems:      The number of elements in the N-dimensional array.
+ * @elem_size:  The size in bytes of the control.
+ * @dims:       The size of each dimension.
+ * @nr_of_dims:The number of dimensions in @dims.
+ * @menu_skip_mask: The control's skip mask for menu controls. This makes it
+ *              easy to skip menu items that are not valid. If bit X is set,
+ *              then menu item X is skipped. Of course, this only works for
+ *              menus with <= 32 menu items. There are no menus that come
+ *              close to that number, so this is OK. Should we ever need more,
+ *              then this will have to be extended to a u64 or a bit array.
+ * @qmenu:      A const char * array for all menu items. Array entries that are
+ *              empty strings ("") correspond to non-existing menu items (this
+ *              is in addition to the menu_skip_mask above). The last entry
+ *              must be NULL.
+ * @flags:      The control's flags.
+ * @cur:        The control's current value.
+ * @val:        The control's new s32 value.
+ * @priv:       The control's private pointer. For use by the driver. It is
+ *              untouched by the control framework. Note that this pointer is
+ *              not freed when the control is deleted. Should this be needed
+ *              then a new internal bitfield can be added to tell the framework
+ *              to free this pointer.
+ * @p_cur:      The control's current value represented via an union with
+ *              provides a standard way of accessing control types
+ *              through a pointer.
+ * @p_new:      The control's new value represented via an union with provides
+ *              a standard way of accessing control types
+ *              through a pointer.
+ */
 struct v4l2_ctrl {
         /* Administrative fields */
         struct list_head node;
@@ -210,16 +221,17 @@ struct v4l2_ctrl {
         union v4l2_ctrl_ptr p_cur;
 };
 
-/** struct v4l2_ctrl_ref - The control reference.
-  * @node:      List node for the sorted list.
-  * @next:      Single-link list node for the hash.
-  * @ctrl:      The actual control information.
-  * @helper:    Pointer to helper struct. Used internally in prepare_ext_ctrls().
-  *
-  * 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
-  * is used to link the control in the hash's bucket.
-  */
+/**
+ * struct v4l2_ctrl_ref - The control reference.
+ * @node:       List node for the sorted list.
+ * @next:       Single-link list node for the hash.
+ * @ctrl:       The actual control information.
+ * @helper:     Pointer to helper struct. Used internally in prepare_ext_ctrls().
+ *
+ * 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
+ * is used to link the control in the hash's bucket.
+ */
 struct v4l2_ctrl_ref {
         struct list_head node;
         struct v4l2_ctrl_ref *next;
@@ -227,25 +239,26 @@ struct v4l2_ctrl_ref {
         struct v4l2_ctrl_helper *helper;
 };
 
-/** struct v4l2_ctrl_handler - The control handler keeps track of all the
-  * controls: both the controls owned by the handler and those inherited
-  * from other handlers.
-  * @_lock:     Default for "lock".
-  * @lock:      Lock to control access to this handler and its controls.
-  *             May be replaced by the user right after init.
-  * @ctrls:     The list of controls owned by this handler.
-  * @ctrl_refs: The list of control references.
-  * @cached:    The last found control reference. It is common that the same
-  *             control is needed multiple times, so this is a simple
-  *             optimization.
-  * @buckets:   Buckets for the hashing. Allows for quick control lookup.
-  * @notify:    A notify callback that is called whenever the control changes value.
-  *             Note that the handler's lock is held when the notify function
-  *             is called!
-  * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
-  * @nr_of_buckets: Total number of buckets in the array.
-  * @error:     The error code of the first failed control addition.
-  */
+/**
+ * struct v4l2_ctrl_handler - The control handler keeps track of all the
+ * controls: both the controls owned by the handler and those inherited
+ * from other handlers.
+ * @_lock:      Default for "lock".
+ * @lock:       Lock to control access to this handler and its controls.
+ *              May be replaced by the user right after init.
+ * @ctrls:      The list of controls owned by this handler.
+ * @ctrl_refs:  The list of control references.
+ * @cached:     The last found control reference. It is common that the same
+ *              control is needed multiple times, so this is a simple
+ *              optimization.
+ * @buckets:    Buckets for the hashing. Allows for quick control lookup.
+ * @notify:     A notify callback that is called whenever the control changes value.
+ *              Note that the handler's lock is held when the notify function
+ *              is called!
+ * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
+ * @nr_of_buckets: Total number of buckets in the array.
+ * @error:      The error code of the first failed control addition.
+ */
 struct v4l2_ctrl_handler {
         struct mutex _lock;
         struct mutex *lock;
@@ -259,32 +272,35 @@ struct v4l2_ctrl_handler {
         int error;
 };
 
-/** struct v4l2_ctrl_config - Control configuration structure.
-  * @ops:       The control ops.
-  * @type_ops:  The control type ops. Only needed for compound controls.
-  * @id:        The control ID.
-  * @name:      The control name.
-  * @type:      The control type.
-  * @min:       The control's minimum value.
-  * @max:       The control's maximum value.
-  * @step:      The control's step value for non-menu controls.
-  * @def:       The control's default value.
-  * @dims:      The size of each dimension.
-  * @elem_size: The size in bytes of the control.
-  * @flags:     The control's flags.
-  * @menu_skip_mask: The control's skip mask for menu controls. This makes it
-  *             easy to skip menu items that are not valid. If bit X is set,
-  *             then menu item X is skipped. Of course, this only works for
-  *             menus with <= 64 menu items. There are no menus that come
-  *             close to that number, so this is OK. Should we ever need more,
-  *             then this will have to be extended to a bit array.
-  * @qmenu:     A const char * array for all menu items. Array entries that are
-  *             empty strings ("") correspond to non-existing menu items (this
-  *             is in addition to the menu_skip_mask above). The last entry
-  *             must be NULL.
-  * @is_private: If set, then this control is private to its handler and it
-  *             will not be added to any other handlers.
-  */
+/**
+ * struct v4l2_ctrl_config - Control configuration structure.
+ * @ops:        The control ops.
+ * @type_ops:   The control type ops. Only needed for compound controls.
+ * @id: The control ID.
+ * @name:       The control name.
+ * @type:       The control type.
+ * @min:        The control's minimum value.
+ * @max:        The control's maximum value.
+ * @step:       The control's step value for non-menu controls.
+ * @def:        The control's default value.
+ * @dims:       The size of each dimension.
+ * @elem_size:  The size in bytes of the control.
+ * @flags:      The control's flags.
+ * @menu_skip_mask: The control's skip mask for menu controls. This makes it
+ *              easy to skip menu items that are not valid. If bit X is set,
+ *              then menu item X is skipped. Of course, this only works for
+ *              menus with <= 64 menu items. There are no menus that come
+ *              close to that number, so this is OK. Should we ever need more,
+ *              then this will have to be extended to a bit array.
+ * @qmenu:      A const char * array for all menu items. Array entries that are
+ *              empty strings ("") correspond to non-existing menu items (this
+ *              is in addition to the menu_skip_mask above). The last entry
+ *              must be NULL.
+ * @qmenu_int:  A const s64 integer array for all menu items of the type
+ *              V4L2_CTRL_TYPE_INTEGER_MENU.
+ * @is_private: If set, then this control is private to its handler and it
+ *              will not be added to any other handlers.
+ */
 struct v4l2_ctrl_config {
         const struct v4l2_ctrl_ops *ops;
         const struct v4l2_ctrl_type_ops *type_ops;
@@ -304,42 +320,44 @@ struct v4l2_ctrl_config {
         unsigned int is_private:1;
 };
 
-/** v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
-  *
-  * This works for all standard V4L2 controls.
-  * For non-standard controls it will only fill in the given arguments
-  * and @name will be NULL.
-  *
-  * This function will overwrite the contents of @name, @type and @flags.
-  * The contents of @min, @max, @step and @def may be modified depending on
-  * the type.
-  *
-  * Do not use in drivers! It is used internally for backwards compatibility
-  * control handling only. Once all drivers are converted to use the new
-  * control framework this function will no longer be exported.
-  */
+/*
+ * v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
+ *
+ * This works for all standard V4L2 controls.
+ * For non-standard controls it will only fill in the given arguments
+ * and @name will be NULL.
+ *
+ * This function will overwrite the contents of @name, @type and @flags.
+ * The contents of @min, @max, @step and @def may be modified depending on
+ * the type.
+ *
+ * Do not use in drivers! It is used internally for backwards compatibility
+ * control handling only. Once all drivers are converted to use the new
+ * control framework this function will no longer be exported.
+ */
 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
                     s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
 
 
-/** v4l2_ctrl_handler_init_class() - Initialize the control handler.
-  * @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.
-  * @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.
-  *
-  * Never use this call directly, always use the v4l2_ctrl_handler_init
-  * macro that hides the @key and @name arguments.
-  */
+/**
+ * v4l2_ctrl_handler_init_class() - Initialize the control handler.
+ * @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.
+ * @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.
+ *
+ * Never use this call directly, always use the v4l2_ctrl_handler_init
+ * macro that hides the @key and @name arguments.
+ */
 int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
                                  unsigned nr_of_controls_hint,
                                  struct lock_class_key *key, const char *name);
@@ -361,289 +379,326 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
         v4l2_ctrl_handler_init_class(hdl, nr_of_controls_hint, NULL, NULL)
 #endif
 
-/** v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
-  * the control list.
-  * @hdl:       The control handler.
-  *
-  * Does nothing if @hdl == NULL.
-  */
+/**
+ * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
+ * the control list.
+ * @hdl:        The control handler.
+ *
+ * Does nothing if @hdl == NULL.
+ */
 void v4l2_ctrl_handler_free(struct v4l2_ctrl_handler *hdl);
 
-/** v4l2_ctrl_lock() - Helper function to lock the handler
-  * associated with the control.
-  * @ctrl:      The control to lock.
-  */
+/**
+ * v4l2_ctrl_lock() - Helper function to lock the handler
+ * associated with the control.
+ * @ctrl:       The control to lock.
+ */
 static inline void v4l2_ctrl_lock(struct v4l2_ctrl *ctrl)
 {
         mutex_lock(ctrl->handler->lock);
 }
 
-/** v4l2_ctrl_unlock() - Helper function to unlock the handler
-  * associated with the control.
-  * @ctrl:      The control to unlock.
-  */
+/**
+ * v4l2_ctrl_unlock() - Helper function to unlock the handler
+ * associated with the control.
+ * @ctrl:       The control to unlock.
+ */
 static inline void v4l2_ctrl_unlock(struct v4l2_ctrl *ctrl)
 {
         mutex_unlock(ctrl->handler->lock);
 }
 
-/** v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
-  * to the handler to initialize the hardware to the current control values.
-  * @hdl:       The control handler.
-  *
-  * Button controls will be skipped, as are read-only controls.
-  *
-  * If @hdl == NULL, then this just returns 0.
-  */
+/**
+ * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
+ * to the handler to initialize the hardware to the current control values.
+ * @hdl:        The control handler.
+ *
+ * Button controls will be skipped, as are read-only controls.
+ *
+ * If @hdl == NULL, then this just returns 0.
+ */
 int v4l2_ctrl_handler_setup(struct v4l2_ctrl_handler *hdl);
 
-/** v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
-  * @hdl:       The control handler.
-  * @prefix:    The prefix to use when logging the control values. If the
-  *             prefix does not end with a space, then ": " will be added
-  *             after the prefix. If @prefix == NULL, then no prefix will be
-  *             used.
-  *
-  * For use with VIDIOC_LOG_STATUS.
-  *
-  * Does nothing if @hdl == NULL.
-  */
+/**
+ * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
+ * @hdl:        The control handler.
+ * @prefix:     The prefix to use when logging the control values. If the
+ *              prefix does not end with a space, then ": " will be added
+ *              after the prefix. If @prefix == NULL, then no prefix will be
+ *              used.
+ *
+ * For use with VIDIOC_LOG_STATUS.
+ *
+ * Does nothing if @hdl == NULL.
+ */
 void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
                                   const char *prefix);
 
-/** v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
-  * control.
-  * @hdl:       The control handler.
-  * @cfg:       The control's configuration data.
-  * @priv:      The control's driver-specific private data.
-  *
-  * If the &v4l2_ctrl struct could not be allocated then NULL is returned
-  * and @hdl->error is set to the error code (if it wasn't set already).
-  */
+/**
+ * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
+ * control.
+ * @hdl:        The control handler.
+ * @cfg:        The control's configuration data.
+ * @priv:       The control's driver-specific private data.
+ *
+ * If the &v4l2_ctrl struct could not be allocated then NULL is returned
+ * and @hdl->error is set to the error code (if it wasn't set already).
+ */
 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
                         const struct v4l2_ctrl_config *cfg, void *priv);
 
-/** v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
-  * @hdl:       The control handler.
-  * @ops:       The control ops.
-  * @id:        The control ID.
-  * @min:       The control's minimum value.
-  * @max:       The control's maximum value.
-  * @step:      The control's step value
-  * @def:       The control's default value.
-  *
-  * If the &v4l2_ctrl struct could not be allocated, or the control
-  * ID is not known, then NULL is returned and @hdl->error is set to the
-  * appropriate error code (if it wasn't set already).
-  *
-  * If @id refers to a menu control, then this function will return NULL.
-  *
-  * Use v4l2_ctrl_new_std_menu() when adding menu controls.
-  */
+/**
+ * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
+ * @hdl:        The control handler.
+ * @ops:        The control ops.
+ * @id: The control ID.
+ * @min:        The control's minimum value.
+ * @max:        The control's maximum value.
+ * @step:       The control's step value
+ * @def:        The control's default value.
+ *
+ * If the &v4l2_ctrl struct could not be allocated, or the control
+ * ID is not known, then NULL is returned and @hdl->error is set to the
+ * appropriate error code (if it wasn't set already).
+ *
+ * If @id refers to a menu control, then this function will return NULL.
+ *
+ * Use v4l2_ctrl_new_std_menu() when adding menu controls.
+ */
 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
                         const struct v4l2_ctrl_ops *ops,
                         u32 id, s64 min, s64 max, u64 step, s64 def);
 
-/** v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
-  * @hdl:       The control handler.
-  * @ops:       The control ops.
-  * @id:        The control ID.
-  * @max:       The control's maximum value.
-  * @mask:      The control's skip mask for menu controls. This makes it
-  *             easy to skip menu items that are not valid. If bit X is set,
-  *             then menu item X is skipped. Of course, this only works for
-  *             menus with <= 64 menu items. There are no menus that come
-  *             close to that number, so this is OK. Should we ever need more,
-  *             then this will have to be extended to a bit array.
-  * @def:       The control's default value.
-  *
-  * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
-  * determines which menu items are to be skipped.
-  *
-  * If @id refers to a non-menu control, then this function will return NULL.
-  */
+/**
+ * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
+ * @hdl:        The control handler.
+ * @ops:        The control ops.
+ * @id: The control ID.
+ * @max:        The control's maximum value.
+ * @mask:       The control's skip mask for menu controls. This makes it
+ *              easy to skip menu items that are not valid. If bit X is set,
+ *              then menu item X is skipped. Of course, this only works for
+ *              menus with <= 64 menu items. There are no menus that come
+ *              close to that number, so this is OK. Should we ever need more,
+ *              then this will have to be extended to a bit array.
+ * @def:        The control's default value.
+ *
+ * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
+ * determines which menu items are to be skipped.
+ *
+ * If @id refers to a non-menu control, then this function will return NULL.
+ */
 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
                         const struct v4l2_ctrl_ops *ops,
                         u32 id, u8 max, u64 mask, u8 def);
 
-/** v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
-  * with driver specific menu.
-  * @hdl:       The control handler.
-  * @ops:       The control ops.
-  * @id:        The control ID.
-  * @max:       The control's maximum value.
-  * @mask:      The control's skip mask for menu controls. This makes it
-  *             easy to skip menu items that are not valid. If bit X is set,
-  *             then menu item X is skipped. Of course, this only works for
-  *             menus with <= 64 menu items. There are no menus that come
-  *             close to that number, so this is OK. Should we ever need more,
-  *             then this will have to be extended to a bit array.
-  * @def:       The control's default value.
-  * @qmenu:     The new menu.
-  *
-  * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
-  * menu of this control.
-  *
-  */
+/**
+ * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
+ * with driver specific menu.
+ * @hdl:        The control handler.
+ * @ops:        The control ops.
+ * @id: The control ID.
+ * @max:        The control's maximum value.
+ * @mask:       The control's skip mask for menu controls. This makes it
+ *              easy to skip menu items that are not valid. If bit X is set,
+ *              then menu item X is skipped. Of course, this only works for
+ *              menus with <= 64 menu items. There are no menus that come
+ *              close to that number, so this is OK. Should we ever need more,
+ *              then this will have to be extended to a bit array.
+ * @def:        The control's default value.
+ * @qmenu:      The new menu.
+ *
+ * Same as v4l2_ctrl_new_std_menu(), but @qmenu will be the driver specific
+ * menu of this control.
+ *
+ */
 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
                         const struct v4l2_ctrl_ops *ops, u32 id, u8 max,
                         u64 mask, u8 def, const char * const *qmenu);
 
-/** v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
-  * @hdl:       The control handler.
-  * @ops:       The control ops.
-  * @id:        The control ID.
-  * @max:       The control's maximum value.
-  * @def:       The control's default value.
-  * @qmenu_int: The control's menu entries.
-  *
-  * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
-  * takes as an argument an array of integers determining the menu items.
-  *
-  * If @id refers to a non-integer-menu control, then this function will return NULL.
-  */
+/**
+ * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
+ * @hdl:        The control handler.
+ * @ops:        The control ops.
+ * @id: The control ID.
+ * @max:        The control's maximum value.
+ * @def:        The control's default value.
+ * @qmenu_int:  The control's menu entries.
+ *
+ * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
+ * takes as an argument an array of integers determining the menu items.
+ *
+ * If @id refers to a non-integer-menu control, then this function will return NULL.
+ */
 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
                         const struct v4l2_ctrl_ops *ops,
                         u32 id, u8 max, u8 def, const s64 *qmenu_int);
 
-/** v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
-  * @hdl:       The control handler.
-  * @ctrl:      The control to add.
-  *
-  * It will return NULL if it was unable to add the control reference.
-  * If the control already belonged to the handler, then it will do
-  * nothing and just return @ctrl.
-  */
+/**
+ * v4l2_ctrl_add_ctrl() - Add a control from another handler to this handler.
+ * @hdl:        The control handler.
+ * @ctrl:       The control to add.
+ *
+ * It will return NULL if it was unable to add the control reference.
+ * If the control already belonged to the handler, then it will do
+ * nothing and just return @ctrl.
+ */
 struct v4l2_ctrl *v4l2_ctrl_add_ctrl(struct v4l2_ctrl_handler *hdl,
                                           struct v4l2_ctrl *ctrl);
 
-/** v4l2_ctrl_add_handler() - Add all controls from handler @add to
-  * handler @hdl.
-  * @hdl:       The control handler.
-  * @add:       The control handler whose controls you want to add to
-  *             the @hdl control handler.
-  * @filter:    This function will filter which controls should be added.
-  *
-  * Does nothing if either of the two handlers is a NULL pointer.
-  * If @filter is NULL, then all controls are added. Otherwise only those
-  * controls for which @filter returns true will be added.
-  * In case of an error @hdl->error will be set to the error code (if it
-  * wasn't set already).
-  */
+/**
+ * v4l2_ctrl_add_handler() - Add all controls from handler @add to
+ * handler @hdl.
+ * @hdl:        The control handler.
+ * @add:        The control handler whose controls you want to add to
+ *              the @hdl control handler.
+ * @filter:     This function will filter which controls should be added.
+ *
+ * Does nothing if either of the two handlers is a NULL pointer.
+ * If @filter is NULL, then all controls are added. Otherwise only those
+ * controls for which @filter returns true will be added.
+ * In case of an error @hdl->error will be set to the error code (if it
+ * wasn't set already).
+ */
 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
                           struct v4l2_ctrl_handler *add,
                           bool (*filter)(const struct v4l2_ctrl *ctrl));
 
-/** v4l2_ctrl_radio_filter() - Standard filter for radio controls.
-  * @ctrl:      The control that is filtered.
-  *
-  * This will return true for any controls that are valid for radio device
-  * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
-  * transmitter class controls.
-  *
-  * This function is to be used with v4l2_ctrl_add_handler().
-  */
+/**
+ * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
+ * @ctrl:       The control that is filtered.
+ *
+ * This will return true for any controls that are valid for radio device
+ * nodes. Those are all of the V4L2_CID_AUDIO_* user controls and all FM
+ * transmitter class controls.
+ *
+ * This function is to be used with v4l2_ctrl_add_handler().
+ */
 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
 
-/** v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
-  * @ncontrols: The number of controls in this cluster.
-  * @controls:  The cluster control array of size @ncontrols.
-  */
+/**
+ * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
+ * @ncontrols:  The number of controls in this cluster.
+ * @controls:   The cluster control array of size @ncontrols.
+ */
 void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
 
 
-/** v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
-  * that cluster and set it up for autofoo/foo-type handling.
-  * @ncontrols: The number of controls in this cluster.
-  * @controls:  The cluster control array of size @ncontrols. The first control
-  *             must be the 'auto' control (e.g. autogain, autoexposure, etc.)
-  * @manual_val: The value for the first control in the cluster that equals the
-  *             manual setting.
-  * @set_volatile: If true, then all controls except the first auto control will
-  *             be volatile.
-  *
-  * Use for control groups where one control selects some automatic feature and
-  * the other controls are only active whenever the automatic feature is turned
-  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
-  * red and blue balance, etc.
-  *
-  * The behavior of such controls is as follows:
-  *
-  * When the autofoo control is set to automatic, then any manual controls
-  * are set to inactive and any reads will call g_volatile_ctrl (if the control
-  * was marked volatile).
-  *
-  * When the autofoo control is set to manual, then any manual controls will
-  * 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)
-  * if autofoo is in auto mode.
-  */
+/**
+ * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
+ * that cluster and set it up for autofoo/foo-type handling.
+ * @ncontrols:  The number of controls in this cluster.
+ * @controls:   The cluster control array of size @ncontrols. The first control
+ *              must be the 'auto' control (e.g. autogain, autoexposure, etc.)
+ * @manual_val: The value for the first control in the cluster that equals the
+ *              manual setting.
+ * @set_volatile: If true, then all controls except the first auto control will
+ *              be volatile.
+ *
+ * Use for control groups where one control selects some automatic feature and
+ * the other controls are only active whenever the automatic feature is turned
+ * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
+ * red and blue balance, etc.
+ *
+ * The behavior of such controls is as follows:
+ *
+ * When the autofoo control is set to automatic, then any manual controls
+ * are set to inactive and any reads will call g_volatile_ctrl (if the control
+ * was marked volatile).
+ *
+ * When the autofoo control is set to manual, then any manual controls will
+ * 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)
+ * if autofoo is in auto mode.
+ */
 void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
                         u8 manual_val, bool set_volatile);
 
 
-/** v4l2_ctrl_find() - Find a control with the given ID.
-  * @hdl:       The control handler.
-  * @id:        The control ID to find.
-  *
-  * If @hdl == NULL this will return NULL as well. Will lock the handler so
-  * do not use from inside &v4l2_ctrl_ops.
-  */
+/**
+ * v4l2_ctrl_find() - Find a control with the given ID.
+ * @hdl:        The control handler.
+ * @id: The control ID to find.
+ *
+ * If @hdl == NULL this will return NULL as well. Will lock the handler so
+ * do not use from inside &v4l2_ctrl_ops.
+ */
 struct v4l2_ctrl *v4l2_ctrl_find(struct v4l2_ctrl_handler *hdl, u32 id);
 
-/** v4l2_ctrl_activate() - Make the control active or inactive.
-  * @ctrl:      The control to (de)activate.
-  * @active:    True if the control should become active.
-  *
-  * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
-  * Does nothing if @ctrl == NULL.
-  * This will usually be called from within the s_ctrl op.
-  * The V4L2_EVENT_CTRL event will be generated afterwards.
-  *
-  * This function assumes that the control handler is locked.
-  */
+/**
+ * v4l2_ctrl_activate() - Make the control active or inactive.
+ * @ctrl:       The control to (de)activate.
+ * @active:     True if the control should become active.
+ *
+ * This sets or clears the V4L2_CTRL_FLAG_INACTIVE flag atomically.
+ * Does nothing if @ctrl == NULL.
+ * This will usually be called from within the s_ctrl op.
+ * The V4L2_EVENT_CTRL event will be generated afterwards.
+ *
+ * This function assumes that the control handler is locked.
+ */
 void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
 
-/** v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
-  * @ctrl:      The control to (de)activate.
-  * @grabbed:   True if the control should become grabbed.
-  *
-  * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
-  * Does nothing if @ctrl == NULL.
-  * The V4L2_EVENT_CTRL event will be generated afterwards.
-  * This will usually be called when starting or stopping streaming in the
-  * driver.
-  *
-  * This function assumes that the control handler is not locked and will
-  * take the lock itself.
-  */
+/**
+ * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
+ * @ctrl:       The control to (de)activate.
+ * @grabbed:    True if the control should become grabbed.
+ *
+ * This sets or clears the V4L2_CTRL_FLAG_GRABBED flag atomically.
+ * Does nothing if @ctrl == NULL.
+ * The V4L2_EVENT_CTRL event will be generated afterwards.
+ * This will usually be called when starting or stopping streaming in the
+ * driver.
+ *
+ * This function assumes that the control handler is not locked and will
+ * take the lock itself.
+ */
 void v4l2_ctrl_grab(struct v4l2_ctrl *ctrl, bool grabbed);
 
 
-/** __v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range() */
+/**
+ *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
+ *
+ * @ctrl:       The control to update.
+ * @min:        The control's minimum value.
+ * @max:        The control's maximum value.
+ * @step:       The control's step value
+ * @def:        The control's default value.
+ *
+ * Update the range of a control on the fly. This works for control types
+ * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
+ * @step value is interpreted as a menu_skip_mask.
+ *
+ * An error is returned if one of the range arguments is invalid for this
+ * control type.
+ *
+ * This function assumes that the control handler is not locked and will
+ * take the lock itself.
+ */
 int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
                              s64 min, s64 max, u64 step, s64 def);
 
-/** v4l2_ctrl_modify_range() - Update the range of a control.
-  * @ctrl:      The control to update.
-  * @min:       The control's minimum value.
-  * @max:       The control's maximum value.
-  * @step:      The control's step value
-  * @def:       The control's default value.
-  *
-  * Update the range of a control on the fly. This works for control types
-  * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
-  * @step value is interpreted as a menu_skip_mask.
-  *
-  * An error is returned if one of the range arguments is invalid for this
-  * control type.
-  *
-  * This function assumes that the control handler is not locked and will
-  * take the lock itself.
-  */
+/**
+ * v4l2_ctrl_modify_range() - Update the range of a control.
+ * @ctrl:       The control to update.
+ * @min:        The control's minimum value.
+ * @max:        The control's maximum value.
+ * @step:       The control's step value
+ * @def:        The control's default value.
+ *
+ * Update the range of a control on the fly. This works for control types
+ * INTEGER, BOOLEAN, MENU, INTEGER MENU and BITMASK. For menu controls the
+ * @step value is interpreted as a menu_skip_mask.
+ *
+ * An error is returned if one of the range arguments is invalid for this
+ * control type.
+ *
+ * This function assumes that the control handler is not locked and will
+ * take the lock itself.
+ */
 static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
                                          s64 min, s64 max, u64 step, s64 def)
 {
@@ -656,21 +711,23 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
         return rval;
 }
 
-/** v4l2_ctrl_notify() - Function to set a notify callback for a control.
-  * @ctrl:      The control.
-  * @notify:    The callback function.
-  * @priv:      The callback private handle, passed as argument to the callback.
-  *
-  * This function sets a callback function for the control. If @ctrl is NULL,
-  * then it will do nothing. If @notify is NULL, then the notify callback will
-  * be removed.
-  *
-  * There can be only one notify. If another already exists, then a WARN_ON
-  * will be issued and the function will do nothing.
-  */
+/**
+ * v4l2_ctrl_notify() - Function to set a notify callback for a control.
+ * @ctrl:       The control.
+ * @notify:     The callback function.
+ * @priv:       The callback private handle, passed as argument to the callback.
+ *
+ * This function sets a callback function for the control. If @ctrl is NULL,
+ * then it will do nothing. If @notify is NULL, then the notify callback will
+ * be removed.
+ *
+ * There can be only one notify. If another already exists, then a WARN_ON
+ * will be issued and the function will do nothing.
+ */
 void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv);
 
-/** v4l2_ctrl_get_name() - Get the name of the control
+/**
+ * v4l2_ctrl_get_name() - Get the name of the control
  * @id:         The control ID.
  *
  * This function returns the name of the given control ID or NULL if it isn't
@@ -678,7 +735,8 @@ void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void
  */
 const char *v4l2_ctrl_get_name(u32 id);
 
-/** v4l2_ctrl_get_menu() - Get the menu string array of the control
+/**
+ * v4l2_ctrl_get_menu() - Get the menu string array of the control
  * @id:         The control ID.
  *
  * This function returns the NULL-terminated menu string array name of the
@@ -686,7 +744,8 @@ const char *v4l2_ctrl_get_name(u32 id);
  */
 const char * const *v4l2_ctrl_get_menu(u32 id);
 
-/** v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
+/**
+ * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
  * @id:         The control ID.
  * @len:        The size of the integer array.
  *
@@ -695,29 +754,41 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
  */
 const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
 
-/** v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
-  * @ctrl:      The control.
-  *
-  * This returns the control's value safely by going through the control
-  * framework. This function will lock the control's handler, so it cannot be
-  * used from within the &v4l2_ctrl_ops functions.
-  *
-  * This function is for integer type controls only.
-  */
+/**
+ * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
+ * @ctrl:       The control.
+ *
+ * This returns the control's value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for integer type controls only.
+ */
 s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
 
-/** __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl(). */
+/**
+ * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
+ * @ctrl:       The control.
+ * @val:        The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for integer type controls only.
+ */
 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
+
 /** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
-  * @ctrl:      The control.
-  * @val:       The new value.
-  *
-  * This set the control's new value safely by going through the control
-  * framework. This function will lock the control's handler, so it cannot be
-  * used from within the &v4l2_ctrl_ops functions.
-  *
-  * This function is for integer type controls only.
-  */
+ * @ctrl:       The control.
+ * @val:        The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for integer type controls only.
+ */
 static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
 {
         int rval;
@@ -729,30 +800,45 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
         return rval;
 }
 
-/** v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value from within a driver.
-  * @ctrl:      The control.
-  *
-  * This returns the control's value safely by going through the control
-  * framework. This function will lock the control's handler, so it cannot be
-  * used from within the &v4l2_ctrl_ops functions.
-  *
-  * This function is for 64-bit integer type controls only.
-  */
+/**
+ * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
+ *      from within a driver.
+ * @ctrl:       The control.
+ *
+ * This returns the control's value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for 64-bit integer type controls only.
+ */
 s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
 
-/** __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64(). */
+/**
+ * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
+ *
+ * @ctrl:       The control.
+ * @val:        The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for 64-bit integer type controls only.
+ */
 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
 
-/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value from within a driver.
-  * @ctrl:      The control.
-  * @val:       The new value.
-  *
-  * This set the control's new value safely by going through the control
-  * framework. This function will lock the control's handler, so it cannot be
-  * used from within the &v4l2_ctrl_ops functions.
-  *
-  * This function is for 64-bit integer type controls only.
-  */
+/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
+ *      from within a driver.
+ *
+ * @ctrl:       The control.
+ * @val:        The new value.
+ *
+ * This set the control's new value safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for 64-bit integer type controls only.
+ */
 static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
 {
         int rval;
@@ -764,19 +850,31 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
         return rval;
 }
 
-/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string(). */
+/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
+ *
+ * @ctrl:       The control.
+ * @s:          The new string.
+ *
+ * This set the control's new string safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for string type controls only.
+ */
 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
 
-/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value from within a driver.
-  * @ctrl:      The control.
-  * @s:         The new string.
-  *
-  * This set the control's new string safely by going through the control
-  * framework. This function will lock the control's handler, so it cannot be
-  * used from within the &v4l2_ctrl_ops functions.
-  *
-  * This function is for string type controls only.
-  */
+/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
+ *       from within a driver.
+ *
+ * @ctrl:       The control.
+ * @s:          The new string.
+ *
+ * This set the control's new string safely by going through the control
+ * framework. This function will lock the control's handler, so it cannot be
+ * used from within the &v4l2_ctrl_ops functions.
+ *
+ * This function is for string type controls only.
+ */
 static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
 {
         int rval;
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index eecd3102a618..b6130b50a0f1 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -23,11 +23,14 @@
 
 #include <linux/videodev2.h>
 
-/** v4l2_dv_timings_presets: list of all dv_timings presets.
+/**
+ * v4l2_dv_timings_presets: list of all dv_timings presets.
  */
 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
 
-/** v4l2_check_dv_timings_fnc - timings check callback
+/**
+ * v4l2_check_dv_timings_fnc - timings check callback
+ *
  * @t: the v4l2_dv_timings struct.
  * @handle: a handle from the driver.
  *
@@ -35,86 +38,101 @@ extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
  */
 typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
 
-/** v4l2_valid_dv_timings() - are these timings valid?
-  * @t:   the v4l2_dv_timings struct.
-  * @cap: the v4l2_dv_timings_cap capabilities.
-  * @fnc: callback to check if this timing is OK. May be NULL.
-  * @fnc_handle: a handle that is passed on to @fnc.
-  *
-  * Returns true if the given dv_timings struct is supported by the
-  * hardware capabilities and the callback function (if non-NULL), returns
-  * false otherwise.
-  */
+/**
+ * v4l2_valid_dv_timings() - are these timings valid?
+ *
+ * @t:    the v4l2_dv_timings struct.
+ * @cap: the v4l2_dv_timings_cap capabilities.
+ * @fnc: callback to check if this timing is OK. May be NULL.
+ * @fnc_handle: a handle that is passed on to @fnc.
+ *
+ * Returns true if the given dv_timings struct is supported by the
+ * hardware capabilities and the callback function (if non-NULL), returns
+ * false otherwise.
+ */
 bool v4l2_valid_dv_timings(const struct v4l2_dv_timings *t,
                            const struct v4l2_dv_timings_cap *cap,
                            v4l2_check_dv_timings_fnc fnc,
                            void *fnc_handle);
 
-/** v4l2_enum_dv_timings_cap() - Helper function to enumerate possible DV timings based on capabilities
-  * @t:   the v4l2_enum_dv_timings struct.
-  * @cap: the v4l2_dv_timings_cap capabilities.
-  * @fnc: callback to check if this timing is OK. May be NULL.
-  * @fnc_handle: a handle that is passed on to @fnc.
-  *
-  * This enumerates dv_timings using the full list of possible CEA-861 and DMT
-  * timings, filtering out any timings that are not supported based on the
-  * hardware capabilities and the callback function (if non-NULL).
-  *
-  * If a valid timing for the given index is found, it will fill in @t and
-  * return 0, otherwise it returns -EINVAL.
-  */
+/**
+ * v4l2_enum_dv_timings_cap() - Helper function to enumerate possible DV
+ *       timings based on capabilities
+ *
+ * @t:    the v4l2_enum_dv_timings struct.
+ * @cap: the v4l2_dv_timings_cap capabilities.
+ * @fnc: callback to check if this timing is OK. May be NULL.
+ * @fnc_handle: a handle that is passed on to @fnc.
+ *
+ * This enumerates dv_timings using the full list of possible CEA-861 and DMT
+ * timings, filtering out any timings that are not supported based on the
+ * hardware capabilities and the callback function (if non-NULL).
+ *
+ * If a valid timing for the given index is found, it will fill in @t and
+ * return 0, otherwise it returns -EINVAL.
+ */
 int v4l2_enum_dv_timings_cap(struct v4l2_enum_dv_timings *t,
                              const struct v4l2_dv_timings_cap *cap,
                              v4l2_check_dv_timings_fnc fnc,
                              void *fnc_handle);
 
-/** v4l2_find_dv_timings_cap() - Find the closest timings struct
-  * @t:   the v4l2_enum_dv_timings struct.
-  * @cap: the v4l2_dv_timings_cap capabilities.
-  * @pclock_delta: maximum delta between t->pixelclock and the timing struct
-  *             under consideration.
-  * @fnc: callback to check if a given timings struct is OK. May be NULL.
-  * @fnc_handle: a handle that is passed on to @fnc.
-  *
-  * This function tries to map the given timings to an entry in the
-  * full list of possible CEA-861 and DMT timings, filtering out any timings
-  * that are not supported based on the hardware capabilities and the callback
-  * function (if non-NULL).
-  *
-  * On success it will fill in @t with the found timings and it returns true.
-  * On failure it will return false.
-  */
+/**
+ * v4l2_find_dv_timings_cap() - Find the closest timings struct
+ *
+ * @t:    the v4l2_enum_dv_timings struct.
+ * @cap: the v4l2_dv_timings_cap capabilities.
+ * @pclock_delta: maximum delta between t->pixelclock and the timing struct
+ *              under consideration.
+ * @fnc: callback to check if a given timings struct is OK. May be NULL.
+ * @fnc_handle: a handle that is passed on to @fnc.
+ *
+ * This function tries to map the given timings to an entry in the
+ * full list of possible CEA-861 and DMT timings, filtering out any timings
+ * that are not supported based on the hardware capabilities and the callback
+ * function (if non-NULL).
+ *
+ * On success it will fill in @t with the found timings and it returns true.
+ * On failure it will return false.
+ */
 bool v4l2_find_dv_timings_cap(struct v4l2_dv_timings *t,
                               const struct v4l2_dv_timings_cap *cap,
                               unsigned pclock_delta,
                               v4l2_check_dv_timings_fnc fnc,
                               void *fnc_handle);
 
-/** v4l2_match_dv_timings() - do two timings match?
-  * @measured:    the measured timings data.
-  * @standard:    the timings according to the standard.
-  * @pclock_delta: maximum delta in Hz between standard->pixelclock and
-  *             the measured timings.
-  *
-  * Returns true if the two timings match, returns false otherwise.
-  */
+/**
+ * v4l2_match_dv_timings() - do two timings match?
+ *
+ * @measured:     the measured timings data.
+ * @standard:     the timings according to the standard.
+ * @pclock_delta: maximum delta in Hz between standard->pixelclock and
+ *              the measured timings.
+ *
+ * Returns true if the two timings match, returns false otherwise.
+ */
 bool v4l2_match_dv_timings(const struct v4l2_dv_timings *measured,
                            const struct v4l2_dv_timings *standard,
                            unsigned pclock_delta);
 
-/** v4l2_print_dv_timings() - log the contents of a dv_timings struct
-  * @dev_prefix:device prefix for each log line.
-  * @prefix:    additional prefix for each log line, may be NULL.
-  * @t:         the timings data.
-  * @detailed:  if true, give a detailed log.
-  */
+/**
+ * v4l2_print_dv_timings() - log the contents of a dv_timings struct
+ * @dev_prefix:device prefix for each log line.
+ * @prefix:     additional prefix for each log line, may be NULL.
+ * @t:          the timings data.
+ * @detailed:   if true, give a detailed log.
+ */
 void v4l2_print_dv_timings(const char *dev_prefix, const char *prefix,
                            const struct v4l2_dv_timings *t, bool detailed);
 
-/** v4l2_detect_cvt - detect if the given timings follow the CVT standard
+/**
+ * v4l2_detect_cvt - detect if the given timings follow the CVT standard
+ *
  * @frame_height - the total height of the frame (including blanking) in lines.
  * @hfreq - the horizontal frequency in Hz.
  * @vsync - the height of the vertical sync in lines.
+ * @active_width - active width of image (does not include blanking). This
+ * information is needed only in case of version 2 of reduced blanking.
+ * In other cases, this parameter does not have any effect on timings.
  * @polarities - the horizontal and vertical polarities (same as struct
  *              v4l2_bt_timings polarities).
  * @interlaced - if this flag is true, it indicates interlaced format
@@ -125,9 +143,12 @@ void v4l2_print_dv_timings(const char *dev_prefix, const char *prefix,
  * in with the found CVT timings.
  */
 bool v4l2_detect_cvt(unsigned frame_height, unsigned hfreq, unsigned vsync,
-                u32 polarities, bool interlaced, struct v4l2_dv_timings *fmt);
+                unsigned active_width, u32 polarities, bool interlaced,
+                struct v4l2_dv_timings *fmt);
 
-/** v4l2_detect_gtf - detect if the given timings follow the GTF standard
+/**
+ * v4l2_detect_gtf - detect if the given timings follow the GTF standard
+ *
  * @frame_height - the total height of the frame (including blanking) in lines.
  * @hfreq - the horizontal frequency in Hz.
  * @vsync - the height of the vertical sync in lines.
@@ -149,8 +170,10 @@ bool v4l2_detect_gtf(unsigned frame_height, unsigned hfreq, unsigned vsync,
                 u32 polarities, bool interlaced, struct v4l2_fract aspect,
                 struct v4l2_dv_timings *fmt);
 
-/** v4l2_calc_aspect_ratio - calculate the aspect ratio based on bytes
+/**
+ * v4l2_calc_aspect_ratio - calculate the aspect ratio based on bytes
  *      0x15 and 0x16 from the EDID.
+ *
  * @hor_landscape - byte 0x15 from the EDID.
  * @vert_portrait - byte 0x16 from the EDID.
  *
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 1ab9045e52e3..9792f906423b 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -68,10 +68,11 @@ struct v4l2_subdev;
 struct v4l2_subscribed_event;
 struct video_device;
 
-/** struct v4l2_kevent - Internal kernel event struct.
-  * @list:      List node for the v4l2_fh->available list.
-  * @sev:       Pointer to parent v4l2_subscribed_event.
-  * @event:     The event itself.
+/**
+ * struct v4l2_kevent - Internal kernel event struct.
+ * @list:       List node for the v4l2_fh->available list.
+ * @sev:        Pointer to parent v4l2_subscribed_event.
+ * @event:      The event itself.
   */
 struct v4l2_kevent {
         struct list_head        list;
@@ -80,11 +81,12 @@ struct v4l2_kevent {
 };
 
 /** struct v4l2_subscribed_event_ops - Subscribed event operations.
-  * @add:       Optional callback, called when a new listener is added
-  * @del:       Optional callback, called when a listener stops listening
-  * @replace:   Optional callback that can replace event 'old' with event 'new'.
-  * @merge:     Optional callback that can merge event 'old' into event 'new'.
-  */
+ *
+ * @add:        Optional callback, called when a new listener is added
+ * @del:        Optional callback, called when a listener stops listening
+ * @replace:    Optional callback that can replace event 'old' with event 'new'.
+ * @merge:      Optional callback that can merge event 'old' into event 'new'.
+ */
 struct v4l2_subscribed_event_ops {
         int  (*add)(struct v4l2_subscribed_event *sev, unsigned elems);
         void (*del)(struct v4l2_subscribed_event *sev);
@@ -92,19 +94,20 @@ struct v4l2_subscribed_event_ops {
         void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
 };
 
-/** struct v4l2_subscribed_event - Internal struct representing a subscribed event.
-  * @list:      List node for the v4l2_fh->subscribed list.
-  * @type:      Event type.
-  * @id:        Associated object ID (e.g. control ID). 0 if there isn't any.
-  * @flags:     Copy of v4l2_event_subscription->flags.
-  * @fh:        Filehandle that subscribed to this event.
-  * @node:      List node that hooks into the object's event list (if there is one).
-  * @ops:       v4l2_subscribed_event_ops
-  * @elems:     The number of elements in the events array.
-  * @first:     The index of the events containing the oldest available event.
-  * @in_use:    The number of queued events.
-  * @events:    An array of @elems events.
-  */
+/**
+ * struct v4l2_subscribed_event - Internal struct representing a subscribed event.
+ * @list:       List node for the v4l2_fh->subscribed list.
+ * @type:       Event type.
+ * @id: Associated object ID (e.g. control ID). 0 if there isn't any.
+ * @flags:      Copy of v4l2_event_subscription->flags.
+ * @fh: Filehandle that subscribed to this event.
+ * @node:       List node that hooks into the object's event list (if there is one).
+ * @ops:        v4l2_subscribed_event_ops
+ * @elems:      The number of elements in the events array.
+ * @first:      The index of the events containing the oldest available event.
+ * @in_use:     The number of queued events.
+ * @events:     An array of @elems events.
+ */
 struct v4l2_subscribed_event {
         struct list_head        list;
         u32                     type;
diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h
index 098236c083b8..3d184ab52274 100644
--- a/include/media/v4l2-flash-led-class.h
+++ b/include/media/v4l2-flash-led-class.h
@@ -48,13 +48,13 @@ struct v4l2_flash_ops {
 /**
  * struct v4l2_flash_config - V4L2 Flash sub-device initialization data
  * @dev_name:                   the name of the media entity,
-                                unique in the system
+ *                              unique in the system
  * @torch_intensity:            constraints for the LED in torch mode
  * @indicator_intensity:        constraints for the indicator LED
  * @flash_faults:               bitmask of flash faults that the LED flash class
-                                device can report; corresponding LED_FAULT* bit
-                                definitions are available in the header file
-                                <linux/led-class-flash.h>
+ *                              device can report; corresponding LED_FAULT* bit
+ *                              definitions are available in the header file
+ *                              <linux/led-class-flash.h>
  * @has_external_strobe:        external strobe capability
  */
 struct v4l2_flash_config {
@@ -105,7 +105,7 @@ static inline struct v4l2_flash *v4l2_ctrl_to_v4l2_flash(struct v4l2_ctrl *c)
  * @fled_cdev:  LED flash class device to wrap
  * @iled_cdev:  LED flash class device representing indicator LED associated
  *              with fled_cdev, may be NULL
- * @flash_ops:  V4L2 Flash device ops
+ * @ops:        V4L2 Flash device ops
  * @config:     initialization data for V4L2 Flash sub-device
  *
  * Create V4L2 Flash sub-device wrapping given LED subsystem device.
@@ -123,7 +123,7 @@ struct v4l2_flash *v4l2_flash_init(
 
 /**
  * v4l2_flash_release - release V4L2 Flash sub-device
- * @flash: the V4L2 Flash sub-device to release
+ * @v4l2_flash: the V4L2 Flash sub-device to release
  *
  * Release V4L2 Flash sub-device.
  */
diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index 73069e4c2796..34cc99e093ef 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -65,7 +65,7 @@
                                          V4L2_MBUS_CSI2_CHANNEL_2 | V4L2_MBUS_CSI2_CHANNEL_3)
 
 /**
- * v4l2_mbus_type - media bus type
+ * enum v4l2_mbus_type - media bus type
  * @V4L2_MBUS_PARALLEL: parallel interface with hsync and vsync
  * @V4L2_MBUS_BT656:    parallel interface with embedded synchronisation, can
  *                      also be used for BT.1120
@@ -78,7 +78,7 @@ enum v4l2_mbus_type {
 };
 
 /**
- * v4l2_mbus_config - media bus configuration
+ * struct v4l2_mbus_config - media bus configuration
  * @type:       in: interface type
  * @flags:      in / out: configuration flags, depending on @type
  */
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
index 3bbd96da25c9..8849aaba6aa5 100644
--- a/include/media/v4l2-mem2mem.h
+++ b/include/media/v4l2-mem2mem.h
@@ -40,6 +40,10 @@
  *              v4l2_m2m_job_finish() (as if the transaction ended normally).
  *              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.
+ * @unlock:     optional. Define a driver's own unlock callback, instead of
+ *              using m2m_ctx->q_lock.
  */
 struct v4l2_m2m_ops {
         void (*device_run)(void *priv);
@@ -161,6 +165,8 @@ void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, struct vb2_buffer *vb);
 /**
  * v4l2_m2m_num_src_bufs_ready() - return the number of source buffers ready for
  * use
+ *
+ * @m2m_ctx: pointer to struct v4l2_m2m_ctx
  */
 static inline
 unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -171,6 +177,8 @@ 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
  * ready for use
+ *
+ * @m2m_ctx: pointer to struct v4l2_m2m_ctx
  */
 static inline
 unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
@@ -183,6 +191,8 @@ 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
  */
 static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -192,6 +202,8 @@ 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
  */
 static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -200,6 +212,8 @@ 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
  */
 static inline
 struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -209,6 +223,8 @@ 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
  */
 static inline
 struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx)
@@ -221,6 +237,8 @@ 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
  */
 static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx)
 {
@@ -230,6 +248,8 @@ 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
  */
 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 4e18318eb425..b273cf9ac047 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -44,6 +44,7 @@
 
 struct v4l2_device;
 struct v4l2_ctrl_handler;
+struct v4l2_event;
 struct v4l2_event_subscription;
 struct v4l2_fh;
 struct v4l2_subdev;
@@ -117,34 +118,67 @@ struct v4l2_subdev_io_pin_config {
         u8 strength;    /* Pin drive strength */
 };
 
-/*
-   s_io_pin_config: configure one or more chip I/O pins for chips that
-        multiplex different internal signal pads out to IO pins.  This function
-        takes a pointer to an array of 'n' pin configuration entries, one for
-        each pin being configured.  This function could be called at times
-        other than just subdevice initialization.
-
-   init: initialize the sensor registers to some sort of reasonable default
-        values. Do not use for new drivers and should be removed in existing
-        drivers.
-
-   load_fw: load firmware.
-
-   reset: generic reset command. The argument selects which subsystems to
-        reset. Passing 0 will always reset the whole chip. Do not use for new
-        drivers without discussing this first on the linux-media mailinglist.
-        There should be no reason normally to reset a device.
-
-   s_gpio: set GPIO pins. Very simple right now, might need to be extended with
-        a direction argument if needed.
-
-   s_power: puts subdevice in power saving mode (on == 0) or normal operation
-        mode (on == 1).
-
-   interrupt_service_routine: Called by the bridge chip's interrupt service
-        handler, when an interrupt status has be raised due to this subdev,
-        so that this subdev can handle the details.  It may schedule work to be
-        performed later.  It must not sleep.  *Called from an IRQ context*.
+/**
+ * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
+ *
+ * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code.
+ *
+ * @s_io_pin_config: configure one or more chip I/O pins for chips that
+ *      multiplex different internal signal pads out to IO pins.  This function
+ *      takes a pointer to an array of 'n' pin configuration entries, one for
+ *      each pin being configured.  This function could be called at times
+ *      other than just subdevice initialization.
+ *
+ * @init: initialize the sensor registers to some sort of reasonable default
+ *      values. Do not use for new drivers and should be removed in existing
+ *      drivers.
+ *
+ * @load_fw: load firmware.
+ *
+ * @reset: generic reset command. The argument selects which subsystems to
+ *      reset. Passing 0 will always reset the whole chip. Do not use for new
+ *      drivers without discussing this first on the linux-media mailinglist.
+ *      There should be no reason normally to reset a device.
+ *
+ * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with
+ *      a direction argument if needed.
+ *
+ * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code.
+ *
+ * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code.
+ *
+ * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code.
+ *
+ * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code.
+ *
+ * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code.
+ *
+ * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code.
+ *
+ * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code.
+ *
+ * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core.
+ *         used to provide support for private ioctls used on the driver.
+ *
+ * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
+ *                  in order to fix data passed from/to userspace.
+ *
+ * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ *
+ * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ *
+ * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
+ *      mode (on == 1).
+ *
+ * @interrupt_service_routine: Called by the bridge chip's interrupt service
+ *      handler, when an interrupt status has be raised due to this subdev,
+ *      so that this subdev can handle the details.  It may schedule work to be
+ *      performed later.  It must not sleep.  *Called from an IRQ context*.
+ *
+ * @subscribe_event: used by the drivers to request the control framework that
+ *                   for it to be warned when the value of a control changes.
+ *
+ * @unsubscribe_event: remove event subscription from the control framework.
  */
 struct v4l2_subdev_core_ops {
         int (*log_status)(struct v4l2_subdev *sd);
@@ -179,18 +213,32 @@ struct v4l2_subdev_core_ops {
                                  struct v4l2_event_subscription *sub);
 };
 
-/* s_radio: v4l device was opened in radio mode.
-
-   g_frequency: freq->type must be filled in. Normally done by video_ioctl2
-        or the bridge driver.
-
-   g_tuner:
-   s_tuner: vt->type must be filled in. Normally done by video_ioctl2 or the
-        bridge driver.
-
-   s_type_addr: sets tuner type and its I2C addr.
-
-   s_config: sets tda9887 specific stuff, like port1, port2 and qss
+/**
+ * struct s_radio - Callbacks used when v4l device was opened in radio mode.
+ *
+ * @s_radio: callback for VIDIOC_S_RADIO ioctl handler code.
+ *
+ * @s_frequency: callback for VIDIOC_S_FREQUENCY ioctl handler code.
+ *
+ * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code.
+ *               freq->type must be filled in. Normally done by video_ioctl2
+ *              or the bridge driver.
+ *
+ * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
+ *
+ * @g_tuner: callback for VIDIOC_G_TUNER ioctl handler code.
+ *
+ * @s_tuner: callback for VIDIOC_S_TUNER ioctl handler code. vt->type must be
+ *           filled in. Normally done by video_ioctl2 or the
+ *      bridge driver.
+ *
+ * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code.
+ *
+ * @s_modulator: callback for VIDIOC_S_MODULATOR ioctl handler code.
+ *
+ * @s_type_addr: sets tuner type and its I2C addr.
+ *
+ * @s_config: sets tda9887 specific stuff, like port1, port2 and qss
  */
 struct v4l2_subdev_tuner_ops {
         int (*s_radio)(struct v4l2_subdev *sd);
@@ -205,25 +253,31 @@ struct v4l2_subdev_tuner_ops {
         int (*s_config)(struct v4l2_subdev *sd, const struct v4l2_priv_tun_config *config);
 };
 
-/* s_clock_freq: set the frequency (in Hz) of the audio clock output.
-        Used to slave an audio processor to the video decoder, ensuring that
-        audio and video remain synchronized. Usual values for the frequency
-        are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
-        -EINVAL is returned.
-
-   s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
-        way to select I2S clock used by driving digital audio streams at some
-        board designs. Usual values for the frequency are 1024000 and 2048000.
-        If the frequency is not supported, then -EINVAL is returned.
-
-   s_routing: used to define the input and/or output pins of an audio chip,
-        and any additional configuration data.
-        Never attempt to use user-level input IDs (e.g. Composite, S-Video,
-        Tuner) at this level. An i2c device shouldn't know about whether an
-        input pin is connected to a Composite connector, become on another
-        board or platform it might be connected to something else entirely.
-        The calling driver is responsible for mapping a user-level input to
-        the right pins on the i2c device.
+/**
+ * struct v4l2_subdev_audio_ops - Callbacks used for audio-related settings
+ *
+ * @s_clock_freq: set the frequency (in Hz) of the audio clock output.
+ *      Used to slave an audio processor to the video decoder, ensuring that
+ *      audio and video remain synchronized. Usual values for the frequency
+ *      are 48000, 44100 or 32000 Hz. If the frequency is not supported, then
+ *      -EINVAL is returned.
+ *
+ * @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
+ *      way to select I2S clock used by driving digital audio streams at some
+ *      board designs. Usual values for the frequency are 1024000 and 2048000.
+ *      If the frequency is not supported, then -EINVAL is returned.
+ *
+ * @s_routing: used to define the input and/or output pins of an audio chip,
+ *      and any additional configuration data.
+ *      Never attempt to use user-level input IDs (e.g. Composite, S-Video,
+ *      Tuner) at this level. An i2c device shouldn't know about whether an
+ *      input pin is connected to a Composite connector, become on another
+ *      board or platform it might be connected to something else entirely.
+ *      The calling driver is responsible for mapping a user-level input to
+ *      the right pins on the i2c device.
+ *
+ * @s_stream: used to notify the audio code that stream will start or has
+ *      stopped.
  */
 struct v4l2_subdev_audio_ops {
         int (*s_clock_freq)(struct v4l2_subdev *sd, u32 freq);
@@ -242,6 +296,7 @@ struct v4l2_subdev_audio_ops {
 
 /**
  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
+ *
  * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags
  * @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
  * @length: number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB
@@ -265,45 +320,73 @@ struct v4l2_mbus_frame_desc {
         unsigned short num_entries;
 };
 
-/*
-   s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
-        video input devices.
-
-   g_std_output: get current standard for video OUTPUT devices. This is ignored
-        by video input devices.
-
-   g_tvnorms: get v4l2_std_id with all standards supported by the video
-        CAPTURE device. This is ignored by video output devices.
-
-   g_tvnorms_output: get v4l2_std_id with all standards supported by the video
-        OUTPUT device. This is ignored by video capture devices.
-
-   s_crystal_freq: sets the frequency of the crystal used to generate the
-        clocks in Hz. An extra flags field allows device specific configuration
-        regarding clock frequency dividers, etc. If not used, then set flags
-        to 0. If the frequency is not supported, then -EINVAL is returned.
-
-   g_input_status: get input status. Same as the status field in the v4l2_input
-        struct.
-
-   s_routing: see s_routing in audio_ops, except this version is for video
-        devices.
-
-   s_dv_timings(): Set custom dv timings in the sub device. This is used
-        when sub device is capable of setting detailed timing information
-        in the hardware to generate/detect the video signal.
-
-   g_dv_timings(): Get custom dv timings in the sub device.
-
-   g_mbus_config: get supported mediabus configurations
-
-   s_mbus_config: set a certain mediabus configuration. This operation is added
-        for compatibility with soc-camera drivers and should not be used by new
-        software.
-
-   s_rx_buffer: set a host allocated memory buffer for the subdev. The subdev
-        can adjust @size to a lower value and must not write more data to the
-        buffer starting at @data than the original value of @size.
+/**
+ * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
+ *                                in video mode.
+ *
+ * @s_routing: see s_routing in audio_ops, except this version is for video
+ *      devices.
+ *
+ * @s_crystal_freq: sets the frequency of the crystal used to generate the
+ *      clocks in Hz. An extra flags field allows device specific configuration
+ *      regarding clock frequency dividers, etc. If not used, then set flags
+ *      to 0. If the frequency is not supported, then -EINVAL is returned.
+ *
+ * @g_std: callback for VIDIOC_G_STD ioctl handler code.
+ *
+ * @s_std: callback for VIDIOC_S_STD ioctl handler code.
+ *
+ * @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
+ *      video input devices.
+ *
+ * @g_std_output: get current standard for video OUTPUT devices. This is ignored
+ *      by video input devices.
+ *
+ * @querystd: callback for VIDIOC_QUERYSTD ioctl handler code.
+ *
+ * @g_tvnorms: get v4l2_std_id with all standards supported by the video
+ *      CAPTURE device. This is ignored by video output devices.
+ *
+ * @g_tvnorms_output: get v4l2_std_id with all standards supported by the video
+ *      OUTPUT device. This is ignored by video capture devices.
+ *
+ * @g_input_status: get input status. Same as the status field in the v4l2_input
+ *      struct.
+ *
+ * @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_parm: callback for VIDIOC_G_PARM ioctl handler code.
+ *
+ * @s_parm: callback for VIDIOC_S_PARM ioctl handler code.
+ *
+ * @g_frame_interval: callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code.
+ *
+ * @s_frame_interval: callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code.
+ *
+ * @s_dv_timings: Set custom dv timings in the sub device. This is used
+ *      when sub device is capable of setting detailed timing information
+ *      in the hardware to generate/detect the video signal.
+ *
+ * @g_dv_timings: Get custom dv timings in the sub device.
+ *
+ * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
+ *
+ * @g_mbus_config: get supported mediabus configurations
+ *
+ * @s_mbus_config: set a certain mediabus configuration. This operation is added
+ *      for compatibility with soc-camera drivers and should not be used by new
+ *      software.
+ *
+ * @s_rx_buffer: set a host allocated memory buffer for the subdev. The subdev
+ *      can adjust @size to a lower value and must not write more data to the
+ *      buffer starting at @data than the original value of @size.
  */
 struct v4l2_subdev_video_ops {
         int (*s_routing)(struct v4l2_subdev *sd, u32 input, u32 output, u32 config);
@@ -340,34 +423,39 @@ struct v4l2_subdev_video_ops {
                            unsigned int *size);
 };
 
-/*
-   decode_vbi_line: video decoders that support sliced VBI need to implement
-        this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
-        start of the VBI data that was generated by the decoder. The driver
-        then parses the sliced VBI data and sets the other fields in the
-        struct accordingly. The pointer p is updated to point to the start of
-        the payload which can be copied verbatim into the data field of the
-        v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
-        type field is set to 0 on return.
-
-   s_vbi_data: used to generate VBI signals on a video signal.
-        v4l2_sliced_vbi_data is filled with the data packets that should be
-        output. Note that if you set the line field to 0, then that VBI signal
-        is disabled. If no valid VBI data was found, then the type field is
-        set to 0 on return.
-
-   g_vbi_data: used to obtain the sliced VBI packet from a readback register.
-        Not all video decoders support this. If no data is available because
-        the readback register contains invalid or erroneous data -EIO is
-        returned. Note that you must fill in the 'id' member and the 'field'
-        member (to determine whether CC data from the first or second field
-        should be obtained).
-
-   s_raw_fmt: setup the video encoder/decoder for raw VBI.
-
-   g_sliced_fmt: retrieve the current sliced VBI settings.
-
-   s_sliced_fmt: setup the sliced VBI settings.
+/**
+ * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
+ *                                in video mode via the vbi device node.
+ *
+ *  @decode_vbi_line: video decoders that support sliced VBI need to implement
+ *      this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
+ *      start of the VBI data that was generated by the decoder. The driver
+ *      then parses the sliced VBI data and sets the other fields in the
+ *      struct accordingly. The pointer p is updated to point to the start of
+ *      the payload which can be copied verbatim into the data field of the
+ *      v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
+ *      type field is set to 0 on return.
+ *
+ * @s_vbi_data: used to generate VBI signals on a video signal.
+ *      v4l2_sliced_vbi_data is filled with the data packets that should be
+ *      output. Note that if you set the line field to 0, then that VBI signal
+ *      is disabled. If no valid VBI data was found, then the type field is
+ *      set to 0 on return.
+ *
+ * @g_vbi_data: used to obtain the sliced VBI packet from a readback register.
+ *      Not all video decoders support this. If no data is available because
+ *      the readback register contains invalid or erroneous data -EIO is
+ *      returned. Note that you must fill in the 'id' member and the 'field'
+ *      member (to determine whether CC data from the first or second field
+ *      should be obtained).
+ *
+ * @g_sliced_vbi_cap: callback for VIDIOC_SLICED_VBI_CAP ioctl handler code.
+ *
+ * @s_raw_fmt: setup the video encoder/decoder for raw VBI.
+ *
+ * @g_sliced_fmt: retrieve the current sliced VBI settings.
+ *
+ * @s_sliced_fmt: setup the sliced VBI settings.
  */
 struct v4l2_subdev_vbi_ops {
         int (*decode_vbi_line)(struct v4l2_subdev *sd, struct v4l2_decode_vbi_line *vbi_line);
@@ -480,8 +568,39 @@ struct v4l2_subdev_pad_config {
 
 /**
  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
+ *
+ * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
+ *                  code.
+ * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
+ *                   code.
+ *
+ * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
+ *                       handler code.
+ *
+ * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT ioctl handler code.
+ *
+ * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT ioctl handler code.
+ *
+ * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
+ *
+ * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
+ *
+ * @get_edid: callback for VIDIOC_SUBDEV_G_EDID ioctl handler code.
+ *
+ * @set_edid: callback for VIDIOC_SUBDEV_S_EDID ioctl handler code.
+ *
+ * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
+ *                  code.
+ *
+ * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
+ *                   code.
+ *
+ * @link_validate: used by the media controller code to check if the links
+ *                 that belongs to a pipeline can be used for stream.
+ *
  * @get_frame_desc: get the current low level media bus frame parameters.
- * @get_frame_desc: set the low level media bus frame parameters, @fd array
+ *
+ * @set_frame_desc: set the low level media bus frame parameters, @fd array
  *                  may be adjusted by the subdev driver to device capabilities.
  */
 struct v4l2_subdev_pad_ops {
@@ -695,4 +814,7 @@ void v4l2_subdev_init(struct v4l2_subdev *sd,
 #define v4l2_subdev_has_op(sd, o, f) \
         ((sd)->ops->o && (sd)->ops->o->f)
 
+void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
+                              const struct v4l2_event *ev);
+
 #endif
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index c192e1b46cdc..589b56c68400 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -364,7 +364,9 @@ struct v4l2_fh;
  *              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):
  * @mmap_lock:  private mutex used when buffers are allocated/freed/mmapped
  * @memory:     current memory type used
  * @bufs:       videobuf buffer structures
@@ -407,7 +409,7 @@ struct vb2_queue {
         gfp_t                           gfp_flags;
         u32                             min_buffers_needed;
 
-/* private: internal use only */
+        /* private: internal use only */
         struct mutex                    mmap_lock;
         enum v4l2_memory                memory;
         struct vb2_buffer               *bufs[VIDEO_MAX_FRAME];
@@ -484,7 +486,8 @@ 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
  *
  * This is called whenever a buffer is dequeued in the thread.
@@ -577,7 +580,6 @@ static inline void vb2_set_plane_payload(struct vb2_buffer *vb,
  * vb2_get_plane_payload() - get bytesused for the plane plane_no
  * @vb:         buffer for which plane payload should be set
  * @plane_no:   plane number for which payload should be set
- * @size:       payload in bytes
  */
 static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb,
                                  unsigned int plane_no)
diff --git a/include/media/videobuf2-memops.h b/include/media/videobuf2-memops.h
index f05444ca8c0c..9f36641a6781 100644
--- a/include/media/videobuf2-memops.h
+++ b/include/media/videobuf2-memops.h
@@ -17,7 +17,8 @@
 #include <media/videobuf2-core.h>
 
 /**
- * vb2_vmarea_handler - common vma refcount tracking handler
+ * struct vb2_vmarea_handler - common vma refcount tracking handler
+ *
  * @refcount:   pointer to refcount entry in the buffer
  * @put:        callback to function that decreases buffer refcount
  * @arg:        argument for @put callback