1 files changed, 91 insertions, 51 deletions

diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 28a686eb7d09..53f32022fabe 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -21,31 +21,63 @@
 
 #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
-
-/* 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_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
+
+/**
+ * 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;
 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 */
 
@@ -152,7 +184,7 @@ struct v4l2_file_operations {
         struct module *owner;
         ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
         ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
-        unsigned int (*poll) (struct file *, struct poll_table_struct *);
+        __poll_t (*poll) (struct file *, struct poll_table_struct *);
         long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
 #ifdef CONFIG_COMPAT
         long (*compat_ioctl32) (struct file *, unsigned int, unsigned long);
@@ -166,7 +198,7 @@ struct v4l2_file_operations {
 
 /*
  * Newer version of video_device, handled by videodev2.c
- *      This version moves redundant code from video device code to
+ *      This version moves redundant code from video device code to
  *      the common handler
  */
 
@@ -189,11 +221,12 @@ 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
- * @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
@@ -237,8 +270,8 @@ struct video_device
 
         /* device info */
         char name[32];
-        int vfl_type;
-        int vfl_dir;
+        enum vfl_devnode_type vfl_type;
+        enum vfl_devnode_direction vfl_dir;
         int minor;
         u16 num;
         unsigned long flags;
@@ -261,18 +294,30 @@ 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)
+
+/**
+ * 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)
 
 /**
  * __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)
+ *      (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  * @warn_if_nr_in_use: warn if the desired device node number
  *        was already in use and another number was chosen instead.
  * @owner: module that owns the video device node
@@ -289,43 +334,37 @@ 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)
+ *      (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  *
  * Internally, it calls __video_register_device(). Please see its
  * documentation for more details.
  *
  * .. note::
- *      if video_register_device fails, the release() callback of
+ *      if video_register_device fails, the release() callback of
  *      &struct video_device structure is *not* called, so the caller
  *      is responsible for freeing any data. Usually that means that
  *      you video_device_release() should be called on failure.
  */
 static inline int __must_check video_register_device(struct video_device *vdev,
-                int type, int nr)
+                                                     enum vfl_devnode_type type,
+                                                     int nr)
 {
         return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
 }
@@ -334,9 +373,9 @@ 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)
+ *      (0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
  *
  * This function is identical to video_register_device() except that no
  * warning is issued if the desired device node number was already in use.
@@ -345,13 +384,14 @@ static inline int __must_check video_register_device(struct video_device *vdev,
  * documentation for more details.
  *
  * .. note::
- *      if video_register_device fails, the release() callback of
+ *      if video_register_device fails, the release() callback of
  *      &struct video_device structure is *not* called, so the caller
  *      is responsible for freeing any data. Usually that means that
  *      you video_device_release() should be called on failure.
  */
-static inline int __must_check video_register_device_no_warn(
-                struct video_device *vdev, int type, int nr)
+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);
 }
@@ -383,7 +423,7 @@ void video_device_release(struct video_device *vdev);
 
 /**
  * video_device_release_empty - helper function to implement the
- *      video_device->release\(\) callback.
+ *      video_device->release\(\) callback.
  *
  * @vdev: pointer to &struct video_device
  *