From nobody Tue Apr 7 14:41:28 2026 Received: from mail-oa1-f44.google.com (mail-oa1-f44.google.com [209.85.160.44]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 52FCB3B7749 for ; Thu, 12 Mar 2026 21:58:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=pass smtp.client-ip=209.85.160.44 ARC-Seal: i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773352722; cv=pass; b=CFrwnbxeDthKlexGuRYIUnZ9JvBiUX2p/B4HY7AVkisUpC1ucufbPENAvapVT9m4rQXpXtA+W59DUUH29x/ShVHTcxRon6WBrBjUJZ+3BZ2UB9OoyhjfMKRouuWiLhkeUkIru3r3LfxX8m0i/1H3AKP6JQbw+ATpWzByz6FmCas= ARC-Message-Signature: i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773352722; c=relaxed/simple; bh=/UXbidtDU54/5v7kkzH9PAfgESqYtiigH9Z7woqu25w=; h=MIME-Version:From:Date:Message-ID:Subject:To:Cc:Content-Type; b=g5Ql/OJKlbVh4PXDYMs/RwVvDgtDK8lYclBCFNsX2PIV+KbbkComLq3DI2XUKKAbkJ45sGyBEbTl62kvpGb8KlJepDwIG35BbZQiGtIFICINlxa3TI0xoQ1X+e/6edZXI0ySzJS6sFDo7WjRzBH+oZOURQFetCKeL5PnysbIZyA= ARC-Authentication-Results: i=2; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=kLjFKNkc; arc=pass smtp.client-ip=209.85.160.44 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="kLjFKNkc" Received: by mail-oa1-f44.google.com with SMTP id 586e51a60fabf-4170e916d77so522198fac.1 for ; Thu, 12 Mar 2026 14:58:40 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1773352719; cv=none; d=google.com; s=arc-20240605; b=R9e7jDmJH5A6MAuTVU/VojRpE9iVR+BFSoVMwwm7Qzd3AUfnE32WmBKwfCvXrkW35N 9OTvVaIJ7JnNpBFoORNHISBgf5efKOXZkY8FugRRFszonjzgZDvR3nra4pOy+zz7DyHe +2S+moDX5LiTUFh+eMQHeSM8ZGDHPnzbNIMCYDwH4egMRcL6N5NnTsG+uDiSgaZtddBm RtlvMEND8pfuOEQ6kcxKmvlahC3plJZn6QlTrJtauJzSS9pg5zk85WbMM1FVrESRWx61 OCLTHgG2BKEuuUgzXzoAsCKHV9o9/I/krkb8fOgfoGrIADvrJBVeF2G8JqdnmpF3PUEQ CbiQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=cc:to:subject:message-id:date:from:mime-version:dkim-signature; bh=FqP84TGmgvyTgfJsFq+pkxpoA3lD0KYlwSD57EbzY8Y=; fh=RqcvigxvuzZnFf4DOzUfMCgqjzkUmql6wGrikkZkIF8=; b=k+BcutGzUjDTEscxcre+PPiZ7tTRbTGiiU0gzrd/R6bnwSs4vyHofaRUO5yanVWz/r cKSqwvXp3+5KO5qf661gjMRWPeBUx3GsUo90E9Q03Ct4vvQh0w/4ixirIPdy+NVyHlGf SMY5PNAxswKwSa/salpaD32LKRgugGVKXqlwbMh8a0FjEzyJU4vGrcT6+D8CzNy6QGIM UVztWMy4ZpnQzGd7xIm8puaOmneRsi7Y8BG3sf4kRh+CQZIOoaVvia8twMlIW+7NlUxs IXibCwmLGj13t2M35UrMW5bgiQ0edAFc+tFYjKbt+zw6DvONpNQbCeoL/uC60R7qqk2R nV+Q==; darn=vger.kernel.org ARC-Authentication-Results: i=1; mx.google.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1773352719; x=1773957519; darn=vger.kernel.org; h=cc:to:subject:message-id:date:from:mime-version:from:to:cc:subject :date:message-id:reply-to; bh=FqP84TGmgvyTgfJsFq+pkxpoA3lD0KYlwSD57EbzY8Y=; b=kLjFKNkcyHGrvKdNmhragVkqK2yhm1eU42X6gW9Nz3314svj5NHvsFVk1cy/XuohWV xmQa35/lj6RpdhqU58ZMBpYtFGfXLiAJwD1y2mPzW2I3MVamXbpqhlHaoNUoHwnQGXx/ vCIPATibO5MVW6GFZAHAFJQzF19Fj3Zb9M8fou1exuDTHHw6mVZyqEiLrKewtca2AWdp eQ5XUU7eJGdoKsnfeBh9OjJS2pGu1aDWsTRkFtW1srGEWx8AhSZRSbPo6I0274UAkzdo gTz/OZfXv/XZRMQTENtOr792Om7yPZuFi8xmOP67RgmiUi8PctAM5f+9YTQxaOIMEuqK OJbg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1773352719; x=1773957519; h=cc:to:subject:message-id:date:from:mime-version:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=FqP84TGmgvyTgfJsFq+pkxpoA3lD0KYlwSD57EbzY8Y=; b=azFvxRW1aoRhrRCg2ZuXMk2wJ4yS3zFA10ALW/JXPJN3kSO4V6UGYNooD4kkBOl4aa nczkITQV2EZ3Kwh2D29g5ZfNMboqLJx9XrNvE0lbx1jh4OvWUuuCLhLScGt4HVRzNOmz w44vJHgNCzoG34Zk33UKzViJc47MFKTkd8wjlacJEX8wI/AW+Ejww+tYgn/hvOXMCJWu N0Ax6vz8PeYVEVcVz9RqHgp8c5P/9Oh6wuuWeffWCBRcsBwwJIvhGSwXLzP7vDgFkXih BTZLxkT44xpLmhyuOu5pZgkRD4cDvtJ/qQrYXbav78E1iSPUVOYcA7n569r+JPIIYVEf RzHg== X-Forwarded-Encrypted: i=1; AJvYcCVKwhOChnIzyIKXQTL0mFMxHVP/vzRGnEzNp6BsAbdNLhLbO9pzeRyY/dETzyzx3BmpW9jPLT/vMC4QJOY=@vger.kernel.org X-Gm-Message-State: AOJu0Yw87IgqxaR1RZWOkPqm3+1dZnBn4ZNX9umq8T25/z8WkmO7Bha2 BI11dNBoQ0ajon6He6DaSSK47sQ0qjMNglKPwsMTO4/UYTkQD2KtmhyxhGkLWmbRM9KHA8GFdli JegCUFBI0MMXpGqmSHgV307pyQFymZZg= X-Gm-Gg: ATEYQzwuZD6Yqx6a7LDstISRI2gidw4jaevYPc3lPfpCzX6ZJqhYrQLmiiSExDzDs95 vqXJILQbCZdVms2wTi5cSjqaLXwrL3rdmoafAE/o0XrJQB5UWpmKGsK1Ma9wDrrqsGgFC/3WODK GfwUeFtVRmJdAmTocP0/JTGmArlBGykectKU15VkWX5qSkpsylnncIxmBH18Wke5+e7/uO0eSzL nZm3nCZEkoAWa/1dafLIQ8AlkNjitL1hVEG376BfUP6GxMGOWOTNP0yDa7XjwY9L2P2YajsiPlW t8WzqrFRRHfuEGOY7aERuaFlPVZ8WHWzbIXWuqMdhFmquH6EXwGiuMxLUr3WGMSAgEf4EQ== X-Received: by 2002:a05:6871:582b:b0:417:5cf7:48f6 with SMTP id 586e51a60fabf-417b9059c22mr617649fac.3.1773352719154; Thu, 12 Mar 2026 14:58:39 -0700 (PDT) Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 From: John S Date: Thu, 12 Mar 2026 22:58:26 +0100 X-Gm-Features: AaiRm53jG2HdeSoWg3E3eUPDX7LBFweqaGa9oOaMogvds1ztn67HqyTh2Ab3FCg Message-ID: Subject: [PATCH] virtio: document the map API in the driver writing guide To: mst@redhat.com, jasowang@redhat.com Cc: xuanzhuo@linux.alibaba.com, eperezma@redhat.com, corbet@lwn.net, skhan@linuxfoundation.org, virtualization@lists.linux.dev, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add a new "Buffer mapping" section to the virtio driver writing guide documenting the virtio map API (struct virtio_map_ops). This API was introduced in commit bee8c7c24b73 ("virtio: introduce map ops in virtio core") to allow transports and devices that do not perform DMA (such as VDUSE) to provide their own buffer mapping logic instead of abusing the DMA API. The new section explains when and why custom map ops are used, documents the virtio_map_ops structure and the union virtio_map token, and references the driver-facing mapping helpers with their kernel-doc. Signed-off-by: Kit Dallege Acked-by: Jason Wang --- .../virtio/writing_virtio_drivers.rst | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst b/Documentation/driver-api/virtio/writing_virtio_drivers.rst index e5de6f5d061a..a3fcbf91ffe0 100644 --- a/Documentation/driver-api/virtio/writing_virtio_drivers.rst +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst @@ -187,6 +187,78 @@ certain scenarios. The way to disable callbacks reliably is to reset the device or the virtqueue (virtio_reset_device()). +Buffer mapping +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Virtio devices need to map buffers so they can be accessed by the device. +Historically, virtio relied exclusively on the kernel DMA API for this, +which works well for hardware devices that perform real DMA. However, some +virtio backends (such as VDUSE, a user-space vDPA device) do not perform +DMA at all and previously had to abuse the DMA API with custom +``dma_ops`` to make things work. + +The virtio map API, introduced via ``struct virtio_map_ops``, solves +this by allowing transports and devices to provide their own mapping +logic. When a device supplies custom map ops, those are used instead of +the DMA API. When no custom ops are provided, the standard DMA API path +is used as before, so existing drivers require no changes. + +Map operations +-------------- + +A transport or device that needs custom mapping implements +``struct virtio_map_ops`` and assigns it to the ``map`` field of +``struct virtio_device``. The ``vmap`` field carries opaque mapping +metadata (a ``union virtio_map``) that is passed through to every map +operation: + +.. kernel-doc:: include/linux/virtio_config.h + :identifiers: struct virtio_map_ops + +The ``union virtio_map`` holds the mapping token -- for DMA-capable +devices this is a ``struct device *`` pointer, while for devices like +VDUSE it can be a pointer to their own mapping context (e.g. an IOVA +domain): + +.. kernel-doc:: include/linux/virtio.h + :identifiers: union virtio_map + +Driver-facing helpers +--------------------- + +Most virtio drivers do not need to call the map API directly -- the +virtqueue helpers (``virtqueue_add_inbuf()``, ``virtqueue_add_outbuf()``, +etc.) handle mapping internally. However, drivers that perform their own +pre-mapping or need coherent allocations can use the following helpers: + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_single_attrs + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_unmap_single_attrs + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_page_attrs + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_unmap_page_attrs + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_alloc_coherent + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_free_coherent + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_mapping_error + +.. kernel-doc:: drivers/virtio/virtio_ring.c + :identifiers: virtqueue_map_need_sync + +After mapping a buffer, always check the returned address with +``virtqueue_map_mapping_error()`` before using it. + + References =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -- 2.53.0