diff mbox series

[v4,9/9] vhost_user.rst: Add MEM_READ/WRITE messages

Message ID 20250217164012.246727-10-aesteve@redhat.com (mailing list archive)
State New
Headers show
Series vhost-user: Add SHMEM_MAP/UNMAP requests | expand

Commit Message

Albert Esteve Feb. 17, 2025, 4:40 p.m. UTC 
Add MEM_READ/WRITE request to the vhost-user
spec documentation.

Signed-off-by: Albert Esteve <aesteve@redhat.com>
---
 docs/interop/vhost-user.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Comments

Stefan Hajnoczi Feb. 18, 2025, 11 a.m. UTC | #1 
On Mon, Feb 17, 2025 at 05:40:12PM +0100, Albert Esteve wrote:
> Add MEM_READ/WRITE request to the vhost-user
> spec documentation.
> 
> Signed-off-by: Albert Esteve <aesteve@redhat.com>
> ---
>  docs/interop/vhost-user.rst | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
> index 96156f1900..9f7a2c4cf7 100644
> --- a/docs/interop/vhost-user.rst
> +++ b/docs/interop/vhost-user.rst
> @@ -391,6 +391,7 @@ In QEMU the vhost-user message is implemented with the following struct:
>            VhostUserTransferDeviceState transfer_state;
>            VhostUserMMap mmap;
>            VhostUserShMemConfig shmem;
> +          VhostUserMemRWMsg mem_rw;

Is this struct defined anywhere in the spec?

>        };
>    } QEMU_PACKED VhostUserMsg;
>  
> @@ -1938,6 +1939,38 @@ is sent by the front-end.
>    given range shall correspond to the entirety of a valid mapped region.
>    A reply is generated indicating whether unmapping succeeded.
>  
> +``VHOST_USER_BACKEND_MEM_READ``
> +  :id: 11
> +  :equivalent ioctl: N/A
> +  :request payload: ``struct VhostUserMemRWMsg``
> +  :reply payload: N/A
> +
> +  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
> +  successfully negotiated, this message can be submitted by the backends to
> +  read a memory region that has failed to resolve a translation due to an
> +  incomplete memory table, after another device called
> +  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
> +  descriptor file.
> +
> +  This mechanism works as a fallback for resolving those memory
> +  accesses and ensure that DMA works with Shared Memory Regions.
> +
> +``VHOST_USER_BACKEND_MEM_WRITE``
> +  :id: 12
> +  :equivalent ioctl: N/A
> +  :request payload: ``struct VhostUserMemRWMsg``
> +  :reply payload: N/A
> +
> +  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
> +  successfully negotiated, this message can be submitted by the backends to
> +  write a memory region that has failed due to resolve a translation an
> +  incomplete memory table  after another device called
> +  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
> +  descriptor file.
> +
> +  This mechanism works as a fallback for resolving those memory
> +  accesses and ensure that DMA works with Shared Memory Regions.
> +
>  .. _reply_ack:
>  
>  VHOST_USER_PROTOCOL_F_REPLY_ACK
> -- 
> 2.48.1
>
Albert Esteve Feb. 18, 2025, 12:50 p.m. UTC | #2 
On Tue, Feb 18, 2025 at 12:00 PM Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Mon, Feb 17, 2025 at 05:40:12PM +0100, Albert Esteve wrote:
> > Add MEM_READ/WRITE request to the vhost-user
> > spec documentation.
> >
> > Signed-off-by: Albert Esteve <aesteve@redhat.com>
> > ---
> >  docs/interop/vhost-user.rst | 33 +++++++++++++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> >
> > diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
> > index 96156f1900..9f7a2c4cf7 100644
> > --- a/docs/interop/vhost-user.rst
> > +++ b/docs/interop/vhost-user.rst
> > @@ -391,6 +391,7 @@ In QEMU the vhost-user message is implemented with the following struct:
> >            VhostUserTransferDeviceState transfer_state;
> >            VhostUserMMap mmap;
> >            VhostUserShMemConfig shmem;
> > +          VhostUserMemRWMsg mem_rw;
>
> Is this struct defined anywhere in the spec?

Ah, no, right. I did not see all the other structs defined, so I
assumed some were just to be found in the code. But then it wouldn't
serve as a specification... I realized I was not looking at the right
section.

VhostUserMMap is also missing, then. I will add them in the next
iteration in their respective commits.

>
> >        };
> >    } QEMU_PACKED VhostUserMsg;
> >
> > @@ -1938,6 +1939,38 @@ is sent by the front-end.
> >    given range shall correspond to the entirety of a valid mapped region.
> >    A reply is generated indicating whether unmapping succeeded.
> >
> > +``VHOST_USER_BACKEND_MEM_READ``
> > +  :id: 11
> > +  :equivalent ioctl: N/A
> > +  :request payload: ``struct VhostUserMemRWMsg``
> > +  :reply payload: N/A
> > +
> > +  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
> > +  successfully negotiated, this message can be submitted by the backends to
> > +  read a memory region that has failed to resolve a translation due to an
> > +  incomplete memory table, after another device called
> > +  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
> > +  descriptor file.
> > +
> > +  This mechanism works as a fallback for resolving those memory
> > +  accesses and ensure that DMA works with Shared Memory Regions.
> > +
> > +``VHOST_USER_BACKEND_MEM_WRITE``
> > +  :id: 12
> > +  :equivalent ioctl: N/A
> > +  :request payload: ``struct VhostUserMemRWMsg``
> > +  :reply payload: N/A
> > +
> > +  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
> > +  successfully negotiated, this message can be submitted by the backends to
> > +  write a memory region that has failed due to resolve a translation an
> > +  incomplete memory table  after another device called
> > +  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
> > +  descriptor file.
> > +
> > +  This mechanism works as a fallback for resolving those memory
> > +  accesses and ensure that DMA works with Shared Memory Regions.
> > +
> >  .. _reply_ack:
> >
> >  VHOST_USER_PROTOCOL_F_REPLY_ACK
> > --
> > 2.48.1
> >
diff mbox series

Patch

diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index 96156f1900..9f7a2c4cf7 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -391,6 +391,7 @@  In QEMU the vhost-user message is implemented with the following struct:
           VhostUserTransferDeviceState transfer_state;
           VhostUserMMap mmap;
           VhostUserShMemConfig shmem;
+          VhostUserMemRWMsg mem_rw;
       };
   } QEMU_PACKED VhostUserMsg;
 
@@ -1938,6 +1939,38 @@  is sent by the front-end.
   given range shall correspond to the entirety of a valid mapped region.
   A reply is generated indicating whether unmapping succeeded.
 
+``VHOST_USER_BACKEND_MEM_READ``
+  :id: 11
+  :equivalent ioctl: N/A
+  :request payload: ``struct VhostUserMemRWMsg``
+  :reply payload: N/A
+
+  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
+  successfully negotiated, this message can be submitted by the backends to
+  read a memory region that has failed to resolve a translation due to an
+  incomplete memory table, after another device called
+  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
+  descriptor file.
+
+  This mechanism works as a fallback for resolving those memory
+  accesses and ensure that DMA works with Shared Memory Regions.
+
+``VHOST_USER_BACKEND_MEM_WRITE``
+  :id: 12
+  :equivalent ioctl: N/A
+  :request payload: ``struct VhostUserMemRWMsg``
+  :reply payload: N/A
+
+  When the ``VHOST_USER_PROTOCOL_F_SHMEM`` protocol feature has been
+  successfully negotiated, this message can be submitted by the backends to
+  write a memory region that has failed due to resolve a translation an
+  incomplete memory table  after another device called
+  ``VHOST_USER_BACKEND_SHMEM_MAP`` for the same region on a shared
+  descriptor file.
+
+  This mechanism works as a fallback for resolving those memory
+  accesses and ensure that DMA works with Shared Memory Regions.
+
 .. _reply_ack:
 
 VHOST_USER_PROTOCOL_F_REPLY_ACK