[PATCH 00/24] V4L2 kAPI cleanups and documentation improvements part 2

[PATCH 00/24] V4L2 kAPI cleanups and documentation improvements part 2

[Mauro Carvalho Chehab]

That's the second part of my V4L2 kAPI documentation improvements.
It is meant to reduce the gap between the kAPI media headers
and documentation, at least with regards to kernel-doc markups.

We should likely write more things at the ReST files under Documentation/
to better describe some of those APIs (VB2 being likely the first candidate),
but at least let's be sure that all V4L2 bits have kernel-doc markups.

Mauro Carvalho Chehab (24):
  media: v4l2-dev.h: add kernel-doc to two macros
  media: v4l2-flash-led-class.h: add kernel-doc to two ancillary funcs
  media: v4l2-mediabus: use BIT() macro for flags
  media: v4l2-mediabus: convert flags to enums and document them
  media: v4l2-dev: convert VFL_TYPE_* into an enum
  media: i2c-addr.h: get rid of now unused defines
  media: get rid of i2c-addr.h
  media: v4l2-dev: document VFL_DIR_* direction defines
  media: v4l2-dev: document video_device flags
  media: v4l2-subdev: use kernel-doc markups to document subdev flags
  media: v4l2-subdev: create cross-references for ioctls
  media: v4l2-subdev: fix description of tuner.s_radio ops
  media: v4l2-subdev: better document IO pin configuration flags
  media: v4l2-subdev: convert frame description to enum
  media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro
  media: v4l2-subdev: document remaining undocumented functions
  media: v4l2-subdev: fix a typo
  media: vb2-core: use bitops for bits
  media: vb2-core: Improve kernel-doc markups
  media: vb2-core: document remaining functions
  media: vb2-core: fix descriptions for VB2-only functions
  media: vb2: add cross references at memops and v4l2 kernel-doc markups
  media: v4l2-tpg*.h: move headers to include/media/tpg and merge them
  media: v4l2-tpg.h: rename color structs

 Documentation/media/kapi/v4l2-dev.rst              |  17 +-
 drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c    |   8 +-
 drivers/media/common/v4l2-tpg/v4l2-tpg-core.c      |   2 +-
 drivers/media/i2c/adv7180.c                        |  10 +-
 drivers/media/i2c/ml86v7667.c                      |   5 +-
 drivers/media/i2c/mt9m111.c                        |   8 +-
 drivers/media/i2c/ov6650.c                         |  19 +-
 drivers/media/i2c/soc_camera/imx074.c              |   6 +-
 drivers/media/i2c/soc_camera/mt9m001.c             |  10 +-
 drivers/media/i2c/soc_camera/mt9t031.c             |  11 +-
 drivers/media/i2c/soc_camera/mt9t112.c             |  11 +-
 drivers/media/i2c/soc_camera/mt9v022.c             |  16 +-
 drivers/media/i2c/soc_camera/ov5642.c              |   5 +-
 drivers/media/i2c/soc_camera/ov772x.c              |  10 +-
 drivers/media/i2c/soc_camera/ov9640.c              |  10 +-
 drivers/media/i2c/soc_camera/ov9740.c              |  10 +-
 drivers/media/i2c/soc_camera/rj54n1cb0c.c          |  12 +-
 drivers/media/i2c/soc_camera/tw9910.c              |  13 +-
 drivers/media/i2c/tc358743.c                       |  10 +-
 drivers/media/i2c/tda7432.c                        |   1 -
 drivers/media/i2c/tvaudio.c                        |   2 -
 drivers/media/i2c/tvp5150.c                        |   6 +-
 drivers/media/pci/bt8xx/bttv-cards.c               |   7 +
 drivers/media/pci/bt8xx/bttv.h                     |   1 -
 drivers/media/pci/cx88/cx88-blackbird.c            |   3 +-
 drivers/media/pci/cx88/cx88-video.c                |  10 +-
 drivers/media/pci/cx88/cx88.h                      |   4 +-
 drivers/media/pci/saa7134/saa7134-video.c          |   2 +
 drivers/media/platform/pxa_camera.c                |   8 +-
 drivers/media/platform/rcar-vin/rcar-core.c        |   4 +-
 drivers/media/platform/rcar-vin/rcar-dma.c         |   4 +-
 .../platform/soc_camera/sh_mobile_ceu_camera.c     |   2 +-
 drivers/media/platform/soc_camera/soc_camera.c     |   3 +-
 .../platform/soc_camera/soc_camera_platform.c      |   2 +-
 drivers/media/platform/soc_camera/soc_mediabus.c   |   2 +-
 drivers/media/platform/vimc/vimc-sensor.c          |   2 +-
 drivers/media/platform/vivid/vivid-core.h          |   2 +-
 drivers/media/usb/cx231xx/cx231xx-video.c          |   2 +
 drivers/media/usb/em28xx/em28xx-cards.c            |   1 -
 drivers/media/usb/pvrusb2/pvrusb2-v4l2.c           |   2 +
 drivers/media/usb/tm6000/tm6000-cards.c            |   1 -
 drivers/media/usb/tm6000/tm6000-video.c            |   2 +
 drivers/media/v4l2-core/v4l2-dev.c                 |  10 +-
 drivers/media/v4l2-core/v4l2-fwnode.c              |   5 +-
 include/media/i2c-addr.h                           |  42 --
 include/media/i2c/tvaudio.h                        |  17 +-
 include/media/{ => tpg}/v4l2-tpg.h                 |  45 +-
 include/media/v4l2-dev.h                           | 124 ++++--
 include/media/v4l2-flash-led-class.h               |  12 +
 include/media/v4l2-fwnode.h                        |   4 +-
 include/media/v4l2-mediabus.h                      | 176 ++++++--
 include/media/v4l2-subdev.h                        | 293 +++++++++----
 include/media/v4l2-tpg-colors.h                    |  68 ---
 include/media/videobuf2-core.h                     | 483 ++++++++++++---------
 include/media/videobuf2-memops.h                   |   8 +-
 include/media/videobuf2-v4l2.h                     | 112 ++---
 56 files changed, 1006 insertions(+), 659 deletions(-)
 delete mode 100644 include/media/i2c-addr.h
 rename include/media/{ => tpg}/v4l2-tpg.h (93%)
 delete mode 100644 include/media/v4l2-tpg-colors.h

-- 
2.13.6

[PATCH 01/24] media: v4l2-dev.h: add kernel-doc to two macros

[Mauro Carvalho Chehab]

There are two macros at v4l2-dev.h that aren't documented.

Document them, for completeness.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-dev.h | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index e657614521e3..de1a1453cfd9 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -260,9 +260,21 @@ struct video_device
 	struct mutex *lock;
 };
 
-#define media_entity_to_video_device(__e) \
-	container_of(__e, struct video_device, entity)
-/* dev to video-device */
+/**
+ * media_entity_to_video_device - Returns a &struct video_device from
+ * 	the &struct media_entity embedded on it.
+ *
+ * @entity: pointer to &struct media_entity
+ */
+#define media_entity_to_video_device(entity) \
+	container_of(entity, struct video_device, entity)
+
+/**
+ * media_entity_to_video_device - Returns a &struct video_device from
+ * 	the &struct device embedded on it.
+ *
+ * @cd: pointer to &struct device
+ */
 #define to_video_device(cd) container_of(cd, struct video_device, dev)
 
 /**
-- 
2.13.6

[PATCH 02/24] media: v4l2-flash-led-class.h: add kernel-doc to two ancillary funcs

[Mauro Carvalho Chehab]

There are two ancillary functions at v4l2-flash-led-class.h
that aren't documented.

Document them.

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

diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h
index 5c1d50f78e12..39a5daa977aa 100644
--- a/include/media/v4l2-flash-led-class.h
+++ b/include/media/v4l2-flash-led-class.h
@@ -91,12 +91,24 @@ struct v4l2_flash {
 	struct v4l2_ctrl **ctrls;
 };
 
+/**
+ * v4l2_subdev_to_v4l2_flash - Returns a &v4l2_flash from the
+ * &struct v4l2_subdev embedded on it.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 static inline struct v4l2_flash *v4l2_subdev_to_v4l2_flash(
 							struct v4l2_subdev *sd)
 {
 	return container_of(sd, struct v4l2_flash, sd);
 }
 
+/**
+ * v4l2_ctrl_to_v4l2_flash - Returns a &v4l2_flash from the
+ * &struct v4l2_ctrl embedded on it.
+ *
+ * @c: pointer to &struct v4l2_ctrl
+ */
 static inline struct v4l2_flash *v4l2_ctrl_to_v4l2_flash(struct v4l2_ctrl *c)
 {
 	return container_of(c->handler, struct v4l2_flash, hdl);
-- 
2.13.6

[PATCH 03/24] media: v4l2-mediabus: use BIT() macro for flags

[Mauro Carvalho Chehab]

Instead of using (1 << n) for bits, use the BIT() macro,
as it makes them better documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-mediabus.h | 50 ++++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index 93f8afcb7a22..e5281e1086c4 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -12,6 +12,8 @@
 #define V4L2_MEDIABUS_H
 
 #include <linux/v4l2-mediabus.h>
+#include <linux/bitops.h>
+
 
 /* Parallel flags */
 /*
@@ -20,44 +22,44 @@
  * horizontal and vertical synchronisation. In "Slave mode" the host is
  * providing these signals to the slave.
  */
-#define V4L2_MBUS_MASTER			(1 << 0)
-#define V4L2_MBUS_SLAVE				(1 << 1)
+#define V4L2_MBUS_MASTER			BIT(0)
+#define V4L2_MBUS_SLAVE				BIT(1)
 /*
  * Signal polarity flags
  * Note: in BT.656 mode HSYNC, FIELD, and VSYNC are unused
  * V4L2_MBUS_[HV]SYNC* flags should be also used for specifying
  * configuration of hardware that uses [HV]REF signals
  */
-#define V4L2_MBUS_HSYNC_ACTIVE_HIGH		(1 << 2)
-#define V4L2_MBUS_HSYNC_ACTIVE_LOW		(1 << 3)
-#define V4L2_MBUS_VSYNC_ACTIVE_HIGH		(1 << 4)
-#define V4L2_MBUS_VSYNC_ACTIVE_LOW		(1 << 5)
-#define V4L2_MBUS_PCLK_SAMPLE_RISING		(1 << 6)
-#define V4L2_MBUS_PCLK_SAMPLE_FALLING		(1 << 7)
-#define V4L2_MBUS_DATA_ACTIVE_HIGH		(1 << 8)
-#define V4L2_MBUS_DATA_ACTIVE_LOW		(1 << 9)
+#define V4L2_MBUS_HSYNC_ACTIVE_HIGH		BIT(2)
+#define V4L2_MBUS_HSYNC_ACTIVE_LOW		BIT(3)
+#define V4L2_MBUS_VSYNC_ACTIVE_HIGH		BIT(4)
+#define V4L2_MBUS_VSYNC_ACTIVE_LOW		BIT(5)
+#define V4L2_MBUS_PCLK_SAMPLE_RISING		BIT(6)
+#define V4L2_MBUS_PCLK_SAMPLE_FALLING		BIT(7)
+#define V4L2_MBUS_DATA_ACTIVE_HIGH		BIT(8)
+#define V4L2_MBUS_DATA_ACTIVE_LOW		BIT(9)
 /* FIELD = 0/1 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_HIGH		(1 << 10)
+#define V4L2_MBUS_FIELD_EVEN_HIGH		BIT(10)
 /* FIELD = 1/0 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_LOW		(1 << 11)
+#define V4L2_MBUS_FIELD_EVEN_LOW		BIT(11)
 /* Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively. */
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH	(1 << 12)
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW		(1 << 13)
+#define V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH		BIT(12)
+#define V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW		BIT(13)
 
 /* Serial flags */
 /* How many lanes the client can use */
-#define V4L2_MBUS_CSI2_1_LANE			(1 << 0)
-#define V4L2_MBUS_CSI2_2_LANE			(1 << 1)
-#define V4L2_MBUS_CSI2_3_LANE			(1 << 2)
-#define V4L2_MBUS_CSI2_4_LANE			(1 << 3)
+#define V4L2_MBUS_CSI2_1_LANE			BIT(0)
+#define V4L2_MBUS_CSI2_2_LANE			BIT(1)
+#define V4L2_MBUS_CSI2_3_LANE			BIT(2)
+#define V4L2_MBUS_CSI2_4_LANE			BIT(3)
 /* On which channels it can send video data */
-#define V4L2_MBUS_CSI2_CHANNEL_0		(1 << 4)
-#define V4L2_MBUS_CSI2_CHANNEL_1		(1 << 5)
-#define V4L2_MBUS_CSI2_CHANNEL_2		(1 << 6)
-#define V4L2_MBUS_CSI2_CHANNEL_3		(1 << 7)
+#define V4L2_MBUS_CSI2_CHANNEL_0		BIT(4)
+#define V4L2_MBUS_CSI2_CHANNEL_1		BIT(5)
+#define V4L2_MBUS_CSI2_CHANNEL_2		BIT(6)
+#define V4L2_MBUS_CSI2_CHANNEL_3		BIT(7)
 /* Does it support only continuous or also non-continuous clock mode */
-#define V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		(1 << 8)
-#define V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	(1 << 9)
+#define V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		BIT(8)
+#define V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	BIT(9)
 
 #define V4L2_MBUS_CSI2_LANES		(V4L2_MBUS_CSI2_1_LANE | V4L2_MBUS_CSI2_2_LANE | \
 					 V4L2_MBUS_CSI2_3_LANE | V4L2_MBUS_CSI2_4_LANE)
-- 
2.13.6

[PATCH 04/24] media: v4l2-mediabus: convert flags to enums and document them

[Mauro Carvalho Chehab]

There is a mess with media bus flags: there are two sets of
flags, one used by parallel and ITU-R BT.656 outputs,
and another one for CSI2.

Depending on the type, the same bit has different meanings.

That's very confusing, and counter-intuitive. So, split them
into two sets of flags, inside an enum.

This way, it becomes clearer that there are two separate sets
of flags. It also makes easier if CSI1, CSP, CSI3, etc. would
need a different set of flags.

As a side effect, enums can be documented via kernel-docs,
so there will be an improvement at flags documentation.

Unfortunately, soc_camera and pxa_camera do a mess with
the flags, using either one set of flags without proper
checks about the type. That could be fixed, but, as both drivers
are obsolete and in the process of cleanings, I opted to just
keep the behavior, using an unsigned int inside those two
drivers.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/media/i2c/adv7180.c                        |  10 +-
 drivers/media/i2c/ml86v7667.c                      |   5 +-
 drivers/media/i2c/mt9m111.c                        |   8 +-
 drivers/media/i2c/ov6650.c                         |  19 +--
 drivers/media/i2c/soc_camera/imx074.c              |   6 +-
 drivers/media/i2c/soc_camera/mt9m001.c             |  10 +-
 drivers/media/i2c/soc_camera/mt9t031.c             |  11 +-
 drivers/media/i2c/soc_camera/mt9t112.c             |  11 +-
 drivers/media/i2c/soc_camera/mt9v022.c             |  16 ++-
 drivers/media/i2c/soc_camera/ov5642.c              |   5 +-
 drivers/media/i2c/soc_camera/ov772x.c              |  10 +-
 drivers/media/i2c/soc_camera/ov9640.c              |  10 +-
 drivers/media/i2c/soc_camera/ov9740.c              |  10 +-
 drivers/media/i2c/soc_camera/rj54n1cb0c.c          |  12 +-
 drivers/media/i2c/soc_camera/tw9910.c              |  13 +-
 drivers/media/i2c/tc358743.c                       |  10 +-
 drivers/media/i2c/tvp5150.c                        |   6 +-
 drivers/media/platform/pxa_camera.c                |   8 +-
 drivers/media/platform/rcar-vin/rcar-core.c        |   4 +-
 drivers/media/platform/rcar-vin/rcar-dma.c         |   4 +-
 .../platform/soc_camera/sh_mobile_ceu_camera.c     |   2 +-
 drivers/media/platform/soc_camera/soc_camera.c     |   3 +-
 .../platform/soc_camera/soc_camera_platform.c      |   2 +-
 drivers/media/platform/soc_camera/soc_mediabus.c   |   2 +-
 drivers/media/v4l2-core/v4l2-fwnode.c              |   5 +-
 include/media/v4l2-fwnode.h                        |   4 +-
 include/media/v4l2-mediabus.h                      | 144 ++++++++++++++-------
 27 files changed, 217 insertions(+), 133 deletions(-)

diff --git a/drivers/media/i2c/adv7180.c b/drivers/media/i2c/adv7180.c
index 3df28f2f9b38..c220504049de 100644
--- a/drivers/media/i2c/adv7180.c
+++ b/drivers/media/i2c/adv7180.c
@@ -743,16 +743,16 @@ static int adv7180_g_mbus_config(struct v4l2_subdev *sd,
 
 	if (state->chip_info->flags & ADV7180_FLAG_MIPI_CSI2) {
 		cfg->type = V4L2_MBUS_CSI2;
-		cfg->flags = V4L2_MBUS_CSI2_1_LANE |
-				V4L2_MBUS_CSI2_CHANNEL_0 |
-				V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+		cfg->csi2_flags = V4L2_MBUS_CSI2_1_LANE
+				  | V4L2_MBUS_CSI2_CHANNEL_0
+				  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 	} else {
 		/*
 		 * The ADV7180 sensor supports BT.601/656 output modes.
 		 * The BT.656 is default and not yet configurable by s/w.
 		 */
-		cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-				 V4L2_MBUS_DATA_ACTIVE_HIGH;
+		cfg->pb_flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING
+			        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 		cfg->type = V4L2_MBUS_BT656;
 	}
 
diff --git a/drivers/media/i2c/ml86v7667.c b/drivers/media/i2c/ml86v7667.c
index 57ef901edb06..a25114d0c31f 100644
--- a/drivers/media/i2c/ml86v7667.c
+++ b/drivers/media/i2c/ml86v7667.c
@@ -226,8 +226,9 @@ static int ml86v7667_fill_fmt(struct v4l2_subdev *sd,
 static int ml86v7667_g_mbus_config(struct v4l2_subdev *sd,
 				   struct v4l2_mbus_config *cfg)
 {
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		     V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_BT656;
 
 	return 0;
diff --git a/drivers/media/i2c/mt9m111.c b/drivers/media/i2c/mt9m111.c
index 99b992e46702..53c406f87aa7 100644
--- a/drivers/media/i2c/mt9m111.c
+++ b/drivers/media/i2c/mt9m111.c
@@ -857,9 +857,11 @@ static int mt9m111_enum_mbus_code(struct v4l2_subdev *sd,
 static int mt9m111_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+		        | V4L2_MBUS_PCLK_SAMPLE_RISING
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_VSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
 
 	return 0;
diff --git a/drivers/media/i2c/ov6650.c b/drivers/media/i2c/ov6650.c
index 768f2950ea36..9f6ddb804cc1 100644
--- a/drivers/media/i2c/ov6650.c
+++ b/drivers/media/i2c/ov6650.c
@@ -880,11 +880,14 @@ static int ov6650_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 
-	cfg->flags = V4L2_MBUS_MASTER |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
 
 	return 0;
@@ -897,21 +900,21 @@ static int ov6650_s_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	int ret;
 
-	if (cfg->flags & V4L2_MBUS_PCLK_SAMPLE_RISING)
+	if (cfg->pb_flags & V4L2_MBUS_PCLK_SAMPLE_RISING)
 		ret = ov6650_reg_rmw(client, REG_COMJ, COMJ_PCLK_RISING, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMJ, 0, COMJ_PCLK_RISING);
 	if (ret)
 		return ret;
 
-	if (cfg->flags & V4L2_MBUS_HSYNC_ACTIVE_LOW)
+	if (cfg->pb_flags & V4L2_MBUS_HSYNC_ACTIVE_LOW)
 		ret = ov6650_reg_rmw(client, REG_COMF, COMF_HREF_LOW, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMF, 0, COMF_HREF_LOW);
 	if (ret)
 		return ret;
 
-	if (cfg->flags & V4L2_MBUS_VSYNC_ACTIVE_HIGH)
+	if (cfg->pb_flags & V4L2_MBUS_VSYNC_ACTIVE_HIGH)
 		ret = ov6650_reg_rmw(client, REG_COMJ, COMJ_VSYNC_HIGH, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMJ, 0, COMJ_VSYNC_HIGH);
diff --git a/drivers/media/i2c/soc_camera/imx074.c b/drivers/media/i2c/soc_camera/imx074.c
index 77f1e0243d6e..f52d64e31975 100644
--- a/drivers/media/i2c/soc_camera/imx074.c
+++ b/drivers/media/i2c/soc_camera/imx074.c
@@ -264,9 +264,9 @@ static int imx074_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 	cfg->type = V4L2_MBUS_CSI2;
-	cfg->flags = V4L2_MBUS_CSI2_2_LANE |
-		V4L2_MBUS_CSI2_CHANNEL_0 |
-		V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_2_LANE
+			  | V4L2_MBUS_CSI2_CHANNEL_0
+			  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9m001.c b/drivers/media/i2c/soc_camera/mt9m001.c
index 1bfb0d53059e..91545e8160b7 100644
--- a/drivers/media/i2c/soc_camera/mt9m001.c
+++ b/drivers/media/i2c/soc_camera/mt9m001.c
@@ -603,11 +603,13 @@ static int mt9m001_g_mbus_config(struct v4l2_subdev *sd,
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
 	/* MT9M001 has all capture_format parameters fixed */
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH | V4L2_MBUS_MASTER;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_FALLING
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_MASTER;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9t031.c b/drivers/media/i2c/soc_camera/mt9t031.c
index 4802d30e47de..c3c531cd5caa 100644
--- a/drivers/media/i2c/soc_camera/mt9t031.c
+++ b/drivers/media/i2c/soc_camera/mt9t031.c
@@ -704,11 +704,14 @@ static int mt9t031_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		V4L2_MBUS_PCLK_SAMPLE_FALLING | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9t112.c b/drivers/media/i2c/soc_camera/mt9t112.c
index 297d22ebcb18..4fa761693872 100644
--- a/drivers/media/i2c/soc_camera/mt9t112.c
+++ b/drivers/media/i2c/soc_camera/mt9t112.c
@@ -1009,11 +1009,14 @@ static int mt9t112_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_DATA_ACTIVE_HIGH |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9v022.c b/drivers/media/i2c/soc_camera/mt9v022.c
index 762f06919329..8297dfdad4e9 100644
--- a/drivers/media/i2c/soc_camera/mt9v022.c
+++ b/drivers/media/i2c/soc_camera/mt9v022.c
@@ -798,13 +798,17 @@ static int mt9v022_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_SLAVE |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_SLAVE
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov5642.c b/drivers/media/i2c/soc_camera/ov5642.c
index 39f420db9c70..629370d8feaa 100644
--- a/drivers/media/i2c/soc_camera/ov5642.c
+++ b/drivers/media/i2c/soc_camera/ov5642.c
@@ -914,8 +914,9 @@ static int ov5642_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 	cfg->type = V4L2_MBUS_CSI2;
-	cfg->flags = V4L2_MBUS_CSI2_2_LANE | V4L2_MBUS_CSI2_CHANNEL_0 |
-					V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_2_LANE
+			  | V4L2_MBUS_CSI2_CHANNEL_0
+			  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov772x.c b/drivers/media/i2c/soc_camera/ov772x.c
index 806383500313..7e1391460393 100644
--- a/drivers/media/i2c/soc_camera/ov772x.c
+++ b/drivers/media/i2c/soc_camera/ov772x.c
@@ -1003,11 +1003,13 @@ static int ov772x_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov9640.c b/drivers/media/i2c/soc_camera/ov9640.c
index 0146d1f7aacb..905e8e251b7b 100644
--- a/drivers/media/i2c/soc_camera/ov9640.c
+++ b/drivers/media/i2c/soc_camera/ov9640.c
@@ -634,11 +634,13 @@ static int ov9640_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+		        | V4L2_MBUS_MASTER
+		        | V4L2_MBUS_VSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov9740.c b/drivers/media/i2c/soc_camera/ov9740.c
index cc07b7ae5407..f6ab060d4af0 100644
--- a/drivers/media/i2c/soc_camera/ov9740.c
+++ b/drivers/media/i2c/soc_camera/ov9740.c
@@ -882,11 +882,13 @@ static int ov9740_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/rj54n1cb0c.c b/drivers/media/i2c/soc_camera/rj54n1cb0c.c
index 02398d0bc649..f1d36f6a72b7 100644
--- a/drivers/media/i2c/soc_camera/rj54n1cb0c.c
+++ b/drivers/media/i2c/soc_camera/rj54n1cb0c.c
@@ -1227,12 +1227,14 @@ static int rj54n1_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags =
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_MASTER | V4L2_MBUS_DATA_ACTIVE_HIGH |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/tw9910.c b/drivers/media/i2c/soc_camera/tw9910.c
index bdb5e0a431e9..aa64bea2ef9f 100644
--- a/drivers/media/i2c/soc_camera/tw9910.c
+++ b/drivers/media/i2c/soc_camera/tw9910.c
@@ -862,12 +862,15 @@ static int tw9910_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/tc358743.c b/drivers/media/i2c/tc358743.c
index e6f5c363ccab..bdd2b492e93c 100644
--- a/drivers/media/i2c/tc358743.c
+++ b/drivers/media/i2c/tc358743.c
@@ -1462,20 +1462,20 @@ static int tc358743_g_mbus_config(struct v4l2_subdev *sd,
 	cfg->type = V4L2_MBUS_CSI2;
 
 	/* Support for non-continuous CSI-2 clock is missing in the driver */
-	cfg->flags = V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	switch (state->csi_lanes_in_use) {
 	case 1:
-		cfg->flags |= V4L2_MBUS_CSI2_1_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_1_LANE;
 		break;
 	case 2:
-		cfg->flags |= V4L2_MBUS_CSI2_2_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_2_LANE;
 		break;
 	case 3:
-		cfg->flags |= V4L2_MBUS_CSI2_3_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_3_LANE;
 		break;
 	case 4:
-		cfg->flags |= V4L2_MBUS_CSI2_4_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_4_LANE;
 		break;
 	default:
 		return -EINVAL;
diff --git a/drivers/media/i2c/tvp5150.c b/drivers/media/i2c/tvp5150.c
index 7b79a7498751..2078a12c46bf 100644
--- a/drivers/media/i2c/tvp5150.c
+++ b/drivers/media/i2c/tvp5150.c
@@ -977,8 +977,10 @@ static int tvp5150_g_mbus_config(struct v4l2_subdev *sd,
 	struct tvp5150 *decoder = to_tvp5150(sd);
 
 	cfg->type = decoder->mbus_type;
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING
-		   | V4L2_MBUS_FIELD_EVEN_LOW | V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_FIELD_EVEN_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 
 	return 0;
 }
diff --git a/drivers/media/platform/pxa_camera.c b/drivers/media/platform/pxa_camera.c
index 4a23a60f3418..2a3fdb87be4b 100644
--- a/drivers/media/platform/pxa_camera.c
+++ b/drivers/media/platform/pxa_camera.c
@@ -616,7 +616,7 @@ static unsigned int pxa_mbus_config_compatible(const struct v4l2_mbus_config *cf
 	bool hsync = true, vsync = true, pclk, data, mode;
 	bool mipi_lanes, mipi_clock;
 
-	common_flags = cfg->flags & flags;
+	common_flags = cfg->flag & flags;
 
 	switch (cfg->type) {
 	case V4L2_MBUS_PARALLEL:
@@ -1619,7 +1619,7 @@ static int pxa_camera_set_bus_param(struct pxa_camera_dev *pcdev)
 		if (!common_flags) {
 			dev_warn(pcdev_to_dev(pcdev),
 				 "Flags incompatible: camera 0x%x, host 0x%lx\n",
-				 cfg.flags, bus_flags);
+				 cfg.flag, bus_flags);
 			return -EINVAL;
 		}
 	} else if (ret != -ENOIOCTLCMD) {
@@ -1655,7 +1655,7 @@ static int pxa_camera_set_bus_param(struct pxa_camera_dev *pcdev)
 			common_flags &= ~V4L2_MBUS_PCLK_SAMPLE_FALLING;
 	}
 
-	cfg.flags = common_flags;
+	cfg.flag = common_flags;
 	ret = sensor_call(pcdev, video, s_mbus_config, &cfg);
 	if (ret < 0 && ret != -ENOIOCTLCMD) {
 		dev_dbg(pcdev_to_dev(pcdev),
@@ -1686,7 +1686,7 @@ static int pxa_camera_try_bus_param(struct pxa_camera_dev *pcdev,
 		if (!common_flags) {
 			dev_warn(pcdev_to_dev(pcdev),
 				 "Flags incompatible: camera 0x%x, host 0x%lx\n",
-				 cfg.flags, bus_flags);
+				 cfg.flag, bus_flags);
 			return -EINVAL;
 		}
 	} else if (ret == -ENOIOCTLCMD) {
diff --git a/drivers/media/platform/rcar-vin/rcar-core.c b/drivers/media/platform/rcar-vin/rcar-core.c
index 3835a2fa0cb7..95fccabc924c 100644
--- a/drivers/media/platform/rcar-vin/rcar-core.c
+++ b/drivers/media/platform/rcar-vin/rcar-core.c
@@ -152,11 +152,11 @@ static int rvin_digitial_parse_v4l2(struct rvin_dev *vin,
 	switch (mbus_cfg->type) {
 	case V4L2_MBUS_PARALLEL:
 		vin_dbg(vin, "Found PARALLEL media bus\n");
-		mbus_cfg->flags = v4l2_ep.bus.parallel.flags;
+		mbus_cfg->pb_flags = v4l2_ep.bus.parallel.flags;
 		break;
 	case V4L2_MBUS_BT656:
 		vin_dbg(vin, "Found BT656 media bus\n");
-		mbus_cfg->flags = 0;
+		mbus_cfg->pb_flags = 0;
 		break;
 	default:
 		vin_err(vin, "Unknown media bus type\n");
diff --git a/drivers/media/platform/rcar-vin/rcar-dma.c b/drivers/media/platform/rcar-vin/rcar-dma.c
index b136844499f6..16759a19c928 100644
--- a/drivers/media/platform/rcar-vin/rcar-dma.c
+++ b/drivers/media/platform/rcar-vin/rcar-dma.c
@@ -212,11 +212,11 @@ static int rvin_setup(struct rvin_dev *vin)
 	dmr2 = VNDMR2_FTEV | VNDMR2_VLV(1);
 
 	/* Hsync Signal Polarity Select */
-	if (!(vin->digital.mbus_cfg.flags & V4L2_MBUS_HSYNC_ACTIVE_LOW))
+	if (!(vin->digital.mbus_cfg.pb_flags & V4L2_MBUS_HSYNC_ACTIVE_LOW))
 		dmr2 |= VNDMR2_HPS;
 
 	/* Vsync Signal Polarity Select */
-	if (!(vin->digital.mbus_cfg.flags & V4L2_MBUS_VSYNC_ACTIVE_LOW))
+	if (!(vin->digital.mbus_cfg.pb_flags & V4L2_MBUS_VSYNC_ACTIVE_LOW))
 		dmr2 |= VNDMR2_VPS;
 
 	/*
diff --git a/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c b/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
index 36762ec954e7..b2d053ee6686 100644
--- a/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
+++ b/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
@@ -744,7 +744,7 @@ static int sh_mobile_ceu_set_bus_param(struct soc_camera_device *icd)
 			common_flags &= ~V4L2_MBUS_VSYNC_ACTIVE_LOW;
 	}
 
-	cfg.flags = common_flags;
+	cfg.flag = common_flags;
 	ret = v4l2_subdev_call(sd, video, s_mbus_config, &cfg);
 	if (ret < 0 && ret != -ENOIOCTLCMD)
 		return ret;
diff --git a/drivers/media/platform/soc_camera/soc_camera.c b/drivers/media/platform/soc_camera/soc_camera.c
index 1bef3ebb49ee..befa6ac80269 100644
--- a/drivers/media/platform/soc_camera/soc_camera.c
+++ b/drivers/media/platform/soc_camera/soc_camera.c
@@ -217,7 +217,8 @@ EXPORT_SYMBOL(soc_camera_xlate_by_fourcc);
 unsigned long soc_camera_apply_board_flags(struct soc_camera_subdev_desc *ssdd,
 					   const struct v4l2_mbus_config *cfg)
 {
-	unsigned long f, flags = cfg->flags;
+	unsigned long f;
+	enum v4l2_mbus_parallel_and_bt656_flags flags = cfg->pb_flags;
 
 	/* If only one of the two polarities is supported, switch to the opposite */
 	if (ssdd->flags & SOCAM_SENSOR_INVERT_HSYNC) {
diff --git a/drivers/media/platform/soc_camera/soc_camera_platform.c b/drivers/media/platform/soc_camera/soc_camera_platform.c
index cb4986b8f798..ba5f91207dc0 100644
--- a/drivers/media/platform/soc_camera/soc_camera_platform.c
+++ b/drivers/media/platform/soc_camera/soc_camera_platform.c
@@ -104,7 +104,7 @@ static int soc_camera_platform_g_mbus_config(struct v4l2_subdev *sd,
 {
 	struct soc_camera_platform_info *p = v4l2_get_subdevdata(sd);
 
-	cfg->flags = p->mbus_param;
+	cfg->flag = p->mbus_param;
 	cfg->type = p->mbus_type;
 
 	return 0;
diff --git a/drivers/media/platform/soc_camera/soc_mediabus.c b/drivers/media/platform/soc_camera/soc_mediabus.c
index 0ad4b28266e4..9ee9f550b477 100644
--- a/drivers/media/platform/soc_camera/soc_mediabus.c
+++ b/drivers/media/platform/soc_camera/soc_mediabus.c
@@ -486,7 +486,7 @@ unsigned int soc_mbus_config_compatible(const struct v4l2_mbus_config *cfg,
 	bool hsync = true, vsync = true, pclk, data, mode;
 	bool mipi_lanes, mipi_clock;
 
-	common_flags = cfg->flags & flags;
+	common_flags = cfg->flag & flags;
 
 	switch (cfg->type) {
 	case V4L2_MBUS_PARALLEL:
diff --git a/drivers/media/v4l2-core/v4l2-fwnode.c b/drivers/media/v4l2-core/v4l2-fwnode.c
index 40b2fbfe8865..b38fc5f930ac 100644
--- a/drivers/media/v4l2-core/v4l2-fwnode.c
+++ b/drivers/media/v4l2-core/v4l2-fwnode.c
@@ -41,7 +41,8 @@ static int v4l2_fwnode_endpoint_parse_csi2_bus(struct fwnode_handle *fwnode,
 {
 	struct v4l2_fwnode_bus_mipi_csi2 *bus = &vep->bus.mipi_csi2;
 	bool have_clk_lane = false;
-	unsigned int flags = 0, lanes_used = 0;
+	unsigned int lanes_used = 0;
+	enum v4l2_mbus_csi2_flags flags = 0;
 	unsigned int i;
 	u32 v;
 	int rval;
@@ -109,7 +110,7 @@ static void v4l2_fwnode_endpoint_parse_parallel_bus(
 	struct fwnode_handle *fwnode, struct v4l2_fwnode_endpoint *vep)
 {
 	struct v4l2_fwnode_bus_parallel *bus = &vep->bus.parallel;
-	unsigned int flags = 0;
+	enum v4l2_mbus_parallel_and_bt656_flags flags = 0;
 	u32 v;
 
 	if (!fwnode_property_read_u32(fwnode, "hsync-active", &v))
diff --git a/include/media/v4l2-fwnode.h b/include/media/v4l2-fwnode.h
index 5f4716f967d0..3429400601a8 100644
--- a/include/media/v4l2-fwnode.h
+++ b/include/media/v4l2-fwnode.h
@@ -30,7 +30,7 @@ struct fwnode_handle;
 
 /**
  * struct v4l2_fwnode_bus_mipi_csi2 - MIPI CSI-2 bus data structure
- * @flags: media bus (V4L2_MBUS_*) flags
+ * @flags: media bus CSI flags, as defined by &enum v4l2_mbus_csi2_flags
  * @data_lanes: an array of physical data lane indexes
  * @clock_lane: physical lane index of the clock lane
  * @num_data_lanes: number of data lanes
@@ -38,7 +38,7 @@ struct fwnode_handle;
  *		   the physical lanes.
  */
 struct v4l2_fwnode_bus_mipi_csi2 {
-	unsigned int flags;
+	enum v4l2_mbus_csi2_flags flags;
 	unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES];
 	unsigned char clock_lane;
 	unsigned short num_data_lanes;
diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index e5281e1086c4..47adb1608d98 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -15,51 +15,90 @@
 #include <linux/bitops.h>
 
 
-/* Parallel flags */
-/*
- * Can the client run in master or in slave mode. By "Master mode" an operation
- * mode is meant, when the client (e.g., a camera sensor) is producing
- * horizontal and vertical synchronisation. In "Slave mode" the host is
- * providing these signals to the slave.
+/**
+ * enum v4l2_mbus_flags - Media bus parallel and polarity flags
+ *
+ * @V4L2_MBUS_MASTER:			the client runs on parallel master mode;
+ * @V4L2_MBUS_SLAVE:			the client runs on parallel slave mode.
+ * @V4L2_MBUS_HSYNC_ACTIVE_HIGH:	horizontal sync active on high level
+ * @V4L2_MBUS_HSYNC_ACTIVE_LOW:		horizontal sync active on low level
+ * @V4L2_MBUS_VSYNC_ACTIVE_HIGH:	vertical sync active on high level
+ * @V4L2_MBUS_VSYNC_ACTIVE_LOW:		vertical sync active on low level
+ * @V4L2_MBUS_PCLK_SAMPLE_RISING:	pixel clock sample on level rising
+ * @V4L2_MBUS_PCLK_SAMPLE_FALLING:	pixel clock sample on level falling
+ * @V4L2_MBUS_DATA_ACTIVE_HIGH:		data active on high level
+ * @V4L2_MBUS_DATA_ACTIVE_LOW:		data active on low level
+ * @V4L2_MBUS_FIELD_EVEN_HIGH:		FIELD = 0/1 - Field1 (odd)/Field2 (even)
+ * @V4L2_MBUS_FIELD_EVEN_LOW:		FIELD = 1/0 - Field1 (odd)/Field2 (even)
+ * @V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH:	Sync-on-green (SoG) signal active
+ *					on high level
+ * @V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW:	Sync-on-green (SoG) signal active
+ *					on low level
+ *
+ * Those flags are used when the bus is in %V4L2_MBUS_PARALLEL or
+ * %V4L2_MBUS_BT656 mode.
+ *
+ * .. note::
+ *
+ *    #) @V4L2_MBUS_MASTER and @V4L2_MBUS_SLAVE are only valid if the bus
+ *       is in %V4L2_MBUS_PARALLEL mode. They are used to specify if the
+ *       client runs in master or in slave mode.
+ *
+ *       In "Master mode" (@V4L2_MBUS_MASTER), the client (e.g., a camera
+ *       sensor) is producing horizontal and vertical synchronization.
+ *
+ *       In "Slave mode" (@V4L2_MBUS_SLAVE) the host is providing these signals
+ *       to the slave.
+ *    #) in %V4L2_MBUS_BT656 mode, ``V4L2_MBUS_HSYNC_*``, ``V4L2_MBUS_VSYNC_*``
+ *       and ``V4L2_MBUS_FIELD_*`` flags are unused.
+ *    #) ``V4L2_MBUS_[HV]SYNC*`` flags should be also used for specifying
+ *       configuration of hardware that uses [HV]REF signals
  */
-#define V4L2_MBUS_MASTER			BIT(0)
-#define V4L2_MBUS_SLAVE				BIT(1)
-/*
- * Signal polarity flags
- * Note: in BT.656 mode HSYNC, FIELD, and VSYNC are unused
- * V4L2_MBUS_[HV]SYNC* flags should be also used for specifying
- * configuration of hardware that uses [HV]REF signals
- */
-#define V4L2_MBUS_HSYNC_ACTIVE_HIGH		BIT(2)
-#define V4L2_MBUS_HSYNC_ACTIVE_LOW		BIT(3)
-#define V4L2_MBUS_VSYNC_ACTIVE_HIGH		BIT(4)
-#define V4L2_MBUS_VSYNC_ACTIVE_LOW		BIT(5)
-#define V4L2_MBUS_PCLK_SAMPLE_RISING		BIT(6)
-#define V4L2_MBUS_PCLK_SAMPLE_FALLING		BIT(7)
-#define V4L2_MBUS_DATA_ACTIVE_HIGH		BIT(8)
-#define V4L2_MBUS_DATA_ACTIVE_LOW		BIT(9)
-/* FIELD = 0/1 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_HIGH		BIT(10)
-/* FIELD = 1/0 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_LOW		BIT(11)
-/* Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively. */
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH		BIT(12)
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW		BIT(13)
+enum v4l2_mbus_parallel_and_bt656_flags {
+	V4L2_MBUS_MASTER		= BIT(0),
+	V4L2_MBUS_SLAVE			= BIT(1),
+	V4L2_MBUS_HSYNC_ACTIVE_HIGH	= BIT(2),
+	V4L2_MBUS_HSYNC_ACTIVE_LOW	= BIT(3),
+	V4L2_MBUS_VSYNC_ACTIVE_HIGH	= BIT(4),
+	V4L2_MBUS_VSYNC_ACTIVE_LOW	= BIT(5),
+	V4L2_MBUS_PCLK_SAMPLE_RISING	= BIT(6),
+	V4L2_MBUS_PCLK_SAMPLE_FALLING	= BIT(7),
+	V4L2_MBUS_DATA_ACTIVE_HIGH	= BIT(8),
+	V4L2_MBUS_DATA_ACTIVE_LOW	= BIT(9),
+	V4L2_MBUS_FIELD_EVEN_HIGH	= BIT(10),
+	V4L2_MBUS_FIELD_EVEN_LOW	= BIT(11),
+	V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH	= BIT(12),
+	V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW	= BIT(13),
+};
 
-/* Serial flags */
-/* How many lanes the client can use */
-#define V4L2_MBUS_CSI2_1_LANE			BIT(0)
-#define V4L2_MBUS_CSI2_2_LANE			BIT(1)
-#define V4L2_MBUS_CSI2_3_LANE			BIT(2)
-#define V4L2_MBUS_CSI2_4_LANE			BIT(3)
-/* On which channels it can send video data */
-#define V4L2_MBUS_CSI2_CHANNEL_0		BIT(4)
-#define V4L2_MBUS_CSI2_CHANNEL_1		BIT(5)
-#define V4L2_MBUS_CSI2_CHANNEL_2		BIT(6)
-#define V4L2_MBUS_CSI2_CHANNEL_3		BIT(7)
-/* Does it support only continuous or also non-continuous clock mode */
-#define V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		BIT(8)
-#define V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	BIT(9)
+/**
+ * enum v4l2_mbus_csi2_flags - Media bus serial flags
+ *
+ * @V4L2_MBUS_CSI2_1_LANE:		One lane in use
+ * @V4L2_MBUS_CSI2_2_LANE:		Two lanes in use
+ * @V4L2_MBUS_CSI2_3_LANE:		Three lanes in use
+ * @V4L2_MBUS_CSI2_4_LANE:		Four lanes in use
+ * @V4L2_MBUS_CSI2_CHANNEL_0:		Channel 0 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_1:		Channel 1 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_2:		Channel 2 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_3:		Channel 3 can send video data
+ * @V4L2_MBUS_CSI2_CONTINUOUS_CLOCK:	Supports continuous clock mode
+ * @V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK:	Supports non-continuous clock mode
+ *
+ * Used only when the bus type is MIPI CSI-2.
+ */
+enum v4l2_mbus_csi2_flags {
+	V4L2_MBUS_CSI2_1_LANE			= BIT(0),
+	V4L2_MBUS_CSI2_2_LANE			= BIT(1),
+	V4L2_MBUS_CSI2_3_LANE			= BIT(2),
+	V4L2_MBUS_CSI2_4_LANE			= BIT(3),
+	V4L2_MBUS_CSI2_CHANNEL_0		= BIT(4),
+	V4L2_MBUS_CSI2_CHANNEL_1		= BIT(5),
+	V4L2_MBUS_CSI2_CHANNEL_2		= BIT(6),
+	V4L2_MBUS_CSI2_CHANNEL_3		= BIT(7),
+	V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		= BIT(8),
+	V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	= BIT(9),
+};
 
 #define V4L2_MBUS_CSI2_LANES		(V4L2_MBUS_CSI2_1_LANE | V4L2_MBUS_CSI2_2_LANE | \
 					 V4L2_MBUS_CSI2_3_LANE | V4L2_MBUS_CSI2_4_LANE)
@@ -69,8 +108,8 @@
 /**
  * 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
+ * @V4L2_MBUS_BT656:	parallel interface with embedded synchronization using ITU-R BT.656
+ * 			signaling. Can also be used for ISO-R BT.1120 signaling.
  * @V4L2_MBUS_CSI1:	MIPI CSI-1 serial interface
  * @V4L2_MBUS_CCP2:	CCP2 (Compact Camera Port 2)
  * @V4L2_MBUS_CSI2:	MIPI CSI-2 serial interface
@@ -86,11 +125,22 @@ enum v4l2_mbus_type {
 /**
  * struct v4l2_mbus_config - media bus configuration
  * @type:	in: interface type
- * @flags:	in / out: configuration flags, depending on @type
+ * @pb_flags:	in / out: configuration flags, if @type is
+ *		%V4L2_MBUS_PARALLEL or %V4L2_MBUS_BT656.
+ * @csi2_flags:	in / out: configuration flags, if @type is
+ *		%V4L2_MBUS_CSI2.
+ * @flag:	access flags, no matter the @type.
+ *		Used just to avoid needing to rewrite the logic inside
+ *		soc_camera and pxa_camera drivers. Don't use on newer
+ * 		drivers!
  */
 struct v4l2_mbus_config {
 	enum v4l2_mbus_type type;
-	unsigned int flags;
+	union {
+		enum v4l2_mbus_parallel_and_bt656_flags	pb_flags;
+		enum v4l2_mbus_csi2_flags		csi2_flags;
+		unsigned int				flag;
+	};
 };
 
 static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
-- 
2.13.6

[PATCH 05/24] media: v4l2-dev: convert VFL_TYPE_* into an enum

[Mauro Carvalho Chehab]

Using enums makes easier to document, as it can use kernel-doc
markups. It also allows cross-referencing, with increases the
kAPI readability.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/kapi/v4l2-dev.rst     | 17 ++++++---
 drivers/media/pci/cx88/cx88-blackbird.c   |  3 +-
 drivers/media/pci/cx88/cx88-video.c       | 10 +++---
 drivers/media/pci/cx88/cx88.h             |  4 +--
 drivers/media/pci/saa7134/saa7134-video.c |  2 ++
 drivers/media/usb/cx231xx/cx231xx-video.c |  2 ++
 drivers/media/usb/pvrusb2/pvrusb2-v4l2.c  |  2 ++
 drivers/media/usb/tm6000/tm6000-video.c   |  2 ++
 drivers/media/v4l2-core/v4l2-dev.c        | 10 +++---
 include/media/v4l2-dev.h                  | 59 +++++++++++++++++--------------
 include/media/v4l2-mediabus.h             | 30 ++++++++++++++++
 11 files changed, 98 insertions(+), 43 deletions(-)

diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
index b29aa616c267..7bb0505b60f1 100644
--- a/Documentation/media/kapi/v4l2-dev.rst
+++ b/Documentation/media/kapi/v4l2-dev.rst
@@ -196,11 +196,18 @@ device.
 Which device is registered depends on the type argument. The following
 types exist:
 
-- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices
-- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext)
-- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners
-- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners
-- ``VFL_TYPE_TOUCH``: ``/dev/v4l-touchX`` for touch sensors
+========================== ====================	 ==============================
+:c:type:`vfl_devnode_type` Device name		 Usage
+========================== ====================	 ==============================
+``VFL_TYPE_GRABBER``       ``/dev/videoX``       for video input/output devices
+``VFL_TYPE_VBI``           ``/dev/vbiX``         for vertical blank data (i.e.
+						 closed captions, teletext)
+``VFL_TYPE_RADIO``         ``/dev/radioX``       for radio tuners
+``VFL_TYPE_SUBDEV``        ``/dev/v4l-subdevX``  for V4L2 subdevices
+``VFL_TYPE_SDR``           ``/dev/swradioX``     for Software Defined Radio
+						 (SDR) tuners
+``VFL_TYPE_TOUCH``         ``/dev/v4l-touchX``   for touch sensors
+========================== ====================	 ==============================
 
 The last argument gives you a certain amount of control over the device
 device node number used (i.e. the X in ``videoX``). Normally you will pass -1
diff --git a/drivers/media/pci/cx88/cx88-blackbird.c b/drivers/media/pci/cx88/cx88-blackbird.c
index e3101f04941c..0e0952e60795 100644
--- a/drivers/media/pci/cx88/cx88-blackbird.c
+++ b/drivers/media/pci/cx88/cx88-blackbird.c
@@ -805,8 +805,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
 
 	strcpy(cap->driver, "cx88_blackbird");
 	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
-	cx88_querycap(file, core, cap);
-	return 0;
+	return cx88_querycap(file, core, cap);
 }
 
 static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
diff --git a/drivers/media/pci/cx88/cx88-video.c b/drivers/media/pci/cx88/cx88-video.c
index 7d25ecd4404b..9be682cdb644 100644
--- a/drivers/media/pci/cx88/cx88-video.c
+++ b/drivers/media/pci/cx88/cx88-video.c
@@ -806,8 +806,8 @@ static int vidioc_s_fmt_vid_cap(struct file *file, void *priv,
 	return 0;
 }
 
-void cx88_querycap(struct file *file, struct cx88_core *core,
-		   struct v4l2_capability *cap)
+int cx88_querycap(struct file *file, struct cx88_core *core,
+		  struct v4l2_capability *cap)
 {
 	struct video_device *vdev = video_devdata(file);
 
@@ -825,11 +825,14 @@ void cx88_querycap(struct file *file, struct cx88_core *core,
 	case VFL_TYPE_VBI:
 		cap->device_caps |= V4L2_CAP_VBI_CAPTURE;
 		break;
+	default:
+		return -EINVAL;
 	}
 	cap->capabilities = cap->device_caps | V4L2_CAP_VIDEO_CAPTURE |
 		V4L2_CAP_VBI_CAPTURE | V4L2_CAP_DEVICE_CAPS;
 	if (core->board.radio.type == CX88_RADIO)
 		cap->capabilities |= V4L2_CAP_RADIO;
+	return 0;
 }
 EXPORT_SYMBOL(cx88_querycap);
 
@@ -841,8 +844,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
 
 	strcpy(cap->driver, "cx8800");
 	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
-	cx88_querycap(file, core, cap);
-	return 0;
+	return cx88_querycap(file, core, cap);
 }
 
 static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
diff --git a/drivers/media/pci/cx88/cx88.h b/drivers/media/pci/cx88/cx88.h
index 6777926f20f2..07a33f02fef4 100644
--- a/drivers/media/pci/cx88/cx88.h
+++ b/drivers/media/pci/cx88/cx88.h
@@ -734,7 +734,7 @@ int cx8802_start_dma(struct cx8802_dev    *dev,
 int cx88_enum_input(struct cx88_core *core, struct v4l2_input *i);
 int cx88_set_freq(struct cx88_core  *core, const struct v4l2_frequency *f);
 int cx88_video_mux(struct cx88_core *core, unsigned int input);
-void cx88_querycap(struct file *file, struct cx88_core *core,
-		   struct v4l2_capability *cap);
+int cx88_querycap(struct file *file, struct cx88_core *core,
+		  struct v4l2_capability *cap);
 
 #endif
diff --git a/drivers/media/pci/saa7134/saa7134-video.c b/drivers/media/pci/saa7134/saa7134-video.c
index 51d42bbf969e..e5e02eab3e23 100644
--- a/drivers/media/pci/saa7134/saa7134-video.c
+++ b/drivers/media/pci/saa7134/saa7134-video.c
@@ -1531,6 +1531,8 @@ int saa7134_querycap(struct file *file, void *priv,
 	case VFL_TYPE_VBI:
 		cap->device_caps |= vbi_caps;
 		break;
+	default:
+		return -EINVAL;
 	}
 	cap->capabilities = radio_caps | video_caps | vbi_caps |
 		cap->device_caps | V4L2_CAP_DEVICE_CAPS;
diff --git a/drivers/media/usb/cx231xx/cx231xx-video.c b/drivers/media/usb/cx231xx/cx231xx-video.c
index 179b8481a870..946306aa4a4e 100644
--- a/drivers/media/usb/cx231xx/cx231xx-video.c
+++ b/drivers/media/usb/cx231xx/cx231xx-video.c
@@ -1756,6 +1756,8 @@ static int cx231xx_v4l2_open(struct file *filp)
 	case VFL_TYPE_RADIO:
 		radio = 1;
 		break;
+	default:
+		return -EINVAL;
 	}
 
 	cx231xx_videodbg("open dev=%s type=%s users=%d\n",
diff --git a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
index 4320bda9352d..864830d4c741 100644
--- a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
+++ b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
@@ -153,6 +153,8 @@ static int pvr2_querycap(struct file *file, void *priv, struct v4l2_capability *
 	case VFL_TYPE_RADIO:
 		cap->device_caps = V4L2_CAP_RADIO;
 		break;
+	default:
+		return -EINVAL;
 	}
 	cap->device_caps |= V4L2_CAP_TUNER | V4L2_CAP_READWRITE;
 	return 0;
diff --git a/drivers/media/usb/tm6000/tm6000-video.c b/drivers/media/usb/tm6000/tm6000-video.c
index ec8c4d2534dc..6b8a2e265762 100644
--- a/drivers/media/usb/tm6000/tm6000-video.c
+++ b/drivers/media/usb/tm6000/tm6000-video.c
@@ -1330,6 +1330,8 @@ static int __tm6000_open(struct file *file)
 	case VFL_TYPE_RADIO:
 		radio = 1;
 		break;
+	default:
+		return -EINVAL;
 	}
 
 	/* If more than one user, mutex should be added */
diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
index c647ba648805..d5e0e536ef04 100644
--- a/drivers/media/v4l2-core/v4l2-dev.c
+++ b/drivers/media/v4l2-core/v4l2-dev.c
@@ -102,7 +102,7 @@ static DECLARE_BITMAP(devnode_nums[VFL_TYPE_MAX], VIDEO_NUM_DEVICES);
 
 #ifdef CONFIG_VIDEO_FIXED_MINOR_RANGES
 /* Return the bitmap corresponding to vfl_type. */
-static inline unsigned long *devnode_bits(int vfl_type)
+static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
 {
 	/* Any types not assigned to fixed minor ranges must be mapped to
 	   one single bitmap for the purposes of finding a free node number
@@ -113,7 +113,7 @@ static inline unsigned long *devnode_bits(int vfl_type)
 }
 #else
 /* Return the bitmap corresponding to vfl_type. */
-static inline unsigned long *devnode_bits(int vfl_type)
+static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
 {
 	return devnode_nums[vfl_type];
 }
@@ -821,8 +821,10 @@ static int video_register_media_controller(struct video_device *vdev, int type)
 	return 0;
 }
 
-int __video_register_device(struct video_device *vdev, int type, int nr,
-		int warn_if_nr_in_use, struct module *owner)
+int __video_register_device(struct video_device *vdev,
+			    enum vfl_devnode_type type,
+			    int nr, int warn_if_nr_in_use,
+			    struct module *owner)
 {
 	int i = 0;
 	int ret;
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index de1a1453cfd9..f182b47dfd71 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -20,13 +20,25 @@
 
 #define VIDEO_MAJOR	81
 
-#define VFL_TYPE_GRABBER	0
-#define VFL_TYPE_VBI		1
-#define VFL_TYPE_RADIO		2
-#define VFL_TYPE_SUBDEV		3
-#define VFL_TYPE_SDR		4
-#define VFL_TYPE_TOUCH		5
-#define VFL_TYPE_MAX		6
+/**
+ * enum vfl_devnode_type - type of V4L2 device node
+ *
+ * @VFL_TYPE_GRABBER:	for video input/output devices
+ * @VFL_TYPE_VBI:	for vertical blank data (i.e. closed captions, teletext)
+ * @VFL_TYPE_RADIO:	for radio tuners
+ * @VFL_TYPE_SUBDEV:	for V4L2 subdevices
+ * @VFL_TYPE_SDR:	for Software Defined Radio tuners
+ * @VFL_TYPE_TOUCH:	for touch sensors
+ */
+enum vfl_devnode_type {
+	VFL_TYPE_GRABBER	= 0,
+	VFL_TYPE_VBI		= 1,
+	VFL_TYPE_RADIO		= 2,
+	VFL_TYPE_SUBDEV		= 3,
+	VFL_TYPE_SDR		= 4,
+	VFL_TYPE_TOUCH		= 5,
+};
+#define VFL_TYPE_MAX VFL_TYPE_TOUCH
 
 /* Is this a receiver, transmitter or mem-to-mem? */
 /* Ignored for VFL_TYPE_SUBDEV. */
@@ -188,7 +200,7 @@ struct v4l2_file_operations {
  * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
  *	 If NULL, then v4l2_dev->prio will be used.
  * @name: video device name
- * @vfl_type: V4L device type
+ * @vfl_type: V4L device type, as defined by &enum vfl_devnode_type
  * @vfl_dir: V4L receiver, transmitter or m2m
  * @minor: device node 'minor'. It is set to -1 if the registration failed
  * @num: number of the video device node
@@ -236,7 +248,7 @@ struct video_device
 
 	/* device info */
 	char name[32];
-	int vfl_type;
+	enum vfl_devnode_type vfl_type;
 	int vfl_dir;
 	int minor;
 	u16 num;
@@ -281,7 +293,7 @@ struct video_device
  * __video_register_device - register video4linux devices
  *
  * @vdev: struct video_device to register
- * @type: type of device to register
+ * @type: type of device to register, as defined by &enum vfl_devnode_type
  * @nr:   which device node number is desired:
  * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  * @warn_if_nr_in_use: warn if the desired device node number
@@ -300,29 +312,22 @@ struct video_device
  *
  * Returns 0 on success.
  *
- * Valid values for @type are:
- *
- *	- %VFL_TYPE_GRABBER - A frame grabber
- *	- %VFL_TYPE_VBI - Vertical blank data (undecoded)
- *	- %VFL_TYPE_RADIO - A radio card
- *	- %VFL_TYPE_SUBDEV - A subdevice
- *	- %VFL_TYPE_SDR - Software Defined Radio
- *	- %VFL_TYPE_TOUCH - A touch sensor
- *
  * .. note::
  *
  *	This function is meant to be used only inside the V4L2 core.
  *	Drivers should use video_register_device() or
  *	video_register_device_no_warn().
  */
-int __must_check __video_register_device(struct video_device *vdev, int type,
-		int nr, int warn_if_nr_in_use, struct module *owner);
+int __must_check __video_register_device(struct video_device *vdev,
+					 enum vfl_devnode_type type,
+					 int nr, int warn_if_nr_in_use,
+					 struct module *owner);
 
 /**
  *  video_register_device - register video4linux devices
  *
  * @vdev: struct video_device to register
- * @type: type of device to register
+ * @type: type of device to register, as defined by &enum vfl_devnode_type
  * @nr:   which device node number is desired:
  * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  *
@@ -336,7 +341,8 @@ int __must_check __video_register_device(struct video_device *vdev, int type,
  *	you video_device_release() should be called on failure.
  */
 static inline int __must_check video_register_device(struct video_device *vdev,
-		int type, int nr)
+						     enum vfl_devnode_type type,
+						     int nr)
 {
 	return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
 }
@@ -345,7 +351,7 @@ static inline int __must_check video_register_device(struct video_device *vdev,
  *  video_register_device_no_warn - register video4linux devices
  *
  * @vdev: struct video_device to register
- * @type: type of device to register
+ * @type: type of device to register, as defined by &enum vfl_devnode_type
  * @nr:   which device node number is desired:
  * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  *
@@ -361,8 +367,9 @@ static inline int __must_check video_register_device(struct video_device *vdev,
  *	is responsible for freeing any data. Usually that means that
  *	you video_device_release() should be called on failure.
  */
-static inline int __must_check video_register_device_no_warn(
-		struct video_device *vdev, int type, int nr)
+static inline int __must_check
+video_register_device_no_warn(struct video_device *vdev,
+			      enum vfl_devnode_type type, int nr)
 {
 	return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
 }
diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index 47adb1608d98..3bfe6bcc8365 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -143,6 +143,13 @@ struct v4l2_mbus_config {
 	};
 };
 
+/**
+ * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ *	v4l2_pix_format fields from a &struct v4l2_mbus_framefmt.
+ *
+ * @pix_fmt:	pointer to &struct v4l2_pix_format to be filled
+ * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
+ */
 static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
 				const struct v4l2_mbus_framefmt *mbus_fmt)
 {
@@ -155,6 +162,15 @@ static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
 	pix_fmt->xfer_func = mbus_fmt->xfer_func;
 }
 
+/**
+ * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format and a
+ *	data format code.
+ *
+ * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
+ * @pix_fmt:	pointer to &struct v4l2_pix_format to be used as model
+ * @code:	data format code (from &enum v4l2_mbus_pixelcode)
+ */
 static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
 			   const struct v4l2_pix_format *pix_fmt,
 			   u32 code)
@@ -169,6 +185,13 @@ static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
 	mbus_fmt->code = code;
 }
 
+/**
+ * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ *	v4l2_pix_format_mplane fields from a media bus structure.
+ *
+ * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be filled
+ * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
+ */
 static inline void v4l2_fill_pix_format_mplane(
 				struct v4l2_pix_format_mplane *pix_mp_fmt,
 				const struct v4l2_mbus_framefmt *mbus_fmt)
@@ -182,6 +205,13 @@ static inline void v4l2_fill_pix_format_mplane(
 	pix_mp_fmt->xfer_func = mbus_fmt->xfer_func;
 }
 
+/**
+ * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format_mplane.
+ *
+ * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
+ * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be used as model
+ */
 static inline void v4l2_fill_mbus_format_mplane(
 				struct v4l2_mbus_framefmt *mbus_fmt,
 				const struct v4l2_pix_format_mplane *pix_mp_fmt)
-- 
2.13.6

[PATCH 06/24] media: i2c-addr.h: get rid of now unused defines

[Mauro Carvalho Chehab]

Some of the previously used I2C addresses there aren't used
anymore. So, get rid of them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/i2c-addr.h | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/include/media/i2c-addr.h b/include/media/i2c-addr.h
index 5d0f56054d26..fba0457b74c4 100644
--- a/include/media/i2c-addr.h
+++ b/include/media/i2c-addr.h
@@ -10,21 +10,14 @@
  */
 
 /* bttv address list */
-#define I2C_ADDR_TSA5522	0xc2
 #define I2C_ADDR_TDA7432	0x8a
 #define I2C_ADDR_TDA8425	0x82
 #define I2C_ADDR_TDA9840	0x84
-#define I2C_ADDR_TDA9850	0xb6 /* also used by 9855,9873 */
 #define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
 #define I2C_ADDR_TDA9875	0xb0
-#define I2C_ADDR_HAUPEE		0xa0
-#define I2C_ADDR_STBEE		0xae
-#define I2C_ADDR_VHX		0xc0
 #define I2C_ADDR_MSP3400	0x80
 #define I2C_ADDR_MSP3400_ALT	0x88
 #define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
-#define I2C_ADDR_DPL3518	0x84
-#define I2C_ADDR_TDA9887	0x86
 
 /*
  * i2c bus addresses for the chips supported by tvaudio.c
-- 
2.13.6

[PATCH 07/24] media: get rid of i2c-addr.h

[Mauro Carvalho Chehab]

In the past, the same I2C address were used on multiple places.
After I2C rebinding changes, this is no longer needed. So, we
can just get rid of this header, placing the I2C address where
they belong, e. g. either at bttv driver or at tvtuner.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/media/i2c/tda7432.c             |  1 -
 drivers/media/i2c/tvaudio.c             |  2 --
 drivers/media/pci/bt8xx/bttv-cards.c    |  7 +++++++
 drivers/media/pci/bt8xx/bttv.h          |  1 -
 drivers/media/usb/em28xx/em28xx-cards.c |  1 -
 drivers/media/usb/tm6000/tm6000-cards.c |  1 -
 include/media/i2c-addr.h                | 35 ---------------------------------
 include/media/i2c/tvaudio.h             | 17 +++++++++++++++-
 8 files changed, 23 insertions(+), 42 deletions(-)
 delete mode 100644 include/media/i2c-addr.h

diff --git a/drivers/media/i2c/tda7432.c b/drivers/media/i2c/tda7432.c
index d87168adee45..1c5c61d829d6 100644
--- a/drivers/media/i2c/tda7432.c
+++ b/drivers/media/i2c/tda7432.c
@@ -36,7 +36,6 @@
 #include <media/v4l2-device.h>
 #include <media/v4l2-ioctl.h>
 #include <media/v4l2-ctrls.h>
-#include <media/i2c-addr.h>
 
 #ifndef VIDEO_AUDIO_BALANCE
 # define VIDEO_AUDIO_BALANCE 32
diff --git a/drivers/media/i2c/tvaudio.c b/drivers/media/i2c/tvaudio.c
index ce86534450ac..92718a9ff5ea 100644
--- a/drivers/media/i2c/tvaudio.c
+++ b/drivers/media/i2c/tvaudio.c
@@ -40,8 +40,6 @@
 #include <media/v4l2-device.h>
 #include <media/v4l2-ctrls.h>
 
-#include <media/i2c-addr.h>
-
 /* ---------------------------------------------------------------------- */
 /* insmod args                                                            */
 
diff --git a/drivers/media/pci/bt8xx/bttv-cards.c b/drivers/media/pci/bt8xx/bttv-cards.c
index 5cc42b426715..7dcf509e66d9 100644
--- a/drivers/media/pci/bt8xx/bttv-cards.c
+++ b/drivers/media/pci/bt8xx/bttv-cards.c
@@ -141,6 +141,13 @@ MODULE_PARM_DESC(audiodev, "specify audio device:\n"
 MODULE_PARM_DESC(saa6588, "if 1, then load the saa6588 RDS module, default (0) is to use the card definition.");
 MODULE_PARM_DESC(no_overlay, "allow override overlay default (0 disables, 1 enables) [some VIA/SIS chipsets are known to have problem with overlay]");
 
+
+/* I2C addresses list */
+#define I2C_ADDR_TDA7432	0x8a
+#define I2C_ADDR_MSP3400	0x80
+#define I2C_ADDR_MSP3400_ALT	0x88
+
+
 /* ----------------------------------------------------------------------- */
 /* list of card IDs for bt878+ cards                                       */
 
diff --git a/drivers/media/pci/bt8xx/bttv.h b/drivers/media/pci/bt8xx/bttv.h
index 91301c3cad1e..faea9aeff711 100644
--- a/drivers/media/pci/bt8xx/bttv.h
+++ b/drivers/media/pci/bt8xx/bttv.h
@@ -17,7 +17,6 @@
 #include <linux/videodev2.h>
 #include <linux/i2c.h>
 #include <media/v4l2-device.h>
-#include <media/i2c-addr.h>
 #include <media/tuner.h>
 
 /* ---------------------------------------------------------- */
diff --git a/drivers/media/usb/em28xx/em28xx-cards.c b/drivers/media/usb/em28xx/em28xx-cards.c
index 4c57fd7929cb..34e16f6ab4ac 100644
--- a/drivers/media/usb/em28xx/em28xx-cards.c
+++ b/drivers/media/usb/em28xx/em28xx-cards.c
@@ -36,7 +36,6 @@
 #include <media/i2c/saa7115.h>
 #include <dt-bindings/media/tvp5150.h>
 #include <media/i2c/tvaudio.h>
-#include <media/i2c-addr.h>
 #include <media/tveeprom.h>
 #include <media/v4l2-common.h>
 #include <sound/ac97_codec.h>
diff --git a/drivers/media/usb/tm6000/tm6000-cards.c b/drivers/media/usb/tm6000/tm6000-cards.c
index 2537643a1808..b4df9181c54b 100644
--- a/drivers/media/usb/tm6000/tm6000-cards.c
+++ b/drivers/media/usb/tm6000/tm6000-cards.c
@@ -23,7 +23,6 @@
 #include <media/v4l2-common.h>
 #include <media/tuner.h>
 #include <media/i2c/tvaudio.h>
-#include <media/i2c-addr.h>
 #include <media/rc-map.h>
 
 #include "tm6000.h"
diff --git a/include/media/i2c-addr.h b/include/media/i2c-addr.h
deleted file mode 100644
index fba0457b74c4..000000000000
--- a/include/media/i2c-addr.h
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- *	V4L I2C address list
- *
- *
- *	Copyright (C) 2006 Mauro Carvalho Chehab <mchehab@infradead.org>
- *	Based on a previous mapping by
- *	Ralph Metzler (rjkm@thp.uni-koeln.de)
- *	Gerd Knorr <kraxel@goldbach.in-berlin.de>
- *
- */
-
-/* bttv address list */
-#define I2C_ADDR_TDA7432	0x8a
-#define I2C_ADDR_TDA8425	0x82
-#define I2C_ADDR_TDA9840	0x84
-#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
-#define I2C_ADDR_TDA9875	0xb0
-#define I2C_ADDR_MSP3400	0x80
-#define I2C_ADDR_MSP3400_ALT	0x88
-#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
-
-/*
- * i2c bus addresses for the chips supported by tvaudio.c
- */
-
-#define I2C_ADDR_TDA8425	0x82
-#define I2C_ADDR_TDA9840	0x84 /* also used by TA8874Z */
-#define I2C_ADDR_TDA985x_L	0xb4 /* also used by 9873 */
-#define I2C_ADDR_TDA985x_H	0xb6
-#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
-
-#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
-#define I2C_ADDR_TEA6420	0x98
-
-#define I2C_ADDR_PIC16C54	0x96 /* PV951 */
diff --git a/include/media/i2c/tvaudio.h b/include/media/i2c/tvaudio.h
index 1ac8184693f8..f13e1a386364 100644
--- a/include/media/i2c/tvaudio.h
+++ b/include/media/i2c/tvaudio.h
@@ -21,7 +21,22 @@
 #ifndef _TVAUDIO_H
 #define _TVAUDIO_H
 
-#include <media/i2c-addr.h>
+/*
+ * i2c bus addresses for the chips supported by tvaudio.c
+ */
+
+#define I2C_ADDR_TDA8425	0x82
+#define I2C_ADDR_TDA9840	0x84
+#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
+#define I2C_ADDR_TDA9875	0xb0
+#define I2C_ADDR_TDA8425	0x82
+#define I2C_ADDR_TDA9840	0x84 /* also used by TA8874Z */
+#define I2C_ADDR_TDA985x_L	0xb4 /* also used by 9873 */
+#define I2C_ADDR_TDA985x_H	0xb6
+#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
+#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
+#define I2C_ADDR_TEA6420	0x98
+#define I2C_ADDR_PIC16C54	0x96 /* PV951 */
 
 /* The tvaudio module accepts the following inputs: */
 #define TVAUDIO_INPUT_TUNER  0
-- 
2.13.6

[PATCH 08/24] media: v4l2-dev: document VFL_DIR_* direction defines

[Mauro Carvalho Chehab]

The V4L_DIR_* direction flags document the direction for a
V4L2 device node. Convert them to enum and document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-dev.h | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index f182b47dfd71..87dac58c7799 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -40,11 +40,21 @@ enum vfl_devnode_type {
 };
 #define VFL_TYPE_MAX VFL_TYPE_TOUCH
 
-/* Is this a receiver, transmitter or mem-to-mem? */
-/* Ignored for VFL_TYPE_SUBDEV. */
-#define VFL_DIR_RX		0
-#define VFL_DIR_TX		1
-#define VFL_DIR_M2M		2
+/**
+ * enum  vfl_direction - Identifies if a &struct video_device corresponds
+ *	to a receiver, a transmitter or a mem-to-mem device.
+ *
+ * @VFL_DIR_RX:		device is a receiver.
+ * @VFL_DIR_TX:		device is a transmitter.
+ * @VFL_DIR_M2M:	device is a memory to memory device.
+ *
+ * Note: Ignored if &enum vfl_devnode_type is %VFL_TYPE_SUBDEV.
+ */
+enum vfl_devnode_direction {
+	VFL_DIR_RX,
+	VFL_DIR_TX,
+	VFL_DIR_M2M,
+};
 
 struct v4l2_ioctl_callbacks;
 struct video_device;
@@ -249,7 +259,7 @@ struct video_device
 	/* device info */
 	char name[32];
 	enum vfl_devnode_type vfl_type;
-	int vfl_dir;
+	enum vfl_devnode_direction vfl_dir;
 	int minor;
 	u16 num;
 	unsigned long flags;
-- 
2.13.6

[PATCH 09/24] media: v4l2-dev: document video_device flags

[Mauro Carvalho Chehab]

Convert #defines to enums and add kernel-doc markups for V4L2
video_device flags.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-dev.h | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 87dac58c7799..33a5256232f8 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -61,12 +61,22 @@ struct video_device;
 struct v4l2_device;
 struct v4l2_ctrl_handler;
 
-/* Flag to mark the video_device struct as registered.
-   Drivers can clear this flag if they want to block all future
-   device access. It is cleared by video_unregister_device. */
-#define V4L2_FL_REGISTERED	(0)
-/* file->private_data points to struct v4l2_fh */
-#define V4L2_FL_USES_V4L2_FH	(1)
+/**
+ * enum v4l2_video_device_flags - Flags used by &struct video_device
+ *
+ * @V4L2_FL_REGISTERED:
+ * 	indicates that a &struct video_device is registered.
+ *	Drivers can clear this flag if they want to block all future
+ *	device access. It is cleared by video_unregister_device.
+ * @V4L2_FL_USES_V4L2_FH:
+ *	indicates that file->private_data points to &struct v4l2_fh.
+ *	This flag is set by the core when v4l2_fh_init() is called.
+ *	All new drivers should use it.
+ */
+enum v4l2_video_device_flags {
+	V4L2_FL_REGISTERED	= 0,
+	V4L2_FL_USES_V4L2_FH	= 1,
+};
 
 /* Priority helper functions */
 
@@ -214,7 +224,8 @@ struct v4l2_file_operations {
  * @vfl_dir: V4L receiver, transmitter or m2m
  * @minor: device node 'minor'. It is set to -1 if the registration failed
  * @num: number of the video device node
- * @flags: video device flags. Use bitops to set/clear/test flags
+ * @flags: video device flags. Use bitops to set/clear/test flags.
+ *	   Contains a set of &enum v4l2_video_device_flags.
  * @index: attribute to differentiate multiple indices on one physical device
  * @fh_lock: Lock for all v4l2_fhs
  * @fh_list: List of &struct v4l2_fh
-- 
2.13.6

[PATCH 10/24] media: v4l2-subdev: use kernel-doc markups to document subdev flags

[Mauro Carvalho Chehab]

Right now, those are documented together with the subdev struct,
instead of together with the definitions.

Convert the definitions to an enum, use BIT() macros and document
it at its right place.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-subdev.h | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index e83872078376..6286c69a12ba 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -18,6 +18,7 @@
 #define _V4L2_SUBDEV_H
 
 #include <linux/types.h>
+#include <linux/bitops.h>
 #include <linux/v4l2-subdev.h>
 #include <media/media-entity.h>
 #include <media/v4l2-async.h>
@@ -734,14 +735,23 @@ struct v4l2_subdev_internal_ops {
 
 #define V4L2_SUBDEV_NAME_SIZE 32
 
-/* Set this flag if this subdev is a i2c device. */
-#define V4L2_SUBDEV_FL_IS_I2C			(1U << 0)
-/* Set this flag if this subdev is a spi device. */
-#define V4L2_SUBDEV_FL_IS_SPI			(1U << 1)
-/* Set this flag if this subdev needs a device node. */
-#define V4L2_SUBDEV_FL_HAS_DEVNODE		(1U << 2)
-/* Set this flag if this subdev generates events. */
-#define V4L2_SUBDEV_FL_HAS_EVENTS		(1U << 3)
+/**
+ * enum v4l2_subdev_flags - flags used to describe a sub-device
+ *	at &struct v4l2_subdev.
+ *
+ * @V4L2_SUBDEV_FL_IS_I2C: set this flag if this subdev is an I2C device;
+ * @V4L2_SUBDEV_FL_IS_SPI: set this flag if this subdev is a SPI device;
+ * @V4L2_SUBDEV_FL_HAS_DEVNODE: set this flag if this subdev needs
+ *				a device node;
+ * @V4L2_SUBDEV_FL_HAS_EVENTS: set this flag if this subdev
+ *			       generates events.
+ */
+enum v4l2_subdev_flags {
+	V4L2_SUBDEV_FL_IS_I2C		= BIT(0),
+	V4L2_SUBDEV_FL_IS_SPI		= BIT(1),
+	V4L2_SUBDEV_FL_HAS_DEVNODE	= BIT(2),
+	V4L2_SUBDEV_FL_HAS_EVENTS	= BIT(3),
+};
 
 struct regulator_bulk_data;
 
@@ -767,13 +777,7 @@ struct v4l2_subdev_platform_data {
  * @owner: The owner is the same as the driver's &struct device owner.
  * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
  *	ownner. Initialized by v4l2_device_register_subdev().
- * @flags: subdev flags. Can be:
- *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
- *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
- *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
- *   device node;
- *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
- *   events.
+ * @flags: subdev flags, as defined by &enum v4l2_subdev_flags.
  *
  * @v4l2_dev: pointer to struct &v4l2_device
  * @ops: pointer to struct &v4l2_subdev_ops
@@ -808,7 +812,7 @@ struct v4l2_subdev {
 	struct list_head list;
 	struct module *owner;
 	bool owner_v4l2_dev;
-	u32 flags;
+	enum v4l2_subdev_flags flags;
 	struct v4l2_device *v4l2_dev;
 	const struct v4l2_subdev_ops *ops;
 	const struct v4l2_subdev_internal_ops *internal_ops;
-- 
2.13.6

[PATCH 11/24] media: v4l2-subdev: create cross-references for ioctls

[Mauro Carvalho Chehab]

When generating Sphinx output, create cross-references for the
callbacks for each ioctl.

While here, fix a few wrong names for ioctls.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-subdev.h | 65 ++++++++++++++++++++++++---------------------
 1 file changed, 34 insertions(+), 31 deletions(-)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 6286c69a12ba..b299cf63972b 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -141,7 +141,7 @@ struct v4l2_subdev_io_pin_config {
 /**
  * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
  *
- * @log_status: callback for %VIDIOC_LOG_STATUS ioctl handler code.
+ * @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
@@ -169,9 +169,9 @@ struct v4l2_subdev_io_pin_config {
  * @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.
+ * @g_register: callback for VIDIOC_DBG_G_REGISTER() ioctl handler code.
  *
- * @s_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
+ * @s_register: callback for VIDIOC_DBG_S_REGISTER() ioctl handler code.
  *
  * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
  *	mode (on == 1).
@@ -216,25 +216,25 @@ struct v4l2_subdev_core_ops {
  * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
  *	in radio mode.
  *
- * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
+ * @s_radio: callback for VIDIOC_S_RADIO() ioctl handler code.
  *
- * @s_frequency: callback for %VIDIOC_S_FREQUENCY ioctl handler code.
+ * @s_frequency: callback for VIDIOC_S_FREQUENCY() ioctl handler code.
  *
- * @g_frequency: callback for %VIDIOC_G_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.
+ * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS() ioctl handler code.
  *
- * @g_tuner: callback for %VIDIOC_G_TUNER 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
+ * @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.
+ * @g_modulator: callback for VIDIOC_G_MODULATOR() ioctl handler code.
  *
- * @s_modulator: callback for %VIDIOC_S_MODULATOR ioctl handler code.
+ * @s_modulator: callback for VIDIOC_S_MODULATOR() ioctl handler code.
  *
  * @s_type_addr: sets tuner type and its I2C addr.
  *
@@ -333,9 +333,9 @@ struct v4l2_mbus_frame_desc {
  *	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.
+ * @g_std: callback for VIDIOC_G_STD() ioctl handler code.
  *
- * @s_std: callback for %VIDIOC_S_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.
@@ -343,7 +343,7 @@ struct v4l2_mbus_frame_desc {
  * @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.
+ * @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.
@@ -359,13 +359,15 @@ struct v4l2_mbus_frame_desc {
  *
  * @g_pixelaspect: callback to return the pixelaspect ratio.
  *
- * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code.
+ * @g_parm: callback for VIDIOC_G_PARM() ioctl handler code.
  *
- * @s_parm: callback for %VIDIOC_S_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.
+ * @g_frame_interval: callback for VIDIOC_SUBDEV_G_FRAME_INTERVAL()
+ *		      ioctl handler code.
  *
- * @s_frame_interval: callback for %VIDIOC_S_FRAMEINTERVAL ioctl handler code.
+ * @s_frame_interval: callback for VIDIOC_SUBDEV_S_FRAME_INTERVAL()
+ *		      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
@@ -373,7 +375,7 @@ struct v4l2_mbus_frame_desc {
  *
  * @g_dv_timings: Get custom dv timings in the sub device.
  *
- * @query_dv_timings: callback for %VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
+ * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS() ioctl handler code.
  *
  * @g_mbus_config: get supported mediabus configurations
  *
@@ -444,7 +446,8 @@ struct v4l2_subdev_video_ops {
  *	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.
+ * @g_sliced_vbi_cap: callback for VIDIOC_G_SLICED_VBI_CAP() ioctl handler
+ *		      code.
  *
  * @s_raw_fmt: setup the video encoder/decoder for raw VBI.
  *
@@ -611,30 +614,30 @@ struct v4l2_subdev_pad_config {
  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
  *
  * @init_cfg: initialize the pad config to default values
- * @enum_mbus_code: callback for %VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
+ * @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
+ * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE() ioctl handler
  *		     code.
  *
- * @enum_frame_interval: callback for %VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
+ * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL() ioctl
  *			 handler code.
  *
- * @get_fmt: callback for %VIDIOC_SUBDEV_G_FMT 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.
+ * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT() ioctl handler code.
  *
- * @get_selection: callback for %VIDIOC_SUBDEV_G_SELECTION 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.
+ * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION() ioctl handler code.
  *
- * @get_edid: callback for %VIDIOC_SUBDEV_G_EDID 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.
+ * @set_edid: callback for VIDIOC_SUBDEV_S_EDID() ioctl handler code.
  *
- * @dv_timings_cap: callback for %VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
+ * @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
+ * @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
-- 
2.13.6

[PATCH 12/24] media: v4l2-subdev: fix description of tuner.s_radio ops

[Mauro Carvalho Chehab]

The description there is completely broken and it mentions
an ioctl that doesn't exist.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-subdev.h | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index b299cf63972b..c43e3d650fe6 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -216,7 +216,10 @@ struct v4l2_subdev_core_ops {
  * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
  *	in radio mode.
  *
- * @s_radio: callback for VIDIOC_S_RADIO() ioctl handler code.
+ * @s_radio: callback that switches the tuner to radio mode.
+ *	     drivers should explicitly call it when a tuner ops should
+ *	     operate on radio mode, before being able to handle it.
+ *	     Used on devices that have both AM/FM radio receiver and TV.
  *
  * @s_frequency: callback for VIDIOC_S_FREQUENCY() ioctl handler code.
  *
@@ -239,6 +242,22 @@ struct v4l2_subdev_core_ops {
  * @s_type_addr: sets tuner type and its I2C addr.
  *
  * @s_config: sets tda9887 specific stuff, like port1, port2 and qss
+ *
+ * .. note::
+ *
+ * 	On devices that have both AM/FM and TV, it is up to the driver
+ *	to explicitly call s_radio when the tuner should be switched to
+ *	radio mode, before handling other &struct v4l2_subdev_tuner_ops
+ *	that would require it. An example of such usage is::
+ *
+ *	  static void s_frequency(void *priv, const struct v4l2_frequency *f)
+ *	  {
+ * 		...
+ *		if (f.type == V4L2_TUNER_RADIO)
+ *			v4l2_device_call_all(v4l2_dev, 0, tuner, s_radio);
+ *		...
+ *		v4l2_device_call_all(v4l2_dev, 0, tuner, s_frequency);
+ *	  }
  */
 struct v4l2_subdev_tuner_ops {
 	int (*s_radio)(struct v4l2_subdev *sd);
-- 
2.13.6

[PATCH 13/24] media: v4l2-subdev: better document IO pin configuration flags

[Mauro Carvalho Chehab]

Convert V4L2_SUBDEV_IO_PIN_* to enums, use BIT() and document
via kernel-doc.

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

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index c43e3d650fe6..249604bbd3cb 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -109,22 +109,31 @@ struct v4l2_decode_vbi_line {
  * not yet implemented) since ops provide proper type-checking.
  */
 
-/* Subdevice external IO pin configuration */
-#define V4L2_SUBDEV_IO_PIN_DISABLE	(1 << 0) /* ENABLE assumed */
-#define V4L2_SUBDEV_IO_PIN_OUTPUT	(1 << 1)
-#define V4L2_SUBDEV_IO_PIN_INPUT	(1 << 2)
-#define V4L2_SUBDEV_IO_PIN_SET_VALUE	(1 << 3) /* Set output value */
-#define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW	(1 << 4) /* ACTIVE HIGH assumed */
+/**
+ * enum v4l2_subdev_io_pin_flags - Subdevice external IO pin configuration
+ *	flags
+ *
+ * @V4L2_SUBDEV_IO_PIN_DISABLE: disables a pin config. ENABLE assumed.
+ * @V4L2_SUBDEV_IO_PIN_OUTPUT: set it if pin is an output.
+ * @V4L2_SUBDEV_IO_PIN_INPUT: set it if pin is an input.
+ * @V4L2_SUBDEV_IO_PIN_SET_VALUE: to set the output value via
+ * 				  &struct v4l2_subdev_io_pin_config->value.
+ * @V4L2_SUBDEV_IO_PIN_ACTIVE_LOW: pin active is bit 0.
+ *				   Otherwise, ACTIVE HIGH is assumed.
+ */
+enum v4l2_subdev_io_pin_flags {
+	V4L2_SUBDEV_IO_PIN_DISABLE	= BIT(0),
+	V4L2_SUBDEV_IO_PIN_OUTPUT	= BIT(1),
+	V4L2_SUBDEV_IO_PIN_INPUT	= BIT(2),
+	V4L2_SUBDEV_IO_PIN_SET_VALUE	= BIT(3),
+	V4L2_SUBDEV_IO_PIN_ACTIVE_LOW	= BIT(4),
+};
 
 /**
  * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
  *
- * @flags: bitmask with flags for this pin's config:
- *	   %V4L2_SUBDEV_IO_PIN_DISABLE - disables a pin config,
- *	   %V4L2_SUBDEV_IO_PIN_OUTPUT - if pin is an output,
- *	   %V4L2_SUBDEV_IO_PIN_INPUT - if pin is an input,
- *	   %V4L2_SUBDEV_IO_PIN_SET_VALUE - to set the output value via @value
- *	   and %V4L2_SUBDEV_IO_PIN_ACTIVE_LOW - if active is 0.
+ * @flags: bitmask with flags for this pin's config, as defined by
+ *	   &enum v4l2_subdev_io_pin_flags.
  * @pin: Chip external IO pin to configure
  * @function: Internal signal pad/function to route to IO pin
  * @value: Initial value for pin - e.g. GPIO output value
-- 
2.13.6

[PATCH 14/24] media: v4l2-subdev: convert frame description to enum

[Mauro Carvalho Chehab]

As kernel-doc doesn't support documenting #define values,
and using enum makes easier to identify where the values
are used, convert V4L2_MBUS_FRAME_DESC_FL_* to enum, and
use BIT() macro.

While here, fix the description at v4l2_mbus_frame_desc_entry,
in order to match what's described for
V4L2_MBUS_FRAME_DESC_FL_LEN_MAX.

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

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 249604bbd3cb..1f34045f07ce 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -314,25 +314,32 @@ struct v4l2_subdev_audio_ops {
 	int (*s_stream)(struct v4l2_subdev *sd, int enable);
 };
 
-/* Indicates the @length field specifies maximum data length. */
-#define V4L2_MBUS_FRAME_DESC_FL_LEN_MAX		(1U << 0)
-/*
- * Indicates that the format does not have line offsets, i.e. the
- * receiver should use 1D DMA.
+/**
+ * enum v4l2_mbus_frame_desc_entry - media bus frame description flags
+ *
+ * @V4L2_MBUS_FRAME_DESC_FL_LEN_MAX:
+ *	Indicates that &struct v4l2_mbus_frame_desc_entry->length field
+ *	specifies maximum data length.
+ * @V4L2_MBUS_FRAME_DESC_FL_BLOB:
+ *	Indicates that the format does not have line offsets, i.e.
+ *	the receiver should use 1D DMA.
  */
-#define V4L2_MBUS_FRAME_DESC_FL_BLOB		(1U << 1)
+enum v4l2_mbus_frame_desc_flags {
+	V4L2_MBUS_FRAME_DESC_FL_LEN_MAX	= BIT(0),
+	V4L2_MBUS_FRAME_DESC_FL_BLOB	= BIT(1),
+};
 
 /**
  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
  *
- * @flags: bitmask flags: %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX and
- *			  %V4L2_MBUS_FRAME_DESC_FL_BLOB.
- * @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
- *	    is set
+ * @flags:	bitmask flags, as defined by &enum v4l2_mbus_frame_desc_flags.
+ * @pixelcode:	media bus pixel code, valid if @flags
+ * 		%FRAME_DESC_FL_BLOB is not set.
+ * @length:	number of octets per frame, valid if @flags
+ *		%V4L2_MBUS_FRAME_DESC_FL_LEN_MAX is set.
  */
 struct v4l2_mbus_frame_desc_entry {
-	u16 flags;
+	enum v4l2_mbus_frame_desc_flags flags;
 	u32 pixelcode;
 	u32 length;
 };
-- 
2.13.6

[PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Mauro Carvalho Chehab]

The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
3 functions that have the same arguments. The code of those
functions is simple enough to just declare them, de-obfuscating
the code.

While here, replace BUG_ON() by WARN_ON() as there's no reason
why to panic the Kernel if this fails.

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

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 1f34045f07ce..35c4476c56ee 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -897,19 +897,32 @@ struct v4l2_subdev_fh {
 	container_of(fh, struct v4l2_subdev_fh, vfh)
 
 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
-#define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)		\
-	static inline struct rtype *					\
-	fun_name(struct v4l2_subdev *sd,				\
-		 struct v4l2_subdev_pad_config *cfg,			\
-		 unsigned int pad)					\
-	{								\
-		BUG_ON(pad >= sd->entity.num_pads);			\
-		return &cfg[pad].field_name;				\
-	}
+static inline struct v4l2_mbus_framefmt
+*v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
+			    struct v4l2_subdev_pad_config *cfg,
+			    unsigned int pad)
+{
+	WARN_ON(pad >= sd->entity.num_pads);
+	return &cfg[pad].try_fmt;
+}
 
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, v4l2_subdev_get_try_format, try_fmt)
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_crop, try_crop)
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
+static inline struct v4l2_rect
+*v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
+			  struct v4l2_subdev_pad_config *cfg,
+			  unsigned int pad)
+{
+	WARN_ON(pad >= sd->entity.num_pads);
+	return &cfg[pad].try_crop;
+}
+
+static inline struct v4l2_rect
+*v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
+			     struct v4l2_subdev_pad_config *cfg,
+			     unsigned int pad)
+{
+	WARN_ON(pad >= sd->entity.num_pads);
+	return &cfg[pad].try_compose;
+}
 #endif
 
 extern const struct v4l2_file_operations v4l2_subdev_fops;
-- 
2.13.6

[PATCH 16/24] media: v4l2-subdev: document remaining undocumented functions

[Mauro Carvalho Chehab]

There are several undocumented v4l2-subdev functions that are
part of kAPI. Document them.

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

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 35c4476c56ee..e215732eed45 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -868,6 +868,13 @@ struct v4l2_subdev {
 	struct v4l2_subdev_platform_data *pdata;
 };
 
+
+/**
+ * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from
+ *     the &struct media_entity embedded on it.
+ *
+ * @ent: pointer to &struct media_entity.
+ */
 #define media_entity_to_v4l2_subdev(ent)				\
 ({									\
 	typeof(ent) __me_sd_ent = (ent);				\
@@ -877,14 +884,20 @@ struct v4l2_subdev {
 		NULL;							\
 })
 
+/**
+ * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from
+ *     the &struct video_device embedded on it.
+ *
+ * @vdev: pointer to &struct video_device
+ */
 #define vdev_to_v4l2_subdev(vdev) \
 	((struct v4l2_subdev *)video_get_drvdata(vdev))
 
 /**
  * struct v4l2_subdev_fh - Used for storing subdev information per file handle
  *
- * @vfh: pointer to struct v4l2_fh
- * @pad: pointer to v4l2_subdev_pad_config
+ * @vfh: pointer to &struct v4l2_fh
+ * @pad: pointer to &struct v4l2_subdev_pad_config
  */
 struct v4l2_subdev_fh {
 	struct v4l2_fh vfh;
@@ -893,10 +906,25 @@ struct v4l2_subdev_fh {
 #endif
 };
 
+/**
+ * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from
+ *     the &struct v4l2_fh embedded on it.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ */
 #define to_v4l2_subdev_fh(fh)	\
 	container_of(fh, struct v4l2_subdev_fh, vfh)
 
 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
+
+/**
+ * v4l2_subdev_get_try_format - ancillary routine to call
+ * 	&struct v4l2_subdev_pad_config->try_fmt
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @cfg: pointer to &struct v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_mbus_framefmt
 *v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
 			    struct v4l2_subdev_pad_config *cfg,
@@ -906,6 +934,14 @@ static inline struct v4l2_mbus_framefmt
 	return &cfg[pad].try_fmt;
 }
 
+/**
+ * v4l2_subdev_get_try_crop - ancillary routine to call
+ * 	&struct v4l2_subdev_pad_config->try_crop
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @cfg: pointer to &struct v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_rect
 *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
 			  struct v4l2_subdev_pad_config *cfg,
@@ -915,6 +951,14 @@ static inline struct v4l2_rect
 	return &cfg[pad].try_crop;
 }
 
+/**
+ * v4l2_subdev_get_try_crop - ancillary routine to call
+ * 	&struct v4l2_subdev_pad_config->try_compose
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @cfg: pointer to &struct v4l2_subdev_pad_config array.
+ * @pad: index of the pad a the @cfg array.
+ */
 static inline struct v4l2_rect
 *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
 			     struct v4l2_subdev_pad_config *cfg,
@@ -1030,9 +1074,17 @@ void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
 void v4l2_subdev_init(struct v4l2_subdev *sd,
 		      const struct v4l2_subdev_ops *ops);
 
-/*
- * Call an ops of a v4l2_subdev, doing the right checks against
- * NULL pointers.
+/**
+ * v4l2_subdev_call - call an ops of a v4l2_subdev, doing the right checks
+ *	against NULL pointers.
+ *
+ * @sd: pointer to the &struct v4l2_subdev
+ * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
+ *     Each element there groups a set of callbacks functions.
+ * @f: callback function that will be called if @cond matches.
+ *     The callback functions are defined in groups, according to
+ *     each element at &struct v4l2_subdev_ops.
+ * @args...: arguments for @f.
  *
  * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
  */
@@ -1048,6 +1100,14 @@ void v4l2_subdev_init(struct v4l2_subdev *sd,
 		__result;						\
 	})
 
+/**
+ * v4l2_subdev_has_op - Checks if a subdev defines a certain ops.
+ *
+ * @sd: pointer to the &struct v4l2_subdev
+ * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
+ *     Each element there groups a set of callbacks functions.
+ * @f: callback function to be checked for its existence.
+ */
 #define v4l2_subdev_has_op(sd, o, f) \
 	((sd)->ops->o && (sd)->ops->o->f)
 
-- 
2.13.6

[PATCH 17/24] media: v4l2-subdev: fix a typo

[Mauro Carvalho Chehab]

ownner -> owner

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-subdev.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index e215732eed45..345da052618c 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -814,7 +814,7 @@ struct v4l2_subdev_platform_data {
  * @list: List of sub-devices
  * @owner: The owner is the same as the driver's &struct device owner.
  * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
- *	ownner. Initialized by v4l2_device_register_subdev().
+ *	owner. Initialized by v4l2_device_register_subdev().
  * @flags: subdev flags, as defined by &enum v4l2_subdev_flags.
  *
  * @v4l2_dev: pointer to struct &v4l2_device
-- 
2.13.6

[PATCH 18/24] media: vb2-core: use bitops for bits

[Mauro Carvalho Chehab]

Use the existing macros to identify vb2_io_modes bits.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/videobuf2-core.h | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 5f4df060affb..0308d8439049 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -16,6 +16,7 @@
 #include <linux/mutex.h>
 #include <linux/poll.h>
 #include <linux/dma-buf.h>
+#include <linux/bitops.h>
 
 #define VB2_MAX_FRAME	(32)
 #define VB2_MAX_PLANES	(8)
@@ -191,11 +192,11 @@ struct vb2_plane {
  * @VB2_DMABUF:		driver supports DMABUF with streaming API
  */
 enum vb2_io_modes {
-	VB2_MMAP	= (1 << 0),
-	VB2_USERPTR	= (1 << 1),
-	VB2_READ	= (1 << 2),
-	VB2_WRITE	= (1 << 3),
-	VB2_DMABUF	= (1 << 4),
+	VB2_MMAP	= BIT(0),
+	VB2_USERPTR	= BIT(1),
+	VB2_READ	= BIT(2),
+	VB2_WRITE	= BIT(3),
+	VB2_DMABUF	= BIT(4),
 };
 
 /**
-- 
2.13.6

[PATCH 19/24] media: vb2-core: Improve kernel-doc markups

[Mauro Carvalho Chehab]

There are several issues on the current markups:
- lack of cross-references;
- wrong cross-references;
- lack of a period of the end of several phrases;
- Some descriptions can be enhanced.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/videobuf2-core.h | 376 ++++++++++++++++++++++-------------------
 1 file changed, 204 insertions(+), 172 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 0308d8439049..e145f1475ffe 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -46,7 +46,7 @@ struct vb2_fileio_data;
 struct vb2_threadio_data;
 
 /**
- * struct vb2_mem_ops - memory handling/memory allocator operations
+ * struct vb2_mem_ops - memory handling/memory allocator operations.
  * @alloc:	allocate video memory and, optionally, allocator private data,
  *		return ERR_PTR() on failure or a pointer to allocator private,
  *		per-buffer data on success; the returned private structure
@@ -146,27 +146,28 @@ struct vb2_mem_ops {
 };
 
 /**
- * struct vb2_plane - plane information
- * @mem_priv:	private data with this plane
- * @dbuf:	dma_buf - shared buffer object
+ * struct vb2_plane - plane information.
+ * @mem_priv:	private data with this plane.
+ * @dbuf:	dma_buf - shared buffer object.
  * @dbuf_mapped:	flag to show whether dbuf is mapped or not
- * @bytesused:	number of bytes occupied by data in the plane (payload)
- * @length:	size of this plane (NOT the payload) in bytes
+ * @bytesused:	number of bytes occupied by data in the plane (payload).
+ * @length:	size of this plane (NOT the payload) in bytes.
  * @min_length:	minimum required size of this plane (NOT the payload) in bytes.
  *		@length is always greater or equal to @min_length.
- * @m:		Union with memtype-specific data
+ * @m:		Union with memtype-specific data.
  * @m.offset:	when memory in the associated struct vb2_buffer is
  *		%VB2_MEMORY_MMAP, equals the offset from the start of
  *		the device memory for this plane (or is a "cookie" that
- *		should be passed to mmap() called on the video node)
+ *		should be passed to mmap() called on the video node).
  * @m.userptr:	when memory is %VB2_MEMORY_USERPTR, a userspace pointer
- *		pointing to this plane
+ *		pointing to this plane.
  * @m.fd:	when memory is %VB2_MEMORY_DMABUF, a userspace file
- *		descriptor associated with this plane
+ *		descriptor associated with this plane.
  * @data_offset:	offset in the plane to the start of data; usually 0,
- *		unless there is a header in front of the data
+ *		unless there is a header in front of the data.
+ *
  * Should contain enough information to be able to cover all the fields
- * of &struct v4l2_plane at videodev2.h
+ * of &struct v4l2_plane at videodev2.h.
  */
 struct vb2_plane {
 	void			*mem_priv;
@@ -184,12 +185,12 @@ struct vb2_plane {
 };
 
 /**
- * enum vb2_io_modes - queue access methods
- * @VB2_MMAP:		driver supports MMAP with streaming API
- * @VB2_USERPTR:	driver supports USERPTR with streaming API
- * @VB2_READ:		driver supports read() style access
- * @VB2_WRITE:		driver supports write() style access
- * @VB2_DMABUF:		driver supports DMABUF with streaming API
+ * enum vb2_io_modes - queue access methods.
+ * @VB2_MMAP:		driver supports MMAP with streaming API.
+ * @VB2_USERPTR:	driver supports USERPTR with streaming API.
+ * @VB2_READ:		driver supports read() style access.
+ * @VB2_WRITE:		driver supports write() style access.
+ * @VB2_DMABUF:		driver supports DMABUF with streaming API.
  */
 enum vb2_io_modes {
 	VB2_MMAP	= BIT(0),
@@ -200,19 +201,19 @@ enum vb2_io_modes {
 };
 
 /**
- * enum vb2_buffer_state - current video buffer state
- * @VB2_BUF_STATE_DEQUEUED:	buffer under userspace control
- * @VB2_BUF_STATE_PREPARING:	buffer is being prepared in videobuf
- * @VB2_BUF_STATE_PREPARED:	buffer prepared in videobuf and by the driver
- * @VB2_BUF_STATE_QUEUED:	buffer queued in videobuf, but not in driver
- * @VB2_BUF_STATE_REQUEUEING:	re-queue a buffer to the driver
+ * enum vb2_buffer_state - current video buffer state.
+ * @VB2_BUF_STATE_DEQUEUED:	buffer under userspace control.
+ * @VB2_BUF_STATE_PREPARING:	buffer is being prepared in videobuf.
+ * @VB2_BUF_STATE_PREPARED:	buffer prepared in videobuf and by the driver.
+ * @VB2_BUF_STATE_QUEUED:	buffer queued in videobuf, but not in driver.
+ * @VB2_BUF_STATE_REQUEUEING:	re-queue a buffer to the driver.
  * @VB2_BUF_STATE_ACTIVE:	buffer queued in driver and possibly used
- *				in a hardware operation
+ *				in a hardware operation.
  * @VB2_BUF_STATE_DONE:		buffer returned from driver to videobuf, but
- *				not yet dequeued to userspace
+ *				not yet dequeued to userspace.
  * @VB2_BUF_STATE_ERROR:	same as above, but the operation on the buffer
  *				has ended with an error, which will be reported
- *				to the userspace when it is dequeued
+ *				to the userspace when it is dequeued.
  */
 enum vb2_buffer_state {
 	VB2_BUF_STATE_DEQUEUED,
@@ -228,15 +229,15 @@ enum vb2_buffer_state {
 struct vb2_queue;
 
 /**
- * struct vb2_buffer - represents a video buffer
- * @vb2_queue:		the queue to which this driver belongs
- * @index:		id number of the buffer
- * @type:		buffer type
- * @memory:		the method, in which the actual data is passed
+ * struct vb2_buffer - represents a video buffer.
+ * @vb2_queue:		pointer to &struct vb2_queue with the queue to
+ *			which this driver belongs.
+ * @index:		id number of the buffer.
+ * @type:		buffer type.
+ * @memory:		the method, in which the actual data is passed.
  * @num_planes:		number of planes in the buffer
- *			on an internal driver queue
- * @planes:		private per-plane information; do not change
- * @timestamp:		frame timestamp in ns
+ *			on an internal driver queue.
+ * @timestamp:		frame timestamp in ns.
  */
 struct vb2_buffer {
 	struct vb2_queue	*vb2_queue;
@@ -244,7 +245,6 @@ struct vb2_buffer {
 	unsigned int		type;
 	unsigned int		memory;
 	unsigned int		num_planes;
-	struct vb2_plane	planes[VB2_MAX_PLANES];
 	u64			timestamp;
 
 	/* private: internal use only
@@ -254,9 +254,11 @@ struct vb2_buffer {
 	 *			all buffers queued from userspace
 	 * done_entry:		entry on the list that stores all buffers ready
 	 *			to be dequeued to userspace
+	 * vb2_plane:		per-plane information; do not change
 	 */
 	enum vb2_buffer_state	state;
 
+	struct vb2_plane	planes[VB2_MAX_PLANES];
 	struct list_head	queued_entry;
 	struct list_head	done_entry;
 #ifdef CONFIG_VIDEO_ADV_DEBUG
@@ -292,7 +294,7 @@ struct vb2_buffer {
 };
 
 /**
- * struct vb2_ops - driver-specific callbacks
+ * struct vb2_ops - driver-specific callbacks.
  *
  * @queue_setup:	called from VIDIOC_REQBUFS() and VIDIOC_CREATE_BUFS()
  *			handlers before memory allocation. It can be called
@@ -356,17 +358,17 @@ struct vb2_buffer {
  *			driver can return an error if hardware fails, in that
  *			case all buffers that have been already given by
  *			the @buf_queue callback are to be returned by the driver
- *			by calling vb2_buffer_done() with %%VB2_BUF_STATE_QUEUED.
+ *			by calling vb2_buffer_done() with %VB2_BUF_STATE_QUEUED.
  *			If you need a minimum number of buffers before you can
- *			start streaming, then set @min_buffers_needed in the
- *			vb2_queue structure. If that is non-zero then
+ *			start streaming, then set
+ *			&vb2_queue->min_buffers_needed. If that is non-zero then
  *			@start_streaming won't be called until at least that
  *			many buffers have been queued up by userspace.
  * @stop_streaming:	called when 'streaming' state must be disabled; driver
  *			should stop any DMA transactions or wait until they
  *			finish and give back all buffers it got from &buf_queue
  *			callback by calling vb2_buffer_done() with either
- *			%VB2_BUF_STATE_DONE or %%VB2_BUF_STATE_ERROR; may use
+ *			%VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
  *			vb2_wait_for_all_buffers() function
  * @buf_queue:		passes buffer vb to the driver; driver may start
  *			hardware operation on this buffer; driver should give
@@ -396,18 +398,18 @@ struct vb2_ops {
 };
 
 /**
- * struct vb2_buf_ops - driver-specific callbacks
+ * struct vb2_buf_ops - driver-specific callbacks.
  *
  * @verify_planes_array: Verify that a given user space structure contains
  *			enough planes for the buffer. This is called
  *			for each dequeued buffer.
  * @fill_user_buffer:	given a &vb2_buffer fill in the userspace structure.
- *			For V4L2 this is a struct v4l2_buffer.
+ *			For V4L2 this is a &struct v4l2_buffer.
  * @fill_vb2_buffer:	given a userspace structure, fill in the &vb2_buffer.
  *			If the userspace structure is invalid, then this op
  *			will return an error.
  * @copy_timestamp:	copy the timestamp from a userspace structure to
- *			the &vb2_buffer struct.
+ *			the &struct vb2_buffer.
  */
 struct vb2_buf_ops {
 	int (*verify_planes_array)(struct vb2_buffer *vb, const void *pb);
@@ -418,12 +420,13 @@ struct vb2_buf_ops {
 };
 
 /**
- * struct vb2_queue - a videobuf queue
+ * struct vb2_queue - a videobuf queue.
  *
  * @type:	private buffer type whose content is defined by the vb2-core
  *		caller. For example, for V4L2, it should match
- *		the types defined on enum &v4l2_buf_type
- * @io_modes:	supported io methods (see vb2_io_modes enum)
+ *		the types defined on &enum v4l2_buf_type.
+ * @io_modes:	supported io methods (see &enum vb2_io_modes).
+ * @alloc_devs:	&struct device memory type/allocator-specific per-plane device
  * @dev:	device to use for the default allocation context if the driver
  *		doesn't fill in the @alloc_devs array.
  * @dma_attrs:	DMA attributes to use for the DMA.
@@ -443,7 +446,7 @@ struct vb2_buf_ops {
  * @quirk_poll_must_check_waiting_for_buffers: Return %POLLERR at poll when QBUF
  *              has not been called. This is a vb1 idiom that has been adopted
  *              also by vb2.
- * @lock:	pointer to a mutex that protects the &vb2_queue struct. The
+ * @lock:	pointer to a mutex that protects the &struct vb2_queue. The
  *		driver can set this to a mutex to let the v4l2 core serialize
  *		the queuing ioctls. If the driver wants to handle locking
  *		itself, then this should be set to NULL. This lock is not used
@@ -454,15 +457,15 @@ struct vb2_buf_ops {
  *		drivers to easily associate an owner filehandle with the queue.
  * @ops:	driver-specific callbacks
  * @mem_ops:	memory allocator specific callbacks
- * @buf_ops:	callbacks to deliver buffer information
- *		between user-space and kernel-space
- * @drv_priv:	driver private data
+ * @buf_ops:	callbacks to deliver buffer information.
+ *		between user-space and kernel-space.
+ * @drv_priv:	driver private data.
  * @buf_struct_size: size of the driver-specific buffer structure;
  *		"0" indicates the driver doesn't want to use a custom buffer
- *		structure type. for example, sizeof(struct vb2_v4l2_buffer)
+ *		structure type. for example, ``sizeof(struct vb2_v4l2_buffer)``
  *		will be used for v4l2.
- * @timestamp_flags: Timestamp flags; V4L2_BUF_FLAG_TIMESTAMP_* and
- *		V4L2_BUF_FLAG_TSTAMP_SRC_*
+ * @timestamp_flags: Timestamp flags; ``V4L2_BUF_FLAG_TIMESTAMP_*`` and
+ *		``V4L2_BUF_FLAG_TSTAMP_SRC_*``
  * @gfp_flags:	additional gfp flags used when allocating the buffers.
  *		Typically this is 0, but it may be e.g. %GFP_DMA or %__GFP_DMA32
  *		to force the buffer allocation to a specific memory zone.
@@ -484,7 +487,6 @@ struct vb2_buf_ops {
  * @done_list:	list of buffers ready to be dequeued to userspace
  * @done_lock:	lock to protect done_list list
  * @done_wq:	waitqueue for processes waiting for buffers ready to be dequeued
- * @alloc_devs:	memory type/allocator-specific per-plane device
  * @streaming:	current streaming state
  * @start_streaming_called: @start_streaming was called successfully and we
  *		started streaming.
@@ -525,6 +527,8 @@ struct vb2_queue {
 	gfp_t				gfp_flags;
 	u32				min_buffers_needed;
 
+	struct device			*alloc_devs[VB2_MAX_PLANES];
+
 	/* private: internal use only */
 	struct mutex			mmap_lock;
 	unsigned int			memory;
@@ -540,8 +544,6 @@ struct vb2_queue {
 	spinlock_t			done_lock;
 	wait_queue_head_t		done_wq;
 
-	struct device			*alloc_devs[VB2_MAX_PLANES];
-
 	unsigned int			streaming:1;
 	unsigned int			start_streaming_called:1;
 	unsigned int			error:1;
@@ -568,9 +570,10 @@ struct vb2_queue {
 };
 
 /**
- * vb2_plane_vaddr() - Return a kernel virtual address of a given plane
- * @vb:		&vb2_buffer to which the plane in question belongs to
- * @plane_no:	plane number for which the address is to be returned
+ * vb2_plane_vaddr() - Return a kernel virtual address of a given plane.
+ * @vb:		pointer to &struct vb2_buffer to which the plane in
+ *		question belongs to.
+ * @plane_no:	plane number for which the address is to be returned.
  *
  * This function returns a kernel virtual address of a given plane if
  * such a mapping exist, NULL otherwise.
@@ -578,9 +581,10 @@ struct vb2_queue {
 void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
 
 /**
- * vb2_plane_cookie() - Return allocator specific cookie for the given plane
- * @vb:		&vb2_buffer to which the plane in question belongs to
- * @plane_no:	plane number for which the cookie is to be returned
+ * vb2_plane_cookie() - Return allocator specific cookie for the given plane.
+ * @vb:		pointer to &struct vb2_buffer to which the plane in
+ *		question belongs to.
+ * @plane_no:	plane number for which the cookie is to be returned.
  *
  * This function returns an allocator specific cookie for a given plane if
  * available, NULL otherwise. The allocator should provide some simple static
@@ -591,9 +595,11 @@ void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
 void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
 
 /**
- * vb2_buffer_done() - inform videobuf that an operation on a buffer is finished
- * @vb:		vb2_buffer returned from the driver
- * @state:	either %VB2_BUF_STATE_DONE if the operation finished
+ * vb2_buffer_done() - inform videobuf that an operation on a buffer
+ *	is finished.
+ * @vb:		pointer to &struct vb2_buffer to be used.
+ * @state:	state of the buffer, as defined by &enum vb2_buffer_state.
+ *		Either %VB2_BUF_STATE_DONE if the operation finished
  *		successfully, %VB2_BUF_STATE_ERROR if the operation finished
  *		with an error or %VB2_BUF_STATE_QUEUED if the driver wants to
  *		requeue buffers. If start_streaming fails then it should return
@@ -614,8 +620,8 @@ void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
 void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
 
 /**
- * vb2_discard_done() - discard all buffers marked as DONE
- * @q:		videobuf2 queue
+ * vb2_discard_done() - discard all buffers marked as DONE.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This function is intended to be used with suspend/resume operations. It
  * discards all 'done' buffers as they would be too old to be requested after
@@ -628,35 +634,40 @@ void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
 void vb2_discard_done(struct vb2_queue *q);
 
 /**
- * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2
- * @q:		videobuf2 queue
+ * vb2_wait_for_all_buffers() - wait until all buffers are given back to vb2.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This function will wait until all buffers that have been given to the driver
  * by &vb2_ops->buf_queue are given back to vb2 with vb2_buffer_done(). It
- * doesn't call wait_prepare()/wait_finish() pair. It is intended to be called
- * with all locks taken, for example from &vb2_ops->stop_streaming callback.
+ * doesn't call &vb2_ops->wait_prepare/&vb2_ops->wait_finish pair.
+ * It is intended to be called with all locks taken, for example from
+ * &vb2_ops->stop_streaming callback.
  */
 int vb2_wait_for_all_buffers(struct vb2_queue *q);
 
 /**
- * vb2_core_querybuf() - query video buffer information
- * @q:		videobuf queue
- * @index:	id number of the buffer
- * @pb:		buffer struct passed from userspace
+ * vb2_core_querybuf() - query video buffer information.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @index:	id number of the buffer.
+ * @pb:		buffer struct passed from userspace.
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_querybuf ioctl handler
+ * in driver.
  *
- * Should be called from &vidioc_querybuf ioctl handler in driver.
  * The passed buffer should have been verified.
+ *
  * This function fills the relevant information for the userspace.
  */
 void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
 
 /**
- * vb2_core_reqbufs() - Initiate streaming
- * @q:		videobuf2 queue
- * @memory: memory type
- * @count: requested buffer count
+ * vb2_core_reqbufs() - Initiate streaming.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @memory:	memory type, as defined by &enum vb2_memory.
+ * @count:	requested buffer count.
  *
- * Should be called from &vidioc_reqbufs ioctl handler of a driver.
+ * Should be called from &v4l2_ioctl_ops->vidioc_reqbufs ioctl
+ * handler of a driver.
  *
  * This function:
  *
@@ -670,32 +681,35 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
  *    memory handling/allocation routines provided during queue initialization
  *
  * If req->count is 0, all the memory will be freed instead.
- * If the queue has been allocated previously (by a previous vb2_reqbufs) call
- * and the queue is not busy, memory will be reallocated.
+ *
+ * If the queue has been allocated previously by a previous vb2_core_reqbufs()
+ * call and the queue is not busy, memory will be reallocated.
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_reqbufs handler in driver.
+ * from &v4l2_ioctl_ops->vidioc_reqbufs handler in driver.
  */
 int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
 		unsigned int *count);
 
 /**
  * vb2_core_create_bufs() - Allocate buffers and any required auxiliary structs
- * @q:		videobuf2 queue
- * @memory: memory type
- * @count: requested buffer count
- * @requested_planes: number of planes requested
- * @requested_sizes: array with the size of the planes
+ * @q: pointer to &struct vb2_queue with videobuf2 queue.
+ * @memory: memory type, as defined by &enum vb2_memory.
+ * @count: requested buffer count.
+ * @requested_planes: number of planes requested.
+ * @requested_sizes: array with the size of the planes.
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_create_bufs ioctl handler
+ * of a driver.
  *
- * Should be called from VIDIOC_CREATE_BUFS() ioctl handler of a driver.
  * This function:
  *
  * #) verifies parameter sanity
- * #) calls the .queue_setup() queue operation
+ * #) calls the &vb2_ops->queue_setup queue operation
  * #) performs any necessary memory allocations
  *
  * Return: the return values from this function are intended to be directly
- * returned from VIDIOC_CREATE_BUFS() handler in driver.
+ * returned from &v4l2_ioctl_ops->vidioc_create_bufs handler in driver.
  */
 int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
 			 unsigned int *count, unsigned int requested_planes,
@@ -703,31 +717,34 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
 
 /**
  * vb2_core_prepare_buf() - Pass ownership of a buffer from userspace
- *			to the kernel
- * @q:		videobuf2 queue
- * @index:	id number of the buffer
- * @pb:		buffer structure passed from userspace to vidioc_prepare_buf
- *		handler in driver
+ *			to the kernel.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @index:	id number of the buffer.
+ * @pb:		buffer structure passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_prepare_buf ioctl handler
+ * of a driver.
  *
- * Should be called from vidioc_prepare_buf ioctl handler of a driver.
  * The passed buffer should have been verified.
+ *
  * This function calls buf_prepare callback in the driver (if provided),
  * in which driver-specific buffer initialization can be performed,
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_prepare_buf handler in driver.
+ * from v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
  */
 int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
 
 /**
  * vb2_core_qbuf() - Queue a buffer from userspace
  *
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @index:	id number of the buffer
- * @pb:		buffer structure passed from userspace to vidioc_qbuf handler
- *		in driver
+ * @pb:		buffer structure passed from userspace to
+ *		v4l2_ioctl_ops->vidioc_qbuf handler in driver
  *
- * Should be called from vidioc_qbuf ioctl handler of a driver.
+ * Should be called from v4l2_ioctl_ops->vidioc_qbuf ioctl handler of a driver.
  * The passed buffer should have been verified.
  *
  * This function:
@@ -738,21 +755,21 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
  *    &vb2_ops->buf_queue callback for processing.
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_qbuf handler in driver.
+ * from v4l2_ioctl_ops->vidioc_qbuf handler in driver.
  */
 int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
 
 /**
  * vb2_core_dqbuf() - Dequeue a buffer to the userspace
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue
  * @pindex:	pointer to the buffer index. May be NULL
- * @pb:		buffer structure passed from userspace to vidioc_dqbuf handler
- *		in driver
+ * @pb:		buffer structure passed from userspace to
+ *		v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
  * @nonblocking: if true, this call will not sleep waiting for a buffer if no
  *		 buffers ready for dequeuing are present. Normally the driver
- *		 would be passing (file->f_flags & O_NONBLOCK) here
+ *		 would be passing (file->f_flags & O_NONBLOCK) here.
  *
- * Should be called from vidioc_dqbuf ioctl handler of a driver.
+ * Should be called from v4l2_ioctl_ops->vidioc_dqbuf ioctl handler of a driver.
  * The passed buffer should have been verified.
  *
  * This function:
@@ -764,7 +781,7 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
  *    the userspace.
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_dqbuf handler in driver.
+ * from v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
  */
 int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
 		   bool nonblocking);
@@ -773,51 +790,57 @@ int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
 int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
 
 /**
- * vb2_core_expbuf() - Export a buffer as a file descriptor
- * @q:		videobuf2 queue
- * @fd:		file descriptor associated with DMABUF (set by driver) *
- * @type:	buffer type
- * @index:	id number of the buffer
+ * vb2_core_expbuf() - Export a buffer as a file descriptor.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @fd:		pointer to the file descriptor associated with DMABUF
+ *		(set by driver).
+ * @type:	buffer type.
+ * @index:	id number of the buffer.
  * @plane:	index of the plane to be exported, 0 for single plane queues
- * @flags:	flags for newly created file, currently only %O_CLOEXEC is
- *		supported, refer to manual of open syscall for more details
+ * @flags:	file flags for newly created file, as defined at
+ *		include/uapi/asm-generic/fcntl.h.
+ *		Currently, the only used flag is %O_CLOEXEC.
+ *		is supported, refer to manual of open syscall for more details.
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_expbuf handler in driver.
+ * from v4l2_ioctl_ops->vidioc_expbuf handler in driver.
  */
 int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
 		unsigned int index, unsigned int plane, unsigned int flags);
 
 /**
  * vb2_core_queue_init() - initialize a videobuf2 queue
- * @q:		videobuf2 queue; this structure should be allocated in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ *		This structure should be allocated in driver
  *
  * The &vb2_queue structure should be allocated by the driver. The driver is
  * responsible of clearing it's content and setting initial values for some
  * required entries before calling this function.
- * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
- * to the struct vb2_queue description in include/media/videobuf2-core.h
- * for more information.
+ *
+ * .. note::
+ *
+ *    The following fields at @q should be set before calling this function:
+ *    &vb2_queue->ops, &vb2_queue->mem_ops, &vb2_queue->type.
  */
 int vb2_core_queue_init(struct vb2_queue *q);
 
 /**
  * vb2_core_queue_release() - stop streaming, release the queue and free memory
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This function stops streaming and performs necessary clean ups, including
  * freeing video buffer memory. The driver is responsible for freeing
- * the vb2_queue structure itself.
+ * the &struct vb2_queue itself.
  */
 void vb2_core_queue_release(struct vb2_queue *q);
 
 /**
  * vb2_queue_error() - signal a fatal error on the queue
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * Flag that a fatal unrecoverable error has occurred and wake up all processes
- * waiting on the queue. Polling will now set POLLERR and queuing and dequeuing
- * buffers will return -EIO.
+ * waiting on the queue. Polling will now set %POLLERR and queuing and dequeuing
+ * buffers will return %-EIO.
  *
  * The error flag will be cleared when canceling the queue, either from
  * vb2_streamoff() or vb2_queue_release(). Drivers should thus not call this
@@ -827,9 +850,10 @@ void vb2_core_queue_release(struct vb2_queue *q);
 void vb2_queue_error(struct vb2_queue *q);
 
 /**
- * vb2_mmap() - map video buffers into application address space
- * @q:		videobuf2 queue
- * @vma:	vma passed to the mmap file operation handler in the driver
+ * vb2_mmap() - map video buffers into application address space.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @vma:	pointer to &struct vm_area_struct with the vma passed
+ *		to the mmap file operation handler in the driver.
  *
  * Should be called from mmap file operation handler of a driver.
  * This function maps one plane of one of the available video buffers to
@@ -837,8 +861,10 @@ void vb2_queue_error(struct vb2_queue *q);
  * has to be called once per each plane per each buffer previously allocated.
  *
  * When the userspace application calls mmap, it passes to it an offset returned
- * to it earlier by the means of vidioc_querybuf handler. That offset acts as
- * a "cookie", which is then used to identify the plane to be mapped.
+ * to it earlier by the means of &v4l2_ioctl_ops->vidioc_querybuf handler.
+ * That offset acts as a "cookie", which is then used to identify the plane
+ * to be mapped.
+ *
  * This function finds a plane with a matching offset and a mapping is performed
  * by the means of a provided memory operation.
  *
@@ -856,10 +882,12 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 #endif
 
 /**
- * vb2_core_poll() - implements poll userspace operation
- * @q:		videobuf2 queue
- * @file:	file argument passed to the poll file operation handler
- * @wait:	wait argument passed to the poll file operation handler
+ * vb2_core_poll() - implements poll userspace operation.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @file:	&struct file argument passed to the poll
+ *		file operation handler.
+ * @wait:	&poll_table wait argument passed to the poll
+ *		file operation handler.
  *
  * This function implements poll file operation handler for a driver.
  * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
@@ -880,10 +908,10 @@ size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
 
 /**
- * typedef vb2_thread_fnc - callback function for use with vb2_thread
+ * typedef vb2_thread_fnc - callback function for use with vb2_thread.
  *
- * @vb: pointer to struct &vb2_buffer
- * @priv: pointer to a private pointer
+ * @vb: pointer to struct &vb2_buffer.
+ * @priv: pointer to a private data.
  *
  * This is called whenever a buffer is dequeued in the thread.
  */
@@ -891,13 +919,13 @@ typedef int (*vb2_thread_fnc)(struct vb2_buffer *vb, void *priv);
 
 /**
  * vb2_thread_start() - start a thread for the given queue.
- * @q:		videobuf queue
- * @fnc:	callback function
- * @priv:	priv pointer passed to the callback function
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @fnc:	&vb2_thread_fnc callback function.
+ * @priv:	priv pointer passed to the callback function.
  * @thread_name:the name of the thread. This will be prefixed with "vb2-".
  *
  * This starts a thread that will queue and dequeue until an error occurs
- * or @vb2_thread_stop is called.
+ * or vb2_thread_stop() is called.
  *
  * .. attention::
  *
@@ -910,13 +938,13 @@ int vb2_thread_start(struct vb2_queue *q, vb2_thread_fnc fnc, void *priv,
 
 /**
  * vb2_thread_stop() - stop the thread for the given queue.
- * @q:		videobuf queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 int vb2_thread_stop(struct vb2_queue *q);
 
 /**
- * vb2_is_streaming() - return streaming status of the queue
- * @q:		videobuf queue
+ * vb2_is_streaming() - return streaming status of the queue.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 static inline bool vb2_is_streaming(struct vb2_queue *q)
 {
@@ -925,15 +953,16 @@ static inline bool vb2_is_streaming(struct vb2_queue *q)
 
 /**
  * vb2_fileio_is_active() - return true if fileio is active.
- * @q:		videobuf queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This returns true if read() or write() is used to stream the data
  * as opposed to stream I/O. This is almost never an important distinction,
  * except in rare cases. One such case is that using read() or write() to
- * stream a format using V4L2_FIELD_ALTERNATE is not allowed since there
+ * stream a format using %V4L2_FIELD_ALTERNATE is not allowed since there
  * is no way you can pass the field information of each buffer to/from
  * userspace. A driver that supports this field format should check for
- * this in the queue_setup op and reject it if this function returns true.
+ * this in the &vb2_ops->queue_setup op and reject it if this function returns
+ * true.
  */
 static inline bool vb2_fileio_is_active(struct vb2_queue *q)
 {
@@ -941,8 +970,8 @@ static inline bool vb2_fileio_is_active(struct vb2_queue *q)
 }
 
 /**
- * vb2_is_busy() - return busy status of the queue
- * @q:		videobuf queue
+ * vb2_is_busy() - return busy status of the queue.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This function checks if queue has any buffers allocated.
  */
@@ -952,8 +981,8 @@ static inline bool vb2_is_busy(struct vb2_queue *q)
 }
 
 /**
- * vb2_get_drv_priv() - return driver private data associated with the queue
- * @q:		videobuf queue
+ * vb2_get_drv_priv() - return driver private data associated with the queue.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 static inline void *vb2_get_drv_priv(struct vb2_queue *q)
 {
@@ -961,10 +990,11 @@ static inline void *vb2_get_drv_priv(struct vb2_queue *q)
 }
 
 /**
- * vb2_set_plane_payload() - set 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
+ * vb2_set_plane_payload() - set bytesused for the plane @plane_no.
+ * @vb:		pointer to &struct vb2_buffer to which the plane in
+ *		question belongs to.
+ * @plane_no:	plane number for which payload should be set.
+ * @size:	payload in bytes.
  */
 static inline void vb2_set_plane_payload(struct vb2_buffer *vb,
 				 unsigned int plane_no, unsigned long size)
@@ -975,8 +1005,9 @@ 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
+ * @vb:		pointer to &struct vb2_buffer to which the plane in
+ *		question belongs to.
+ * @plane_no:	plane number for which payload should be set.
  */
 static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb,
 				 unsigned int plane_no)
@@ -987,9 +1018,10 @@ static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb,
 }
 
 /**
- * vb2_plane_size() - return plane size in bytes
- * @vb:		buffer for which plane size should be returned
- * @plane_no:	plane number for which size should be returned
+ * vb2_plane_size() - return plane size in bytes.
+ * @vb:		pointer to &struct vb2_buffer to which the plane in
+ *		question belongs to.
+ * @plane_no:	plane number for which size should be returned.
  */
 static inline unsigned long
 vb2_plane_size(struct vb2_buffer *vb, unsigned int plane_no)
@@ -1000,8 +1032,8 @@ vb2_plane_size(struct vb2_buffer *vb, unsigned int plane_no)
 }
 
 /**
- * vb2_start_streaming_called() - return streaming status of driver
- * @q:		videobuf queue
+ * vb2_start_streaming_called() - return streaming status of driver.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 static inline bool vb2_start_streaming_called(struct vb2_queue *q)
 {
@@ -1009,8 +1041,8 @@ static inline bool vb2_start_streaming_called(struct vb2_queue *q)
 }
 
 /**
- * vb2_clear_last_buffer_dequeued() - clear last buffer dequeued flag of queue
- * @q:		videobuf queue
+ * vb2_clear_last_buffer_dequeued() - clear last buffer dequeued flag of queue.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q)
 {
@@ -1024,10 +1056,10 @@ static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q)
 
 /**
  * vb2_buffer_in_use() - return true if the buffer is in use and
- * the queue cannot be freed (by the means of REQBUFS(0)) call
+ * the queue cannot be freed (by the means of VIDIOC_REQBUFS(0)) call.
  *
- * @vb:		buffer for which plane size should be returned
- * @q:		videobuf queue
+ * @vb:		buffer for which plane size should be returned.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  */
 bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
 
@@ -1035,11 +1067,11 @@ bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
  * vb2_verify_memory_type() - Check whether the memory type and buffer type
  * passed to a buffer operation are compatible with the queue.
  *
- * @q:		videobuf queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @memory:	memory model, as defined by enum &vb2_memory.
  * @type:	private buffer type whose content is defined by the vb2-core
  *		caller. For example, for V4L2, it should match
- *		the types defined on enum &v4l2_buf_type
+ *		the types defined on enum &v4l2_buf_type.
  */
 int vb2_verify_memory_type(struct vb2_queue *q,
 		enum vb2_memory memory, unsigned int type);
-- 
2.13.6

[PATCH 20/24] media: vb2-core: document remaining functions

[Mauro Carvalho Chehab]

There are several VB2 core functions that aren't documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/videobuf2-core.h | 54 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index e145f1475ffe..ce795cd0a7cc 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -786,7 +786,28 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
 int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
 		   bool nonblocking);
 
+/**
+ * vb2_core_streamon() - Implements VB2 stream ON logic
+ *
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue
+ * @type:	type of the queue to be started.
+ *		For V4L2, this is defined by &enum v4l2_buf_type type.
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
+ * a driver.
+ */
 int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
+
+/**
+ * vb2_core_streamoff() - Implements VB2 stream OFF logic
+ *
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue
+ * @type:	type of the queue to be started.
+ *		For V4L2, this is defined by &enum v4l2_buf_type type.
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
+ * a driver.
+ */
 int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
 
 /**
@@ -874,6 +895,21 @@ void vb2_queue_error(struct vb2_queue *q);
 int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
 
 #ifndef CONFIG_MMU
+/**
+ * vb2_get_unmapped_area - map video buffers into application address space.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @addr:	memory address.
+ * @len:	buffer size.
+ * @pgoff:	page offset.
+ * @flags:	memory flags.
+ *
+ * This function is used in noMMU platforms to propose address mapping
+ * for a given buffer. It's intended to be used as a handler for the
+ * &file_operations->get_unmapped_area operation.
+ *
+ * This is called by the mmap() syscall routines will call this
+ * to get a proposed address for the mapping, when ``!CONFIG_MMU``.
+ */
 unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 				    unsigned long addr,
 				    unsigned long len,
@@ -882,7 +918,7 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 #endif
 
 /**
- * vb2_core_poll() - implements poll userspace operation.
+ * vb2_core_poll() - implements poll syscall() logic.
  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @file:	&struct file argument passed to the poll
  *		file operation handler.
@@ -902,8 +938,24 @@ unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
 			   poll_table *wait);
 
+/**
+ * vb2_read() - implements read() syscall logic.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @data:	pointed to target userspace buffer
+ * @count:	number of bytes to read
+ * @ppos:	file handle position tracking pointer
+ * @nonblock:	mode selector (1 means blocking calls, 0 means nonblocking)
+ */
 size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
+/**
+ * vb2_read() - implements write() syscall logic.
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @data:	pointed to target userspace buffer
+ * @count:	number of bytes to write
+ * @ppos:	file handle position tracking pointer
+ * @nonblock:	mode selector (1 means blocking calls, 0 means nonblocking)
+ */
 size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
 
-- 
2.13.6

[PATCH 21/24] media: vb2-core: fix descriptions for VB2-only functions

[Mauro Carvalho Chehab]

When we split VB2 into an independent streaming module and
a V4L2 one, some vb2-core functions started to have a wrong
description: they're meant to be used only by the API-specific
parts of VB2, like vb2-v4l2, as the functions that V4L2 drivers
should use are all under videobuf2-v4l2.h.

Correct their descriptions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/videobuf2-core.h | 86 ++++++++++++++++++++++--------------------
 1 file changed, 46 insertions(+), 40 deletions(-)

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index ce795cd0a7cc..3165f0f9a85f 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -651,12 +651,14 @@ int vb2_wait_for_all_buffers(struct vb2_queue *q);
  * @index:	id number of the buffer.
  * @pb:		buffer struct passed from userspace.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_querybuf ioctl handler
- * in driver.
+ * Videbuf2 core helper to implement QUERYBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * The passed buffer should have been verified.
  *
  * This function fills the relevant information for the userspace.
+ *
+ * Return: returns zero on success; an error code otherwise.
  */
 void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
 
@@ -666,27 +668,26 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
  * @memory:	memory type, as defined by &enum vb2_memory.
  * @count:	requested buffer count.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_reqbufs ioctl
- * handler of a driver.
+ * Videbuf2 core helper to implement REQBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
- * #) verifies streaming parameters passed from the userspace,
- * #) sets up the queue,
+ * #) verifies streaming parameters passed from the userspace;
+ * #) sets up the queue;
  * #) negotiates number of buffers and planes per buffer with the driver
- *    to be used during streaming,
+ *    to be used during streaming;
  * #) allocates internal buffer structures (&struct vb2_buffer), according to
- *    the agreed parameters,
+ *    the agreed parameters;
  * #) for MMAP memory type, allocates actual video memory, using the
- *    memory handling/allocation routines provided during queue initialization
+ *    memory handling/allocation routines provided during queue initialization.
  *
  * If req->count is 0, all the memory will be freed instead.
  *
  * If the queue has been allocated previously by a previous vb2_core_reqbufs()
  * call and the queue is not busy, memory will be reallocated.
  *
- * The return values from this function are intended to be directly returned
- * from &v4l2_ioctl_ops->vidioc_reqbufs handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
 		unsigned int *count);
@@ -699,17 +700,16 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
  * @requested_planes: number of planes requested.
  * @requested_sizes: array with the size of the planes.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_create_bufs ioctl handler
- * of a driver.
+ * Videbuf2 core helper to implement CREATE_BUFS operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
- * #) verifies parameter sanity
- * #) calls the &vb2_ops->queue_setup queue operation
- * #) performs any necessary memory allocations
+ * #) verifies parameter sanity;
+ * #) calls the &vb2_ops->queue_setup queue operation;
+ * #) performs any necessary memory allocations.
  *
- * Return: the return values from this function are intended to be directly
- * returned from &v4l2_ioctl_ops->vidioc_create_bufs handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
 			 unsigned int *count, unsigned int requested_planes,
@@ -723,16 +723,16 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
  * @pb:		buffer structure passed from userspace to
  *		&v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_prepare_buf ioctl handler
- * of a driver.
+ * Videbuf2 core helper to implement PREPARE_BUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * The passed buffer should have been verified.
  *
- * This function calls buf_prepare callback in the driver (if provided),
- * in which driver-specific buffer initialization can be performed,
+ * This function calls vb2_ops->buf_prepare callback in the driver
+ * (if provided), in which driver-specific buffer initialization can
+ * be performed.
  *
- * The return values from this function are intended to be directly returned
- * from v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
 
@@ -744,18 +744,18 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
  * @pb:		buffer structure passed from userspace to
  *		v4l2_ioctl_ops->vidioc_qbuf handler in driver
  *
- * Should be called from v4l2_ioctl_ops->vidioc_qbuf ioctl handler of a driver.
- * The passed buffer should have been verified.
+ * Videbuf2 core helper to implement QBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
- * #) if necessary, calls buf_prepare callback in the driver (if provided), in
- *    which driver-specific buffer initialization can be performed,
+ * #) if necessary, calls &vb2_ops->buf_prepare callback in the driver
+ *    (if provided), in which driver-specific buffer initialization can
+ *    be performed;
  * #) if streaming is on, queues the buffer in driver by the means of
  *    &vb2_ops->buf_queue callback for processing.
  *
- * The return values from this function are intended to be directly returned
- * from v4l2_ioctl_ops->vidioc_qbuf handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
 
@@ -769,8 +769,8 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
  *		 buffers ready for dequeuing are present. Normally the driver
  *		 would be passing (file->f_flags & O_NONBLOCK) here.
  *
- * Should be called from v4l2_ioctl_ops->vidioc_dqbuf ioctl handler of a driver.
- * The passed buffer should have been verified.
+ * Videbuf2 core helper to implement DQBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
  *
  * This function:
  *
@@ -780,8 +780,7 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
  * #) the buffer struct members are filled with relevant information for
  *    the userspace.
  *
- * The return values from this function are intended to be directly returned
- * from v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
 		   bool nonblocking);
@@ -793,8 +792,10 @@ int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
  * @type:	type of the queue to be started.
  *		For V4L2, this is defined by &enum v4l2_buf_type type.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
- * a driver.
+ * Videbuf2 core helper to implement STREAMON operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
+ *
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
 
@@ -805,8 +806,10 @@ int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
  * @type:	type of the queue to be started.
  *		For V4L2, this is defined by &enum v4l2_buf_type type.
  *
- * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
- * a driver.
+ * Videbuf2 core helper to implement STREAMOFF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
+ *
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
 
@@ -823,8 +826,11 @@ int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
  *		Currently, the only used flag is %O_CLOEXEC.
  *		is supported, refer to manual of open syscall for more details.
  *
- * The return values from this function are intended to be directly returned
- * from v4l2_ioctl_ops->vidioc_expbuf handler in driver.
+ *
+ * Videbuf2 core helper to implement EXPBUF operation. It is called
+ * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
+ *
+ * Return: returns zero on success; an error code otherwise.
  */
 int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
 		unsigned int index, unsigned int plane, unsigned int flags);
-- 
2.13.6

[PATCH 22/24] media: vb2: add cross references at memops and v4l2 kernel-doc markups

[Mauro Carvalho Chehab]

Add cross-references where needed and add periods at the end of
each kernel-doc paragraph, in order to make it coherent with other
VB2 descriptions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/videobuf2-memops.h |   8 +--
 include/media/videobuf2-v4l2.h   | 112 +++++++++++++++++++++------------------
 2 files changed, 63 insertions(+), 57 deletions(-)

diff --git a/include/media/videobuf2-memops.h b/include/media/videobuf2-memops.h
index a6ed091b79ce..4b5b84f93538 100644
--- a/include/media/videobuf2-memops.h
+++ b/include/media/videobuf2-memops.h
@@ -19,11 +19,11 @@
 #include <linux/refcount.h>
 
 /**
- * struct 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
+ * @refcount:	pointer to &refcount_t entry in the buffer.
+ * @put:	callback to function that decreases buffer refcount.
+ * @arg:	argument for @put callback.
  */
 struct vb2_vmarea_handler {
 	refcount_t		*refcount;
diff --git a/include/media/videobuf2-v4l2.h b/include/media/videobuf2-v4l2.h
index 036127c54bbf..d38829a9dab3 100644
--- a/include/media/videobuf2-v4l2.h
+++ b/include/media/videobuf2-v4l2.h
@@ -24,16 +24,17 @@
 #endif
 
 /**
- * struct vb2_v4l2_buffer - video buffer information for v4l2
+ * struct vb2_v4l2_buffer - video buffer information for v4l2.
  *
- * @vb2_buf:	video buffer 2
- * @flags:	buffer informational flags
- * @field:	enum v4l2_field; field order of the image in the buffer
- * @timecode:	frame timecode
- * @sequence:	sequence count of this frame
+ * @vb2_buf:	embedded struct &vb2_buffer.
+ * @flags:	buffer informational flags.
+ * @field:	field order of the image in the buffer, as defined by
+ *		&enum v4l2_field.
+ * @timecode:	frame timecode.
+ * @sequence:	sequence count of this frame.
  *
  * Should contain enough information to be able to cover all the fields
- * of struct v4l2_buffer at videodev2.h
+ * of &struct v4l2_buffer at ``videodev2.h``.
  */
 struct vb2_v4l2_buffer {
 	struct vb2_buffer	vb2_buf;
@@ -56,9 +57,9 @@ int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
  * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
  * the memory and type values.
  *
- * @q:		videobuf2 queue
- * @req:	struct passed from userspace to vidioc_reqbufs handler
- *		in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @req:	&struct v4l2_requestbuffers passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_reqbufs handler in driver.
  */
 int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
 
@@ -66,94 +67,99 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
  * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
  * the memory and type values.
  *
- * @q:		videobuf2 queue
- * @create:	creation parameters, passed from userspace to vidioc_create_bufs
- *		handler in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @create:	creation parameters, passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_create_bufs handler in driver
  */
 int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
 
 /**
  * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
  *
- * @q:		videobuf2 queue
- * @b:		buffer structure passed from userspace to vidioc_prepare_buf
- *		handler in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @b:		buffer structure passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_prepare_buf handler in driver
+ *
+ * Should be called from &v4l2_ioctl_ops->vidioc_prepare_buf ioctl handler
+ * of a driver.
  *
- * Should be called from vidioc_prepare_buf ioctl handler of a driver.
  * This function:
  *
  * #) verifies the passed buffer,
- * #) calls buf_prepare callback in the driver (if provided), in which
- *    driver-specific buffer initialization can be performed.
+ * #) calls &vb2_ops->buf_prepare callback in the driver (if provided),
+ *    in which driver-specific buffer initialization can be performed.
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_prepare_buf handler in driver.
+ * from &v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
  */
 int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b);
 
 /**
  * vb2_qbuf() - Queue a buffer from userspace
- * @q:		videobuf2 queue
- * @b:		buffer structure passed from userspace to VIDIOC_QBUF() handler
- *		in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @b:		buffer structure passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_qbuf handler in driver
  *
- * Should be called from VIDIOC_QBUF() ioctl handler of a driver.
+ * Should be called from &v4l2_ioctl_ops->vidioc_qbuf handler of a driver.
  *
  * This function:
  *
- * #) verifies the passed buffer,
- * #) if necessary, calls buf_prepare callback in the driver (if provided), in
- *    which driver-specific buffer initialization can be performed,
- * #) if streaming is on, queues the buffer in driver by the means of buf_queue
- *    callback for processing.
+ * #) verifies the passed buffer;
+ * #) if necessary, calls &vb2_ops->buf_prepare callback in the driver
+ *    (if provided), in which driver-specific buffer initialization can
+ *    be performed;
+ * #) if streaming is on, queues the buffer in driver by the means of
+ *    &vb2_ops->buf_queue callback for processing.
  *
  * The return values from this function are intended to be directly returned
- * from VIDIOC_QBUF() handler in driver.
+ * from &v4l2_ioctl_ops->vidioc_qbuf handler in driver.
  */
 int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b);
 
 /**
  * vb2_expbuf() - Export a buffer as a file descriptor
- * @q:		videobuf2 queue
- * @eb:		export buffer structure passed from userspace to VIDIOC_EXPBUF()
- *		handler in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @eb:		export buffer structure passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_expbuf handler in driver
  *
  * The return values from this function are intended to be directly returned
- * from VIDIOC_EXPBUF() handler in driver.
+ * from &v4l2_ioctl_ops->vidioc_expbuf handler in driver.
  */
 int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
 
 /**
  * vb2_dqbuf() - Dequeue a buffer to the userspace
- * @q:		videobuf2 queue
- * @b:		buffer structure passed from userspace to VIDIOC_DQBUF() handler
- *		in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @b:		buffer structure passed from userspace to
+ *		&v4l2_ioctl_ops->vidioc_dqbuf handler in driver
  * @nonblocking: if true, this call will not sleep waiting for a buffer if no
  *		 buffers ready for dequeuing are present. Normally the driver
- *		 would be passing (file->f_flags & O_NONBLOCK) here
+ *		 would be passing (&file->f_flags & %O_NONBLOCK) here
  *
- * Should be called from VIDIOC_DQBUF() ioctl handler of a driver.
+ * Should be called from &v4l2_ioctl_ops->vidioc_dqbuf ioctl handler
+ * of a driver.
  *
  * This function:
  *
- * #) verifies the passed buffer,
- * #) calls buf_finish callback in the driver (if provided), in which
+ * #) verifies the passed buffer;
+ * #) calls &vb2_ops->buf_finish callback in the driver (if provided), in which
  *    driver can perform any additional operations that may be required before
- *    returning the buffer to userspace, such as cache sync,
+ *    returning the buffer to userspace, such as cache sync;
  * #) the buffer struct members are filled with relevant information for
  *    the userspace.
  *
  * The return values from this function are intended to be directly returned
- * from VIDIOC_DQBUF() handler in driver.
+ * from &v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
  */
 int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
 
 /**
  * vb2_streamon - start streaming
- * @q:		videobuf2 queue
- * @type:	type argument passed from userspace to vidioc_streamon handler
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
+ * @type:	type argument passed from userspace to vidioc_streamon handler,
+ * 		as defined by &enum v4l2_buf_type.
  *
- * Should be called from vidioc_streamon handler of a driver.
+ * Should be called from &v4l2_ioctl_ops->vidioc_streamon handler of a driver.
  *
  * This function:
  *
@@ -161,13 +167,13 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
  * 2) passes any previously queued buffers to the driver and starts streaming
  *
  * The return values from this function are intended to be directly returned
- * from vidioc_streamon handler in the driver.
+ * from &v4l2_ioctl_ops->vidioc_streamon handler in the driver.
  */
 int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
 
 /**
  * vb2_streamoff - stop streaming
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @type:	type argument passed from userspace to vidioc_streamoff handler
  *
  * Should be called from vidioc_streamoff handler of a driver.
@@ -186,7 +192,7 @@ int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type);
 
 /**
  * vb2_queue_init() - initialize a videobuf2 queue
- * @q:		videobuf2 queue; this structure should be allocated in driver
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * The vb2_queue structure should be allocated by the driver. The driver is
  * responsible of clearing it's content and setting initial values for some
@@ -199,7 +205,7 @@ int __must_check vb2_queue_init(struct vb2_queue *q);
 
 /**
  * vb2_queue_release() - stop streaming, release the queue and free memory
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  *
  * This function stops streaming and performs necessary clean ups, including
  * freeing video buffer memory. The driver is responsible for freeing
@@ -209,7 +215,7 @@ void vb2_queue_release(struct vb2_queue *q);
 
 /**
  * vb2_poll() - implements poll userspace operation
- * @q:		videobuf2 queue
+ * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @file:	file argument passed to the poll file operation handler
  * @wait:	wait argument passed to the poll file operation handler
  *
@@ -271,7 +277,7 @@ unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr,
 /**
  * vb2_ops_wait_prepare - helper function to lock a struct &vb2_queue
  *
- * @vq: pointer to struct vb2_queue
+ * @vq: pointer to &struct vb2_queue
  *
  * ..note:: only use if vq->lock is non-NULL.
  */
@@ -280,7 +286,7 @@ void vb2_ops_wait_prepare(struct vb2_queue *vq);
 /**
  * vb2_ops_wait_finish - helper function to unlock a struct &vb2_queue
  *
- * @vq: pointer to struct vb2_queue
+ * @vq: pointer to &struct vb2_queue
  *
  * ..note:: only use if vq->lock is non-NULL.
  */
-- 
2.13.6

[PATCH 23/24] media: v4l2-tpg*.h: move headers to include/media/tpg and merge them

[Mauro Carvalho Chehab]

The v4l2-tpg*.h headers are meant to be used only internally by
vivid and vimc. There's no sense keeping them together with the
V4L2 kAPI headers. Also, one header includes the other as they're
meant to be used together. So, merge them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c |  2 +-
 drivers/media/common/v4l2-tpg/v4l2-tpg-core.c   |  2 +-
 drivers/media/platform/vimc/vimc-sensor.c       |  2 +-
 drivers/media/platform/vivid/vivid-core.h       |  2 +-
 include/media/{ => tpg}/v4l2-tpg.h              | 45 +++++++++++++++-
 include/media/v4l2-tpg-colors.h                 | 68 -------------------------
 6 files changed, 48 insertions(+), 73 deletions(-)
 rename include/media/{ => tpg}/v4l2-tpg.h (93%)
 delete mode 100644 include/media/v4l2-tpg-colors.h

diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
index 5b5f95c38fe1..95b26f6a0d54 100644
--- a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
+++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
@@ -36,7 +36,7 @@
  */
 
 #include <linux/videodev2.h>
-#include <media/v4l2-tpg-colors.h>
+#include <media/tpg/v4l2-tpg.h>
 
 /* sRGB colors with range [0-255] */
 const struct color tpg_colors[TPG_COLOR_MAX] = {
diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
index a772976cfe26..f218b336a3ac 100644
--- a/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
+++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
@@ -21,7 +21,7 @@
  */
 
 #include <linux/module.h>
-#include <media/v4l2-tpg.h>
+#include <media/tpg/v4l2-tpg.h>
 
 /* Must remain in sync with enum tpg_pattern */
 const char * const tpg_pattern_strings[] = {
diff --git a/drivers/media/platform/vimc/vimc-sensor.c b/drivers/media/platform/vimc/vimc-sensor.c
index 02e68c8fc02b..8d2691817aa5 100644
--- a/drivers/media/platform/vimc/vimc-sensor.c
+++ b/drivers/media/platform/vimc/vimc-sensor.c
@@ -23,7 +23,7 @@
 #include <linux/v4l2-mediabus.h>
 #include <linux/vmalloc.h>
 #include <media/v4l2-subdev.h>
-#include <media/v4l2-tpg.h>
+#include <media/tpg/v4l2-tpg.h>
 
 #include "vimc-common.h"
 
diff --git a/drivers/media/platform/vivid/vivid-core.h b/drivers/media/platform/vivid/vivid-core.h
index 5cdf95bdc4d1..36802947a4b0 100644
--- a/drivers/media/platform/vivid/vivid-core.h
+++ b/drivers/media/platform/vivid/vivid-core.h
@@ -27,7 +27,7 @@
 #include <media/v4l2-device.h>
 #include <media/v4l2-dev.h>
 #include <media/v4l2-ctrls.h>
-#include <media/v4l2-tpg.h>
+#include <media/tpg/v4l2-tpg.h>
 #include "vivid-rds-gen.h"
 #include "vivid-vbi-gen.h"
 
diff --git a/include/media/v4l2-tpg.h b/include/media/tpg/v4l2-tpg.h
similarity index 93%
rename from include/media/v4l2-tpg.h
rename to include/media/tpg/v4l2-tpg.h
index 13e49d85cae3..028d81182011 100644
--- a/include/media/v4l2-tpg.h
+++ b/include/media/tpg/v4l2-tpg.h
@@ -26,8 +26,51 @@
 #include <linux/slab.h>
 #include <linux/vmalloc.h>
 #include <linux/videodev2.h>
-#include <media/v4l2-tpg-colors.h>
 
+struct color {
+	unsigned char r, g, b;
+};
+
+struct color16 {
+	int r, g, b;
+};
+
+enum tpg_color {
+	TPG_COLOR_CSC_WHITE,
+	TPG_COLOR_CSC_YELLOW,
+	TPG_COLOR_CSC_CYAN,
+	TPG_COLOR_CSC_GREEN,
+	TPG_COLOR_CSC_MAGENTA,
+	TPG_COLOR_CSC_RED,
+	TPG_COLOR_CSC_BLUE,
+	TPG_COLOR_CSC_BLACK,
+	TPG_COLOR_75_YELLOW,
+	TPG_COLOR_75_CYAN,
+	TPG_COLOR_75_GREEN,
+	TPG_COLOR_75_MAGENTA,
+	TPG_COLOR_75_RED,
+	TPG_COLOR_75_BLUE,
+	TPG_COLOR_100_WHITE,
+	TPG_COLOR_100_YELLOW,
+	TPG_COLOR_100_CYAN,
+	TPG_COLOR_100_GREEN,
+	TPG_COLOR_100_MAGENTA,
+	TPG_COLOR_100_RED,
+	TPG_COLOR_100_BLUE,
+	TPG_COLOR_100_BLACK,
+	TPG_COLOR_TEXTFG,
+	TPG_COLOR_TEXTBG,
+	TPG_COLOR_RANDOM,
+	TPG_COLOR_RAMP,
+	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
+};
+
+extern const struct color tpg_colors[TPG_COLOR_MAX];
+extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
+extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
+extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
+					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
+					  [TPG_COLOR_CSC_BLACK + 1];
 enum tpg_pattern {
 	TPG_PAT_75_COLORBAR,
 	TPG_PAT_100_COLORBAR,
diff --git a/include/media/v4l2-tpg-colors.h b/include/media/v4l2-tpg-colors.h
deleted file mode 100644
index 2a88d1fae0cd..000000000000
--- a/include/media/v4l2-tpg-colors.h
+++ /dev/null
@@ -1,68 +0,0 @@
-/*
- * v4l2-tpg-colors.h - Color definitions for the test pattern generator
- *
- * Copyright 2014 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.
- */
-
-#ifndef _V4L2_TPG_COLORS_H_
-#define _V4L2_TPG_COLORS_H_
-
-struct color {
-	unsigned char r, g, b;
-};
-
-struct color16 {
-	int r, g, b;
-};
-
-enum tpg_color {
-	TPG_COLOR_CSC_WHITE,
-	TPG_COLOR_CSC_YELLOW,
-	TPG_COLOR_CSC_CYAN,
-	TPG_COLOR_CSC_GREEN,
-	TPG_COLOR_CSC_MAGENTA,
-	TPG_COLOR_CSC_RED,
-	TPG_COLOR_CSC_BLUE,
-	TPG_COLOR_CSC_BLACK,
-	TPG_COLOR_75_YELLOW,
-	TPG_COLOR_75_CYAN,
-	TPG_COLOR_75_GREEN,
-	TPG_COLOR_75_MAGENTA,
-	TPG_COLOR_75_RED,
-	TPG_COLOR_75_BLUE,
-	TPG_COLOR_100_WHITE,
-	TPG_COLOR_100_YELLOW,
-	TPG_COLOR_100_CYAN,
-	TPG_COLOR_100_GREEN,
-	TPG_COLOR_100_MAGENTA,
-	TPG_COLOR_100_RED,
-	TPG_COLOR_100_BLUE,
-	TPG_COLOR_100_BLACK,
-	TPG_COLOR_TEXTFG,
-	TPG_COLOR_TEXTBG,
-	TPG_COLOR_RANDOM,
-	TPG_COLOR_RAMP,
-	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
-};
-
-extern const struct color tpg_colors[TPG_COLOR_MAX];
-extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
-extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
-extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
-					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
-					  [TPG_COLOR_CSC_BLACK + 1];
-
-#endif
-- 
2.13.6

[PATCH 24/24] media: v4l2-tpg.h: rename color structs

[Mauro Carvalho Chehab]

The color structs right now are just "color" and "color16".
That may lead into conflicts, and don't define precisely what
they meant. As those are used by two drivers (vivid and vimc),
this is even on a somewhat public header!

So rename them to:
	color ->  tpg_rbg_color8
	color16 ->  tpg_rbg_color16

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c | 6 +++---
 include/media/tpg/v4l2-tpg.h                    | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
index 95b26f6a0d54..43180204fab2 100644
--- a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
+++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
@@ -39,7 +39,7 @@
 #include <media/tpg/v4l2-tpg.h>
 
 /* sRGB colors with range [0-255] */
-const struct color tpg_colors[TPG_COLOR_MAX] = {
+const struct tpg_rbg_color8 tpg_colors[TPG_COLOR_MAX] = {
 	/*
 	 * Colors to test colorspace conversion: converting these colors
 	 * to other colorspaces will never lead to out-of-gamut colors.
@@ -597,7 +597,7 @@ const unsigned short tpg_linear_to_rec709[255 * 16 + 1] = {
 };
 
 /* Generated table */
-const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {
+const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {
 	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][0] = { 2939, 2939, 2939 },
 	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][1] = { 2953, 2963, 586 },
 	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][2] = { 0, 2967, 2937 },
@@ -1392,7 +1392,7 @@ int main(int argc, char **argv)
 	printf("\n};\n\n");
 
 	printf("/* Generated table */\n");
-	printf("const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {\n");
+	printf("const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {\n");
 	for (c = 0; c <= V4L2_COLORSPACE_DCI_P3; c++) {
 		for (x = 1; x <= V4L2_XFER_FUNC_SMPTE2084; x++) {
 			for (i = 0; i <= TPG_COLOR_CSC_BLACK; i++) {
diff --git a/include/media/tpg/v4l2-tpg.h b/include/media/tpg/v4l2-tpg.h
index 028d81182011..bc0b38440719 100644
--- a/include/media/tpg/v4l2-tpg.h
+++ b/include/media/tpg/v4l2-tpg.h
@@ -27,11 +27,11 @@
 #include <linux/vmalloc.h>
 #include <linux/videodev2.h>
 
-struct color {
+struct tpg_rbg_color8 {
 	unsigned char r, g, b;
 };
 
-struct color16 {
+struct tpg_rbg_color16 {
 	int r, g, b;
 };
 
@@ -65,10 +65,10 @@ enum tpg_color {
 	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
 };
 
-extern const struct color tpg_colors[TPG_COLOR_MAX];
+extern const struct tpg_rbg_color8 tpg_colors[TPG_COLOR_MAX];
 extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
 extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
-extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
+extern const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
 					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
 					  [TPG_COLOR_CSC_BLACK + 1];
 enum tpg_pattern {
-- 
2.13.6

Re: [PATCH 23/24] media: v4l2-tpg*.h: move headers to include/media/tpg and merge them

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> The v4l2-tpg*.h headers are meant to be used only internally by
> vivid and vimc. There's no sense keeping them together with the
> V4L2 kAPI headers. Also, one header includes the other as they're
> meant to be used together. So, merge them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Thanks!

	Hans

> ---
>  drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c |  2 +-
>  drivers/media/common/v4l2-tpg/v4l2-tpg-core.c   |  2 +-
>  drivers/media/platform/vimc/vimc-sensor.c       |  2 +-
>  drivers/media/platform/vivid/vivid-core.h       |  2 +-
>  include/media/{ => tpg}/v4l2-tpg.h              | 45 +++++++++++++++-
>  include/media/v4l2-tpg-colors.h                 | 68 -------------------------
>  6 files changed, 48 insertions(+), 73 deletions(-)
>  rename include/media/{ => tpg}/v4l2-tpg.h (93%)
>  delete mode 100644 include/media/v4l2-tpg-colors.h
> 
> diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> index 5b5f95c38fe1..95b26f6a0d54 100644
> --- a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> +++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> @@ -36,7 +36,7 @@
>   */
>  
>  #include <linux/videodev2.h>
> -#include <media/v4l2-tpg-colors.h>
> +#include <media/tpg/v4l2-tpg.h>
>  
>  /* sRGB colors with range [0-255] */
>  const struct color tpg_colors[TPG_COLOR_MAX] = {
> diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
> index a772976cfe26..f218b336a3ac 100644
> --- a/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
> +++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-core.c
> @@ -21,7 +21,7 @@
>   */
>  
>  #include <linux/module.h>
> -#include <media/v4l2-tpg.h>
> +#include <media/tpg/v4l2-tpg.h>
>  
>  /* Must remain in sync with enum tpg_pattern */
>  const char * const tpg_pattern_strings[] = {
> diff --git a/drivers/media/platform/vimc/vimc-sensor.c b/drivers/media/platform/vimc/vimc-sensor.c
> index 02e68c8fc02b..8d2691817aa5 100644
> --- a/drivers/media/platform/vimc/vimc-sensor.c
> +++ b/drivers/media/platform/vimc/vimc-sensor.c
> @@ -23,7 +23,7 @@
>  #include <linux/v4l2-mediabus.h>
>  #include <linux/vmalloc.h>
>  #include <media/v4l2-subdev.h>
> -#include <media/v4l2-tpg.h>
> +#include <media/tpg/v4l2-tpg.h>
>  
>  #include "vimc-common.h"
>  
> diff --git a/drivers/media/platform/vivid/vivid-core.h b/drivers/media/platform/vivid/vivid-core.h
> index 5cdf95bdc4d1..36802947a4b0 100644
> --- a/drivers/media/platform/vivid/vivid-core.h
> +++ b/drivers/media/platform/vivid/vivid-core.h
> @@ -27,7 +27,7 @@
>  #include <media/v4l2-device.h>
>  #include <media/v4l2-dev.h>
>  #include <media/v4l2-ctrls.h>
> -#include <media/v4l2-tpg.h>
> +#include <media/tpg/v4l2-tpg.h>
>  #include "vivid-rds-gen.h"
>  #include "vivid-vbi-gen.h"
>  
> diff --git a/include/media/v4l2-tpg.h b/include/media/tpg/v4l2-tpg.h
> similarity index 93%
> rename from include/media/v4l2-tpg.h
> rename to include/media/tpg/v4l2-tpg.h
> index 13e49d85cae3..028d81182011 100644
> --- a/include/media/v4l2-tpg.h
> +++ b/include/media/tpg/v4l2-tpg.h
> @@ -26,8 +26,51 @@
>  #include <linux/slab.h>
>  #include <linux/vmalloc.h>
>  #include <linux/videodev2.h>
> -#include <media/v4l2-tpg-colors.h>
>  
> +struct color {
> +	unsigned char r, g, b;
> +};
> +
> +struct color16 {
> +	int r, g, b;
> +};
> +
> +enum tpg_color {
> +	TPG_COLOR_CSC_WHITE,
> +	TPG_COLOR_CSC_YELLOW,
> +	TPG_COLOR_CSC_CYAN,
> +	TPG_COLOR_CSC_GREEN,
> +	TPG_COLOR_CSC_MAGENTA,
> +	TPG_COLOR_CSC_RED,
> +	TPG_COLOR_CSC_BLUE,
> +	TPG_COLOR_CSC_BLACK,
> +	TPG_COLOR_75_YELLOW,
> +	TPG_COLOR_75_CYAN,
> +	TPG_COLOR_75_GREEN,
> +	TPG_COLOR_75_MAGENTA,
> +	TPG_COLOR_75_RED,
> +	TPG_COLOR_75_BLUE,
> +	TPG_COLOR_100_WHITE,
> +	TPG_COLOR_100_YELLOW,
> +	TPG_COLOR_100_CYAN,
> +	TPG_COLOR_100_GREEN,
> +	TPG_COLOR_100_MAGENTA,
> +	TPG_COLOR_100_RED,
> +	TPG_COLOR_100_BLUE,
> +	TPG_COLOR_100_BLACK,
> +	TPG_COLOR_TEXTFG,
> +	TPG_COLOR_TEXTBG,
> +	TPG_COLOR_RANDOM,
> +	TPG_COLOR_RAMP,
> +	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
> +};
> +
> +extern const struct color tpg_colors[TPG_COLOR_MAX];
> +extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
> +extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
> +extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
> +					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
> +					  [TPG_COLOR_CSC_BLACK + 1];
>  enum tpg_pattern {
>  	TPG_PAT_75_COLORBAR,
>  	TPG_PAT_100_COLORBAR,
> diff --git a/include/media/v4l2-tpg-colors.h b/include/media/v4l2-tpg-colors.h
> deleted file mode 100644
> index 2a88d1fae0cd..000000000000
> --- a/include/media/v4l2-tpg-colors.h
> +++ /dev/null
> @@ -1,68 +0,0 @@
> -/*
> - * v4l2-tpg-colors.h - Color definitions for the test pattern generator
> - *
> - * Copyright 2014 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.
> - */
> -
> -#ifndef _V4L2_TPG_COLORS_H_
> -#define _V4L2_TPG_COLORS_H_
> -
> -struct color {
> -	unsigned char r, g, b;
> -};
> -
> -struct color16 {
> -	int r, g, b;
> -};
> -
> -enum tpg_color {
> -	TPG_COLOR_CSC_WHITE,
> -	TPG_COLOR_CSC_YELLOW,
> -	TPG_COLOR_CSC_CYAN,
> -	TPG_COLOR_CSC_GREEN,
> -	TPG_COLOR_CSC_MAGENTA,
> -	TPG_COLOR_CSC_RED,
> -	TPG_COLOR_CSC_BLUE,
> -	TPG_COLOR_CSC_BLACK,
> -	TPG_COLOR_75_YELLOW,
> -	TPG_COLOR_75_CYAN,
> -	TPG_COLOR_75_GREEN,
> -	TPG_COLOR_75_MAGENTA,
> -	TPG_COLOR_75_RED,
> -	TPG_COLOR_75_BLUE,
> -	TPG_COLOR_100_WHITE,
> -	TPG_COLOR_100_YELLOW,
> -	TPG_COLOR_100_CYAN,
> -	TPG_COLOR_100_GREEN,
> -	TPG_COLOR_100_MAGENTA,
> -	TPG_COLOR_100_RED,
> -	TPG_COLOR_100_BLUE,
> -	TPG_COLOR_100_BLACK,
> -	TPG_COLOR_TEXTFG,
> -	TPG_COLOR_TEXTBG,
> -	TPG_COLOR_RANDOM,
> -	TPG_COLOR_RAMP,
> -	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
> -};
> -
> -extern const struct color tpg_colors[TPG_COLOR_MAX];
> -extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
> -extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
> -extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
> -					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
> -					  [TPG_COLOR_CSC_BLACK + 1];
> -
> -#endif
> 

Re: [PATCH 24/24] media: v4l2-tpg.h: rename color structs

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> The color structs right now are just "color" and "color16".
> That may lead into conflicts, and don't define precisely what
> they meant. As those are used by two drivers (vivid and vimc),
> this is even on a somewhat public header!
> 
> So rename them to:
> 	color ->  tpg_rbg_color8
> 	color16 ->  tpg_rbg_color16
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Thanks!

	Hans

> ---
>  drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c | 6 +++---
>  include/media/tpg/v4l2-tpg.h                    | 8 ++++----
>  2 files changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> index 95b26f6a0d54..43180204fab2 100644
> --- a/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> +++ b/drivers/media/common/v4l2-tpg/v4l2-tpg-colors.c
> @@ -39,7 +39,7 @@
>  #include <media/tpg/v4l2-tpg.h>
>  
>  /* sRGB colors with range [0-255] */
> -const struct color tpg_colors[TPG_COLOR_MAX] = {
> +const struct tpg_rbg_color8 tpg_colors[TPG_COLOR_MAX] = {
>  	/*
>  	 * Colors to test colorspace conversion: converting these colors
>  	 * to other colorspaces will never lead to out-of-gamut colors.
> @@ -597,7 +597,7 @@ const unsigned short tpg_linear_to_rec709[255 * 16 + 1] = {
>  };
>  
>  /* Generated table */
> -const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {
> +const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {
>  	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][0] = { 2939, 2939, 2939 },
>  	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][1] = { 2953, 2963, 586 },
>  	[V4L2_COLORSPACE_SMPTE170M][V4L2_XFER_FUNC_709][2] = { 0, 2967, 2937 },
> @@ -1392,7 +1392,7 @@ int main(int argc, char **argv)
>  	printf("\n};\n\n");
>  
>  	printf("/* Generated table */\n");
> -	printf("const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {\n");
> +	printf("const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1][V4L2_XFER_FUNC_SMPTE2084 + 1][TPG_COLOR_CSC_BLACK + 1] = {\n");
>  	for (c = 0; c <= V4L2_COLORSPACE_DCI_P3; c++) {
>  		for (x = 1; x <= V4L2_XFER_FUNC_SMPTE2084; x++) {
>  			for (i = 0; i <= TPG_COLOR_CSC_BLACK; i++) {
> diff --git a/include/media/tpg/v4l2-tpg.h b/include/media/tpg/v4l2-tpg.h
> index 028d81182011..bc0b38440719 100644
> --- a/include/media/tpg/v4l2-tpg.h
> +++ b/include/media/tpg/v4l2-tpg.h
> @@ -27,11 +27,11 @@
>  #include <linux/vmalloc.h>
>  #include <linux/videodev2.h>
>  
> -struct color {
> +struct tpg_rbg_color8 {
>  	unsigned char r, g, b;
>  };
>  
> -struct color16 {
> +struct tpg_rbg_color16 {
>  	int r, g, b;
>  };
>  
> @@ -65,10 +65,10 @@ enum tpg_color {
>  	TPG_COLOR_MAX = TPG_COLOR_RAMP + 256
>  };
>  
> -extern const struct color tpg_colors[TPG_COLOR_MAX];
> +extern const struct tpg_rbg_color8 tpg_colors[TPG_COLOR_MAX];
>  extern const unsigned short tpg_rec709_to_linear[255 * 16 + 1];
>  extern const unsigned short tpg_linear_to_rec709[255 * 16 + 1];
> -extern const struct color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
> +extern const struct tpg_rbg_color16 tpg_csc_colors[V4L2_COLORSPACE_DCI_P3 + 1]
>  					  [V4L2_XFER_FUNC_SMPTE2084 + 1]
>  					  [TPG_COLOR_CSC_BLACK + 1];
>  enum tpg_pattern {
> 

Re: [PATCH 04/24] media: v4l2-mediabus: convert flags to enums and document them

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> There is a mess with media bus flags: there are two sets of
> flags, one used by parallel and ITU-R BT.656 outputs,
> and another one for CSI2.
> 
> Depending on the type, the same bit has different meanings.
> 
> That's very confusing, and counter-intuitive. So, split them
> into two sets of flags, inside an enum.
> 
> This way, it becomes clearer that there are two separate sets
> of flags. It also makes easier if CSI1, CSP, CSI3, etc. would
> need a different set of flags.
> 
> As a side effect, enums can be documented via kernel-docs,
> so there will be an improvement at flags documentation.
> 
> Unfortunately, soc_camera and pxa_camera do a mess with
> the flags, using either one set of flags without proper
> checks about the type. That could be fixed, but, as both drivers
> are obsolete and in the process of cleanings, I opted to just
> keep the behavior, using an unsigned int inside those two
> drivers.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Nice cleanup.

Regards,

	Hans

Re: [PATCH 05/24] media: v4l2-dev: convert VFL_TYPE_* into an enum

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> Using enums makes easier to document, as it can use kernel-doc
> markups. It also allows cross-referencing, with increases the
> kAPI readability.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
>  Documentation/media/kapi/v4l2-dev.rst     | 17 ++++++---
>  drivers/media/pci/cx88/cx88-blackbird.c   |  3 +-
>  drivers/media/pci/cx88/cx88-video.c       | 10 +++---
>  drivers/media/pci/cx88/cx88.h             |  4 +--
>  drivers/media/pci/saa7134/saa7134-video.c |  2 ++
>  drivers/media/usb/cx231xx/cx231xx-video.c |  2 ++
>  drivers/media/usb/pvrusb2/pvrusb2-v4l2.c  |  2 ++
>  drivers/media/usb/tm6000/tm6000-video.c   |  2 ++
>  drivers/media/v4l2-core/v4l2-dev.c        | 10 +++---
>  include/media/v4l2-dev.h                  | 59 +++++++++++++++++--------------
>  include/media/v4l2-mediabus.h             | 30 ++++++++++++++++
>  11 files changed, 98 insertions(+), 43 deletions(-)
> 
> diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
> index b29aa616c267..7bb0505b60f1 100644
> --- a/Documentation/media/kapi/v4l2-dev.rst
> +++ b/Documentation/media/kapi/v4l2-dev.rst
> @@ -196,11 +196,18 @@ device.
>  Which device is registered depends on the type argument. The following
>  types exist:
>  
> -- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices
> -- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext)
> -- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners
> -- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners
> -- ``VFL_TYPE_TOUCH``: ``/dev/v4l-touchX`` for touch sensors
> +========================== ====================	 ==============================
> +:c:type:`vfl_devnode_type` Device name		 Usage
> +========================== ====================	 ==============================
> +``VFL_TYPE_GRABBER``       ``/dev/videoX``       for video input/output devices
> +``VFL_TYPE_VBI``           ``/dev/vbiX``         for vertical blank data (i.e.
> +						 closed captions, teletext)
> +``VFL_TYPE_RADIO``         ``/dev/radioX``       for radio tuners
> +``VFL_TYPE_SUBDEV``        ``/dev/v4l-subdevX``  for V4L2 subdevices
> +``VFL_TYPE_SDR``           ``/dev/swradioX``     for Software Defined Radio
> +						 (SDR) tuners
> +``VFL_TYPE_TOUCH``         ``/dev/v4l-touchX``   for touch sensors
> +========================== ====================	 ==============================
>  
>  The last argument gives you a certain amount of control over the device
>  device node number used (i.e. the X in ``videoX``). Normally you will pass -1
> diff --git a/drivers/media/pci/cx88/cx88-blackbird.c b/drivers/media/pci/cx88/cx88-blackbird.c
> index e3101f04941c..0e0952e60795 100644
> --- a/drivers/media/pci/cx88/cx88-blackbird.c
> +++ b/drivers/media/pci/cx88/cx88-blackbird.c
> @@ -805,8 +805,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
>  
>  	strcpy(cap->driver, "cx88_blackbird");
>  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> -	cx88_querycap(file, core, cap);
> -	return 0;
> +	return cx88_querycap(file, core, cap);
>  }
>  
>  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> diff --git a/drivers/media/pci/cx88/cx88-video.c b/drivers/media/pci/cx88/cx88-video.c
> index 7d25ecd4404b..9be682cdb644 100644
> --- a/drivers/media/pci/cx88/cx88-video.c
> +++ b/drivers/media/pci/cx88/cx88-video.c
> @@ -806,8 +806,8 @@ static int vidioc_s_fmt_vid_cap(struct file *file, void *priv,
>  	return 0;
>  }
>  
> -void cx88_querycap(struct file *file, struct cx88_core *core,
> -		   struct v4l2_capability *cap)
> +int cx88_querycap(struct file *file, struct cx88_core *core,
> +		  struct v4l2_capability *cap)
>  {
>  	struct video_device *vdev = video_devdata(file);
>  
> @@ -825,11 +825,14 @@ void cx88_querycap(struct file *file, struct cx88_core *core,
>  	case VFL_TYPE_VBI:
>  		cap->device_caps |= V4L2_CAP_VBI_CAPTURE;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->capabilities = cap->device_caps | V4L2_CAP_VIDEO_CAPTURE |
>  		V4L2_CAP_VBI_CAPTURE | V4L2_CAP_DEVICE_CAPS;
>  	if (core->board.radio.type == CX88_RADIO)
>  		cap->capabilities |= V4L2_CAP_RADIO;
> +	return 0;
>  }
>  EXPORT_SYMBOL(cx88_querycap);
>  
> @@ -841,8 +844,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
>  
>  	strcpy(cap->driver, "cx8800");
>  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> -	cx88_querycap(file, core, cap);
> -	return 0;
> +	return cx88_querycap(file, core, cap);
>  }
>  
>  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> diff --git a/drivers/media/pci/cx88/cx88.h b/drivers/media/pci/cx88/cx88.h
> index 6777926f20f2..07a33f02fef4 100644
> --- a/drivers/media/pci/cx88/cx88.h
> +++ b/drivers/media/pci/cx88/cx88.h
> @@ -734,7 +734,7 @@ int cx8802_start_dma(struct cx8802_dev    *dev,
>  int cx88_enum_input(struct cx88_core *core, struct v4l2_input *i);
>  int cx88_set_freq(struct cx88_core  *core, const struct v4l2_frequency *f);
>  int cx88_video_mux(struct cx88_core *core, unsigned int input);
> -void cx88_querycap(struct file *file, struct cx88_core *core,
> -		   struct v4l2_capability *cap);
> +int cx88_querycap(struct file *file, struct cx88_core *core,
> +		  struct v4l2_capability *cap);
>  
>  #endif
> diff --git a/drivers/media/pci/saa7134/saa7134-video.c b/drivers/media/pci/saa7134/saa7134-video.c
> index 51d42bbf969e..e5e02eab3e23 100644
> --- a/drivers/media/pci/saa7134/saa7134-video.c
> +++ b/drivers/media/pci/saa7134/saa7134-video.c
> @@ -1531,6 +1531,8 @@ int saa7134_querycap(struct file *file, void *priv,
>  	case VFL_TYPE_VBI:
>  		cap->device_caps |= vbi_caps;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->capabilities = radio_caps | video_caps | vbi_caps |
>  		cap->device_caps | V4L2_CAP_DEVICE_CAPS;
> diff --git a/drivers/media/usb/cx231xx/cx231xx-video.c b/drivers/media/usb/cx231xx/cx231xx-video.c
> index 179b8481a870..946306aa4a4e 100644
> --- a/drivers/media/usb/cx231xx/cx231xx-video.c
> +++ b/drivers/media/usb/cx231xx/cx231xx-video.c
> @@ -1756,6 +1756,8 @@ static int cx231xx_v4l2_open(struct file *filp)
>  	case VFL_TYPE_RADIO:
>  		radio = 1;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  
>  	cx231xx_videodbg("open dev=%s type=%s users=%d\n",
> diff --git a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> index 4320bda9352d..864830d4c741 100644
> --- a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> +++ b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> @@ -153,6 +153,8 @@ static int pvr2_querycap(struct file *file, void *priv, struct v4l2_capability *
>  	case VFL_TYPE_RADIO:
>  		cap->device_caps = V4L2_CAP_RADIO;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->device_caps |= V4L2_CAP_TUNER | V4L2_CAP_READWRITE;
>  	return 0;
> diff --git a/drivers/media/usb/tm6000/tm6000-video.c b/drivers/media/usb/tm6000/tm6000-video.c
> index ec8c4d2534dc..6b8a2e265762 100644
> --- a/drivers/media/usb/tm6000/tm6000-video.c
> +++ b/drivers/media/usb/tm6000/tm6000-video.c
> @@ -1330,6 +1330,8 @@ static int __tm6000_open(struct file *file)
>  	case VFL_TYPE_RADIO:
>  		radio = 1;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  
>  	/* If more than one user, mutex should be added */
> diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
> index c647ba648805..d5e0e536ef04 100644
> --- a/drivers/media/v4l2-core/v4l2-dev.c
> +++ b/drivers/media/v4l2-core/v4l2-dev.c
> @@ -102,7 +102,7 @@ static DECLARE_BITMAP(devnode_nums[VFL_TYPE_MAX], VIDEO_NUM_DEVICES);
>  
>  #ifdef CONFIG_VIDEO_FIXED_MINOR_RANGES
>  /* Return the bitmap corresponding to vfl_type. */
> -static inline unsigned long *devnode_bits(int vfl_type)
> +static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
>  {
>  	/* Any types not assigned to fixed minor ranges must be mapped to
>  	   one single bitmap for the purposes of finding a free node number
> @@ -113,7 +113,7 @@ static inline unsigned long *devnode_bits(int vfl_type)
>  }
>  #else
>  /* Return the bitmap corresponding to vfl_type. */
> -static inline unsigned long *devnode_bits(int vfl_type)
> +static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
>  {
>  	return devnode_nums[vfl_type];
>  }
> @@ -821,8 +821,10 @@ static int video_register_media_controller(struct video_device *vdev, int type)
>  	return 0;
>  }
>  
> -int __video_register_device(struct video_device *vdev, int type, int nr,
> -		int warn_if_nr_in_use, struct module *owner)
> +int __video_register_device(struct video_device *vdev,
> +			    enum vfl_devnode_type type,
> +			    int nr, int warn_if_nr_in_use,
> +			    struct module *owner)
>  {
>  	int i = 0;
>  	int ret;
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index de1a1453cfd9..f182b47dfd71 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -20,13 +20,25 @@
>  
>  #define VIDEO_MAJOR	81
>  
> -#define VFL_TYPE_GRABBER	0
> -#define VFL_TYPE_VBI		1
> -#define VFL_TYPE_RADIO		2
> -#define VFL_TYPE_SUBDEV		3
> -#define VFL_TYPE_SDR		4
> -#define VFL_TYPE_TOUCH		5
> -#define VFL_TYPE_MAX		6
> +/**
> + * enum vfl_devnode_type - type of V4L2 device node
> + *
> + * @VFL_TYPE_GRABBER:	for video input/output devices
> + * @VFL_TYPE_VBI:	for vertical blank data (i.e. closed captions, teletext)
> + * @VFL_TYPE_RADIO:	for radio tuners
> + * @VFL_TYPE_SUBDEV:	for V4L2 subdevices
> + * @VFL_TYPE_SDR:	for Software Defined Radio tuners
> + * @VFL_TYPE_TOUCH:	for touch sensors
> + */
> +enum vfl_devnode_type {
> +	VFL_TYPE_GRABBER	= 0,
> +	VFL_TYPE_VBI		= 1,
> +	VFL_TYPE_RADIO		= 2,
> +	VFL_TYPE_SUBDEV		= 3,
> +	VFL_TYPE_SDR		= 4,
> +	VFL_TYPE_TOUCH		= 5,
> +};
> +#define VFL_TYPE_MAX VFL_TYPE_TOUCH
>  
>  /* Is this a receiver, transmitter or mem-to-mem? */
>  /* Ignored for VFL_TYPE_SUBDEV. */
> @@ -188,7 +200,7 @@ struct v4l2_file_operations {
>   * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
>   *	 If NULL, then v4l2_dev->prio will be used.
>   * @name: video device name
> - * @vfl_type: V4L device type
> + * @vfl_type: V4L device type, as defined by &enum vfl_devnode_type
>   * @vfl_dir: V4L receiver, transmitter or m2m
>   * @minor: device node 'minor'. It is set to -1 if the registration failed
>   * @num: number of the video device node
> @@ -236,7 +248,7 @@ struct video_device
>  
>  	/* device info */
>  	char name[32];
> -	int vfl_type;
> +	enum vfl_devnode_type vfl_type;
>  	int vfl_dir;
>  	int minor;
>  	u16 num;
> @@ -281,7 +293,7 @@ struct video_device
>   * __video_register_device - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   * @warn_if_nr_in_use: warn if the desired device node number
> @@ -300,29 +312,22 @@ struct video_device
>   *
>   * Returns 0 on success.
>   *
> - * Valid values for @type are:
> - *
> - *	- %VFL_TYPE_GRABBER - A frame grabber
> - *	- %VFL_TYPE_VBI - Vertical blank data (undecoded)
> - *	- %VFL_TYPE_RADIO - A radio card
> - *	- %VFL_TYPE_SUBDEV - A subdevice
> - *	- %VFL_TYPE_SDR - Software Defined Radio
> - *	- %VFL_TYPE_TOUCH - A touch sensor
> - *
>   * .. note::
>   *
>   *	This function is meant to be used only inside the V4L2 core.
>   *	Drivers should use video_register_device() or
>   *	video_register_device_no_warn().
>   */
> -int __must_check __video_register_device(struct video_device *vdev, int type,
> -		int nr, int warn_if_nr_in_use, struct module *owner);
> +int __must_check __video_register_device(struct video_device *vdev,
> +					 enum vfl_devnode_type type,
> +					 int nr, int warn_if_nr_in_use,
> +					 struct module *owner);
>  
>  /**
>   *  video_register_device - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   *
> @@ -336,7 +341,8 @@ int __must_check __video_register_device(struct video_device *vdev, int type,
>   *	you video_device_release() should be called on failure.
>   */
>  static inline int __must_check video_register_device(struct video_device *vdev,
> -		int type, int nr)
> +						     enum vfl_devnode_type type,
> +						     int nr)
>  {
>  	return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
>  }
> @@ -345,7 +351,7 @@ static inline int __must_check video_register_device(struct video_device *vdev,
>   *  video_register_device_no_warn - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   *
> @@ -361,8 +367,9 @@ static inline int __must_check video_register_device(struct video_device *vdev,
>   *	is responsible for freeing any data. Usually that means that
>   *	you video_device_release() should be called on failure.
>   */
> -static inline int __must_check video_register_device_no_warn(
> -		struct video_device *vdev, int type, int nr)
> +static inline int __must_check
> +video_register_device_no_warn(struct video_device *vdev,
> +			      enum vfl_devnode_type type, int nr)
>  {
>  	return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
>  }
> diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
> index 47adb1608d98..3bfe6bcc8365 100644
> --- a/include/media/v4l2-mediabus.h
> +++ b/include/media/v4l2-mediabus.h
> @@ -143,6 +143,13 @@ struct v4l2_mbus_config {
>  	};
>  };
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + *	v4l2_pix_format fields from a &struct v4l2_mbus_framefmt.
> + *
> + * @pix_fmt:	pointer to &struct v4l2_pix_format to be filled
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
> + */
>  static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
>  				const struct v4l2_mbus_framefmt *mbus_fmt)
>  {
> @@ -155,6 +162,15 @@ static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
>  	pix_fmt->xfer_func = mbus_fmt->xfer_func;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format and a
> + *	data format code.
> + *
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
> + * @pix_fmt:	pointer to &struct v4l2_pix_format to be used as model
> + * @code:	data format code (from &enum v4l2_mbus_pixelcode)
> + */
>  static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
>  			   const struct v4l2_pix_format *pix_fmt,
>  			   u32 code)
> @@ -169,6 +185,13 @@ static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
>  	mbus_fmt->code = code;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + *	v4l2_pix_format_mplane fields from a media bus structure.
> + *
> + * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be filled
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
> + */
>  static inline void v4l2_fill_pix_format_mplane(
>  				struct v4l2_pix_format_mplane *pix_mp_fmt,
>  				const struct v4l2_mbus_framefmt *mbus_fmt)
> @@ -182,6 +205,13 @@ static inline void v4l2_fill_pix_format_mplane(
>  	pix_mp_fmt->xfer_func = mbus_fmt->xfer_func;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format_mplane.
> + *
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
> + * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be used as model
> + */
>  static inline void v4l2_fill_mbus_format_mplane(
>  				struct v4l2_mbus_framefmt *mbus_fmt,
>  				const struct v4l2_pix_format_mplane *pix_mp_fmt)
> 

Re: [PATCH 06/24] media: i2c-addr.h: get rid of now unused defines

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> Some of the previously used I2C addresses there aren't used
> anymore. So, get rid of them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
>  include/media/i2c-addr.h | 7 -------
>  1 file changed, 7 deletions(-)
> 
> diff --git a/include/media/i2c-addr.h b/include/media/i2c-addr.h
> index 5d0f56054d26..fba0457b74c4 100644
> --- a/include/media/i2c-addr.h
> +++ b/include/media/i2c-addr.h
> @@ -10,21 +10,14 @@
>   */
>  
>  /* bttv address list */
> -#define I2C_ADDR_TSA5522	0xc2
>  #define I2C_ADDR_TDA7432	0x8a
>  #define I2C_ADDR_TDA8425	0x82
>  #define I2C_ADDR_TDA9840	0x84
> -#define I2C_ADDR_TDA9850	0xb6 /* also used by 9855,9873 */
>  #define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
>  #define I2C_ADDR_TDA9875	0xb0
> -#define I2C_ADDR_HAUPEE		0xa0
> -#define I2C_ADDR_STBEE		0xae
> -#define I2C_ADDR_VHX		0xc0
>  #define I2C_ADDR_MSP3400	0x80
>  #define I2C_ADDR_MSP3400_ALT	0x88
>  #define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
> -#define I2C_ADDR_DPL3518	0x84
> -#define I2C_ADDR_TDA9887	0x86
>  
>  /*
>   * i2c bus addresses for the chips supported by tvaudio.c
> 

Re: [PATCH 07/24] media: get rid of i2c-addr.h

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> In the past, the same I2C address were used on multiple places.
> After I2C rebinding changes, this is no longer needed. So, we
> can just get rid of this header, placing the I2C address where
> they belong, e. g. either at bttv driver or at tvtuner.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Huh, I thought this header was nuked a long time ago...

Regards,

	Hans

> ---
>  drivers/media/i2c/tda7432.c             |  1 -
>  drivers/media/i2c/tvaudio.c             |  2 --
>  drivers/media/pci/bt8xx/bttv-cards.c    |  7 +++++++
>  drivers/media/pci/bt8xx/bttv.h          |  1 -
>  drivers/media/usb/em28xx/em28xx-cards.c |  1 -
>  drivers/media/usb/tm6000/tm6000-cards.c |  1 -
>  include/media/i2c-addr.h                | 35 ---------------------------------
>  include/media/i2c/tvaudio.h             | 17 +++++++++++++++-
>  8 files changed, 23 insertions(+), 42 deletions(-)
>  delete mode 100644 include/media/i2c-addr.h
> 
> diff --git a/drivers/media/i2c/tda7432.c b/drivers/media/i2c/tda7432.c
> index d87168adee45..1c5c61d829d6 100644
> --- a/drivers/media/i2c/tda7432.c
> +++ b/drivers/media/i2c/tda7432.c
> @@ -36,7 +36,6 @@
>  #include <media/v4l2-device.h>
>  #include <media/v4l2-ioctl.h>
>  #include <media/v4l2-ctrls.h>
> -#include <media/i2c-addr.h>
>  
>  #ifndef VIDEO_AUDIO_BALANCE
>  # define VIDEO_AUDIO_BALANCE 32
> diff --git a/drivers/media/i2c/tvaudio.c b/drivers/media/i2c/tvaudio.c
> index ce86534450ac..92718a9ff5ea 100644
> --- a/drivers/media/i2c/tvaudio.c
> +++ b/drivers/media/i2c/tvaudio.c
> @@ -40,8 +40,6 @@
>  #include <media/v4l2-device.h>
>  #include <media/v4l2-ctrls.h>
>  
> -#include <media/i2c-addr.h>
> -
>  /* ---------------------------------------------------------------------- */
>  /* insmod args                                                            */
>  
> diff --git a/drivers/media/pci/bt8xx/bttv-cards.c b/drivers/media/pci/bt8xx/bttv-cards.c
> index 5cc42b426715..7dcf509e66d9 100644
> --- a/drivers/media/pci/bt8xx/bttv-cards.c
> +++ b/drivers/media/pci/bt8xx/bttv-cards.c
> @@ -141,6 +141,13 @@ MODULE_PARM_DESC(audiodev, "specify audio device:\n"
>  MODULE_PARM_DESC(saa6588, "if 1, then load the saa6588 RDS module, default (0) is to use the card definition.");
>  MODULE_PARM_DESC(no_overlay, "allow override overlay default (0 disables, 1 enables) [some VIA/SIS chipsets are known to have problem with overlay]");
>  
> +
> +/* I2C addresses list */
> +#define I2C_ADDR_TDA7432	0x8a
> +#define I2C_ADDR_MSP3400	0x80
> +#define I2C_ADDR_MSP3400_ALT	0x88
> +
> +
>  /* ----------------------------------------------------------------------- */
>  /* list of card IDs for bt878+ cards                                       */
>  
> diff --git a/drivers/media/pci/bt8xx/bttv.h b/drivers/media/pci/bt8xx/bttv.h
> index 91301c3cad1e..faea9aeff711 100644
> --- a/drivers/media/pci/bt8xx/bttv.h
> +++ b/drivers/media/pci/bt8xx/bttv.h
> @@ -17,7 +17,6 @@
>  #include <linux/videodev2.h>
>  #include <linux/i2c.h>
>  #include <media/v4l2-device.h>
> -#include <media/i2c-addr.h>
>  #include <media/tuner.h>
>  
>  /* ---------------------------------------------------------- */
> diff --git a/drivers/media/usb/em28xx/em28xx-cards.c b/drivers/media/usb/em28xx/em28xx-cards.c
> index 4c57fd7929cb..34e16f6ab4ac 100644
> --- a/drivers/media/usb/em28xx/em28xx-cards.c
> +++ b/drivers/media/usb/em28xx/em28xx-cards.c
> @@ -36,7 +36,6 @@
>  #include <media/i2c/saa7115.h>
>  #include <dt-bindings/media/tvp5150.h>
>  #include <media/i2c/tvaudio.h>
> -#include <media/i2c-addr.h>
>  #include <media/tveeprom.h>
>  #include <media/v4l2-common.h>
>  #include <sound/ac97_codec.h>
> diff --git a/drivers/media/usb/tm6000/tm6000-cards.c b/drivers/media/usb/tm6000/tm6000-cards.c
> index 2537643a1808..b4df9181c54b 100644
> --- a/drivers/media/usb/tm6000/tm6000-cards.c
> +++ b/drivers/media/usb/tm6000/tm6000-cards.c
> @@ -23,7 +23,6 @@
>  #include <media/v4l2-common.h>
>  #include <media/tuner.h>
>  #include <media/i2c/tvaudio.h>
> -#include <media/i2c-addr.h>
>  #include <media/rc-map.h>
>  
>  #include "tm6000.h"
> diff --git a/include/media/i2c-addr.h b/include/media/i2c-addr.h
> deleted file mode 100644
> index fba0457b74c4..000000000000
> --- a/include/media/i2c-addr.h
> +++ /dev/null
> @@ -1,35 +0,0 @@
> -/*
> - *	V4L I2C address list
> - *
> - *
> - *	Copyright (C) 2006 Mauro Carvalho Chehab <mchehab@infradead.org>
> - *	Based on a previous mapping by
> - *	Ralph Metzler (rjkm@thp.uni-koeln.de)
> - *	Gerd Knorr <kraxel@goldbach.in-berlin.de>
> - *
> - */
> -
> -/* bttv address list */
> -#define I2C_ADDR_TDA7432	0x8a
> -#define I2C_ADDR_TDA8425	0x82
> -#define I2C_ADDR_TDA9840	0x84
> -#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
> -#define I2C_ADDR_TDA9875	0xb0
> -#define I2C_ADDR_MSP3400	0x80
> -#define I2C_ADDR_MSP3400_ALT	0x88
> -#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
> -
> -/*
> - * i2c bus addresses for the chips supported by tvaudio.c
> - */
> -
> -#define I2C_ADDR_TDA8425	0x82
> -#define I2C_ADDR_TDA9840	0x84 /* also used by TA8874Z */
> -#define I2C_ADDR_TDA985x_L	0xb4 /* also used by 9873 */
> -#define I2C_ADDR_TDA985x_H	0xb6
> -#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
> -
> -#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
> -#define I2C_ADDR_TEA6420	0x98
> -
> -#define I2C_ADDR_PIC16C54	0x96 /* PV951 */
> diff --git a/include/media/i2c/tvaudio.h b/include/media/i2c/tvaudio.h
> index 1ac8184693f8..f13e1a386364 100644
> --- a/include/media/i2c/tvaudio.h
> +++ b/include/media/i2c/tvaudio.h
> @@ -21,7 +21,22 @@
>  #ifndef _TVAUDIO_H
>  #define _TVAUDIO_H
>  
> -#include <media/i2c-addr.h>
> +/*
> + * i2c bus addresses for the chips supported by tvaudio.c
> + */
> +
> +#define I2C_ADDR_TDA8425	0x82
> +#define I2C_ADDR_TDA9840	0x84
> +#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
> +#define I2C_ADDR_TDA9875	0xb0
> +#define I2C_ADDR_TDA8425	0x82
> +#define I2C_ADDR_TDA9840	0x84 /* also used by TA8874Z */
> +#define I2C_ADDR_TDA985x_L	0xb4 /* also used by 9873 */
> +#define I2C_ADDR_TDA985x_H	0xb6
> +#define I2C_ADDR_TDA9874	0xb0 /* also used by 9875 */
> +#define I2C_ADDR_TEA6300	0x80 /* also used by 6320 */
> +#define I2C_ADDR_TEA6420	0x98
> +#define I2C_ADDR_PIC16C54	0x96 /* PV951 */
>  
>  /* The tvaudio module accepts the following inputs: */
>  #define TVAUDIO_INPUT_TUNER  0
> 

Re: [PATCH 08/24] media: v4l2-dev: document VFL_DIR_* direction defines

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> The V4L_DIR_* direction flags document the direction for a
> V4L2 device node. Convert them to enum and document.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
>  include/media/v4l2-dev.h | 22 ++++++++++++++++------
>  1 file changed, 16 insertions(+), 6 deletions(-)
> 
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index f182b47dfd71..87dac58c7799 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -40,11 +40,21 @@ enum vfl_devnode_type {
>  };
>  #define VFL_TYPE_MAX VFL_TYPE_TOUCH
>  
> -/* Is this a receiver, transmitter or mem-to-mem? */
> -/* Ignored for VFL_TYPE_SUBDEV. */
> -#define VFL_DIR_RX		0
> -#define VFL_DIR_TX		1
> -#define VFL_DIR_M2M		2
> +/**
> + * enum  vfl_direction - Identifies if a &struct video_device corresponds
> + *	to a receiver, a transmitter or a mem-to-mem device.
> + *
> + * @VFL_DIR_RX:		device is a receiver.
> + * @VFL_DIR_TX:		device is a transmitter.
> + * @VFL_DIR_M2M:	device is a memory to memory device.
> + *
> + * Note: Ignored if &enum vfl_devnode_type is %VFL_TYPE_SUBDEV.
> + */
> +enum vfl_devnode_direction {
> +	VFL_DIR_RX,
> +	VFL_DIR_TX,
> +	VFL_DIR_M2M,
> +};
>  
>  struct v4l2_ioctl_callbacks;
>  struct video_device;
> @@ -249,7 +259,7 @@ struct video_device
>  	/* device info */
>  	char name[32];
>  	enum vfl_devnode_type vfl_type;
> -	int vfl_dir;
> +	enum vfl_devnode_direction vfl_dir;
>  	int minor;
>  	u16 num;
>  	unsigned long flags;
> 

Re: [PATCH 09/24] media: v4l2-dev: document video_device flags

[Hans Verkuil]

On 09/10/17 12:19, Mauro Carvalho Chehab wrote:
> Convert #defines to enums and add kernel-doc markups for V4L2
> video_device flags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>

Regards,

	Hans

> ---
>  include/media/v4l2-dev.h | 25 ++++++++++++++++++-------
>  1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index 87dac58c7799..33a5256232f8 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -61,12 +61,22 @@ struct video_device;
>  struct v4l2_device;
>  struct v4l2_ctrl_handler;
>  
> -/* Flag to mark the video_device struct as registered.
> -   Drivers can clear this flag if they want to block all future
> -   device access. It is cleared by video_unregister_device. */
> -#define V4L2_FL_REGISTERED	(0)
> -/* file->private_data points to struct v4l2_fh */
> -#define V4L2_FL_USES_V4L2_FH	(1)
> +/**
> + * enum v4l2_video_device_flags - Flags used by &struct video_device
> + *
> + * @V4L2_FL_REGISTERED:
> + * 	indicates that a &struct video_device is registered.
> + *	Drivers can clear this flag if they want to block all future
> + *	device access. It is cleared by video_unregister_device.
> + * @V4L2_FL_USES_V4L2_FH:
> + *	indicates that file->private_data points to &struct v4l2_fh.
> + *	This flag is set by the core when v4l2_fh_init() is called.
> + *	All new drivers should use it.
> + */
> +enum v4l2_video_device_flags {
> +	V4L2_FL_REGISTERED	= 0,
> +	V4L2_FL_USES_V4L2_FH	= 1,
> +};
>  
>  /* Priority helper functions */
>  
> @@ -214,7 +224,8 @@ struct v4l2_file_operations {
>   * @vfl_dir: V4L receiver, transmitter or m2m
>   * @minor: device node 'minor'. It is set to -1 if the registration failed
>   * @num: number of the video device node
> - * @flags: video device flags. Use bitops to set/clear/test flags
> + * @flags: video device flags. Use bitops to set/clear/test flags.
> + *	   Contains a set of &enum v4l2_video_device_flags.
>   * @index: attribute to differentiate multiple indices on one physical device
>   * @fh_lock: Lock for all v4l2_fhs
>   * @fh_list: List of &struct v4l2_fh
> 

Re: [PATCH 01/24] media: v4l2-dev.h: add kernel-doc to two macros

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:07AM -0300, Mauro Carvalho Chehab wrote:
> There are two macros at v4l2-dev.h that aren't documented.
> 
> Document them, for completeness.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/v4l2-dev.h | 18 +++++++++++++++---
>  1 file changed, 15 insertions(+), 3 deletions(-)
> 
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index e657614521e3..de1a1453cfd9 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -260,9 +260,21 @@ struct video_device
>  	struct mutex *lock;
>  };
>  
> -#define media_entity_to_video_device(__e) \
> -	container_of(__e, struct video_device, entity)
> -/* dev to video-device */
> +/**
> + * media_entity_to_video_device - Returns a &struct video_device from
> + * 	the &struct media_entity embedded on it.
> + *
> + * @entity: pointer to &struct media_entity
> + */
> +#define media_entity_to_video_device(entity) \
> +	container_of(entity, struct video_device, entity)
> +
> +/**
> + * media_entity_to_video_device - Returns a &struct video_device from

-> to_video_device

With that,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> + * 	the &struct device embedded on it.
> + *
> + * @cd: pointer to &struct device
> + */
>  #define to_video_device(cd) container_of(cd, struct video_device, dev)
>  
>  /**

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 02/24] media: v4l2-flash-led-class.h: add kernel-doc to two ancillary funcs

[Sakari Ailus]

Hi Mauro,

Thanks for the patch.

On Mon, Oct 09, 2017 at 07:19:08AM -0300, Mauro Carvalho Chehab wrote:
> There are two ancillary functions at v4l2-flash-led-class.h
> that aren't documented.
> 
> Document them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/v4l2-flash-led-class.h | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/include/media/v4l2-flash-led-class.h b/include/media/v4l2-flash-led-class.h
> index 5c1d50f78e12..39a5daa977aa 100644
> --- a/include/media/v4l2-flash-led-class.h
> +++ b/include/media/v4l2-flash-led-class.h
> @@ -91,12 +91,24 @@ struct v4l2_flash {
>  	struct v4l2_ctrl **ctrls;
>  };
>  
> +/**
> + * v4l2_subdev_to_v4l2_flash - Returns a &v4l2_flash from the

v4l2_flash -> struct v4l2_flash ?

Same below. With these,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> + * &struct v4l2_subdev embedded on it.
> + *
> + * @sd: pointer to &struct v4l2_subdev
> + */
>  static inline struct v4l2_flash *v4l2_subdev_to_v4l2_flash(
>  							struct v4l2_subdev *sd)
>  {
>  	return container_of(sd, struct v4l2_flash, sd);
>  }
>  
> +/**
> + * v4l2_ctrl_to_v4l2_flash - Returns a &v4l2_flash from the
> + * &struct v4l2_ctrl embedded on it.
> + *
> + * @c: pointer to &struct v4l2_ctrl
> + */
>  static inline struct v4l2_flash *v4l2_ctrl_to_v4l2_flash(struct v4l2_ctrl *c)
>  {
>  	return container_of(c->handler, struct v4l2_flash, hdl);

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 03/24] media: v4l2-mediabus: use BIT() macro for flags

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:09AM -0300, Mauro Carvalho Chehab wrote:
> Instead of using (1 << n) for bits, use the BIT() macro,
> as it makes them better documented.

I wouldn't say this makes a difference from documentation point of view.

Anyway,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 00/24] V4L2 kAPI cleanups and documentation improvements part 2

[Mauro Carvalho Chehab]

Em Mon,  9 Oct 2017 07:19:06 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> That's the second part of my V4L2 kAPI documentation improvements.
> It is meant to reduce the gap between the kAPI media headers
> and documentation, at least with regards to kernel-doc markups.
> 
> We should likely write more things at the ReST files under Documentation/
> to better describe some of those APIs (VB2 being likely the first candidate),
> but at least let's be sure that all V4L2 bits have kernel-doc markups.

Forgot to mention: 

This series, together with the part1 one is on this tree:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=v4l-docs-part2-v1

As I may not have time to address the remaining kAPI bits for
a while, let me document what kAPIs at include/media main dir
are still out of sync:

	- cec-pin.h: struct cec_pin;
	- cec.h: several structs;
	- media-device.h, media-devnode.h: a couple of defines;
	- rc-core.h: ancillary functions;
	- soc-camera.h, v4l2-clk.h, videobuf-*.h - probably not
	  worth the efforts, as those are obsolete kAPI;
	- v4l2-common.h: print macros. IMHO, we should try to get
	  rid of them, and use dev_foo() everywhere;
	- v4l2-fwnode.h: In this specific case, Sakari has a patch
	  series addressing it, moving existing documentation from
	  v4l2-fwnode.c;
	- v4l2-mem2mem.h: v4l2 ioctl helpers aren't documented;
	- videobuf2-*.h: This series contain several documentation
	  improvements there for VB2 core and V4L2, with are the
	  most important ones - as they're used by the drivers.
	  The other headers are either undocumented or barely
	  documented.

PS.: It should be noticed that there are other files under
     include/media and inside their sub-directories that aren't
     part of the media kAPI, but are driver-specific stuff,
     like, for example, imx.h, vsp1.h and i2c/ subdir.


Thanks,
Mauro

Re: [PATCH 05/24] media: v4l2-dev: convert VFL_TYPE_* into an enum

[Mike Isely]

Acked-By: Mike Isely <isely@pobox.com>

On Mon, 9 Oct 2017, Mauro Carvalho Chehab wrote:

> Using enums makes easier to document, as it can use kernel-doc
> markups. It also allows cross-referencing, with increases the
> kAPI readability.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/kapi/v4l2-dev.rst     | 17 ++++++---
>  drivers/media/pci/cx88/cx88-blackbird.c   |  3 +-
>  drivers/media/pci/cx88/cx88-video.c       | 10 +++---
>  drivers/media/pci/cx88/cx88.h             |  4 +--
>  drivers/media/pci/saa7134/saa7134-video.c |  2 ++
>  drivers/media/usb/cx231xx/cx231xx-video.c |  2 ++
>  drivers/media/usb/pvrusb2/pvrusb2-v4l2.c  |  2 ++
>  drivers/media/usb/tm6000/tm6000-video.c   |  2 ++
>  drivers/media/v4l2-core/v4l2-dev.c        | 10 +++---
>  include/media/v4l2-dev.h                  | 59 +++++++++++++++++--------------
>  include/media/v4l2-mediabus.h             | 30 ++++++++++++++++
>  11 files changed, 98 insertions(+), 43 deletions(-)
> 
> diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
> index b29aa616c267..7bb0505b60f1 100644
> --- a/Documentation/media/kapi/v4l2-dev.rst
> +++ b/Documentation/media/kapi/v4l2-dev.rst
> @@ -196,11 +196,18 @@ device.
>  Which device is registered depends on the type argument. The following
>  types exist:
>  
> -- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices
> -- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext)
> -- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners
> -- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners
> -- ``VFL_TYPE_TOUCH``: ``/dev/v4l-touchX`` for touch sensors
> +========================== ====================	 ==============================
> +:c:type:`vfl_devnode_type` Device name		 Usage
> +========================== ====================	 ==============================
> +``VFL_TYPE_GRABBER``       ``/dev/videoX``       for video input/output devices
> +``VFL_TYPE_VBI``           ``/dev/vbiX``         for vertical blank data (i.e.
> +						 closed captions, teletext)
> +``VFL_TYPE_RADIO``         ``/dev/radioX``       for radio tuners
> +``VFL_TYPE_SUBDEV``        ``/dev/v4l-subdevX``  for V4L2 subdevices
> +``VFL_TYPE_SDR``           ``/dev/swradioX``     for Software Defined Radio
> +						 (SDR) tuners
> +``VFL_TYPE_TOUCH``         ``/dev/v4l-touchX``   for touch sensors
> +========================== ====================	 ==============================
>  
>  The last argument gives you a certain amount of control over the device
>  device node number used (i.e. the X in ``videoX``). Normally you will pass -1
> diff --git a/drivers/media/pci/cx88/cx88-blackbird.c b/drivers/media/pci/cx88/cx88-blackbird.c
> index e3101f04941c..0e0952e60795 100644
> --- a/drivers/media/pci/cx88/cx88-blackbird.c
> +++ b/drivers/media/pci/cx88/cx88-blackbird.c
> @@ -805,8 +805,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
>  
>  	strcpy(cap->driver, "cx88_blackbird");
>  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> -	cx88_querycap(file, core, cap);
> -	return 0;
> +	return cx88_querycap(file, core, cap);
>  }
>  
>  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> diff --git a/drivers/media/pci/cx88/cx88-video.c b/drivers/media/pci/cx88/cx88-video.c
> index 7d25ecd4404b..9be682cdb644 100644
> --- a/drivers/media/pci/cx88/cx88-video.c
> +++ b/drivers/media/pci/cx88/cx88-video.c
> @@ -806,8 +806,8 @@ static int vidioc_s_fmt_vid_cap(struct file *file, void *priv,
>  	return 0;
>  }
>  
> -void cx88_querycap(struct file *file, struct cx88_core *core,
> -		   struct v4l2_capability *cap)
> +int cx88_querycap(struct file *file, struct cx88_core *core,
> +		  struct v4l2_capability *cap)
>  {
>  	struct video_device *vdev = video_devdata(file);
>  
> @@ -825,11 +825,14 @@ void cx88_querycap(struct file *file, struct cx88_core *core,
>  	case VFL_TYPE_VBI:
>  		cap->device_caps |= V4L2_CAP_VBI_CAPTURE;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->capabilities = cap->device_caps | V4L2_CAP_VIDEO_CAPTURE |
>  		V4L2_CAP_VBI_CAPTURE | V4L2_CAP_DEVICE_CAPS;
>  	if (core->board.radio.type == CX88_RADIO)
>  		cap->capabilities |= V4L2_CAP_RADIO;
> +	return 0;
>  }
>  EXPORT_SYMBOL(cx88_querycap);
>  
> @@ -841,8 +844,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
>  
>  	strcpy(cap->driver, "cx8800");
>  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> -	cx88_querycap(file, core, cap);
> -	return 0;
> +	return cx88_querycap(file, core, cap);
>  }
>  
>  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> diff --git a/drivers/media/pci/cx88/cx88.h b/drivers/media/pci/cx88/cx88.h
> index 6777926f20f2..07a33f02fef4 100644
> --- a/drivers/media/pci/cx88/cx88.h
> +++ b/drivers/media/pci/cx88/cx88.h
> @@ -734,7 +734,7 @@ int cx8802_start_dma(struct cx8802_dev    *dev,
>  int cx88_enum_input(struct cx88_core *core, struct v4l2_input *i);
>  int cx88_set_freq(struct cx88_core  *core, const struct v4l2_frequency *f);
>  int cx88_video_mux(struct cx88_core *core, unsigned int input);
> -void cx88_querycap(struct file *file, struct cx88_core *core,
> -		   struct v4l2_capability *cap);
> +int cx88_querycap(struct file *file, struct cx88_core *core,
> +		  struct v4l2_capability *cap);
>  
>  #endif
> diff --git a/drivers/media/pci/saa7134/saa7134-video.c b/drivers/media/pci/saa7134/saa7134-video.c
> index 51d42bbf969e..e5e02eab3e23 100644
> --- a/drivers/media/pci/saa7134/saa7134-video.c
> +++ b/drivers/media/pci/saa7134/saa7134-video.c
> @@ -1531,6 +1531,8 @@ int saa7134_querycap(struct file *file, void *priv,
>  	case VFL_TYPE_VBI:
>  		cap->device_caps |= vbi_caps;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->capabilities = radio_caps | video_caps | vbi_caps |
>  		cap->device_caps | V4L2_CAP_DEVICE_CAPS;
> diff --git a/drivers/media/usb/cx231xx/cx231xx-video.c b/drivers/media/usb/cx231xx/cx231xx-video.c
> index 179b8481a870..946306aa4a4e 100644
> --- a/drivers/media/usb/cx231xx/cx231xx-video.c
> +++ b/drivers/media/usb/cx231xx/cx231xx-video.c
> @@ -1756,6 +1756,8 @@ static int cx231xx_v4l2_open(struct file *filp)
>  	case VFL_TYPE_RADIO:
>  		radio = 1;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  
>  	cx231xx_videodbg("open dev=%s type=%s users=%d\n",
> diff --git a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> index 4320bda9352d..864830d4c741 100644
> --- a/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> +++ b/drivers/media/usb/pvrusb2/pvrusb2-v4l2.c
> @@ -153,6 +153,8 @@ static int pvr2_querycap(struct file *file, void *priv, struct v4l2_capability *
>  	case VFL_TYPE_RADIO:
>  		cap->device_caps = V4L2_CAP_RADIO;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  	cap->device_caps |= V4L2_CAP_TUNER | V4L2_CAP_READWRITE;
>  	return 0;
> diff --git a/drivers/media/usb/tm6000/tm6000-video.c b/drivers/media/usb/tm6000/tm6000-video.c
> index ec8c4d2534dc..6b8a2e265762 100644
> --- a/drivers/media/usb/tm6000/tm6000-video.c
> +++ b/drivers/media/usb/tm6000/tm6000-video.c
> @@ -1330,6 +1330,8 @@ static int __tm6000_open(struct file *file)
>  	case VFL_TYPE_RADIO:
>  		radio = 1;
>  		break;
> +	default:
> +		return -EINVAL;
>  	}
>  
>  	/* If more than one user, mutex should be added */
> diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c
> index c647ba648805..d5e0e536ef04 100644
> --- a/drivers/media/v4l2-core/v4l2-dev.c
> +++ b/drivers/media/v4l2-core/v4l2-dev.c
> @@ -102,7 +102,7 @@ static DECLARE_BITMAP(devnode_nums[VFL_TYPE_MAX], VIDEO_NUM_DEVICES);
>  
>  #ifdef CONFIG_VIDEO_FIXED_MINOR_RANGES
>  /* Return the bitmap corresponding to vfl_type. */
> -static inline unsigned long *devnode_bits(int vfl_type)
> +static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
>  {
>  	/* Any types not assigned to fixed minor ranges must be mapped to
>  	   one single bitmap for the purposes of finding a free node number
> @@ -113,7 +113,7 @@ static inline unsigned long *devnode_bits(int vfl_type)
>  }
>  #else
>  /* Return the bitmap corresponding to vfl_type. */
> -static inline unsigned long *devnode_bits(int vfl_type)
> +static inline unsigned long *devnode_bits(enum vfl_devnode_type vfl_type)
>  {
>  	return devnode_nums[vfl_type];
>  }
> @@ -821,8 +821,10 @@ static int video_register_media_controller(struct video_device *vdev, int type)
>  	return 0;
>  }
>  
> -int __video_register_device(struct video_device *vdev, int type, int nr,
> -		int warn_if_nr_in_use, struct module *owner)
> +int __video_register_device(struct video_device *vdev,
> +			    enum vfl_devnode_type type,
> +			    int nr, int warn_if_nr_in_use,
> +			    struct module *owner)
>  {
>  	int i = 0;
>  	int ret;
> diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
> index de1a1453cfd9..f182b47dfd71 100644
> --- a/include/media/v4l2-dev.h
> +++ b/include/media/v4l2-dev.h
> @@ -20,13 +20,25 @@
>  
>  #define VIDEO_MAJOR	81
>  
> -#define VFL_TYPE_GRABBER	0
> -#define VFL_TYPE_VBI		1
> -#define VFL_TYPE_RADIO		2
> -#define VFL_TYPE_SUBDEV		3
> -#define VFL_TYPE_SDR		4
> -#define VFL_TYPE_TOUCH		5
> -#define VFL_TYPE_MAX		6
> +/**
> + * enum vfl_devnode_type - type of V4L2 device node
> + *
> + * @VFL_TYPE_GRABBER:	for video input/output devices
> + * @VFL_TYPE_VBI:	for vertical blank data (i.e. closed captions, teletext)
> + * @VFL_TYPE_RADIO:	for radio tuners
> + * @VFL_TYPE_SUBDEV:	for V4L2 subdevices
> + * @VFL_TYPE_SDR:	for Software Defined Radio tuners
> + * @VFL_TYPE_TOUCH:	for touch sensors
> + */
> +enum vfl_devnode_type {
> +	VFL_TYPE_GRABBER	= 0,
> +	VFL_TYPE_VBI		= 1,
> +	VFL_TYPE_RADIO		= 2,
> +	VFL_TYPE_SUBDEV		= 3,
> +	VFL_TYPE_SDR		= 4,
> +	VFL_TYPE_TOUCH		= 5,
> +};
> +#define VFL_TYPE_MAX VFL_TYPE_TOUCH
>  
>  /* Is this a receiver, transmitter or mem-to-mem? */
>  /* Ignored for VFL_TYPE_SUBDEV. */
> @@ -188,7 +200,7 @@ struct v4l2_file_operations {
>   * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
>   *	 If NULL, then v4l2_dev->prio will be used.
>   * @name: video device name
> - * @vfl_type: V4L device type
> + * @vfl_type: V4L device type, as defined by &enum vfl_devnode_type
>   * @vfl_dir: V4L receiver, transmitter or m2m
>   * @minor: device node 'minor'. It is set to -1 if the registration failed
>   * @num: number of the video device node
> @@ -236,7 +248,7 @@ struct video_device
>  
>  	/* device info */
>  	char name[32];
> -	int vfl_type;
> +	enum vfl_devnode_type vfl_type;
>  	int vfl_dir;
>  	int minor;
>  	u16 num;
> @@ -281,7 +293,7 @@ struct video_device
>   * __video_register_device - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   * @warn_if_nr_in_use: warn if the desired device node number
> @@ -300,29 +312,22 @@ struct video_device
>   *
>   * Returns 0 on success.
>   *
> - * Valid values for @type are:
> - *
> - *	- %VFL_TYPE_GRABBER - A frame grabber
> - *	- %VFL_TYPE_VBI - Vertical blank data (undecoded)
> - *	- %VFL_TYPE_RADIO - A radio card
> - *	- %VFL_TYPE_SUBDEV - A subdevice
> - *	- %VFL_TYPE_SDR - Software Defined Radio
> - *	- %VFL_TYPE_TOUCH - A touch sensor
> - *
>   * .. note::
>   *
>   *	This function is meant to be used only inside the V4L2 core.
>   *	Drivers should use video_register_device() or
>   *	video_register_device_no_warn().
>   */
> -int __must_check __video_register_device(struct video_device *vdev, int type,
> -		int nr, int warn_if_nr_in_use, struct module *owner);
> +int __must_check __video_register_device(struct video_device *vdev,
> +					 enum vfl_devnode_type type,
> +					 int nr, int warn_if_nr_in_use,
> +					 struct module *owner);
>  
>  /**
>   *  video_register_device - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   *
> @@ -336,7 +341,8 @@ int __must_check __video_register_device(struct video_device *vdev, int type,
>   *	you video_device_release() should be called on failure.
>   */
>  static inline int __must_check video_register_device(struct video_device *vdev,
> -		int type, int nr)
> +						     enum vfl_devnode_type type,
> +						     int nr)
>  {
>  	return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
>  }
> @@ -345,7 +351,7 @@ static inline int __must_check video_register_device(struct video_device *vdev,
>   *  video_register_device_no_warn - register video4linux devices
>   *
>   * @vdev: struct video_device to register
> - * @type: type of device to register
> + * @type: type of device to register, as defined by &enum vfl_devnode_type
>   * @nr:   which device node number is desired:
>   * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
>   *
> @@ -361,8 +367,9 @@ static inline int __must_check video_register_device(struct video_device *vdev,
>   *	is responsible for freeing any data. Usually that means that
>   *	you video_device_release() should be called on failure.
>   */
> -static inline int __must_check video_register_device_no_warn(
> -		struct video_device *vdev, int type, int nr)
> +static inline int __must_check
> +video_register_device_no_warn(struct video_device *vdev,
> +			      enum vfl_devnode_type type, int nr)
>  {
>  	return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
>  }
> diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
> index 47adb1608d98..3bfe6bcc8365 100644
> --- a/include/media/v4l2-mediabus.h
> +++ b/include/media/v4l2-mediabus.h
> @@ -143,6 +143,13 @@ struct v4l2_mbus_config {
>  	};
>  };
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + *	v4l2_pix_format fields from a &struct v4l2_mbus_framefmt.
> + *
> + * @pix_fmt:	pointer to &struct v4l2_pix_format to be filled
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
> + */
>  static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
>  				const struct v4l2_mbus_framefmt *mbus_fmt)
>  {
> @@ -155,6 +162,15 @@ static inline void v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
>  	pix_fmt->xfer_func = mbus_fmt->xfer_func;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format and a
> + *	data format code.
> + *
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
> + * @pix_fmt:	pointer to &struct v4l2_pix_format to be used as model
> + * @code:	data format code (from &enum v4l2_mbus_pixelcode)
> + */
>  static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
>  			   const struct v4l2_pix_format *pix_fmt,
>  			   u32 code)
> @@ -169,6 +185,13 @@ static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
>  	mbus_fmt->code = code;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + *	v4l2_pix_format_mplane fields from a media bus structure.
> + *
> + * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be filled
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be used as model
> + */
>  static inline void v4l2_fill_pix_format_mplane(
>  				struct v4l2_pix_format_mplane *pix_mp_fmt,
>  				const struct v4l2_mbus_framefmt *mbus_fmt)
> @@ -182,6 +205,13 @@ static inline void v4l2_fill_pix_format_mplane(
>  	pix_mp_fmt->xfer_func = mbus_fmt->xfer_func;
>  }
>  
> +/**
> + * v4l2_fill_pix_format - Ancillary routine that fills a &struct
> + * 	v4l2_mbus_framefmt from a &struct v4l2_pix_format_mplane.
> + *
> + * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
> + * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be used as model
> + */
>  static inline void v4l2_fill_mbus_format_mplane(
>  				struct v4l2_mbus_framefmt *mbus_fmt,
>  				const struct v4l2_pix_format_mplane *pix_mp_fmt)
> 

-- 

Mike Isely
isely @ isely (dot) net
PGP: 03 54 43 4D 75 E5 CC 92 71 16 01 E2 B5 F5 C1 E8

Re: [PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:21AM -0300, Mauro Carvalho Chehab wrote:
> The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
> 3 functions that have the same arguments. The code of those
> functions is simple enough to just declare them, de-obfuscating
> the code.
> 
> While here, replace BUG_ON() by WARN_ON() as there's no reason
> why to panic the Kernel if this fails.

BUG_ON() might actually be a better idea as this will lead to memory
corruption. I presume it's not been hit often.

That said, I, too, favour WARN_ON() in this case. In case pad exceeds the
number of pads, then zero could be used, for instance. The only real
problem comes if there were no pads to begin with. The callers of these
functions also don't expect to receive NULL. Another option would be to
define a static, dummy variable for the purpose that would be at least safe
to access. Or we could just use the dummy entry whenever the pad isn't
valid.

This will make the functions more complex and I might just keep the
original macro. Even grep works on it nowadays.

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/v4l2-subdev.h | 37 +++++++++++++++++++++++++------------
>  1 file changed, 25 insertions(+), 12 deletions(-)
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index 1f34045f07ce..35c4476c56ee 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -897,19 +897,32 @@ struct v4l2_subdev_fh {
>  	container_of(fh, struct v4l2_subdev_fh, vfh)
>  
>  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> -#define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)		\
> -	static inline struct rtype *					\
> -	fun_name(struct v4l2_subdev *sd,				\
> -		 struct v4l2_subdev_pad_config *cfg,			\
> -		 unsigned int pad)					\
> -	{								\
> -		BUG_ON(pad >= sd->entity.num_pads);			\
> -		return &cfg[pad].field_name;				\
> -	}
> +static inline struct v4l2_mbus_framefmt
> +*v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
> +			    struct v4l2_subdev_pad_config *cfg,
> +			    unsigned int pad)
> +{
> +	WARN_ON(pad >= sd->entity.num_pads);
> +	return &cfg[pad].try_fmt;
> +}
>  
> -__V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, v4l2_subdev_get_try_format, try_fmt)
> -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_crop, try_crop)
> -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
> +static inline struct v4l2_rect
> +*v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
> +			  struct v4l2_subdev_pad_config *cfg,
> +			  unsigned int pad)
> +{
> +	WARN_ON(pad >= sd->entity.num_pads);
> +	return &cfg[pad].try_crop;
> +}
> +
> +static inline struct v4l2_rect
> +*v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
> +			     struct v4l2_subdev_pad_config *cfg,
> +			     unsigned int pad)
> +{
> +	WARN_ON(pad >= sd->entity.num_pads);
> +	return &cfg[pad].try_compose;
> +}
>  #endif
>  
>  extern const struct v4l2_file_operations v4l2_subdev_fops;

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 10/24] media: v4l2-subdev: use kernel-doc markups to document subdev flags

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:16AM -0300, Mauro Carvalho Chehab wrote:
> Right now, those are documented together with the subdev struct,
> instead of together with the definitions.
> 
> Convert the definitions to an enum, use BIT() macros and document
> it at its right place.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

For patches 10--14:

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 17/24] media: v4l2-subdev: fix a typo

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:23AM -0300, Mauro Carvalho Chehab wrote:
> ownner -> owner
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/v4l2-subdev.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index e215732eed45..345da052618c 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -814,7 +814,7 @@ struct v4l2_subdev_platform_data {
>   * @list: List of sub-devices
>   * @owner: The owner is the same as the driver's &struct device owner.
>   * @owner_v4l2_dev: true if the &sd->owner matches the owner of @v4l2_dev->dev
> - *	ownner. Initialized by v4l2_device_register_subdev().
> + *	owner. Initialized by v4l2_device_register_subdev().
>   * @flags: subdev flags, as defined by &enum v4l2_subdev_flags.
>   *
>   * @v4l2_dev: pointer to struct &v4l2_device

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 16/24] media: v4l2-subdev: document remaining undocumented functions

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:22AM -0300, Mauro Carvalho Chehab wrote:
> There are several undocumented v4l2-subdev functions that are
> part of kAPI. Document them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/v4l2-subdev.h | 70 +++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 65 insertions(+), 5 deletions(-)
> 
> diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> index 35c4476c56ee..e215732eed45 100644
> --- a/include/media/v4l2-subdev.h
> +++ b/include/media/v4l2-subdev.h
> @@ -868,6 +868,13 @@ struct v4l2_subdev {
>  	struct v4l2_subdev_platform_data *pdata;
>  };
>  
> +
> +/**
> + * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from
> + *     the &struct media_entity embedded on it.

I'd add that "calling this macro with NULL argument safely returns NULL".

> + *
> + * @ent: pointer to &struct media_entity.
> + */
>  #define media_entity_to_v4l2_subdev(ent)				\
>  ({									\
>  	typeof(ent) __me_sd_ent = (ent);				\
> @@ -877,14 +884,20 @@ struct v4l2_subdev {
>  		NULL;							\
>  })
>  
> +/**
> + * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from
> + *     the &struct video_device embedded on it.
> + *
> + * @vdev: pointer to &struct video_device
> + */
>  #define vdev_to_v4l2_subdev(vdev) \
>  	((struct v4l2_subdev *)video_get_drvdata(vdev))
>  
>  /**
>   * struct v4l2_subdev_fh - Used for storing subdev information per file handle
>   *
> - * @vfh: pointer to struct v4l2_fh
> - * @pad: pointer to v4l2_subdev_pad_config
> + * @vfh: pointer to &struct v4l2_fh
> + * @pad: pointer to &struct v4l2_subdev_pad_config
>   */
>  struct v4l2_subdev_fh {
>  	struct v4l2_fh vfh;
> @@ -893,10 +906,25 @@ struct v4l2_subdev_fh {
>  #endif
>  };
>  
> +/**
> + * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from
> + *     the &struct v4l2_fh embedded on it.

s/on/in/

> + *
> + * @fh: pointer to &struct v4l2_fh
> + */
>  #define to_v4l2_subdev_fh(fh)	\
>  	container_of(fh, struct v4l2_subdev_fh, vfh)
>  
>  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> +
> +/**
> + * v4l2_subdev_get_try_format - ancillary routine to call
> + * 	&struct v4l2_subdev_pad_config->try_fmt
> + *
> + * @sd: pointer to &struct v4l2_subdev
> + * @cfg: pointer to &struct v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.

s/a /in /

The same for the other instances.

> + */
>  static inline struct v4l2_mbus_framefmt
>  *v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
>  			    struct v4l2_subdev_pad_config *cfg,
> @@ -906,6 +934,14 @@ static inline struct v4l2_mbus_framefmt
>  	return &cfg[pad].try_fmt;
>  }
>  
> +/**
> + * v4l2_subdev_get_try_crop - ancillary routine to call
> + * 	&struct v4l2_subdev_pad_config->try_crop
> + *
> + * @sd: pointer to &struct v4l2_subdev
> + * @cfg: pointer to &struct v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.
> + */
>  static inline struct v4l2_rect
>  *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
>  			  struct v4l2_subdev_pad_config *cfg,
> @@ -915,6 +951,14 @@ static inline struct v4l2_rect
>  	return &cfg[pad].try_crop;
>  }
>  
> +/**
> + * v4l2_subdev_get_try_crop - ancillary routine to call
> + * 	&struct v4l2_subdev_pad_config->try_compose
> + *
> + * @sd: pointer to &struct v4l2_subdev
> + * @cfg: pointer to &struct v4l2_subdev_pad_config array.
> + * @pad: index of the pad a the @cfg array.
> + */
>  static inline struct v4l2_rect
>  *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
>  			     struct v4l2_subdev_pad_config *cfg,
> @@ -1030,9 +1074,17 @@ void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
>  void v4l2_subdev_init(struct v4l2_subdev *sd,
>  		      const struct v4l2_subdev_ops *ops);
>  
> -/*
> - * Call an ops of a v4l2_subdev, doing the right checks against
> - * NULL pointers.
> +/**
> + * v4l2_subdev_call - call an ops of a v4l2_subdev, doing the right checks

s/ops/operation/ ?

> + *	against NULL pointers.

We already say in struct v4l2_subdev_ops documentation that the individual
ops may be NULL. I think that should be enough.

> + *
> + * @sd: pointer to the &struct v4l2_subdev
> + * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
> + *     Each element there groups a set of callbacks functions.
> + * @f: callback function that will be called if @cond matches.
> + *     The callback functions are defined in groups, according to
> + *     each element at &struct v4l2_subdev_ops.
> + * @args...: arguments for @f.
>   *
>   * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
>   */
> @@ -1048,6 +1100,14 @@ void v4l2_subdev_init(struct v4l2_subdev *sd,
>  		__result;						\
>  	})
>  
> +/**
> + * v4l2_subdev_has_op - Checks if a subdev defines a certain ops.

s/ops/operation/ (or "op").

> + *
> + * @sd: pointer to the &struct v4l2_subdev
> + * @o: name of the element at &struct v4l2_subdev_ops that contains @f.
> + *     Each element there groups a set of callbacks functions.

How about:

@o: The group of callback functions in &struct v4l2_subdev_ops which @f is
a part of.

> + * @f: callback function to be checked for its existence.
> + */
>  #define v4l2_subdev_has_op(sd, o, f) \
>  	((sd)->ops->o && (sd)->ops->o->f)
>  

With these considered,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 19/24] media: vb2-core: Improve kernel-doc markups

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:25AM -0300, Mauro Carvalho Chehab wrote:
> There are several issues on the current markups:
> - lack of cross-references;
> - wrong cross-references;
> - lack of a period of the end of several phrases;
> - Some descriptions can be enhanced.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/videobuf2-core.h | 376 ++++++++++++++++++++++-------------------
>  1 file changed, 204 insertions(+), 172 deletions(-)
> 
> diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
> index 0308d8439049..e145f1475ffe 100644
> --- a/include/media/videobuf2-core.h
> +++ b/include/media/videobuf2-core.h

...

>  /**
>   * vb2_core_queue_init() - initialize a videobuf2 queue
> - * @q:		videobuf2 queue; this structure should be allocated in driver
> + * @q:		pointer to &struct vb2_queue with videobuf2 queue.
> + *		This structure should be allocated in driver
>   *
>   * The &vb2_queue structure should be allocated by the driver. The driver is
>   * responsible of clearing it's content and setting initial values for some
>   * required entries before calling this function.
> - * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
> - * to the struct vb2_queue description in include/media/videobuf2-core.h
> - * for more information.
> + *
> + * .. note::
> + *
> + *    The following fields at @q should be set before calling this function:

should -> shall

I bet there's a lot of that in the documentation elsewhere, including this
patch.

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 21/24] media: vb2-core: fix descriptions for VB2-only functions

[Sakari Ailus]

Hi Mauro,

On Mon, Oct 09, 2017 at 07:19:27AM -0300, Mauro Carvalho Chehab wrote:
> When we split VB2 into an independent streaming module and
> a V4L2 one, some vb2-core functions started to have a wrong
> description: they're meant to be used only by the API-specific
> parts of VB2, like vb2-v4l2, as the functions that V4L2 drivers
> should use are all under videobuf2-v4l2.h.
> 
> Correct their descriptions.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  include/media/videobuf2-core.h | 86 ++++++++++++++++++++++--------------------
>  1 file changed, 46 insertions(+), 40 deletions(-)
> 
> diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
> index ce795cd0a7cc..3165f0f9a85f 100644
> --- a/include/media/videobuf2-core.h
> +++ b/include/media/videobuf2-core.h
> @@ -651,12 +651,14 @@ int vb2_wait_for_all_buffers(struct vb2_queue *q);
>   * @index:	id number of the buffer.
>   * @pb:		buffer struct passed from userspace.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_querybuf ioctl handler
> - * in driver.
> + * Videbuf2 core helper to implement QUERYBUF operation. It is called

"Videobuf2" and "VIDIOC_" prefix for IOCTL commands. With this and the ones
below fixed,

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * The passed buffer should have been verified.
>   *
>   * This function fills the relevant information for the userspace.
> + *
> + * Return: returns zero on success; an error code otherwise.
>   */
>  void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
>  
> @@ -666,27 +668,26 @@ void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
>   * @memory:	memory type, as defined by &enum vb2_memory.
>   * @count:	requested buffer count.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_reqbufs ioctl
> - * handler of a driver.
> + * Videbuf2 core helper to implement REQBUF operation. It is called

Ditto.

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> - * #) verifies streaming parameters passed from the userspace,
> - * #) sets up the queue,
> + * #) verifies streaming parameters passed from the userspace;
> + * #) sets up the queue;
>   * #) negotiates number of buffers and planes per buffer with the driver
> - *    to be used during streaming,
> + *    to be used during streaming;
>   * #) allocates internal buffer structures (&struct vb2_buffer), according to
> - *    the agreed parameters,
> + *    the agreed parameters;
>   * #) for MMAP memory type, allocates actual video memory, using the
> - *    memory handling/allocation routines provided during queue initialization
> + *    memory handling/allocation routines provided during queue initialization.
>   *
>   * If req->count is 0, all the memory will be freed instead.
>   *
>   * If the queue has been allocated previously by a previous vb2_core_reqbufs()
>   * call and the queue is not busy, memory will be reallocated.
>   *
> - * The return values from this function are intended to be directly returned
> - * from &v4l2_ioctl_ops->vidioc_reqbufs handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
>  		unsigned int *count);
> @@ -699,17 +700,16 @@ int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
>   * @requested_planes: number of planes requested.
>   * @requested_sizes: array with the size of the planes.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_create_bufs ioctl handler
> - * of a driver.
> + * Videbuf2 core helper to implement CREATE_BUFS operation. It is called

Ditto.

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> - * #) verifies parameter sanity
> - * #) calls the &vb2_ops->queue_setup queue operation
> - * #) performs any necessary memory allocations
> + * #) verifies parameter sanity;
> + * #) calls the &vb2_ops->queue_setup queue operation;
> + * #) performs any necessary memory allocations.
>   *
> - * Return: the return values from this function are intended to be directly
> - * returned from &v4l2_ioctl_ops->vidioc_create_bufs handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
>  			 unsigned int *count, unsigned int requested_planes,
> @@ -723,16 +723,16 @@ int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
>   * @pb:		buffer structure passed from userspace to
>   *		&v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_prepare_buf ioctl handler
> - * of a driver.
> + * Videbuf2 core helper to implement PREPARE_BUF operation. It is called

Here, too. And elsewhere below.

> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * The passed buffer should have been verified.
>   *
> - * This function calls buf_prepare callback in the driver (if provided),
> - * in which driver-specific buffer initialization can be performed,
> + * This function calls vb2_ops->buf_prepare callback in the driver
> + * (if provided), in which driver-specific buffer initialization can
> + * be performed.
>   *
> - * The return values from this function are intended to be directly returned
> - * from v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
>  
> @@ -744,18 +744,18 @@ int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
>   * @pb:		buffer structure passed from userspace to
>   *		v4l2_ioctl_ops->vidioc_qbuf handler in driver
>   *
> - * Should be called from v4l2_ioctl_ops->vidioc_qbuf ioctl handler of a driver.
> - * The passed buffer should have been verified.
> + * Videbuf2 core helper to implement QBUF operation. It is called
> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> - * #) if necessary, calls buf_prepare callback in the driver (if provided), in
> - *    which driver-specific buffer initialization can be performed,
> + * #) if necessary, calls &vb2_ops->buf_prepare callback in the driver
> + *    (if provided), in which driver-specific buffer initialization can
> + *    be performed;
>   * #) if streaming is on, queues the buffer in driver by the means of
>   *    &vb2_ops->buf_queue callback for processing.
>   *
> - * The return values from this function are intended to be directly returned
> - * from v4l2_ioctl_ops->vidioc_qbuf handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
>  
> @@ -769,8 +769,8 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
>   *		 buffers ready for dequeuing are present. Normally the driver
>   *		 would be passing (file->f_flags & O_NONBLOCK) here.
>   *
> - * Should be called from v4l2_ioctl_ops->vidioc_dqbuf ioctl handler of a driver.
> - * The passed buffer should have been verified.
> + * Videbuf2 core helper to implement DQBUF operation. It is called
> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
>   *
>   * This function:
>   *
> @@ -780,8 +780,7 @@ int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
>   * #) the buffer struct members are filled with relevant information for
>   *    the userspace.
>   *
> - * The return values from this function are intended to be directly returned
> - * from v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
>  		   bool nonblocking);
> @@ -793,8 +792,10 @@ int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
>   * @type:	type of the queue to be started.
>   *		For V4L2, this is defined by &enum v4l2_buf_type type.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
> - * a driver.
> + * Videbuf2 core helper to implement STREAMON operation. It is called
> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
> + *
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
>  
> @@ -805,8 +806,10 @@ int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
>   * @type:	type of the queue to be started.
>   *		For V4L2, this is defined by &enum v4l2_buf_type type.
>   *
> - * Should be called from &v4l2_ioctl_ops->vidioc_streamon ioctl handler of
> - * a driver.
> + * Videbuf2 core helper to implement STREAMOFF operation. It is called
> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
> + *
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
>  
> @@ -823,8 +826,11 @@ int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
>   *		Currently, the only used flag is %O_CLOEXEC.
>   *		is supported, refer to manual of open syscall for more details.
>   *
> - * The return values from this function are intended to be directly returned
> - * from v4l2_ioctl_ops->vidioc_expbuf handler in driver.
> + *
> + * Videbuf2 core helper to implement EXPBUF operation. It is called
> + * internally by VB2 by an API-specific handler, like ``videobuf2-v4l2.h``.
> + *
> + * Return: returns zero on success; an error code otherwise.
>   */
>  int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
>  		unsigned int index, unsigned int plane, unsigned int flags);

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 22/24] media: vb2: add cross references at memops and v4l2 kernel-doc markups

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:28AM -0300, Mauro Carvalho Chehab wrote:
> Add cross-references where needed and add periods at the end of
> each kernel-doc paragraph, in order to make it coherent with other
> VB2 descriptions.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 18/24] media: vb2-core: use bitops for bits

[Sakari Ailus]

On Mon, Oct 09, 2017 at 07:19:24AM -0300, Mauro Carvalho Chehab wrote:
> Use the existing macros to identify vb2_io_modes bits.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 05/24] media: v4l2-dev: convert VFL_TYPE_* into an enum

[Andrey Utkin]

On Mon, Oct 09, 2017 at 07:19:11AM -0300, Mauro Carvalho Chehab wrote:
> Using enums makes easier to document, as it can use kernel-doc
> markups. It also allows cross-referencing, with increases the
> kAPI readability.
> 


All changes look legit.

But I'd expect cx88_querycap() return type change and such to be in
separate commit.

> diff --git a/drivers/media/pci/cx88/cx88-blackbird.c b/drivers/media/pci/cx88/cx88-blackbird.c
> index e3101f04941c..0e0952e60795 100644
> --- a/drivers/media/pci/cx88/cx88-blackbird.c
> +++ b/drivers/media/pci/cx88/cx88-blackbird.c
> @@ -805,8 +805,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
>  
>  	strcpy(cap->driver, "cx88_blackbird");
>  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> -	cx88_querycap(file, core, cap);
> -	return 0;
> +	return cx88_querycap(file, core, cap);
>  }
>  
>  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> diff --git a/drivers/media/pci/cx88/cx88-video.c b/drivers/media/pci/cx88/cx88-video.c
> index 7d25ecd4404b..9be682cdb644 100644
> --- a/drivers/media/pci/cx88/cx88-video.c
> +++ b/drivers/media/pci/cx88/cx88-video.c
> @@ -806,8 +806,8 @@ static int vidioc_s_fmt_vid_cap(struct file *file, void *priv,
>  	return 0;
>  }
>  
> -void cx88_querycap(struct file *file, struct cx88_core *core,
> -		   struct v4l2_capability *cap)
> +int cx88_querycap(struct file *file, struct cx88_core *core,
> +		  struct v4l2_capability *cap)
>  {
>  	struct video_device *vdev = video_devdata(file);
>  

Re: [PATCH 04/24] media: v4l2-mediabus: convert flags to enums and document them

[Pavel Machek]

[-- Attachment #1: Type: text/plain, Size: 1527 bytes --]

On Mon 2017-10-09 07:19:10, Mauro Carvalho Chehab wrote:
> There is a mess with media bus flags: there are two sets of
> flags, one used by parallel and ITU-R BT.656 outputs,
> and another one for CSI2.
> 
> Depending on the type, the same bit has different meanings.
> 

> @@ -86,11 +125,22 @@ enum v4l2_mbus_type {
>  /**
>   * struct v4l2_mbus_config - media bus configuration
>   * @type:	in: interface type
> - * @flags:	in / out: configuration flags, depending on @type
> + * @pb_flags:	in / out: configuration flags, if @type is
> + *		%V4L2_MBUS_PARALLEL or %V4L2_MBUS_BT656.
> + * @csi2_flags:	in / out: configuration flags, if @type is
> + *		%V4L2_MBUS_CSI2.
> + * @flag:	access flags, no matter the @type.
> + *		Used just to avoid needing to rewrite the logic inside
> + *		soc_camera and pxa_camera drivers. Don't use on newer
> + * 		drivers!
>   */
>  struct v4l2_mbus_config {
>  	enum v4l2_mbus_type type;
> -	unsigned int flags;
> +	union {
> +		enum v4l2_mbus_parallel_and_bt656_flags	pb_flags;
> +		enum v4l2_mbus_csi2_flags		csi2_flags;
> +		unsigned int				flag;
> +	};
>  };
>  
>  static inline void v4l2_fill_pix_format(struct v4l2_pix_format
>  *pix_fmt,

The flags->flag conversion is quite subtle, and "flag" is confusing
because there is more than one inside. What about something like
__legacy_flags?

									Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]

Re: [PATCH 05/24] media: v4l2-dev: convert VFL_TYPE_* into an enum

[Mauro Carvalho Chehab]

Em Tue, 10 Oct 2017 21:47:04 +0100
Andrey Utkin <andrey_utkin@fastmail.com> escreveu:

> On Mon, Oct 09, 2017 at 07:19:11AM -0300, Mauro Carvalho Chehab wrote:
> > Using enums makes easier to document, as it can use kernel-doc
> > markups. It also allows cross-referencing, with increases the
> > kAPI readability.
> >   
> 
> 
> All changes look legit.
> 
> But I'd expect cx88_querycap() return type change and such to be in
> separate commit.

It should be together, as the switch() now would generate a warning,
because some enum values aren't listed. On such case, it has to
return an error.

I added an explanation at the commit message.

> 
> > diff --git a/drivers/media/pci/cx88/cx88-blackbird.c b/drivers/media/pci/cx88/cx88-blackbird.c
> > index e3101f04941c..0e0952e60795 100644
> > --- a/drivers/media/pci/cx88/cx88-blackbird.c
> > +++ b/drivers/media/pci/cx88/cx88-blackbird.c
> > @@ -805,8 +805,7 @@ static int vidioc_querycap(struct file *file, void  *priv,
> >  
> >  	strcpy(cap->driver, "cx88_blackbird");
> >  	sprintf(cap->bus_info, "PCI:%s", pci_name(dev->pci));
> > -	cx88_querycap(file, core, cap);
> > -	return 0;
> > +	return cx88_querycap(file, core, cap);
> >  }
> >  
> >  static int vidioc_enum_fmt_vid_cap(struct file *file, void  *priv,
> > diff --git a/drivers/media/pci/cx88/cx88-video.c b/drivers/media/pci/cx88/cx88-video.c
> > index 7d25ecd4404b..9be682cdb644 100644
> > --- a/drivers/media/pci/cx88/cx88-video.c
> > +++ b/drivers/media/pci/cx88/cx88-video.c
> > @@ -806,8 +806,8 @@ static int vidioc_s_fmt_vid_cap(struct file *file, void *priv,
> >  	return 0;
> >  }
> >  
> > -void cx88_querycap(struct file *file, struct cx88_core *core,
> > -		   struct v4l2_capability *cap)
> > +int cx88_querycap(struct file *file, struct cx88_core *core,
> > +		  struct v4l2_capability *cap)
> >  {
> >  	struct video_device *vdev = video_devdata(file);
> >    



Thanks,
Mauro

Re: [PATCH 19/24] media: vb2-core: Improve kernel-doc markups

[Mauro Carvalho Chehab]

Em Tue, 10 Oct 2017 16:32:34 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Mon, Oct 09, 2017 at 07:19:25AM -0300, Mauro Carvalho Chehab wrote:
> > There are several issues on the current markups:
> > - lack of cross-references;
> > - wrong cross-references;
> > - lack of a period of the end of several phrases;
> > - Some descriptions can be enhanced.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  include/media/videobuf2-core.h | 376 ++++++++++++++++++++++-------------------
> >  1 file changed, 204 insertions(+), 172 deletions(-)
> > 
> > diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
> > index 0308d8439049..e145f1475ffe 100644
> > --- a/include/media/videobuf2-core.h
> > +++ b/include/media/videobuf2-core.h  
> 
> ...
> 
> >  /**
> >   * vb2_core_queue_init() - initialize a videobuf2 queue
> > - * @q:		videobuf2 queue; this structure should be allocated in driver
> > + * @q:		pointer to &struct vb2_queue with videobuf2 queue.
> > + *		This structure should be allocated in driver
> >   *
> >   * The &vb2_queue structure should be allocated by the driver. The driver is
> >   * responsible of clearing it's content and setting initial values for some
> >   * required entries before calling this function.
> > - * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
> > - * to the struct vb2_queue description in include/media/videobuf2-core.h
> > - * for more information.
> > + *
> > + * .. note::
> > + *
> > + *    The following fields at @q should be set before calling this function:  
> 
> should -> shall
> 
> I bet there's a lot of that in the documentation elsewhere, including this
> patch.

Yes, there are, and not only on this file (where it uses should
everywhere).

I prefer to do such change globally.

For now, I'll apply this patch as-is.

Thanks,
Mauro

Re: [PATCH 00/24] V4L2 kAPI cleanups and documentation improvements part 2

[Mauro Carvalho Chehab]

Em Mon,  9 Oct 2017 07:19:06 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> That's the second part of my V4L2 kAPI documentation improvements.
> It is meant to reduce the gap between the kAPI media headers
> and documentation, at least with regards to kernel-doc markups.
> 
> We should likely write more things at the ReST files under Documentation/
> to better describe some of those APIs (VB2 being likely the first candidate),
> but at least let's be sure that all V4L2 bits have kernel-doc markups.

I'm also applying the patches from this series that nobody commented,
or whose comments were fully addressed.

Thanks,
Mauro

Re: [PATCH 04/24] media: v4l2-mediabus: convert flags to enums and document them

[Mauro Carvalho Chehab]

Em Wed, 11 Oct 2017 23:26:44 +0200
Pavel Machek <pavel@ucw.cz> escreveu:

> On Mon 2017-10-09 07:19:10, Mauro Carvalho Chehab wrote:
> > There is a mess with media bus flags: there are two sets of
> > flags, one used by parallel and ITU-R BT.656 outputs,
> > and another one for CSI2.
> > 
> > Depending on the type, the same bit has different meanings.
> >   
> 
> > @@ -86,11 +125,22 @@ enum v4l2_mbus_type {
> >  /**
> >   * struct v4l2_mbus_config - media bus configuration
> >   * @type:	in: interface type
> > - * @flags:	in / out: configuration flags, depending on @type
> > + * @pb_flags:	in / out: configuration flags, if @type is
> > + *		%V4L2_MBUS_PARALLEL or %V4L2_MBUS_BT656.
> > + * @csi2_flags:	in / out: configuration flags, if @type is
> > + *		%V4L2_MBUS_CSI2.
> > + * @flag:	access flags, no matter the @type.
> > + *		Used just to avoid needing to rewrite the logic inside
> > + *		soc_camera and pxa_camera drivers. Don't use on newer
> > + * 		drivers!
> >   */
> >  struct v4l2_mbus_config {
> >  	enum v4l2_mbus_type type;
> > -	unsigned int flags;
> > +	union {
> > +		enum v4l2_mbus_parallel_and_bt656_flags	pb_flags;
> > +		enum v4l2_mbus_csi2_flags		csi2_flags;
> > +		unsigned int				flag;
> > +	};
> >  };
> >  
> >  static inline void v4l2_fill_pix_format(struct v4l2_pix_format
> >  *pix_fmt,  
> 
> The flags->flag conversion is quite subtle, and "flag" is confusing
> because there is more than one inside. What about something like
> __legacy_flags?

Good idea.

> 
> 									Pavel

Thanks,
Mauro

[PATCH] media: v4l2-mediabus: convert flags to enums and document them

There is a mess with media bus flags: there are two sets of
flags, one used by parallel and ITU-R BT.656 outputs,
and another one for CSI2.

Depending on the type, the same bit has different meanings.

That's very confusing, and counter-intuitive. So, split them
into two sets of flags, inside an enum.

This way, it becomes clearer that there are two separate sets
of flags. It also makes easier if CSI1, CSP, CSI3, etc. would
need a different set of flags.

As a side effect, enums can be documented via kernel-docs,
so there will be an improvement at flags documentation.

Unfortunately, soc_camera and pxa_camera do a mess with
the flags, using either one set of flags without proper
checks about the type. That could be fixed, but, as both drivers
are obsolete and in the process of cleanings, I opted to just
keep the behavior, using an unsigned int inside those two
drivers.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/drivers/media/i2c/adv7180.c b/drivers/media/i2c/adv7180.c
index 25d24a3f10a7..4bf25a72ef4f 100644
--- a/drivers/media/i2c/adv7180.c
+++ b/drivers/media/i2c/adv7180.c
@@ -743,16 +743,16 @@ static int adv7180_g_mbus_config(struct v4l2_subdev *sd,
 
 	if (state->chip_info->flags & ADV7180_FLAG_MIPI_CSI2) {
 		cfg->type = V4L2_MBUS_CSI2;
-		cfg->flags = V4L2_MBUS_CSI2_1_LANE |
-				V4L2_MBUS_CSI2_CHANNEL_0 |
-				V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+		cfg->csi2_flags = V4L2_MBUS_CSI2_1_LANE
+				  | V4L2_MBUS_CSI2_CHANNEL_0
+				  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 	} else {
 		/*
 		 * The ADV7180 sensor supports BT.601/656 output modes.
 		 * The BT.656 is default and not yet configurable by s/w.
 		 */
-		cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-				 V4L2_MBUS_DATA_ACTIVE_HIGH;
+		cfg->pb_flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING
+			        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 		cfg->type = V4L2_MBUS_BT656;
 	}
 
diff --git a/drivers/media/i2c/ml86v7667.c b/drivers/media/i2c/ml86v7667.c
index 57ef901edb06..a25114d0c31f 100644
--- a/drivers/media/i2c/ml86v7667.c
+++ b/drivers/media/i2c/ml86v7667.c
@@ -226,8 +226,9 @@ static int ml86v7667_fill_fmt(struct v4l2_subdev *sd,
 static int ml86v7667_g_mbus_config(struct v4l2_subdev *sd,
 				   struct v4l2_mbus_config *cfg)
 {
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		     V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_BT656;
 
 	return 0;
diff --git a/drivers/media/i2c/mt9m111.c b/drivers/media/i2c/mt9m111.c
index b1665d97e0fd..d9698b535080 100644
--- a/drivers/media/i2c/mt9m111.c
+++ b/drivers/media/i2c/mt9m111.c
@@ -857,9 +857,11 @@ static int mt9m111_enum_mbus_code(struct v4l2_subdev *sd,
 static int mt9m111_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+		        | V4L2_MBUS_PCLK_SAMPLE_RISING
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_VSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
 
 	return 0;
diff --git a/drivers/media/i2c/ov6650.c b/drivers/media/i2c/ov6650.c
index 8975d16b2b24..61223bbe077e 100644
--- a/drivers/media/i2c/ov6650.c
+++ b/drivers/media/i2c/ov6650.c
@@ -880,11 +880,14 @@ static int ov6650_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 
-	cfg->flags = V4L2_MBUS_MASTER |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
 
 	return 0;
@@ -897,21 +900,21 @@ static int ov6650_s_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	int ret;
 
-	if (cfg->flags & V4L2_MBUS_PCLK_SAMPLE_RISING)
+	if (cfg->pb_flags & V4L2_MBUS_PCLK_SAMPLE_RISING)
 		ret = ov6650_reg_rmw(client, REG_COMJ, COMJ_PCLK_RISING, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMJ, 0, COMJ_PCLK_RISING);
 	if (ret)
 		return ret;
 
-	if (cfg->flags & V4L2_MBUS_HSYNC_ACTIVE_LOW)
+	if (cfg->pb_flags & V4L2_MBUS_HSYNC_ACTIVE_LOW)
 		ret = ov6650_reg_rmw(client, REG_COMF, COMF_HREF_LOW, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMF, 0, COMF_HREF_LOW);
 	if (ret)
 		return ret;
 
-	if (cfg->flags & V4L2_MBUS_VSYNC_ACTIVE_HIGH)
+	if (cfg->pb_flags & V4L2_MBUS_VSYNC_ACTIVE_HIGH)
 		ret = ov6650_reg_rmw(client, REG_COMJ, COMJ_VSYNC_HIGH, 0);
 	else
 		ret = ov6650_reg_rmw(client, REG_COMJ, 0, COMJ_VSYNC_HIGH);
diff --git a/drivers/media/i2c/soc_camera/imx074.c b/drivers/media/i2c/soc_camera/imx074.c
index 77f1e0243d6e..f52d64e31975 100644
--- a/drivers/media/i2c/soc_camera/imx074.c
+++ b/drivers/media/i2c/soc_camera/imx074.c
@@ -264,9 +264,9 @@ static int imx074_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 	cfg->type = V4L2_MBUS_CSI2;
-	cfg->flags = V4L2_MBUS_CSI2_2_LANE |
-		V4L2_MBUS_CSI2_CHANNEL_0 |
-		V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_2_LANE
+			  | V4L2_MBUS_CSI2_CHANNEL_0
+			  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9m001.c b/drivers/media/i2c/soc_camera/mt9m001.c
index 1bfb0d53059e..91545e8160b7 100644
--- a/drivers/media/i2c/soc_camera/mt9m001.c
+++ b/drivers/media/i2c/soc_camera/mt9m001.c
@@ -603,11 +603,13 @@ static int mt9m001_g_mbus_config(struct v4l2_subdev *sd,
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
 	/* MT9M001 has all capture_format parameters fixed */
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH | V4L2_MBUS_MASTER;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_FALLING
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_MASTER;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9t031.c b/drivers/media/i2c/soc_camera/mt9t031.c
index 4802d30e47de..c3c531cd5caa 100644
--- a/drivers/media/i2c/soc_camera/mt9t031.c
+++ b/drivers/media/i2c/soc_camera/mt9t031.c
@@ -704,11 +704,14 @@ static int mt9t031_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING |
-		V4L2_MBUS_PCLK_SAMPLE_FALLING | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9t112.c b/drivers/media/i2c/soc_camera/mt9t112.c
index 297d22ebcb18..4fa761693872 100644
--- a/drivers/media/i2c/soc_camera/mt9t112.c
+++ b/drivers/media/i2c/soc_camera/mt9t112.c
@@ -1009,11 +1009,14 @@ static int mt9t112_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_VSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_DATA_ACTIVE_HIGH |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/mt9v022.c b/drivers/media/i2c/soc_camera/mt9v022.c
index 762f06919329..8297dfdad4e9 100644
--- a/drivers/media/i2c/soc_camera/mt9v022.c
+++ b/drivers/media/i2c/soc_camera/mt9v022.c
@@ -798,13 +798,17 @@ static int mt9v022_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_SLAVE |
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_SLAVE
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov5642.c b/drivers/media/i2c/soc_camera/ov5642.c
index 39f420db9c70..629370d8feaa 100644
--- a/drivers/media/i2c/soc_camera/ov5642.c
+++ b/drivers/media/i2c/soc_camera/ov5642.c
@@ -914,8 +914,9 @@ static int ov5642_g_mbus_config(struct v4l2_subdev *sd,
 				struct v4l2_mbus_config *cfg)
 {
 	cfg->type = V4L2_MBUS_CSI2;
-	cfg->flags = V4L2_MBUS_CSI2_2_LANE | V4L2_MBUS_CSI2_CHANNEL_0 |
-					V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_2_LANE
+			  | V4L2_MBUS_CSI2_CHANNEL_0
+			  | V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov772x.c b/drivers/media/i2c/soc_camera/ov772x.c
index 806383500313..7e1391460393 100644
--- a/drivers/media/i2c/soc_camera/ov772x.c
+++ b/drivers/media/i2c/soc_camera/ov772x.c
@@ -1003,11 +1003,13 @@ static int ov772x_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov9640.c b/drivers/media/i2c/soc_camera/ov9640.c
index c63948989688..30ed9c07d42c 100644
--- a/drivers/media/i2c/soc_camera/ov9640.c
+++ b/drivers/media/i2c/soc_camera/ov9640.c
@@ -634,11 +634,13 @@ static int ov9640_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+		        | V4L2_MBUS_MASTER
+		        | V4L2_MBUS_VSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_HSYNC_ACTIVE_HIGH
+		        | V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/ov9740.c b/drivers/media/i2c/soc_camera/ov9740.c
index 755de2289c39..f3103e7b2924 100644
--- a/drivers/media/i2c/soc_camera/ov9740.c
+++ b/drivers/media/i2c/soc_camera/ov9740.c
@@ -882,11 +882,13 @@ static int ov9740_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_HIGH |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/rj54n1cb0c.c b/drivers/media/i2c/soc_camera/rj54n1cb0c.c
index 02398d0bc649..f1d36f6a72b7 100644
--- a/drivers/media/i2c/soc_camera/rj54n1cb0c.c
+++ b/drivers/media/i2c/soc_camera/rj54n1cb0c.c
@@ -1227,12 +1227,14 @@ static int rj54n1_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags =
-		V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_PCLK_SAMPLE_FALLING |
-		V4L2_MBUS_MASTER | V4L2_MBUS_DATA_ACTIVE_HIGH |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_PCLK_SAMPLE_FALLING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_DATA_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/soc_camera/tw9910.c b/drivers/media/i2c/soc_camera/tw9910.c
index bdb5e0a431e9..aa64bea2ef9f 100644
--- a/drivers/media/i2c/soc_camera/tw9910.c
+++ b/drivers/media/i2c/soc_camera/tw9910.c
@@ -862,12 +862,15 @@ static int tw9910_g_mbus_config(struct v4l2_subdev *sd,
 	struct i2c_client *client = v4l2_get_subdevdata(sd);
 	struct soc_camera_subdev_desc *ssdd = soc_camera_i2c_to_desc(client);
 
-	cfg->flags = V4L2_MBUS_PCLK_SAMPLE_RISING | V4L2_MBUS_MASTER |
-		V4L2_MBUS_VSYNC_ACTIVE_HIGH | V4L2_MBUS_VSYNC_ACTIVE_LOW |
-		V4L2_MBUS_HSYNC_ACTIVE_HIGH | V4L2_MBUS_HSYNC_ACTIVE_LOW |
-		V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_MASTER
+			| V4L2_MBUS_VSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_VSYNC_ACTIVE_LOW
+			| V4L2_MBUS_HSYNC_ACTIVE_HIGH
+			| V4L2_MBUS_HSYNC_ACTIVE_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 	cfg->type = V4L2_MBUS_PARALLEL;
-	cfg->flags = soc_camera_apply_board_flags(ssdd, cfg);
+	cfg->pb_flags = soc_camera_apply_board_flags(ssdd, cfg);
 
 	return 0;
 }
diff --git a/drivers/media/i2c/tc358743.c b/drivers/media/i2c/tc358743.c
index 2b8181469b93..668fe1eab93d 100644
--- a/drivers/media/i2c/tc358743.c
+++ b/drivers/media/i2c/tc358743.c
@@ -1623,20 +1623,20 @@ static int tc358743_g_mbus_config(struct v4l2_subdev *sd,
 	cfg->type = V4L2_MBUS_CSI2;
 
 	/* Support for non-continuous CSI-2 clock is missing in the driver */
-	cfg->flags = V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
+	cfg->csi2_flags = V4L2_MBUS_CSI2_CONTINUOUS_CLOCK;
 
 	switch (state->csi_lanes_in_use) {
 	case 1:
-		cfg->flags |= V4L2_MBUS_CSI2_1_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_1_LANE;
 		break;
 	case 2:
-		cfg->flags |= V4L2_MBUS_CSI2_2_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_2_LANE;
 		break;
 	case 3:
-		cfg->flags |= V4L2_MBUS_CSI2_3_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_3_LANE;
 		break;
 	case 4:
-		cfg->flags |= V4L2_MBUS_CSI2_4_LANE;
+		cfg->csi2_flags |= V4L2_MBUS_CSI2_4_LANE;
 		break;
 	default:
 		return -EINVAL;
diff --git a/drivers/media/i2c/tvp5150.c b/drivers/media/i2c/tvp5150.c
index 3c1851984b90..b25ed35de13e 100644
--- a/drivers/media/i2c/tvp5150.c
+++ b/drivers/media/i2c/tvp5150.c
@@ -976,8 +976,10 @@ static int tvp5150_g_mbus_config(struct v4l2_subdev *sd,
 	struct tvp5150 *decoder = to_tvp5150(sd);
 
 	cfg->type = decoder->mbus_type;
-	cfg->flags = V4L2_MBUS_MASTER | V4L2_MBUS_PCLK_SAMPLE_RISING
-		   | V4L2_MBUS_FIELD_EVEN_LOW | V4L2_MBUS_DATA_ACTIVE_HIGH;
+	cfg->pb_flags = V4L2_MBUS_MASTER
+			| V4L2_MBUS_PCLK_SAMPLE_RISING
+			| V4L2_MBUS_FIELD_EVEN_LOW
+			| V4L2_MBUS_DATA_ACTIVE_HIGH;
 
 	return 0;
 }
diff --git a/drivers/media/platform/pxa_camera.c b/drivers/media/platform/pxa_camera.c
index f028084f0775..2b9d862b883f 100644
--- a/drivers/media/platform/pxa_camera.c
+++ b/drivers/media/platform/pxa_camera.c
@@ -616,7 +616,7 @@ static unsigned int pxa_mbus_config_compatible(const struct v4l2_mbus_config *cf
 	bool hsync = true, vsync = true, pclk, data, mode;
 	bool mipi_lanes, mipi_clock;
 
-	common_flags = cfg->flags & flags;
+	common_flags = cfg->__legacy_flags & flags;
 
 	switch (cfg->type) {
 	case V4L2_MBUS_PARALLEL:
@@ -1621,7 +1621,7 @@ static int pxa_camera_set_bus_param(struct pxa_camera_dev *pcdev)
 		if (!common_flags) {
 			dev_warn(pcdev_to_dev(pcdev),
 				 "Flags incompatible: camera 0x%x, host 0x%lx\n",
-				 cfg.flags, bus_flags);
+				 cfg.__legacy_flags, bus_flags);
 			return -EINVAL;
 		}
 	} else if (ret != -ENOIOCTLCMD) {
@@ -1657,7 +1657,7 @@ static int pxa_camera_set_bus_param(struct pxa_camera_dev *pcdev)
 			common_flags &= ~V4L2_MBUS_PCLK_SAMPLE_FALLING;
 	}
 
-	cfg.flags = common_flags;
+	cfg.__legacy_flags = common_flags;
 	ret = sensor_call(pcdev, video, s_mbus_config, &cfg);
 	if (ret < 0 && ret != -ENOIOCTLCMD) {
 		dev_dbg(pcdev_to_dev(pcdev),
@@ -1688,7 +1688,7 @@ static int pxa_camera_try_bus_param(struct pxa_camera_dev *pcdev,
 		if (!common_flags) {
 			dev_warn(pcdev_to_dev(pcdev),
 				 "Flags incompatible: camera 0x%x, host 0x%lx\n",
-				 cfg.flags, bus_flags);
+				 cfg.__legacy_flags, bus_flags);
 			return -EINVAL;
 		}
 	} else if (ret == -ENOIOCTLCMD) {
diff --git a/drivers/media/platform/rcar-vin/rcar-core.c b/drivers/media/platform/rcar-vin/rcar-core.c
index f1fc7978d6d1..3803ff31eb44 100644
--- a/drivers/media/platform/rcar-vin/rcar-core.c
+++ b/drivers/media/platform/rcar-vin/rcar-core.c
@@ -157,11 +157,11 @@ static int rvin_digital_parse_v4l2(struct device *dev,
 	switch (rvge->mbus_cfg.type) {
 	case V4L2_MBUS_PARALLEL:
 		vin_dbg(vin, "Found PARALLEL media bus\n");
-		rvge->mbus_cfg.flags = vep->bus.parallel.flags;
+		rvge->mbus_cfg.pb_flags = vep->bus.parallel.flags;
 		break;
 	case V4L2_MBUS_BT656:
 		vin_dbg(vin, "Found BT656 media bus\n");
-		rvge->mbus_cfg.flags = 0;
+		rvge->mbus_cfg.pb_flags = 0;
 		break;
 	default:
 		vin_err(vin, "Unknown media bus type\n");
diff --git a/drivers/media/platform/rcar-vin/rcar-dma.c b/drivers/media/platform/rcar-vin/rcar-dma.c
index 23fdff7a7370..ed28fef07cd5 100644
--- a/drivers/media/platform/rcar-vin/rcar-dma.c
+++ b/drivers/media/platform/rcar-vin/rcar-dma.c
@@ -212,11 +212,11 @@ static int rvin_setup(struct rvin_dev *vin)
 	dmr2 = VNDMR2_FTEV | VNDMR2_VLV(1);
 
 	/* Hsync Signal Polarity Select */
-	if (!(vin->digital->mbus_cfg.flags & V4L2_MBUS_HSYNC_ACTIVE_LOW))
+	if (!(vin->digital->mbus_cfg.pb_flags & V4L2_MBUS_HSYNC_ACTIVE_LOW))
 		dmr2 |= VNDMR2_HPS;
 
 	/* Vsync Signal Polarity Select */
-	if (!(vin->digital->mbus_cfg.flags & V4L2_MBUS_VSYNC_ACTIVE_LOW))
+	if (!(vin->digital->mbus_cfg.pb_flags & V4L2_MBUS_VSYNC_ACTIVE_LOW))
 		dmr2 |= VNDMR2_VPS;
 
 	/*
diff --git a/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c b/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
index 36762ec954e7..7f3c7c152347 100644
--- a/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
+++ b/drivers/media/platform/soc_camera/sh_mobile_ceu_camera.c
@@ -744,7 +744,7 @@ static int sh_mobile_ceu_set_bus_param(struct soc_camera_device *icd)
 			common_flags &= ~V4L2_MBUS_VSYNC_ACTIVE_LOW;
 	}
 
-	cfg.flags = common_flags;
+	cfg.__legacy_flags = common_flags;
 	ret = v4l2_subdev_call(sd, video, s_mbus_config, &cfg);
 	if (ret < 0 && ret != -ENOIOCTLCMD)
 		return ret;
diff --git a/drivers/media/platform/soc_camera/soc_camera.c b/drivers/media/platform/soc_camera/soc_camera.c
index d13e2c5fb06f..871554a71c2d 100644
--- a/drivers/media/platform/soc_camera/soc_camera.c
+++ b/drivers/media/platform/soc_camera/soc_camera.c
@@ -217,7 +217,8 @@ EXPORT_SYMBOL(soc_camera_xlate_by_fourcc);
 unsigned long soc_camera_apply_board_flags(struct soc_camera_subdev_desc *ssdd,
 					   const struct v4l2_mbus_config *cfg)
 {
-	unsigned long f, flags = cfg->flags;
+	unsigned long f;
+	enum v4l2_mbus_parallel_and_bt656_flags flags = cfg->pb_flags;
 
 	/* If only one of the two polarities is supported, switch to the opposite */
 	if (ssdd->flags & SOCAM_SENSOR_INVERT_HSYNC) {
diff --git a/drivers/media/platform/soc_camera/soc_camera_platform.c b/drivers/media/platform/soc_camera/soc_camera_platform.c
index cb4986b8f798..c9230aaef614 100644
--- a/drivers/media/platform/soc_camera/soc_camera_platform.c
+++ b/drivers/media/platform/soc_camera/soc_camera_platform.c
@@ -104,7 +104,7 @@ static int soc_camera_platform_g_mbus_config(struct v4l2_subdev *sd,
 {
 	struct soc_camera_platform_info *p = v4l2_get_subdevdata(sd);
 
-	cfg->flags = p->mbus_param;
+	cfg->__legacy_flags = p->mbus_param;
 	cfg->type = p->mbus_type;
 
 	return 0;
diff --git a/drivers/media/platform/soc_camera/soc_mediabus.c b/drivers/media/platform/soc_camera/soc_mediabus.c
index 0ad4b28266e4..f46cc51940e4 100644
--- a/drivers/media/platform/soc_camera/soc_mediabus.c
+++ b/drivers/media/platform/soc_camera/soc_mediabus.c
@@ -486,7 +486,7 @@ unsigned int soc_mbus_config_compatible(const struct v4l2_mbus_config *cfg,
 	bool hsync = true, vsync = true, pclk, data, mode;
 	bool mipi_lanes, mipi_clock;
 
-	common_flags = cfg->flags & flags;
+	common_flags = cfg->__legacy_flags & flags;
 
 	switch (cfg->type) {
 	case V4L2_MBUS_PARALLEL:
diff --git a/drivers/media/v4l2-core/v4l2-fwnode.c b/drivers/media/v4l2-core/v4l2-fwnode.c
index d630640642ee..f9c75a66457a 100644
--- a/drivers/media/v4l2-core/v4l2-fwnode.c
+++ b/drivers/media/v4l2-core/v4l2-fwnode.c
@@ -44,7 +44,8 @@ static int v4l2_fwnode_endpoint_parse_csi2_bus(struct fwnode_handle *fwnode,
 {
 	struct v4l2_fwnode_bus_mipi_csi2 *bus = &vep->bus.mipi_csi2;
 	bool have_clk_lane = false;
-	unsigned int flags = 0, lanes_used = 0;
+	unsigned int lanes_used = 0;
+	enum v4l2_mbus_csi2_flags flags = 0;
 	unsigned int i;
 	u32 v;
 	int rval;
@@ -112,7 +113,7 @@ static void v4l2_fwnode_endpoint_parse_parallel_bus(
 	struct fwnode_handle *fwnode, struct v4l2_fwnode_endpoint *vep)
 {
 	struct v4l2_fwnode_bus_parallel *bus = &vep->bus.parallel;
-	unsigned int flags = 0;
+	enum v4l2_mbus_parallel_and_bt656_flags flags = 0;
 	u32 v;
 
 	if (!fwnode_property_read_u32(fwnode, "hsync-active", &v))
diff --git a/include/media/v4l2-fwnode.h b/include/media/v4l2-fwnode.h
index c228ec1c77cf..6ccb971835f8 100644
--- a/include/media/v4l2-fwnode.h
+++ b/include/media/v4l2-fwnode.h
@@ -32,7 +32,7 @@ struct v4l2_async_subdev;
 
 /**
  * struct v4l2_fwnode_bus_mipi_csi2 - MIPI CSI-2 bus data structure
- * @flags: media bus (V4L2_MBUS_*) flags
+ * @flags: media bus CSI flags, as defined by &enum v4l2_mbus_csi2_flags
  * @data_lanes: an array of physical data lane indexes
  * @clock_lane: physical lane index of the clock lane
  * @num_data_lanes: number of data lanes
@@ -40,7 +40,7 @@ struct v4l2_async_subdev;
  *		   the physical lanes.
  */
 struct v4l2_fwnode_bus_mipi_csi2 {
-	unsigned int flags;
+	enum v4l2_mbus_csi2_flags flags;
 	unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES];
 	unsigned char clock_lane;
 	unsigned short num_data_lanes;
diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index 4d8626c468bc..560e03db0d9b 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -15,51 +15,90 @@
 #include <linux/bitops.h>
 
 
-/* Parallel flags */
-/*
- * Can the client run in master or in slave mode. By "Master mode" an operation
- * mode is meant, when the client (e.g., a camera sensor) is producing
- * horizontal and vertical synchronisation. In "Slave mode" the host is
- * providing these signals to the slave.
- */
-#define V4L2_MBUS_MASTER			BIT(0)
-#define V4L2_MBUS_SLAVE				BIT(1)
-/*
- * Signal polarity flags
- * Note: in BT.656 mode HSYNC, FIELD, and VSYNC are unused
- * V4L2_MBUS_[HV]SYNC* flags should be also used for specifying
- * configuration of hardware that uses [HV]REF signals
+/**
+ * enum v4l2_mbus_flags - Media bus parallel and polarity flags
+ *
+ * @V4L2_MBUS_MASTER:			the client runs on parallel master mode;
+ * @V4L2_MBUS_SLAVE:			the client runs on parallel slave mode.
+ * @V4L2_MBUS_HSYNC_ACTIVE_HIGH:	horizontal sync active on high level
+ * @V4L2_MBUS_HSYNC_ACTIVE_LOW:		horizontal sync active on low level
+ * @V4L2_MBUS_VSYNC_ACTIVE_HIGH:	vertical sync active on high level
+ * @V4L2_MBUS_VSYNC_ACTIVE_LOW:		vertical sync active on low level
+ * @V4L2_MBUS_PCLK_SAMPLE_RISING:	pixel clock sample on level rising
+ * @V4L2_MBUS_PCLK_SAMPLE_FALLING:	pixel clock sample on level falling
+ * @V4L2_MBUS_DATA_ACTIVE_HIGH:		data active on high level
+ * @V4L2_MBUS_DATA_ACTIVE_LOW:		data active on low level
+ * @V4L2_MBUS_FIELD_EVEN_HIGH:		FIELD = 0/1 - Field1 (odd)/Field2 (even)
+ * @V4L2_MBUS_FIELD_EVEN_LOW:		FIELD = 1/0 - Field1 (odd)/Field2 (even)
+ * @V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH:	Sync-on-green (SoG) signal active
+ *					on high level
+ * @V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW:	Sync-on-green (SoG) signal active
+ *					on low level
+ *
+ * Those flags are used when the bus is in %V4L2_MBUS_PARALLEL or
+ * %V4L2_MBUS_BT656 mode.
+ *
+ * .. note::
+ *
+ *    #) @V4L2_MBUS_MASTER and @V4L2_MBUS_SLAVE are only valid if the bus
+ *       is in %V4L2_MBUS_PARALLEL mode. They are used to specify if the
+ *       client runs in master or in slave mode.
+ *
+ *       In "Master mode" (@V4L2_MBUS_MASTER), the client (e.g., a camera
+ *       sensor) is producing horizontal and vertical synchronization.
+ *
+ *       In "Slave mode" (@V4L2_MBUS_SLAVE) the host is providing these signals
+ *       to the slave.
+ *    #) in %V4L2_MBUS_BT656 mode, ``V4L2_MBUS_HSYNC_*``, ``V4L2_MBUS_VSYNC_*``
+ *       and ``V4L2_MBUS_FIELD_*`` flags are unused.
+ *    #) ``V4L2_MBUS_[HV]SYNC*`` flags should be also used for specifying
+ *       configuration of hardware that uses [HV]REF signals
  */
-#define V4L2_MBUS_HSYNC_ACTIVE_HIGH		BIT(2)
-#define V4L2_MBUS_HSYNC_ACTIVE_LOW		BIT(3)
-#define V4L2_MBUS_VSYNC_ACTIVE_HIGH		BIT(4)
-#define V4L2_MBUS_VSYNC_ACTIVE_LOW		BIT(5)
-#define V4L2_MBUS_PCLK_SAMPLE_RISING		BIT(6)
-#define V4L2_MBUS_PCLK_SAMPLE_FALLING		BIT(7)
-#define V4L2_MBUS_DATA_ACTIVE_HIGH		BIT(8)
-#define V4L2_MBUS_DATA_ACTIVE_LOW		BIT(9)
-/* FIELD = 0/1 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_HIGH		BIT(10)
-/* FIELD = 1/0 - Field1 (odd)/Field2 (even) */
-#define V4L2_MBUS_FIELD_EVEN_LOW		BIT(11)
-/* Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively. */
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH		BIT(12)
-#define V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW		BIT(13)
+enum v4l2_mbus_parallel_and_bt656_flags {
+	V4L2_MBUS_MASTER		= BIT(0),
+	V4L2_MBUS_SLAVE			= BIT(1),
+	V4L2_MBUS_HSYNC_ACTIVE_HIGH	= BIT(2),
+	V4L2_MBUS_HSYNC_ACTIVE_LOW	= BIT(3),
+	V4L2_MBUS_VSYNC_ACTIVE_HIGH	= BIT(4),
+	V4L2_MBUS_VSYNC_ACTIVE_LOW	= BIT(5),
+	V4L2_MBUS_PCLK_SAMPLE_RISING	= BIT(6),
+	V4L2_MBUS_PCLK_SAMPLE_FALLING	= BIT(7),
+	V4L2_MBUS_DATA_ACTIVE_HIGH	= BIT(8),
+	V4L2_MBUS_DATA_ACTIVE_LOW	= BIT(9),
+	V4L2_MBUS_FIELD_EVEN_HIGH	= BIT(10),
+	V4L2_MBUS_FIELD_EVEN_LOW	= BIT(11),
+	V4L2_MBUS_VIDEO_SOG_ACTIVE_HIGH	= BIT(12),
+	V4L2_MBUS_VIDEO_SOG_ACTIVE_LOW	= BIT(13),
+};
 
-/* Serial flags */
-/* How many lanes the client can use */
-#define V4L2_MBUS_CSI2_1_LANE			BIT(0)
-#define V4L2_MBUS_CSI2_2_LANE			BIT(1)
-#define V4L2_MBUS_CSI2_3_LANE			BIT(2)
-#define V4L2_MBUS_CSI2_4_LANE			BIT(3)
-/* On which channels it can send video data */
-#define V4L2_MBUS_CSI2_CHANNEL_0		BIT(4)
-#define V4L2_MBUS_CSI2_CHANNEL_1		BIT(5)
-#define V4L2_MBUS_CSI2_CHANNEL_2		BIT(6)
-#define V4L2_MBUS_CSI2_CHANNEL_3		BIT(7)
-/* Does it support only continuous or also non-continuous clock mode */
-#define V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		BIT(8)
-#define V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	BIT(9)
+/**
+ * enum v4l2_mbus_csi2_flags - Media bus serial flags
+ *
+ * @V4L2_MBUS_CSI2_1_LANE:		One lane in use
+ * @V4L2_MBUS_CSI2_2_LANE:		Two lanes in use
+ * @V4L2_MBUS_CSI2_3_LANE:		Three lanes in use
+ * @V4L2_MBUS_CSI2_4_LANE:		Four lanes in use
+ * @V4L2_MBUS_CSI2_CHANNEL_0:		Channel 0 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_1:		Channel 1 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_2:		Channel 2 can send video data
+ * @V4L2_MBUS_CSI2_CHANNEL_3:		Channel 3 can send video data
+ * @V4L2_MBUS_CSI2_CONTINUOUS_CLOCK:	Supports continuous clock mode
+ * @V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK:	Supports non-continuous clock mode
+ *
+ * Used only when the bus type is MIPI CSI-2.
+ */
+enum v4l2_mbus_csi2_flags {
+	V4L2_MBUS_CSI2_1_LANE			= BIT(0),
+	V4L2_MBUS_CSI2_2_LANE			= BIT(1),
+	V4L2_MBUS_CSI2_3_LANE			= BIT(2),
+	V4L2_MBUS_CSI2_4_LANE			= BIT(3),
+	V4L2_MBUS_CSI2_CHANNEL_0		= BIT(4),
+	V4L2_MBUS_CSI2_CHANNEL_1		= BIT(5),
+	V4L2_MBUS_CSI2_CHANNEL_2		= BIT(6),
+	V4L2_MBUS_CSI2_CHANNEL_3		= BIT(7),
+	V4L2_MBUS_CSI2_CONTINUOUS_CLOCK		= BIT(8),
+	V4L2_MBUS_CSI2_NONCONTINUOUS_CLOCK	= BIT(9),
+};
 
 #define V4L2_MBUS_CSI2_LANES		(V4L2_MBUS_CSI2_1_LANE | V4L2_MBUS_CSI2_2_LANE | \
 					 V4L2_MBUS_CSI2_3_LANE | V4L2_MBUS_CSI2_4_LANE)
@@ -69,8 +108,8 @@
 /**
  * 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
+ * @V4L2_MBUS_BT656:	parallel interface with embedded synchronization using ITU-R BT.656
+ * 			signaling. Can also be used for ISO-R BT.1120 signaling.
  * @V4L2_MBUS_CSI1:	MIPI CSI-1 serial interface
  * @V4L2_MBUS_CCP2:	CCP2 (Compact Camera Port 2)
  * @V4L2_MBUS_CSI2:	MIPI CSI-2 serial interface
@@ -86,11 +125,23 @@ enum v4l2_mbus_type {
 /**
  * struct v4l2_mbus_config - media bus configuration
  * @type:	in: interface type
- * @flags:	in / out: configuration flags, depending on @type
+ * @pb_flags:	in / out: configuration flags, if @type is
+ *		%V4L2_MBUS_PARALLEL or %V4L2_MBUS_BT656.
+ * @csi2_flags:	in / out: configuration flags, if @type is
+ *		%V4L2_MBUS_CSI2.
+ * @__legacy_flags:
+ *		access flags, no matter the @type.
+ *		Used just to avoid needing to rewrite the logic inside
+ *		soc_camera and pxa_camera drivers. Don't use on newer
+ * 		drivers!
  */
 struct v4l2_mbus_config {
 	enum v4l2_mbus_type type;
-	unsigned int flags;
+	union {
+		enum v4l2_mbus_parallel_and_bt656_flags	pb_flags;
+		enum v4l2_mbus_csi2_flags		csi2_flags;
+		unsigned int				__legacy_flags;
+	};
 };
 
 /**

Re: [PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Mauro Carvalho Chehab]

Em Mon, 9 Oct 2017 23:23:56 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Mon, Oct 09, 2017 at 07:19:21AM -0300, Mauro Carvalho Chehab wrote:
> > The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
> > 3 functions that have the same arguments. The code of those
> > functions is simple enough to just declare them, de-obfuscating
> > the code.
> > 
> > While here, replace BUG_ON() by WARN_ON() as there's no reason
> > why to panic the Kernel if this fails.
> 
> BUG_ON() might actually be a better idea as this will lead to memory
> corruption. I presume it's not been hit often.

Well, let's then change the code to:

        if (WARN_ON(pad >= sd->entity.num_pads)) 
                return -EINVAL;

This way, it won't try to use an invalid value. As those are default
handlers for ioctls, userspace should be able to handle it.

> 
> That said, I, too, favour WARN_ON() in this case. In case pad exceeds the
> number of pads, then zero could be used, for instance. The only real
> problem comes if there were no pads to begin with. The callers of these
> functions also don't expect to receive NULL. Another option would be to
> define a static, dummy variable for the purpose that would be at least safe
> to access. Or we could just use the dummy entry whenever the pad isn't
> valid.
> 
> This will make the functions more complex and I might just keep the
> original macro. Even grep works on it nowadays.
> 
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  include/media/v4l2-subdev.h | 37 +++++++++++++++++++++++++------------
> >  1 file changed, 25 insertions(+), 12 deletions(-)
> > 
> > diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> > index 1f34045f07ce..35c4476c56ee 100644
> > --- a/include/media/v4l2-subdev.h
> > +++ b/include/media/v4l2-subdev.h
> > @@ -897,19 +897,32 @@ struct v4l2_subdev_fh {
> >  	container_of(fh, struct v4l2_subdev_fh, vfh)
> >  
> >  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> > -#define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)		\
> > -	static inline struct rtype *					\
> > -	fun_name(struct v4l2_subdev *sd,				\
> > -		 struct v4l2_subdev_pad_config *cfg,			\
> > -		 unsigned int pad)					\
> > -	{								\
> > -		BUG_ON(pad >= sd->entity.num_pads);			\
> > -		return &cfg[pad].field_name;				\
> > -	}
> > +static inline struct v4l2_mbus_framefmt
> > +*v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
> > +			    struct v4l2_subdev_pad_config *cfg,
> > +			    unsigned int pad)
> > +{
> > +	WARN_ON(pad >= sd->entity.num_pads);
> > +	return &cfg[pad].try_fmt;
> > +}
> >  
> > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, v4l2_subdev_get_try_format, try_fmt)
> > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_crop, try_crop)
> > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
> > +static inline struct v4l2_rect
> > +*v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
> > +			  struct v4l2_subdev_pad_config *cfg,
> > +			  unsigned int pad)
> > +{
> > +	WARN_ON(pad >= sd->entity.num_pads);
> > +	return &cfg[pad].try_crop;
> > +}
> > +
> > +static inline struct v4l2_rect
> > +*v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
> > +			     struct v4l2_subdev_pad_config *cfg,
> > +			     unsigned int pad)
> > +{
> > +	WARN_ON(pad >= sd->entity.num_pads);
> > +	return &cfg[pad].try_compose;
> > +}
> >  #endif
> >  
> >  extern const struct v4l2_file_operations v4l2_subdev_fops;
> 



Thanks,
Mauro

Re: [PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Sakari Ailus]

On Mon, Dec 18, 2017 at 05:27:04PM -0200, Mauro Carvalho Chehab wrote:
> Em Mon, 9 Oct 2017 23:23:56 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > Hi Mauro,
> > 
> > On Mon, Oct 09, 2017 at 07:19:21AM -0300, Mauro Carvalho Chehab wrote:
> > > The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
> > > 3 functions that have the same arguments. The code of those
> > > functions is simple enough to just declare them, de-obfuscating
> > > the code.
> > > 
> > > While here, replace BUG_ON() by WARN_ON() as there's no reason
> > > why to panic the Kernel if this fails.
> > 
> > BUG_ON() might actually be a better idea as this will lead to memory
> > corruption. I presume it's not been hit often.
> 
> Well, let's then change the code to:
> 
>         if (WARN_ON(pad >= sd->entity.num_pads)) 
>                 return -EINVAL;
> 
> This way, it won't try to use an invalid value. As those are default
> handlers for ioctls, userspace should be able to handle it.

Another approach would be to return the entry for a valid pad. Few if any
drivers perform error handling on the value returned for the simple reason
that they know how many pads their own entities have.

> 
> > 
> > That said, I, too, favour WARN_ON() in this case. In case pad exceeds the
> > number of pads, then zero could be used, for instance. The only real
> > problem comes if there were no pads to begin with. The callers of these
> > functions also don't expect to receive NULL. Another option would be to
> > define a static, dummy variable for the purpose that would be at least safe
> > to access. Or we could just use the dummy entry whenever the pad isn't
> > valid.
> > 
> > This will make the functions more complex and I might just keep the
> > original macro. Even grep works on it nowadays.
> > 
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > ---
> > >  include/media/v4l2-subdev.h | 37 +++++++++++++++++++++++++------------
> > >  1 file changed, 25 insertions(+), 12 deletions(-)
> > > 
> > > diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
> > > index 1f34045f07ce..35c4476c56ee 100644
> > > --- a/include/media/v4l2-subdev.h
> > > +++ b/include/media/v4l2-subdev.h
> > > @@ -897,19 +897,32 @@ struct v4l2_subdev_fh {
> > >  	container_of(fh, struct v4l2_subdev_fh, vfh)
> > >  
> > >  #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
> > > -#define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)		\
> > > -	static inline struct rtype *					\
> > > -	fun_name(struct v4l2_subdev *sd,				\
> > > -		 struct v4l2_subdev_pad_config *cfg,			\
> > > -		 unsigned int pad)					\
> > > -	{								\
> > > -		BUG_ON(pad >= sd->entity.num_pads);			\
> > > -		return &cfg[pad].field_name;				\
> > > -	}
> > > +static inline struct v4l2_mbus_framefmt
> > > +*v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
> > > +			    struct v4l2_subdev_pad_config *cfg,
> > > +			    unsigned int pad)
> > > +{
> > > +	WARN_ON(pad >= sd->entity.num_pads);
> > > +	return &cfg[pad].try_fmt;
> > > +}
> > >  
> > > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, v4l2_subdev_get_try_format, try_fmt)
> > > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_crop, try_crop)
> > > -__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
> > > +static inline struct v4l2_rect
> > > +*v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
> > > +			  struct v4l2_subdev_pad_config *cfg,
> > > +			  unsigned int pad)
> > > +{
> > > +	WARN_ON(pad >= sd->entity.num_pads);
> > > +	return &cfg[pad].try_crop;
> > > +}
> > > +
> > > +static inline struct v4l2_rect
> > > +*v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
> > > +			     struct v4l2_subdev_pad_config *cfg,
> > > +			     unsigned int pad)
> > > +{
> > > +	WARN_ON(pad >= sd->entity.num_pads);
> > > +	return &cfg[pad].try_compose;
> > > +}
> > >  #endif
> > >  
> > >  extern const struct v4l2_file_operations v4l2_subdev_fops;
> > 
> 
> 
> 
> Thanks,
> Mauro

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Mauro Carvalho Chehab]

Em Tue, 19 Dec 2017 10:24:51 +0200
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> On Mon, Dec 18, 2017 at 05:27:04PM -0200, Mauro Carvalho Chehab wrote:
> > Em Mon, 9 Oct 2017 23:23:56 +0300
> > Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > On Mon, Oct 09, 2017 at 07:19:21AM -0300, Mauro Carvalho Chehab wrote:  
> > > > The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
> > > > 3 functions that have the same arguments. The code of those
> > > > functions is simple enough to just declare them, de-obfuscating
> > > > the code.
> > > > 
> > > > While here, replace BUG_ON() by WARN_ON() as there's no reason
> > > > why to panic the Kernel if this fails.  
> > > 
> > > BUG_ON() might actually be a better idea as this will lead to memory
> > > corruption. I presume it's not been hit often.  
> > 
> > Well, let's then change the code to:
> > 
> >         if (WARN_ON(pad >= sd->entity.num_pads)) 
> >                 return -EINVAL;
> > 
> > This way, it won't try to use an invalid value. As those are default
> > handlers for ioctls, userspace should be able to handle it.  
> 
> Another approach would be to return the entry for a valid pad. Few if any
> drivers perform error handling on the value returned for the simple reason
> that they know how many pads their own entities have.

Well, they should check for errors on returned values :-)

Anyway, I guess that using pad=0 as a way to avoid Kernel crashes
is not a bad idea.

Patch enclosed. It replaces patch 6/8.

Thanks,
Mauro

[PATCH] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
3 functions that have the same arguments. The code of those
functions is simple enough to just declare them, de-obfuscating
the code.

While here, replace BUG_ON() by WARN_ON() as there's no reason
why to panic the Kernel if this fails.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 71b8ff4b2e0e..443e5e019006 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -896,19 +896,35 @@ struct v4l2_subdev_fh {
 	container_of(fh, struct v4l2_subdev_fh, vfh)
 
 #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API)
-#define __V4L2_SUBDEV_MK_GET_TRY(rtype, fun_name, field_name)		\
-	static inline struct rtype *					\
-	fun_name(struct v4l2_subdev *sd,				\
-		 struct v4l2_subdev_pad_config *cfg,			\
-		 unsigned int pad)					\
-	{								\
-		BUG_ON(pad >= sd->entity.num_pads);			\
-		return &cfg[pad].field_name;				\
-	}
+static inline struct v4l2_mbus_framefmt
+*v4l2_subdev_get_try_format(struct v4l2_subdev *sd,
+			    struct v4l2_subdev_pad_config *cfg,
+			    unsigned int pad)
+{
+	if (WARN_ON(pad >= sd->entity.num_pads))
+		pad = 0;
+	return &cfg[pad].try_fmt;
+}
+
+static inline struct v4l2_rect
+*v4l2_subdev_get_try_crop(struct v4l2_subdev *sd,
+			  struct v4l2_subdev_pad_config *cfg,
+			  unsigned int pad)
+{
+	if (WARN_ON(pad >= sd->entity.num_pads))
+		pad = 0;
+	return &cfg[pad].try_crop;
+}
 
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_mbus_framefmt, v4l2_subdev_get_try_format, try_fmt)
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_crop, try_crop)
-__V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
+static inline struct v4l2_rect
+*v4l2_subdev_get_try_compose(struct v4l2_subdev *sd,
+			     struct v4l2_subdev_pad_config *cfg,
+			     unsigned int pad)
+{
+	if (WARN_ON(pad >= sd->entity.num_pads))
+		pad = 0;
+	return &cfg[pad].try_compose;
+}
 #endif
 
 extern const struct v4l2_file_operations v4l2_subdev_fops;

Re: [PATCH 15/24] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro

[Sakari Ailus]

On Tue, Dec 19, 2017 at 09:03:55AM -0200, Mauro Carvalho Chehab wrote:
> [PATCH] media: v4l2-subdev: get rid of __V4L2_SUBDEV_MK_GET_TRY() macro
> 
> The __V4L2_SUBDEV_MK_GET_TRY() macro is used to define
> 3 functions that have the same arguments. The code of those
> functions is simple enough to just declare them, de-obfuscating
> the code.
> 
> While here, replace BUG_ON() by WARN_ON() as there's no reason
> why to panic the Kernel if this fails.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Thanks!

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi