Re: [PATCH v2 1/3] shared memory: Define shared memory regions

[Cornelia Huck <cohuck@redhat.com>]

On Fri, 22 Feb 2019 11:54:31 +0000
"Dr. David Alan Gilbert (git)" <dgilbert@redhat.com> wrote:

> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
> 
> Define the requirements and idea behind shared memory regions.
> 
> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
> ---
>  content.tex    |  2 ++
>  shared-mem.tex | 33 +++++++++++++++++++++++++++++++++
>  2 files changed, 35 insertions(+)
>  create mode 100644 shared-mem.tex
> 
> diff --git a/content.tex b/content.tex
> index 836ee52..3dd504c 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -371,6 +371,8 @@ making any more buffers available. When VIRTIO_F_NOTIFICATION_DATA
>  has been negotiated, these notifications would then have
>  identical \field{next_off} and \field{next_wrap} values.
>  
> +\input{shared-mem.tex}
> +
>  \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
>  
>  We start with an overview of device initialization, then expand on the
> diff --git a/shared-mem.tex b/shared-mem.tex
> new file mode 100644
> index 0000000..85b0c55
> --- /dev/null
> +++ b/shared-mem.tex
> @@ -0,0 +1,33 @@
> +\section{Shared Memory Regions}\label{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}
> +
> +Shared memory regions are an additional facility
> +available to devices that need a region of memory that's
> +continuously shared between the host and the guest, rather
> +than passed between them in the way virtqueue elements are.
> +
> +Example uses include shared caches and version pools for versioned
> +data structures.
> +
> +The region is chosen by the host and presented to the guest, as
> +such it is useful in situations where the memory is accessed on
> +the host by other libraries that can't safely access guest RAM.

This explanation looks good to me.

> +
> +Shared memory regions MUST NOT be used to control the operation
> +of the device, nor to stream data; those should still be performed
> +using virtqueues.

The 'MUST NOT' makes it look like a normative statement; however, this
is more like design advice?

> +
> +A device may have multiple shared memory regions associated with
> +it.  Each region has a \field{shmid} to identify it, the meaning
> +of which is device-specific.
> +
> +Enumeration and location of shared memory regions is performed
> +using a transport-specific data structure and mechanism.
> +
> +Memory consistency rules vary depending on the region and the
> +device.  Devices MUST define the required behaviour for each
> +region.

Same here.

> +
> +The guest physical address and the host virtual address MUST NOT
> +be used to identify structures within the memory regions; all
> +addressing MUST be relative to the start of a particular region.
> +

For that high-level overview, I'm not sure if any normative statements
are needed/wanted, or whether those should be confined to the individual
transport or device type definitions...

The text on its own looks good to me.