From nobody Mon Jun 8 04:27:21 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=reject dis=none) header.from=meta.com ARC-Seal: i=1; a=rsa-sha256; t=1780411222; cv=none; d=zohomail.com; s=zohoarc; b=TVwHNzKrFfUijtPVK0MrtBENVg81SfyyEfrS0CKxyhE4jAMjwViHc9HNAMS/Fngl8MM92SZLqg8Cm7Vpo/PCbhct3k5lSWlt5cxTvxB34R7HXxz+DuO7fn/0ImMwBsAwMApDlYLzE23hM4QdSrOsN+FAaA/ov4LjkUyml3WOss8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780411222; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=gYagSwz16GrA6Sm165brLVtxDNJo/MGlmgsaUncimgk=; b=f46zFzDdUIzhjFvaMkFoFohctpCg4xPpUo9p9QXzWhbsxXJ3JYUj1KDtWAUpyMN7FxkFZJz8+Bxn1d5ikrVbqTtL0kzaFLMsKDot0ftfHWtkcfMKpBSk+L9Wo4x1flswoqeu/X7ZiPp+PZH+i+qM5DMwu0Ra6txLdZjuXoQWL7A= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780411222881570.7113882713829; Tue, 2 Jun 2026 07:40:22 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUQHU-00044B-RW; Tue, 02 Jun 2026 10:39:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUPKP-0001E6-6L for qemu-devel@nongnu.org; Tue, 02 Jun 2026 09:38:47 -0400 Received: from mx0a-00082601.pphosted.com ([67.231.145.42]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUPKN-0000LH-4h for qemu-devel@nongnu.org; Tue, 02 Jun 2026 09:38:44 -0400 Received: from pps.filterd (m0528009.ppops.net [127.0.0.1]) by mx0a-00082601.pphosted.com (8.18.1.11/8.18.1.11) with ESMTP id 651K2Vcn1621208; Tue, 2 Jun 2026 06:38:38 -0700 Received: from maileast.thefacebook.com ([163.114.135.16]) by mx0a-00082601.pphosted.com (PPS) with ESMTPS id 4eghn5dbqc-3 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128 verify=NOT); Tue, 02 Jun 2026 06:38:37 -0700 (PDT) Received: from localhost (2620:10d:c0a8:1c::11) by mail.thefacebook.com (2620:10d:c0a9:6f::237c) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.2.2562.41; Tue, 2 Jun 2026 13:38:36 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=meta.com; h=cc :content-transfer-encoding:content-type:date:from:message-id :mime-version:subject:to; s=s2048-2025-q2; bh=gYagSwz16GrA6Sm165 brLVtxDNJo/MGlmgsaUncimgk=; b=h4rShyrIhDu+FuwyOUoxbuN6xdV19eujfc iu1PdbIzRfGVRJPrY7+WbUQWrY8bKsoBmzAqs1YVp1fXqn2/zTopH6vFB7Y7tO7h CFTCifEsFjAriAq0BawuJnv881EqxCmg5+ZfKIC5oPHS/wohDGFW0x+bwRURc0Is aOBXqNNOnSPfjA5z0TuWqq1AHK0rR6A7ii5Th1bsSJoiGcQBRBlcJ7h8PTbomISp FS7Iwrwx8yQ+YmQE5EDD0cZf7OnOWzbfZJ5EJK90BpkailzgT/sR/UGmhY3IMvHn /T1MKp98FgYKgavUuLb+G8UMN1/Wlh1DZKJ8yQHWdmE+Qo6+P9kQ== From: Mattias Nissler To: CC: Thanos Makatos , =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Pierrick Bouvier , John Levon , Subject: [PATCH] docs: Update vfio-user spec to describe DMA access mode bits Date: Tue, 2 Jun 2026 06:38:29 -0700 Message-ID: <20260602133829.305842-1-mnissler@meta.com> X-Mailer: git-send-email 2.52.0 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Originating-IP: [2620:10d:c0a8:1c::11] X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwNjAyMDEzMCBTYWx0ZWRfX+xVrrE3ERCQT UAzcdK7UOgxmO9ixgGpETEyNfmExQg6lWyDR1wSaTGqOA/6jqVCf4m7nbMUje2rSa2l1nRvss6k A1lKOVOgbfMdMvN7bPcYPIilCXrNGEpp0IiHnbDbvTYo1dnMSrH5eWyx01A6nek8likLjE9geIQ BolmRvUJbIF4gYcM0BPnL60S6MYManrAshoAzT7QeTUyzqiy6gXCg7l8XdFywcI4hm7ZymIGgJJ y2S1gAsajb7Wx6ThLvfAj5Rs1iTUSX7FwjGejTiLiXCsTM4iSRynyXf7QgP2F+C9G2j10ica10U LV+vP+Kwx+ubaDmS0ZtHOPwHI4E6DuZplT95OtA6MWba0nManDwDvU596OEMnU/hthg8Pg2rgae HkodUKMgLvejUicuMUWIgff1imdtaiTIHlfAASEZgMQIoJA6/7DIFcvIHECmanl7dsM7Sadk9HO 0dHZ1Rljr7kPj362UgQ== X-Proofpoint-GUID: nzez_HIbkGXqRC1wpj15cVdQ0huMNUpx X-Authority-Analysis: v=2.4 cv=HrZG3UTS c=1 sm=1 tr=0 ts=6a1edcdd cx=c_pps a=MfjaFnPeirRr97d5FC5oHw==:117 a=MfjaFnPeirRr97d5FC5oHw==:17 a=FelO9ux0wxsA:10 a=VkNPw1HP01LnGYTKEx00:22 a=7x6HtfJdh03M6CCDgxCd:22 a=U_y8lYiYyhHBU5rMqhb2:22 a=VabnemYjAAAA:8 a=qN4U-Vrk9NcT6eTNmKQA:9 a=gKebqoRLp9LExxC7YDUY:22 X-Proofpoint-ORIG-GUID: nzez_HIbkGXqRC1wpj15cVdQ0huMNUpx X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1143,Hydra:6.1.125,FMLib:17.12.100.49 definitions=2026-06-02_02,2026-05-28_03,2025-10-01_01 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=67.231.145.42; envelope-from=prvs=4613c7fe8e=mnissler@meta.com; helo=mx0a-00082601.pphosted.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, TVD_PH_SUBJ_META1=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Tue, 02 Jun 2026 10:39:47 -0400 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @meta.com) X-ZM-MESSAGEID: 1780411224418154100 Content-Type: text/plain; charset="utf-8" This makes the intended access mode explicit when registering DMA regions with the server. A new "file I/O" access mode is defined, which can be used if the file descriptor provided by the client doesn't support `mmap()`. Signed-off-by: Mattias Nissler Reviewed-by: John Levon --- docs/interop/vfio-user.rst | 82 ++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/docs/interop/vfio-user.rst b/docs/interop/vfio-user.rst index 12deb25102..1c92f442d2 100644 --- a/docs/interop/vfio-user.rst +++ b/docs/interop/vfio-user.rst @@ -604,27 +604,31 @@ Request =20 The request payload for this message is a structure of the following forma= t: =20 -+-------------+--------+-------------+ -| Name | Offset | Size | -+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ -| argsz | 0 | 4 | -+-------------+--------+-------------+ -| flags | 4 | 4 | -+-------------+--------+-------------+ -| | +-----+------------+ | -| | | Bit | Definition | | -| | +=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ | -| | | 0 | readable | | -| | +-----+------------+ | -| | | 1 | writeable | | -| | +-----+------------+ | -+-------------+--------+-------------+ -| offset | 8 | 8 | -+-------------+--------+-------------+ -| address | 16 | 8 | -+-------------+--------+-------------+ -| size | 24 | 8 | -+-------------+--------+-------------+ ++-------------+--------+------------------------+ +| Name | Offset | Size | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ +| argsz | 0 | 4 | ++-------------+--------+------------------------+ +| flags | 4 | 4 | ++-------------+--------+------------------------+ +| | +-----+-----------------------+ | +| | | Bit | Definition | | +| | +=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ | +| | | 0 | readable | | +| | +-----+-----------------------+ | +| | | 1 | writeable | | +| | +-----+-----------------------+ | +| | | 2 | access mode: mmap | | +| | +-----+-----------------------+ | +| | | 3 | access mode: file I/O | | +| | +-----+-----------------------+ | ++-------------+--------+------------------------+ +| offset | 8 | 8 | ++-------------+--------+------------------------+ +| address | 16 | 8 | ++-------------+--------+------------------------+ +| size | 24 | 8 | ++-------------+--------+------------------------+ =20 * *argsz* is the size of the above structure. Note there is no reply paylo= ad, so this field differs from other message types. @@ -634,6 +638,8 @@ The request payload for this message is a structure of = the following format: =20 * *writeable* indicates that the region can be written to. =20 + * *access mode* bits indicate how the region is to be accessed by the se= rver. + * *offset* is the file offset of the region with respect to the associated= file descriptor, or zero if the region is not mappable * *address* is the base DMA address of the region. @@ -641,16 +647,30 @@ The request payload for this message is a structure o= f the following format: =20 This structure is 32 bytes in size, so the message size is 16 + 32 bytes. =20 -If the DMA region being added can be directly mapped by the server, a file -descriptor must be sent as part of the message meta-data. The region can be -mapped via the mmap() system call. On ``AF_UNIX`` sockets, the file descri= ptor -must be passed as ``SCM_RIGHTS`` type ancillary data. Otherwise, if the D= MA -region cannot be directly mapped by the server, no file descriptor must be= sent -as part of the message meta-data and the DMA region can be accessed by the -server using ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages, -explained in `Read and Write Operations`_. A command to map over an existi= ng -region must be failed by the server with ``EEXIST`` set in error field in = the -reply. +There are several alternative access modes for the server to use when acce= ssing +the region: + +* ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages, explained in + `Read and Write Operations`_. + +* ``mmap()`` a client-provided file descriptor, then perform direct access= es to + the underlying memory. + +* File I/O system calls (such as ``pread()`` / ``pwrite()``) against a + client-provided file descriptor. + +The access mode bits in the flags field indicate which access mode to use.= If +an access mode requiring a file descriptor is specified, but the client do= es +not provide a file descriptor, the server must fail the request with +``EINVAL``. If no access mode flag bit is set, the server should use ``mma= p()`` +based access if the client provided a file descriptor and message-based ac= cess +otherwise. + +On ``AF_UNIX`` sockets, the file descriptor must be passed as ``SCM_RIGHTS= `` +type ancillary data. + +A command to map over an existing region must be failed by the server with +``EEXIST`` set in the error field in the reply. =20 Reply ^^^^^ --=20 2.52.0