[PATCH 07/11] drm/drm_ioctl.c: kerneldoc
Hi
On Tue, Sep 8, 2015 at 1:56 PM, Daniel Vetter wrote:
> As usual pull it into the drm docbook template, too. And again as
> usual I've decided to only document stuff exported to drivers, so all
> the old leftover markup from the shared drm repo days lost the magic
> ** signature.
>
> Signed-off-by: Daniel Vetter
Reviewed-by: David Herrmann
Thanks
David
> ---
> Documentation/DocBook/drm.tmpl | 1 +
> drivers/gpu/drm/drm_ioctl.c| 76
> ++
> 2 files changed, 55 insertions(+), 22 deletions(-)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 7d10be2a2ba0..cfb43203a6a7 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -3752,6 +3752,7 @@ int num_ioctls;
>
>
>
> +!Edrivers/gpu/drm/drm_ioctl.c
>
>
>
> diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
> index f0b4f581f6ce..75df8ea87cd7 100644
> --- a/drivers/gpu/drm/drm_ioctl.c
> +++ b/drivers/gpu/drm/drm_ioctl.c
> @@ -40,7 +40,7 @@
> static int drm_version(struct drm_device *dev, void *data,
>struct drm_file *file_priv);
>
> -/**
> +/*
> * Get the bus id.
> *
> * \param inode device inode.
> @@ -75,7 +75,7 @@ drm_unset_busid(struct drm_device *dev,
> master->unique_len = 0;
> }
>
> -/**
> +/*
> * Set the bus id.
> *
> * \param inode device inode.
> @@ -149,7 +149,7 @@ static int drm_set_busid(struct drm_device *dev, struct
> drm_file *file_priv)
> return 0;
> }
>
> -/**
> +/*
> * Get a mapping information.
> *
> * \param inode device inode.
> @@ -201,7 +201,7 @@ static int drm_getmap(struct drm_device *dev, void *data,
> return 0;
> }
>
> -/**
> +/*
> * Get client information.
> *
> * \param inode device inode.
> @@ -244,7 +244,7 @@ static int drm_getclient(struct drm_device *dev, void
> *data,
> }
> }
>
> -/**
> +/*
> * Get statistics information.
> *
> * \param inode device inode.
> @@ -265,7 +265,7 @@ static int drm_getstats(struct drm_device *dev, void
> *data,
> return 0;
> }
>
> -/**
> +/*
> * Get device/driver capabilities
> */
> static int drm_getcap(struct drm_device *dev, void *data, struct drm_file
> *file_priv)
> @@ -318,7 +318,7 @@ static int drm_getcap(struct drm_device *dev, void *data,
> struct drm_file *file_
> return 0;
> }
>
> -/**
> +/*
> * Set device/driver capabilities
> */
> static int
> @@ -352,7 +352,7 @@ drm_setclientcap(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> return 0;
> }
>
> -/**
> +/*
> * Setversion ioctl.
> *
> * \param inode device inode.
> @@ -406,7 +406,18 @@ done:
> return retcode;
> }
>
> -/** No-op ioctl. */
> +/**
> + * drm_noop - DRM no-op ioctl implemntation
> + * @dev: DRM device for the ioctl
> + * @data: data pointer for the ioctl
> + * @file_priv: DRM file for the ioctl call
> + *
> + * This no-op implementation for drm ioctls is useful for deprecated
> + * functionality where we can't return a failure code because existing
> userspace
> + * checks the result of the ioctl, but doesn't care about the action.
> + *
> + * Always returns successfully with 0.
> + */
> int drm_noop(struct drm_device *dev, void *data,
> struct drm_file *file_priv)
> {
> @@ -415,6 +426,21 @@ int drm_noop(struct drm_device *dev, void *data,
> }
> EXPORT_SYMBOL(drm_noop);
>
> +/**
> + * drm_invalid_op - DRM invalid ioctl implemntation
> + * @dev: DRM device for the ioctl
> + * @data: data pointer for the ioctl
> + * @file_priv: DRM file for the ioctl call
> + *
> + * This no-op implementation for drm ioctls is useful for deprecated
> + * functionality where we really don't want to allow userspace to call the
> ioctl
> + * any more. This is the case for old ums interfaces for drivers that
> + * transitioned to kms gradually and so kept the old legacy tables around.
> This
> + * only applies to radeon and i915 kms drivers, other drivers shouldn't need
> to
> + * use this function.
> + *
> + * Always fails with a return value of -EINVAL.
> + */
> int drm_invalid_op(struct drm_device *dev, void *data,
>struct drm_file *file_priv)
> {
> @@ -422,7 +448,7 @@ int drm_invalid_op(struct drm_device *dev, void *data,
> }
> EXPORT_SYMBOL(drm_invalid_op);
>
> -/**
> +/*
> * Copy and IOCTL return string to user space
> */
> static int drm_copy_field(char __user *buf, size_t *buf_len, const char
> *value)
> @@ -445,7 +471,7 @@ static int drm_copy_field(char __user *buf, size_t
> *buf_len, const char *value)
> return 0;
> }
>
> -/**
> +/*
> * Get version information
> *
> * \param inode device inode.
> @@ -477,7 +503,7 @@ static int drm_version(struct drm_device *dev, void *data,
> return err;
> }
>
> -/**
> +/*
> * drm_ioctl_permit - Check ioctl permissions against caller
> *
> * @flags: ioctl permission flags.
>
[PATCH 07/11] drm/drm_ioctl.c: kerneldoc
As usual pull it into the drm docbook template, too. And again as
usual I've decided to only document stuff exported to drivers, so all
the old leftover markup from the shared drm repo days lost the magic
** signature.
Signed-off-by: Daniel Vetter
---
Documentation/DocBook/drm.tmpl | 1 +
drivers/gpu/drm/drm_ioctl.c| 76 ++
2 files changed, 55 insertions(+), 22 deletions(-)
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 7d10be2a2ba0..cfb43203a6a7 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -3752,6 +3752,7 @@ int num_ioctls;
+!Edrivers/gpu/drm/drm_ioctl.c
diff --git a/drivers/gpu/drm/drm_ioctl.c b/drivers/gpu/drm/drm_ioctl.c
index f0b4f581f6ce..75df8ea87cd7 100644
--- a/drivers/gpu/drm/drm_ioctl.c
+++ b/drivers/gpu/drm/drm_ioctl.c
@@ -40,7 +40,7 @@
static int drm_version(struct drm_device *dev, void *data,
struct drm_file *file_priv);
-/**
+/*
* Get the bus id.
*
* \param inode device inode.
@@ -75,7 +75,7 @@ drm_unset_busid(struct drm_device *dev,
master->unique_len = 0;
}
-/**
+/*
* Set the bus id.
*
* \param inode device inode.
@@ -149,7 +149,7 @@ static int drm_set_busid(struct drm_device *dev, struct
drm_file *file_priv)
return 0;
}
-/**
+/*
* Get a mapping information.
*
* \param inode device inode.
@@ -201,7 +201,7 @@ static int drm_getmap(struct drm_device *dev, void *data,
return 0;
}
-/**
+/*
* Get client information.
*
* \param inode device inode.
@@ -244,7 +244,7 @@ static int drm_getclient(struct drm_device *dev, void *data,
}
}
-/**
+/*
* Get statistics information.
*
* \param inode device inode.
@@ -265,7 +265,7 @@ static int drm_getstats(struct drm_device *dev, void *data,
return 0;
}
-/**
+/*
* Get device/driver capabilities
*/
static int drm_getcap(struct drm_device *dev, void *data, struct drm_file
*file_priv)
@@ -318,7 +318,7 @@ static int drm_getcap(struct drm_device *dev, void *data,
struct drm_file *file_
return 0;
}
-/**
+/*
* Set device/driver capabilities
*/
static int
@@ -352,7 +352,7 @@ drm_setclientcap(struct drm_device *dev, void *data, struct
drm_file *file_priv)
return 0;
}
-/**
+/*
* Setversion ioctl.
*
* \param inode device inode.
@@ -406,7 +406,18 @@ done:
return retcode;
}
-/** No-op ioctl. */
+/**
+ * drm_noop - DRM no-op ioctl implemntation
+ * @dev: DRM device for the ioctl
+ * @data: data pointer for the ioctl
+ * @file_priv: DRM file for the ioctl call
+ *
+ * This no-op implementation for drm ioctls is useful for deprecated
+ * functionality where we can't return a failure code because existing
userspace
+ * checks the result of the ioctl, but doesn't care about the action.
+ *
+ * Always returns successfully with 0.
+ */
int drm_noop(struct drm_device *dev, void *data,
struct drm_file *file_priv)
{
@@ -415,6 +426,21 @@ int drm_noop(struct drm_device *dev, void *data,
}
EXPORT_SYMBOL(drm_noop);
+/**
+ * drm_invalid_op - DRM invalid ioctl implemntation
+ * @dev: DRM device for the ioctl
+ * @data: data pointer for the ioctl
+ * @file_priv: DRM file for the ioctl call
+ *
+ * This no-op implementation for drm ioctls is useful for deprecated
+ * functionality where we really don't want to allow userspace to call the
ioctl
+ * any more. This is the case for old ums interfaces for drivers that
+ * transitioned to kms gradually and so kept the old legacy tables around. This
+ * only applies to radeon and i915 kms drivers, other drivers shouldn't need to
+ * use this function.
+ *
+ * Always fails with a return value of -EINVAL.
+ */
int drm_invalid_op(struct drm_device *dev, void *data,
struct drm_file *file_priv)
{
@@ -422,7 +448,7 @@ int drm_invalid_op(struct drm_device *dev, void *data,
}
EXPORT_SYMBOL(drm_invalid_op);
-/**
+/*
* Copy and IOCTL return string to user space
*/
static int drm_copy_field(char __user *buf, size_t *buf_len, const char *value)
@@ -445,7 +471,7 @@ static int drm_copy_field(char __user *buf, size_t
*buf_len, const char *value)
return 0;
}
-/**
+/*
* Get version information
*
* \param inode device inode.
@@ -477,7 +503,7 @@ static int drm_version(struct drm_device *dev, void *data,
return err;
}
-/**
+/*
* drm_ioctl_permit - Check ioctl permissions against caller
*
* @flags: ioctl permission flags.
@@ -525,7 +551,7 @@ EXPORT_SYMBOL(drm_ioctl_permit);
.name = #ioctl \
}
-/** Ioctl table */
+/* Ioctl table */
static const struct drm_ioctl_desc drm_ioctls[] = {
DRM_IOCTL_DEF(DRM_IOCTL_VERSION, drm_version,
DRM_UNLOCKED|DRM_RENDER_ALLOW),
DRM_IOCTL_DEF(DRM_IOCTL_GET_UNIQUE, drm_getunique, 0),
@@ -641,16 +667,16 @@ static const struct drm_ioctl_desc drm_ioctls[] = {
#define
