From patchwork Mon Jan 31 17:23:07 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Demi Marie Obenour X-Patchwork-Id: 12730946 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 4507EC433F5 for ; Mon, 31 Jan 2022 17:23:41 +0000 (UTC) Received: from list by lists.xenproject.org with outflank-mailman.263240.455885 (Exim 4.92) (envelope-from ) id 1nEaOb-0003ub-4l; Mon, 31 Jan 2022 17:23:17 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 263240.455885; Mon, 31 Jan 2022 17:23:17 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nEaOb-0003uU-1T; Mon, 31 Jan 2022 17:23:17 +0000 Received: by outflank-mailman (input) for mailman id 263240; Mon, 31 Jan 2022 17:23:15 +0000 Received: from se1-gles-sth1-in.inumbo.com ([159.253.27.254] helo=se1-gles-sth1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nEaOZ-0003uN-Gu for xen-devel@lists.xenproject.org; Mon, 31 Jan 2022 17:23:15 +0000 Received: from mail-qv1-xf2c.google.com (mail-qv1-xf2c.google.com [2607:f8b0:4864:20::f2c]) by se1-gles-sth1.inumbo.com (Halon) with ESMTPS id 782db902-82ba-11ec-8eb8-a37418f5ba1a; Mon, 31 Jan 2022 18:23:14 +0100 (CET) Received: by mail-qv1-xf2c.google.com with SMTP id h16so13411387qvk.10 for ; Mon, 31 Jan 2022 09:23:13 -0800 (PST) Received: from [10.139.255.254] ([89.187.171.240]) by smtp.gmail.com with ESMTPSA id r3sm8735666qkm.56.2022.01.31.09.23.11 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 31 Jan 2022 09:23:12 -0800 (PST) X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: 782db902-82ba-11ec-8eb8-a37418f5ba1a DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:from:subject:to:cc :content-language; bh=bPILK0yhACFpprVLxksCilL8cYY3PolxdleU68y4ooA=; b=FjFa+zrsc3qD881ulSSHXKU8UPvaUT0pCpq7bRxFVtb8dAVuCfYJDqD54f+ePCE8Me fheCqyCUDYfiDFOAkpQkovYZ7tjDE00l8K2iXLVM+WbJx3OFtEJxqF3MXibeN0ZldNHE Fhvmm2qfTKTq5QsgoelPS/kd5IoOOL1yBnSpV6jeIhTx9G3TQQqKfJjKUKmwMTOKSHgF uCBsi2Vr+rGVxX3oFGPBtxoNDpb16nnHIn3wYfp9YtUyrBrMpYOnPfys0Z0DPid6YuJA LmJ4RELwypJTcFFQem4okazyUa6eRpjvZw40N6vAE65vqcXUeIa3HkpuqGaVINH6Q5ZR FtlQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:from :subject:to:cc:content-language; bh=bPILK0yhACFpprVLxksCilL8cYY3PolxdleU68y4ooA=; b=oO7CJR3dVcApAXPJiZLY4kDZ57V0Ai2ccMSn6tGM9agswrqHfL/g2O3y2S6lZ6fzCk mM/3GYdOA/7wt0AvyBQ8W85uOz5hAnrK3yqIidXk8G6HlW5yVmm4rxK7rmnDvKmssnWD oBioBihBVmNhdt8sNnWDo3g5RiCBkhZmhHLKMzkU8ZMpD5gSPKvpehTB9SdeQOdKTLiz 5pMY0damBfWHaWVUCanGxPswlRA37Ros0V+kyQyvxnAE56j2SkrrrdiDwMUovdSNQG++ Hr3+iqTM0/QCYHTk9DmRHltBhBskzDGgQFQg69wr1OYG2utaT5nfMIGCeIdNY48Aj7cn PREw== X-Gm-Message-State: AOAM530LzLVGnRUL6srs72RHq7SudYjBdKTNdvPawmgkjnBVxFdtyTpy HEGkLLDEufuoI5hUuqIF6h0= X-Google-Smtp-Source: ABdhPJy6vaDmp+y3fJCA7gGV2DLanRMhr8/9jPq+zq2/Xy49pzdQAaX3/i08PEqF7oW7dWBgRCy2Kw== X-Received: by 2002:a05:6214:dad:: with SMTP id h13mr18954971qvh.74.1643649792751; Mon, 31 Jan 2022 09:23:12 -0800 (PST) Message-ID: Date: Mon, 31 Jan 2022 12:23:07 -0500 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.5.0 From: Demi Marie Obenour Subject: [PATCH v2] Improve docs for IOCTL_GNTDEV_MAP_GRANT_REF To: Boris Ostrovsky , Juergen Gross , Stefano Stabellini Cc: Demi Marie Obenour , xen-devel@lists.xenproject.org, linux-kernel@vger.kernel.org Content-Language: en-US The current implementation of gntdev guarantees that the first call to IOCTL_GNTDEV_MAP_GRANT_REF will set @index to 0. This is required to use gntdev for Wayland, which is a future desire of Qubes OS. Additionally, requesting zero grants results in an error, but this was not documented either. Document both of these. Signed-off-by: Demi Marie Obenour Reviewed-by: Juergen Gross --- include/uapi/xen/gntdev.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/include/uapi/xen/gntdev.h b/include/uapi/xen/gntdev.h index 9ac5515b9bc2..7a7145395c09 100644 --- a/include/uapi/xen/gntdev.h +++ b/include/uapi/xen/gntdev.h @@ -47,7 +47,13 @@ struct ioctl_gntdev_grant_ref { /* * Inserts the grant references into the mapping table of an instance * of gntdev. N.B. This does not perform the mapping, which is deferred - * until mmap() is called with @index as the offset. + * until mmap() is called with @index as the offset. @index should be + * considered opaque to userspace, with one exception: if no grant + * references have ever been inserted into the mapping table of this + * instance, @index will be set to 0. This is necessary to use gntdev + * with userspace APIs that expect a file descriptor that can be + * mmap()'d at offset 0, such as Wayland. If @count is set to 0, this + * ioctl will fail. */ #define IOCTL_GNTDEV_MAP_GRANT_REF \ _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))