[PATCH 07/11] drm/drm_ioctl.c: kerneldoc
David Herrmann
dh.herrmann at gmail.com
Mon Sep 28 08:07:44 PDT 2015
Hi
On Tue, Sep 8, 2015 at 1:56 PM, Daniel Vetter <daniel.vetter at ffwll.ch> 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 <daniel.vetter at intel.com>
Reviewed-by: David Herrmann <dh.herrmann at gmail.com>
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;</synopsis>
> </itemizedlist>
> </para>
> </para>
> +!Edrivers/gpu/drm/drm_ioctl.c
> </sect2>
> </sect1>
> <sect1>
> 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 DRM_CORE_IOCTL_COUNT ARRAY_SIZE( drm_ioctls )
>
> /**
> - * Called whenever a process performs an ioctl on /dev/drm.
> - *
> - * \param inode device inode.
> - * \param file_priv DRM file private.
> - * \param cmd command.
> - * \param arg user argument.
> - * \return zero on success or negative number on failure.
> + * drm_ioctl - ioctl callback implementation for DRM drivers
> + * @filp: file this ioctl is called on
> + * @cmd: ioctl cmd number
> + * @arg: user argument
> *
> * Looks up the ioctl function in the ::ioctls table, checking for root
> * previleges if so required, and dispatches to the respective function.
> + *
> + * Returns:
> + * Zero on success, negative error code on failure.
> */
> long drm_ioctl(struct file *filp,
> unsigned int cmd, unsigned long arg)
> @@ -760,9 +786,15 @@ EXPORT_SYMBOL(drm_ioctl);
>
> /**
> * drm_ioctl_flags - Check for core ioctl and return ioctl permission flags
> + * @nr: ioctl number
> + * @flags: where to return the ioctl permission flags
> + *
> + * This ioctl is only used by the vmwgfx driver to augment the access checks
> + * done by the drm core and insofar a pretty decent layering violation. This
> + * shouldn't be used by any drivers.
> *
> - * @nr: Ioctl number.
> - * @flags: Where to return the ioctl permission flags
> + * Returns:
> + * True if the @nr corresponds to a DRM core ioctl numer, false otherwise.
> */
> bool drm_ioctl_flags(unsigned int nr, unsigned int *flags)
> {
> --
> 2.5.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel
More information about the dri-devel
mailing list