From: David Herrmann <dh.herrmann@gmail.com>
To: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Daniel Vetter <daniel.vetter@intel.com>,
Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
DRI Development <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH 07/11] drm/drm_ioctl.c: kerneldoc
Date: Mon, 28 Sep 2015 17:07:44 +0200 [thread overview]
Message-ID: <CANq1E4Q7g=tzSSEUWMMgSs_-KshDgOoNvXQaeXigs_-ajUj8rA@mail.gmail.com> (raw)
In-Reply-To: <1441713391-24732-8-git-send-email-daniel.vetter@ffwll.ch>
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
next prev parent reply other threads:[~2015-09-28 15:07 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-09-08 11:56 [PATCH 00/11] Mixed bag of ioctl and agp cleanups Daniel Vetter
2015-09-08 11:56 ` [PATCH 01/11] drm: Remove __OS_HAS_AGP Daniel Vetter
2015-09-09 12:53 ` Ville Syrjälä
2015-09-09 14:45 ` [PATCH] " Daniel Vetter
2015-09-28 15:05 ` David Herrmann
2015-09-08 11:56 ` [PATCH 02/11] drm/i915: Kill cross-module option depencies Daniel Vetter
2015-09-08 11:56 ` [PATCH 03/11] drm/i915: Mark debug mod options as _unsafe Daniel Vetter
2015-09-22 9:34 ` Jani Nikula
2015-09-22 9:54 ` Daniel Vetter
2015-09-08 11:56 ` [PATCH 04/11] drm/i915: Remove setparam ioctl Daniel Vetter
2015-09-09 13:02 ` Ville Syrjälä
2015-09-09 14:46 ` [PATCH] drm/i915: Mark getparam ioctl as DRM_UNLOCKED Daniel Vetter
2015-09-30 8:46 ` [PATCH] drm/i915: Remove setparam ioctl Daniel Vetter
2015-09-30 8:50 ` Chris Wilson
2015-09-30 13:40 ` Ville Syrjälä
2015-09-08 11:56 ` [PATCH 05/11] drm/i915: Mark getparam ioctl as DRM_UNLOCKED Daniel Vetter
2015-10-09 10:00 ` Chris Wilson
2015-09-08 11:56 ` [PATCH 06/11] drm: Define a drm_invalid_op ioctl implementation Daniel Vetter
2015-09-09 12:28 ` David Herrmann
2015-09-08 11:56 ` [PATCH 07/11] drm/drm_ioctl.c: kerneldoc Daniel Vetter
2015-09-28 15:07 ` David Herrmann [this message]
2015-09-08 11:56 ` [PATCH 08/11] drm: Enforce unlocked ioctl operation for kms driver ioctls Daniel Vetter
2015-09-08 18:45 ` Gustavo Padovan
2015-09-28 15:21 ` David Herrmann
2015-09-28 19:42 ` [PATCH] " Daniel Vetter
2015-09-08 11:56 ` [PATCH 09/11] drm/vmwgfx: Stop checking for DRM_UNLOCKED Daniel Vetter
2015-09-28 15:22 ` David Herrmann
2015-09-08 11:56 ` [PATCH 10/11] drm/<drivers>: Drop DRM_UNLOCKED from modeset drivers Daniel Vetter
2015-09-08 18:46 ` [Intel-gfx] " Gustavo Padovan
2015-09-28 15:24 ` David Herrmann
2015-09-08 11:56 ` [PATCH 11/11] drm: Remove dummy agp ioctl wrappers Daniel Vetter
2015-09-28 15:25 ` David Herrmann
2015-09-08 12:58 ` [PATCH 00/11] Mixed bag of ioctl and agp cleanups Christian König
2015-10-08 17:01 ` Daniel Vetter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CANq1E4Q7g=tzSSEUWMMgSs_-KshDgOoNvXQaeXigs_-ajUj8rA@mail.gmail.com' \
--to=dh.herrmann@gmail.com \
--cc=daniel.vetter@ffwll.ch \
--cc=daniel.vetter@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).