[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [PATCH v4 1/1] virtio-ism: introduce new device virtio-ism
On Thu, 18 May 2023 16:09:19 +0800, Xuan Zhuo <xuanzhuo@linux.alibaba.com> wrote: > An ISM(Internal Shared Memory) device provides the ability to access memory > shared between multiple devices. This allows low-overhead communication in > presence of such memory. For example, memory can be shared with guests of > multiple virtual machines running on the same host, with each virtual machine > including an ism device and with the guests getting the shared memory by the ism > devices. > > An ism device can communicate with multiple peers simultaneously. This > communication can be dynamically started and ended. > > |-------------------------------------------------------------------------------------------------------------| > | |------------------------------------------------| |------------------------------------------------| | > | | Guest | | Guest | | > | | | | | | > | | ---------------- | | ---------------- | | > | | | driver | [M1] [M2] [M3] | | | driver | [M2] [M3] | | > | | ---------------- | | | | | ---------------- | | | | > | | |cq| |map |map |map | | |cq| |map |map | | > | | | | | | | | | | | | | | | > | | | | ------------------- | | | | -------------------- | | > | |----|--|----------------| device memory |-----| |----|--|----------------| device memory |----| | > | | | | ------------------- | | | | -------------------- | | > | | | | | | | | > | | | | | | | | > | | | | | | | | > | |--------------------------------+---------------| |-------------------------------+----------------| | > | | | | > | | | | > | |------------------------------+------------------------| | > | | | > | | | > | -------------------------- | > | | M1 | | M2 | | M3 | | > | -------------------------- | > | | > | HOST | > --------------------------------------------------------------------------------------------------------------- > > Inside the guest, all operations of the ism region are implemented through the > driver, and the ism region can be used by other subsystems of the kernel > space, or directly used by user applications. > > Signed-off-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com> > Signed-off-by: Jiang Liu <gerry@linux.alibaba.com> > Signed-off-by: Dust Li <dust.li@linux.alibaba.com> > Signed-off-by: Tony Lu <tonylu@linux.alibaba.com> > Signed-off-by: Helin Guo <helinguo@linux.alibaba.com> > Signed-off-by: Hans Zhang <hans@linux.alibaba.com> > Signed-off-by: He Rongguang <herongguang@linux.alibaba.com> > Suggested-by: Halil Pasic <pasic@linux.ibm.com> Any comments? Thanks. > --- > conformance.tex | 2 + > content.tex | 1 + > device-types/ism/description.tex | 591 ++++++++++++++++++++++++ > device-types/ism/device-conformance.tex | 17 + > device-types/ism/driver-conformance.tex | 13 + > device-types/ism/layout-pic.tex | 112 +++++ > virtio-html.tex | 9 + > virtio.tex | 9 + > 8 files changed, 754 insertions(+) > create mode 100644 device-types/ism/description.tex > create mode 100644 device-types/ism/device-conformance.tex > create mode 100644 device-types/ism/driver-conformance.tex > create mode 100644 device-types/ism/layout-pic.tex > > diff --git a/conformance.tex b/conformance.tex > index 01ccd69..8fd7da3 100644 > --- a/conformance.tex > +++ b/conformance.tex > @@ -152,6 +152,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} > \input{device-types/scmi/driver-conformance.tex} > \input{device-types/gpio/driver-conformance.tex} > \input{device-types/pmem/driver-conformance.tex} > +\input{device-types/ism/driver-conformance.tex} > > \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} > > @@ -238,6 +239,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} > \input{device-types/scmi/device-conformance.tex} > \input{device-types/gpio/device-conformance.tex} > \input{device-types/pmem/device-conformance.tex} > +\input{device-types/ism/device-conformance.tex} > > \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} > A conformant implementation MUST be either transitional or > diff --git a/content.tex b/content.tex > index cff548a..737cdb1 100644 > --- a/content.tex > +++ b/content.tex > @@ -710,6 +710,7 @@ \chapter{Device Types}\label{sec:Device Types} > \input{device-types/scmi/description.tex} > \input{device-types/gpio/description.tex} > \input{device-types/pmem/description.tex} > +\input{device-types/ism/description.tex} > > \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} > > diff --git a/device-types/ism/description.tex b/device-types/ism/description.tex > new file mode 100644 > index 0000000..8ea0c57 > --- /dev/null > +++ b/device-types/ism/description.tex > @@ -0,0 +1,591 @@ > +\section{ISM Device}\label{sec:Device Types / ISM Device} > + > +\resizebox{\textwidth}{!}{% > +\input{device-types/ism/layout-pic.tex} > +}% > + > +An ISM(Internal Shared Memory) device provides the ability to access memory > +shared between multiple devices. This allows low-overhead communication in > +presence of such memory. For example, memory can be shared with guests of > +multiple virtual machines running on the same host, with each virtual machine > +including an ism device and with the guests getting the shared memory by the ism > +devices. > + > +An ism device can communicate with multiple peer devices simultaneously. This > +communication can be dynamically started and ended. > + > +\subsection{Device ID}\label{sec:Device Types / ISM Device / Device ID} > + 44 > + > +\subsection{Virtqueues}\label{sec:Device Types / ISM Device / Virtqueues} > +\begin{description} > +\item[0] controlq > +\item[1] eventq > +\end{description} > + > +\subsection{Feature bits}\label{sec:Device Types / ISM Device / Feature bits} > + > +\subsection{Communication Domain}\label{sec:Device Types / ISM Device / Communication Domain} > + > +All the devices with the ability to communicate with each other form a > +communication domain. Two devices from different communication domains can't > +communicate. > + > +\devicenormative{\subsubsection}{Communication Domain}{Device Types / ISM Device / Communication Domain} > + > +Only ism devices on the same communication domain can communicate. Every > +communication domain has an identification called \field{cdid}. The \field{cdid} > +is world-wide unique in a sense that there not be another communication domain > +with the same \field{cdid}. > + > +The \field{cdid} MUST be a version 4 UUID as specified by \hyperref[intro: > +rfc4122]{[RFC4122]}. > + > +\subsection{Memory}\label{sec:Device Types / ISM Device / Memory} > + > +\subsubsection{Shared Memory Regions}\label{sec:Device Types / ISM Device / Memory / Shared Memory Regions} > + > +The device exposes memory to the driver based on Shared Memory Regions > +\ref{sec:Basic Facilities of a Virtio Device / Shared Memory Regions}. > + > +The \field{shmid} of a shared memory region MUST be one of the following > +\begin{lstlisting} > +enum virtio_ism_shm_id { > + VIRTIO_ISM_SHM_ID_UNDEFINED = 0, > + VIRTIO_ISM_SHM_ID_REGIONS = 1, > + VIRTIO_ISM_SHM_ID_NOTIFY = 2, > +}; > +\end{lstlisting} > + > +The shared memory region with VIRTIO_ISM_SHM_ID_REGIONS is the ism regions > +area. The ism regions are located in here. > + > +The device MUST also provide a shared memory region with > +VIRTIO_ISM_SHM_ID_NOTIFY to the driver. This is the notification area. > +This area is used to notify the device with update event. Each ism chunk > +have a corresponding notify-address inside this area in order, and the size > +of the notify-address is \field{notify_size}. > + > +\subsubsection{Chunk And ISM Region}\label{sec:Device Types / ISM Device / Memory / Chunk And ISM Region} > + > +The ism regions area is divided into multiple chunks with the same size. > + > +The object of each driver operation is an ism region. It consists of at least > +one chunk. > + > +An ism region can be referred by its \field{token}, or the \field{offset}. > +The \field{offset} is the offset of the first chunk inside the ism regions area. > + > +\devicenormative{\paragraph}{Chunk And ISM Region}{Device Types / ISM Device / Memory / Chunk And ISM Region} > + > +\field{chunk_size} MUST be a multiple of the page size. > + > + > +\subsubsection{Physical Memory}\label{sec:Device Types / ISM Device / Memory / Physical Memory} > + > +The ism region is located in the ism regions area. For the driver, the ism > +regions area is physical memory. But for the device, it is a virtual space that > +devices can map into using different physical memory, as determined by the > +device. The device can manage whether each chunk is mapped to a physical memory, > +or modify the memory it mapped. > + > +For example, for a certain chunk A on the driver A's ism regions area, the > +device can use a physical memory A to map into chunk A, so that driver A's > +modification on the chunk A will be reflected in this physical memory A. When a > +physical memory B is mapped to chunk A by the device, the modification on chunk > +A will be reflected on physical memory B. If another device maps physical memory > +B simultaneously to its ism regions area chunk C, then the driver corresponding > +to this device can see the modification of the driver A on chunk C. > + > +\subsubsection{Swap Buffer}\label{sec:Device Types / ISM Device / Memory / Chunk And ISM Region} > + > +For attach/alloc operations, the driver also provides a buffer of the same size > +as the ism region to the device. This buffer is the swap buffer. This is to > +limit the driver to take up too much memory through the virtio ism device. And > +the swap buffer may be used by the device. > + > +For the alloc operation, the device need to choose a physical memory to map, > +which can be the swap buffer or memory from the device. If the memory of the > +device is used to map, the current driver can do detach at any time and the swap > +buffer is free immediately. But if the device use the swap buffer to map, after > +this driver detached the ism region, it needs to wait for other users to release > +the reference to the swap buffer before reclaiming the swap buffer. > + > +\devicenormative{\paragraph}{Swap Buffer}{Device Types / ISM Device / Memory / Swap Buffer} > +Before the swap buffer is free, the driver MUST NOT access the swap buffer. > + > +After the detach operation, if the swap buffer is not free, the driver MUST NOT > +access the swap buffer until it receives the VIRTIO_ISM_EVENT_SWAPBUF_RELEASE > +event. > + > +\drivernormative{\paragraph}{Swap Buffer}{Device Types / ISM Device / Memory / Swap Buffer} > +The swap buffer MUST be page-aligned. > + > +\subsection{Event}\label{sec:Device Types / ISM Device / Event} > + > +The ism device supports event notification of the ism region. When a device > +kick/attach/detach a region, other ism region referrers will receive related > +events. > + > +A buffer received from eventq can contain multiple event structures. > + > +\begin{lstlisting} > +#define VIRTIO_ISM_EVENT_UPDATE (1 << 0) > +#define VIRTIO_ISM_EVENT_ATTACH (1 << 1) > +#define VIRTIO_ISM_EVENT_DETACH (1 << 2) > +#define VIRTIO_ISM_EVENT_SWAPBUF_RELEASE (1 << 3) > +\end{lstlisting} > + > +\begin{description} > + \item[VIRTIO_ISM_EVENT_UPDATE] The driver kick the notify-address to notify > + other peers of the update event of the ism region content. > + > + \item[VIRTIO_ISM_EVENT_ATTACH] A new device attaches the ism region. > + \item[VIRTIO_ISM_EVENT_DETACH] A device detaches the ism region. > + \item[VIRTIO_ISM_EVENT_SWAPBUF_RELEASE] The swap buffer has been free. > +\end{description} > + > +The event structures: > +\begin{lstlisting} > +struct virtio_ism_event_update { > + le64 ev_type; > + le64 offset; > + le64 devid; > +}; > + > +struct virtio_ism_event_attach_detach { > + le64 ev_type; > + le64 offset; > + le64 devid; > + le64 peers; > +}; > + > +struct virtio_ism_event_buffer_free { > + le64 ev_type; > + le64 swap_buffer; > +}; > + > +\end{lstlisting} > + > +\begin{description} > +\item[\field{ev_type}] The type of event, the driver can get the size of the > + structure based on this. > + > + If \field{ev_type} is VIRTIO_ISM_EVENT_UPDATE, the corresponding structure is struct virtio_ism_event_update. > + If \field{ev_type} is VIRTIO_ISM_EVENT_ATTACH or VIRTIO_ISM_EVENT_DETACH, the corresponding structure struct virtio_ism_event_attach_detach. > + If \field{ev_type} is VIRTIO_ISM_EVENT_SWAPBUF_RELEASE, the corresponding structure is struct virtio_ism_event_buffer_free. > + > +\item[\field{offset}] The offset of the first chunk of the ism region with the event. > + > +\item[\field{devid}] \field{devid} of the device that generated this event. > +\item[\field{peers}] The number of the peers referring to this ism region. (does not include the > + device that receiving this event) > + > +\item[\field{swap_buffer}] The swap buffer passed to device when alloc/attach a new ism region. > + > +\end{description} > + > +\drivernormative{\subsubsection}{Event}{Device Types / ISM Device / Event} > + > +The driver MUST generate update events with the notify-address corresponding to > +the first chunk of the ism region. > + > +\subsection{Process Of Sharing Memory}\label{sec:Device Types / ISM Device / Process Of Sharing Memory} > + > +The process of sharing memory between two drivers is: > + > +\begin{itemize} > +\item One driver allocates an ism region and obtains a token. > +\item The peer driver uses this token to attach the same ism region. > + Then the two drivers realize the memory(ism region) sharing. > +\item One driver can notify the peer driver an update event by kick notify-address. > +\item The driver can detach the ism region to stop the sharing. > +\end{itemize} > + > +\subsection{Permission}\label{sec:Device Types / ISM Device / Permission} > + > +The permissions of an ism region determine whether this ism region can be > +attached and the read and write permissions after attach. The driver can set the > +default permissions for all devices, or set the dedicated permissions for a > +certain device. If there are dedicated permissions for a device, the default > +permissions are invalid for this device. > + > +For example, the driver can set the default permission of an ism region as > +read-only, and set the dedicated permissions as writable for a device with devid > +0xff. Then all devices except 0xff in such a communication domain can attach > +this ism region and only have read-only permission. And the device 0xff can > +write to the ism region after attaching. > + > +When a driver has the management permission of the ism region, then it can > +modify the permissions of this ism region. By default, only the device that > +allocated the ism region has this permission. > + > +\subsection{Device configuration layout}\label{sec:Device Types / ISM Device / Device configuration layout} > + > +\begin{lstlisting} > +struct virtio_ism_config { > + u8 cdid[16]; > + le64 devid; > + le64 chunk_size; > + le64 notify_size; > +}; > +\end{lstlisting} > + > +\begin{description} > + \item[\field{cdid}] This is the identification of the communication domain to which the device belongs. > + \item[\field{devid}] This is the identification of the ism device in the communication domain. > + \item[\field{chunk_size}] This is the size of the chunk. > + \item[\field{notify_size}] This is the size of the ism notify-address. > +\end{description} > + > +\devicenormative{\subsubsection}{Device configuration layout}{Device Types / ISM Device / Device configuration layout} > + > +The device MUST ensure that the \field{cdid} of the device on the same > +communication domain is same. > + > +In the single communication domain, the device MUST ensure that the \field{devid} > +is unique. > + > +\subsection{Device Initialization}\label{sec:Device Types / ISM Device / Device Initialization} > + > +\devicenormative{\subsubsection}{Device Initialization}{Device Types / ISM Device / Device Initialization} > + > +The device MUST generate a \field{devid}. \field{devid} remains unchanged > +during reset. \field{devid} MUST NOT be 0. > + > +\drivernormative{\subsubsection}{Device Initialization}{Device Types / ISM Device / Device Initialization} > + > +The driver MUST NOT access any chunk before it is referred by one ism region. > + > +\subsection{Control Virtqueue}\label{sec:Device Types / ISM Device / Control Virtqueue} > + > +The driver uses the control virtqueue to send commands to implement operations > +on the ism region and some global configurations. > + > +All commands are of the following form: > +\begin{lstlisting} > +struct virtio_ism_ctrl { > + u8 class; > + u8 command; > + u8 command_specific_data[]; > + > +#define VIRTIO_ISM_OK 0 > +#define VIRTIO_ISM_ERR 255 > + > +#define VIRTIO_ISM_WAIT_SWAP_BUFF 254 > + > +#define VIRTIO_ISM_ENOENT 2 > +#define VIRTIO_ISM_E2BIG 7 > +#define VIRTIO_ISM_ENOMEM 12 > +#define VIRTIO_ISM_ENOSPEC 28 > + > +#define VIRTIO_ISM_PERM_EATTACH 100 > +#define VIRTIO_ISM_PERM_EREAD 101 > +#define VIRTIO_ISM_PERM_EWRITE 102 > + u8 ack; > + u8 command_specific_data_reply[]; > +}; > + > +\end{lstlisting} > + > +The \field{class}, \field{command} and command-specific-data are set by the > +driver, and the device sets the \field{ack} byte and optionally > +\field{command-specific-data-reply}. > + > +%% device operations > + > +\subsection{Device Operation}\label{sec:Device Types / ISM Driver / Device Operation} > + > +\subsubsection{Alloc ISM Region}\label{sec:Device Types / ISM Device / Device Operation / Alloc ISM Region} > + > +Based on controlq, the driver can request to allocate an ism region. > + > +The reply from the device will carry a token, which can be passed > +to other driver for attaching to this ism region. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_alloc { > + le64 size; > + le64 swap_buffer; > +}; > +\end{lstlisting} > + > +The \field{command_specific_data_reply} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_alloc_reply { > + le64 token; > + le64 num; > + le64 chunks[]; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_ALLOC 0 > + #define VIRTIO_ISM_CTRL_ALLOC_REGION 0 > +\end{lstlisting} > + > + > +\devicenormative{\paragraph}{Alloc ISM Region}{Device Types / ISM Device / Device Operation / Alloc ISM Region} > + > +For the command VIRTIO_ISM_CTRL_ALLOC_REGION, the device MUST look for the > +free chunks from the ism regions area firstly, then maps the physical memory to > +these chunks in order. If there is no enough free chunk, the device MUST set > +\field{ack} to VIRTIO_ISM_NOSPEC. If no physical memory can be allocated by the > +device, the device MUST set \field{ack} to VIRTIO_ISM_NOMEM. > + > +A new token MUST be dynamically created for this ism region simultaneously. The > +token MUST be unique inside this communication domain. And the device MUST fill > +\field{chunks} with the offset of each chunk. \field{num} is the number of the > +chunks. > + > +The device MUST clear the memory of this ism region before committing to the > +driver. > + > +If \field{size} is smaller than \field{chunk_size}, the ism region also > +occupies one chunk. > + > +If \field{virtio_ism_ctrl_alloc_reply} is not enough, the device MUST set the \field{ack} > +to VIRTIO_ISM_E2BIG. > + > +The device sets \field{ack} to VIRTIO_ISM_OK after successfully allocating the > +ism region. > + > +\drivernormative{\paragraph}{Alloc ISM Region}{Device Types / ISM Device / Device Operation / Alloc ISM Region} > + > +The driver MUST provide the swap buffer. The size of the swap buffer MUST equal > +to the size of the ism region that we want to allocate. > + > + > +\subsubsection{Query ISM Region}\label{sec:Device Types / ISM Device / Device Operation / Query ISM Region} > +Based on controlq, the driver can query the information of an ism region. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_query { > + le64 token; > +}; > +\end{lstlisting} > + > +The \field{command_specific_data_reply} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_query_reply { > + le64 size; > + le64 permissions; > + le64 peers; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_QUERY 1 > + #define VIRTIO_ISM_CTRL_QUERY_INFO 0 > +\end{lstlisting} > + > +\devicenormative{\paragraph}{Query ISM Region}{Device Types / ISM Device / Device Operation / Query ISM Region} > + > +If the ism region specified by \field{token} does not exist, the device MUST set > +\field{ack} to VIRTIO_ISM_ENOENT. Otherwise, the device MUST fill the > +\field{size} with the size of the ism region. The device MUST get the > +permissions of this ism region for the device-self, then fill in the > +\field{permissions}. > + > +The device MUST fill the \field{peers} with the number of the peers referring to > +this ism region. (does not include the device that receiving this event) > + > +\subsubsection{Attach ISM Region}\label{sec:Device Types / ISM Device / Device Operation / Attach ISM Region} > + > +Based on controlq, the driver can request to attach an ism region with a > +specified token. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_attach { > + le64 token; > + le64 permissions; > + le64 swap_buffer; > + le64 swap_buffer_size; > +}; > +\end{lstlisting} > + > +The \field{command_specific_data_reply} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_attach_reply { > + le64 size; > + le64 num; > + le64 chunks[]; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_ATTACH 2 > + #define VIRTIO_ISM_CTRL_ATTACH_REGION 0 > +\end{lstlisting} > + > +\devicenormative{\paragraph}{Attach ISM Region}{Device Types / ISM Device / Device Operation / Attach ISM Region} > + > +If the ism region specified by \field{token} does not exist, the device MUST set > +\field{ack} to VIRTIO_ISM_ENOENT. > + > +The device MUST first look for the free chunks from the ism regions area. And > +the physical memory of the ism region is mapped to these chunks in order. If > +there is no enough free chunk, the device MUST set \field{ack} to > +VIRTIO_ISM_NOSPEC. The device MUST fill \field{chunks} with the offset of each > +chunk. \field{num} is the number of the chunks. \field{size} is the size of this > +ism region. > + > +If the device does not have the VIRTIO_ISM_PERM_ATTACH permission for this ism > +region, the device MUST set \field{ack} to VIRTIO_ISM_PERM_EATTACH. If > +\field{permissions} include VIRTIO_ISM_PERM_READ, but the device does not have > +the VIRTIO_ISM_PERM_READ permission for this region, the device MUST set > +\field{ack} to VIRTIO_ISM_PERM_EREAD. If \field{permissions} include > +VIRTIO_ISM_PERM_WRITE, but the device does not have the VIRTIO_ISM_PERM_WRITE > +permission for this region, the device MUST set \field{ack} to > +VIRTIO_ISM_PERM_EWRITE. > + > +The device MUST set the read and write permissions of the physical memory inside > +the ism regions area based on \field{permissions}. > + > +If \field{virtio_ism_ctrl_attach_reply} is not enough or \field{swap_buffer_size} > +is less than the size of the ism region, the device MUST set the > +\field{ack} to VIRTIO_ISM_E2BIG and set the \field{size} for next request. > + > +If the attach operation is successful, the device MUST generate a > +VIRTIO_ISM_EVENT_ATTACH event to other devices and MUST set \field{ack} to > +VIRTIO_ISM_OK. > + > +\drivernormative{\paragraph}{Attach ISM Region}{Device Types / ISM Device / Device Operation / Attach ISM Region} > + > +The driver MUST provide the swap buffer with \field{swap_buffer}. The size of > +the swap buffer MUST equal to the size of the ism region that we want to > +allocate. > + > +If \field{size} is less than \field{num} times \field {chunk_size}, then only > +header part of the last chunk is effective. > + > +If \field{ack} is VIRTIO_ISM_E2BIG, the \field{size} is valid, that this value > +represents the size of the ism region. > + > +\subsubsection{Detach ISM Region}\label{sec:Device Types / ISM Device / Device Operation / Detach ISM Region} > +Based on controlq, the device can release references to the ism region. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_detach { > + le64 token; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_DETACH 3 > + #define VIRTIO_ISM_CTRL_DETACH_REGION 0 > +\end{lstlisting} > + > +\devicenormative{\paragraph}{Detach ISM Region}{Device Types / ISM Device / Device Operation / Detach ISM Region} > + > +If the ism region specified by \field{token} is not attached, the device MUST set > +\field{ack} to VIRTIO_ISM_ENOENT. > + > +If the detach operation is successful, the device MUST generate a > +VIRTIO_ISM_EVENT_DETACH event to other devices. > + > +If no one refers to the swap buffer, the device MUST set the \field{ack} to > +VIRTIO_ISM_OK. If the swap buffer is referred by other device, the device MUST > +set the \field{ack} to VIRTIO_ISM_WAIT_SWAP_BUFF. > + > +If no one refers to the swap buffer, the device that allocated this ism region > +MUST generate a VIRTIO_ISM_EVENT_SWAPBUF_RELEASE event to the driver. > + > +\drivernormative{\paragraph}{Detach ISM Region}{Device Types / ISM Device / Device Operation / Detach ISM Region} > + > +If the \field{ack} is VIRTIO_ISM_OK, the swap buffer is free. > +If the \field{ack} is VIRTIO_ISM_WAIT_SWAP_BUFF, the driver MUST NOT access the > +swap buffer until it receives the VIRTIO_ISM_EVENT_SWAPBUF_RELEASE event. > + > +\subsubsection{Grant ISM Region}\label{sec:Device Types / ISM Device / Device Operation / Grant ISM Region} > +Based on controlq, the driver can set the permissions for each ism > +region. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_grant_default { > + le64 token; > + > +#define VIRTIO_ISM_PERM_READ (1 << 0) > +#define VIRTIO_ISM_PERM_WRITE (1 << 1) > +#define VIRTIO_ISM_PERM_ATTACH (1 << 2) > +#define VIRTIO_ISM_PERM_MANAGE (1 << 3) > + le64 permissions; > +}; > + > +struct virtio_ism_ctrl_grant_dev { > + le64 token; > + le64 permissions; > + le64 peer_devid; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_GRANT 4 > + #define VIRTIO_ISM_CTRL_GRANT_SET_DEFAULT 0 > + #define VIRTIO_ISM_CTRL_GRANT_SET_FOR_DEVICE 1 > +\end{lstlisting} > + > +\begin{description} > +\item[VIRTIO_ISM_PERM_READ] read permission > +\item[VIRTIO_ISM_PERM_WRITE] write permission > +\item[VIRTIO_ISM_PERM_ATTACH] attach permission > +\item[VIRTIO_ISM_PERM_MANAGE] management permission, the device with this > + permission can modify the permission of this ism region. By default, only > + the device that allocated the region has this permission. > +\end{description} > + > +VIRTIO_ISM_CTRL_GRANT_SET_DEFAULT corresponds to virtio_ism_ctrl_grant_default; > +VIRTIO_ISM_CTRL_GRANT_SET_FOR_DEVICE corresponds to virtio_ism_ctrl_grant_dev; > + > +Permission control is divided into two categories, one is the dedicated > +permissions for a certain device, and the other is the default permissions for > +all device. > + > +\devicenormative{\paragraph}{Grant ISM Region}{Device Types / ISM Device / Device Operation / Grant ISM Region} > + > +If the ism region specified by \field{token} is not attached, the device MUST set > +\field{ack} to VIRTIO_ISM_ENOENT. > + > +The default permissions of the newly allocated ism region MUST be (VIRTIO_ISM_PERM_READ | VIRTIO_ISM_PERM_WRITE | VIRTIO_ISM_PERM_ATTACH). > +The device that allocated the ism region MUST have the permissions (VIRTIO_ISM_PERM_READ | VIRTIO_ISM_PERM_WRITE | VIRTIO_ISM_PERM_ATTACH | VIRTIO_ISM_PERM_MANAGE) for this region. > + > +For a certain device, if there is dedicated permissions, the default > +permissions are illegal to this device. > + > +\subsubsection{Inform Update Event IRQ Vector}\label{sec:Device Types / ISM Device / Device Operation / Inform Update Event IRQ Vector} > + > +The update event is a frequent event, and eventq is a relatively slow form. The > +driver can assign an independent interrupt to the ism region. Then this ism > +region's update event will no longer receive from the eventq, but the interrupt > +will be directly triggered. > + > +The \field{command_specific_data} has the following format: > +\begin{lstlisting} > +struct virtio_ism_ctrl_irq_vector { > + le64 token; > + le64 vector; > +}; > +\end{lstlisting} > + > +The \field{class} and \field{command}: > +\begin{lstlisting} > +#define VIRTIO_ISM_CTRL_EVENT_VECTOR 5 > + #define VIRTIO_ISM_CTRL_EVENT_VECTOR_SET 0 > +\end{lstlisting} > + > +\devicenormative{\paragraph}{Inform Event IRQ Vector}{Device Types / ISM Device / Device Operation / Inform Event IRQ Vector} > + > +The device MUST record the vector of this ism region, and MUST notify the update > +event of this ism region to the driver by triggering an interrupt by this vector. > + > + > diff --git a/device-types/ism/device-conformance.tex b/device-types/ism/device-conformance.tex > new file mode 100644 > index 0000000..f2bef5c > --- /dev/null > +++ b/device-types/ism/device-conformance.tex > @@ -0,0 +1,17 @@ > +\conformance{\subsection}{ISM Device Conformance}\label{sec:Conformance / Device Conformance / ISM Device Conformance} > + > +A ISM device MUST conform to the following normative statements: > + > +\begin{itemize} > +\item \ref{devicenormative:Device Types / ISM Device / Communication Domain} > +\item \ref{devicenormative:Device Types / ISM Device / Memory / Swap Buffer} > +\item \ref{devicenormative:Device Types / ISM Device / Memory / Chunk And ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device configuration layout} > +\item \ref{devicenormative:Device Types / ISM Device / Device Initialization} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Alloc ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Query ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Attach ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Detach ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Grant ISM Region} > +\item \ref{devicenormative:Device Types / ISM Device / Device Operation / Inform Event IRQ Vector} > +\end{itemize} > diff --git a/device-types/ism/driver-conformance.tex b/device-types/ism/driver-conformance.tex > new file mode 100644 > index 0000000..2cb5d76 > --- /dev/null > +++ b/device-types/ism/driver-conformance.tex > @@ -0,0 +1,13 @@ > +\conformance{\subsection}{ISM Driver Conformance}\label{sec:Conformance / Driver Conformance / ISM Driver Conformance} > + > +A ISM driver MUST conform to the following normative statements: > + > +\begin{itemize} > +\item \ref{drivernormative:Device Types / ISM Device / Memory / Swap Buffer} > +\item \ref{drivernormative:Device Types / ISM Device / Event} > +\item \ref{drivernormative:Device Types / ISM Device / Device Initialization} > +\item \ref{drivernormative:Device Types / ISM Device / Device Operation / Alloc ISM Region} > +\item \ref{drivernormative:Device Types / ISM Device / Device Operation / Attach ISM Region} > +\item \ref{drivernormative:Device Types / ISM Device / Device Operation / Detach ISM Region} > +\end{itemize} > + > diff --git a/device-types/ism/layout-pic.tex b/device-types/ism/layout-pic.tex > new file mode 100644 > index 0000000..c40aa79 > --- /dev/null > +++ b/device-types/ism/layout-pic.tex > @@ -0,0 +1,112 @@ > +\begin{tikzpicture} > +\definecolor{rg1}{RGB}{153,210,160} > +\definecolor{rg2}{RGB}{206,219,188} > +\definecolor{rg3}{RGB}{210,204,165} > +% vm A > + \node[block,text width=10cm,align=left] (driverA) {virtio-ism driver}; > + > + \node[block,above=of driverA.north east,text width=2cm,anchor=east,fill=rg3] (M3A) {region M3}; > + \node[block,left=of M3A,text width=2cm,fill=rg2] (M2A) {region M2}; > + \node[block,left=of M2A.north west,anchor=south east,yshift=1cm,text width=2cm,fill=rg1] (M1A) {region M1}; > + > + \node[draw,inner xsep=4mm,inner ysep=7mm,fit=(driverA)(M1A)(M2A)(M3A), > + draw=blue!80,line width=0.5mm,label={100:Guest A}](vmA){}; > + > +% device A > + \node[block,below=of driverA.south west, yshift=-1cm, xshift=1cm, > + anchor=north west,text width=2cm] (deviceCoreA) {device core}; > + > + \node[right=of deviceCoreA,name=block,rectangle split,rectangle split horizontal, > + rectangle split parts=4,draw,label=below:{device memory}] (deviceMemA) > + { > + \nodepart{one} chunk > + \nodepart{two} chunk > + \nodepart{three} chunk > + \nodepart{four} chunk > + }; > + > + \node[draw,inner xsep=4mm,inner ysep=7mm,fit=(deviceMemA)(deviceCoreA), > + draw=green!80,line width=0.5mm,label={225:virtio-ism device A}](deviceA){}; > + > +% lines A > + \draw[line] (deviceMemA.four north) -- (M1A); > + \draw[line] (deviceMemA.two north) -- (M1A); > + \draw[line] (deviceMemA.three north)-- (M2A); > + \draw[line] (deviceMemA.one north) -- (M3A); > + > + \draw[-] ($(vmA.north west) + (0, -2.5cm)$) node[above=2pt, anchor=south west] {user space} > + node[below=5pt, anchor=north west] {kernel space}-- ($(vmA.north east) + (0, -2.5cm)$); > + > + \draw[line] (deviceCoreA.north west)-- node[above=1pt,sloped] {control vq} ($(driverA.south west) + (1.1cm,0)$); > + \draw[line] (deviceCoreA.north) -- node[below=1pt,sloped] {event vq} ($(driverA.south west) + (2.2cm,0)$); > + > +% vm B > + \node[block,text width=10cm,align=right,right=of driverA] (driverB) {virtio-ism driver}; > + > + \node[block,above=of driverB.north west,text width=2cm, anchor=west,fill=rg3] (M3B) {region M3}; > + \node[block,right=of M3B.north east,anchor=south west,yshift=1cm,text > + width=2cm,fill=rg1] (M1B) {region M1}; > + > + \node[draw,inner xsep=4mm,inner ysep=7mm,fit=(driverB)(M1B)(M3B), > + draw=blue!80,line width=0.5mm,label={100:Guest B}](vmB){}; > + > + > +% device B > + > + \node[block, below=of driverB.south east, yshift=-1cm, xshift=-1cm, > + anchor=north east,text width=2cm] (deviceCoreB) {device core}; > + > + \node[left=of deviceCoreB,name=block,rectangle split,rectangle split horizontal, > + rectangle split parts=4,draw,label=below:{device memory}] (deviceMemB) > + { > + \nodepart{one} chunk > + \nodepart{two} chunk > + \nodepart{three} chunk > + }; > + > + \node[draw,inner xsep=4mm,inner ysep=7mm,fit=(deviceMemB)(deviceCoreB), > + draw=green!80,line width=0.5mm,label={305:virtio-ism device B}](deviceB){}; > + > +% lines B > + > + \draw[line] (deviceMemB.one north) -- (M1B); > + \draw[line] (deviceMemB.two north) -- (M1B); > + \draw[line] (deviceMemB.three north)-- (M3B); > + > + \draw[-] ($(vmB.north west) + (0, -2.5cm)$) -- ($(vmB.north east) + (0, -2.5cm)$) > +node[anchor=south east] {user space} > + node[anchor=north east] {kernel space} > + ; > + > + \draw[line] (deviceCoreB.north west)-- node[above=1pt,sloped] {control vq} ($(driverB.south east) - (2.2cm,0)$); > + \draw[line] (deviceCoreB.north) -- node[below=1pt,sloped] {event vq} ($(driverB.south east) - (1.1cm,0)$); > + > +% host memory > + \node[right=of deviceA.north east,anchor=north west,name=block,rectangle split, > + rectangle split parts=10, draw,label=below:{host memory}] (HostMem) > + { > + \nodepart{one} chunk > + \nodepart{two} chunk > + \nodepart{three} chunk > + \nodepart{four} chunk > + \nodepart{five} chunk > + \nodepart{six} chunk > + \nodepart{seven} chunk > + \nodepart{eight} chunk > + \nodepart{nine} chunk > + \nodepart{ten} chunk > + }; > + > + \draw[line] (HostMem.seven east) -| (deviceMemB.one south); > + \draw[line] (HostMem.eight east)-| (deviceMemB.two south); > + \draw[line] (HostMem.ten east)-| (deviceMemB.three south); > + > + \draw[line] (HostMem.seven west)-| (deviceMemA.two south); > + \draw[line] (HostMem.eight west)-| (deviceMemA.four south); > + \draw[line] (HostMem.nine west)-| (deviceMemA.three south); > + \draw[line] (HostMem.ten west)-| (deviceMemA.one south); > + > + \node[draw,inner xsep=4mm,inner ysep=7mm,fit=(deviceA)(vmA)(deviceB)(vmB) > + (HostMem),draw=cyan,line width=0.5mm,label=below:{Host}](host){}; > + > +\end{tikzpicture} > diff --git a/virtio-html.tex b/virtio-html.tex > index c822a99..17c1639 100644 > --- a/virtio-html.tex > +++ b/virtio-html.tex > @@ -32,6 +32,15 @@ > \usepackage{underscore} > \usepackage{xstring} > \usepackage{chngcntr} > + > +%config tikz > +\usepackage{tikz} > +\usetikzlibrary{shapes,positioning,fit,calc} > +\tikzset{block/.style={draw, thick, text width=3cm, minimum height=1cm, align=center}, > +line/.style={-latex}, > +} > +%end of config tikz > + > \counterwithout{footnote}{chapter} > > \usepackage[utf8x]{inputenc} > diff --git a/virtio.tex b/virtio.tex > index a99bb3f..ffd2bf3 100644 > --- a/virtio.tex > +++ b/virtio.tex > @@ -37,6 +37,15 @@ > \usepackage{tabularx} > \usepackage{underscore} > \usepackage{xstring} > + > +%config tikz > +\usepackage{tikz} > +\usetikzlibrary{shapes,positioning,fit,calc} > +\tikzset{block/.style={draw, thick, text width=3cm, minimum height=1cm, align=center}, > +line/.style={-latex}, > +} > +%end of config tikz > + > \IfFileExists{ellipsis.sty}{\usepackage{ellipsis}}{ > \message{!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!} > \message{LaTeX Warning: Missing ellipsis.sty: dots (...) will look ugly} > -- > 2.32.0.3.g01195cf9f >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]