From patchwork Tue Sep 8 11:56:27 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7140451 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id E811DBEEC1 for ; Tue, 8 Sep 2015 11:54:10 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id CEDEA206EB for ; Tue, 8 Sep 2015 11:54:09 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id C87F4206F4 for ; Tue, 8 Sep 2015 11:54:08 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id E72736E901; Tue, 8 Sep 2015 04:54:03 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-wi0-f169.google.com (mail-wi0-f169.google.com [209.85.212.169]) by gabe.freedesktop.org (Postfix) with ESMTPS id E247E6E7C1 for ; Tue, 8 Sep 2015 04:53:59 -0700 (PDT) Received: by wiclk2 with SMTP id lk2so117320478wic.0 for ; Tue, 08 Sep 2015 04:53:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=FVT3I/1+gS2HnT178840pfxW5n4M21P1r5Mv1yH+gc8=; b=W3IJ3HLB3zccqpcrS8njiSEJtkgxbk0N/oSYAS7tAGuaru2WTQecIEInjpqYJ5a/sd m6PodXJMcff5wKyvb7eLAM3VxmVOiNgfMk+ZNQ+/1zq4FfxT3VmOhe3vy/sV46Ng/5zx qZ7tyTLK1GR5SDfwpu6q4kW/hqY6lQCT9ktzI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=FVT3I/1+gS2HnT178840pfxW5n4M21P1r5Mv1yH+gc8=; b=Sp6FtElWHEuHwpcPdhg9g4Gze3SBdeKlmecv84XcLh09Kr0FP1wbqqfO/V5Z+FfrPn ENSpKtJoXSiSiO2Kzi3hyYjwUiLgxX3l1/Fpl/IRdBqaEq1mbd3qG8Utw5dypqN9MYNk xtcBruKAF1Bmo6ahlSdFERlkAhgsqcmO0OP8rlxmTesdWwIUCHYUXd4bQZ8AP2HYPmAy AcQjcLO2aK22Iac+2ulP3IiuFwnHVWwPHsPKYalSm9N2gUiHwjX8FeiMv5O47Jzg77kL lJp1SvWd/l+6yauS0na3XBfmZQYrsaRMQzx0OKa80rELkzoJ0a9aI4jsAUkBf/dXX6H+ t0cg== X-Gm-Message-State: ALoCoQkIK2GVrK3DiNxzBYxT6UuCuetXy/fw9VcgWcpGVfXAf14wdp3KQsLJy2D1LIK2yonxX854 X-Received: by 10.194.179.6 with SMTP id dc6mr45348459wjc.39.1441713238713; Tue, 08 Sep 2015 04:53:58 -0700 (PDT) Received: from phenom.ffwll.local (212-51-149-109.fiber7.init7.net. [212.51.149.109]) by smtp.gmail.com with ESMTPSA id o10sm4480145wia.4.2015.09.08.04.53.57 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 08 Sep 2015 04:53:58 -0700 (PDT) From: Daniel Vetter To: DRI Development Date: Tue, 8 Sep 2015 13:56:27 +0200 Message-Id: <1441713391-24732-8-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1441713391-24732-1-git-send-email-daniel.vetter@ffwll.ch> References: <1441713391-24732-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Intel Graphics Development , Daniel Vetter Subject: [Intel-gfx] [PATCH 07/11] drm/drm_ioctl.c: kerneldoc X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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 --- 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 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) {