Re: [PATCH 07/11] drm/drm_ioctl.c: kerneldoc

[David Herrmann <dh.herrmann@gmail.com>]

Hi

On Tue, Sep 8, 2015 at 1:56 PM, Daniel Vetter <daniel.vetter@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@intel.com>

Reviewed-by: David Herrmann <dh.herrmann@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@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx