Revised the spec to clean up a straggling mention of callbacks, and added a concrete example of how it would be used for a video codec.
\subsection{Example Use Case}\label{sec:Device Types / Host Memory Device / Example Use Case}
Suppose the guest wants to decode a compressed video buffer.
\begin{enumerate}
\item Guest creates an instance for the codec vendor id / device id / revision.
\item Guest allocates into the PCI region via config virtqueue messages.
\item Guest sends a message over the ping virtqueue for the host to back that memory.
\item Host codec device implementation exposes codec library's buffer directly to guest.
\item Guest: now that the memory is host backed, the guest mmap()'s and
downloads the compressed video stream directly to the host buffer.
\item Guest: After a packet of compressed video stream is downloaded to the
buffer, another message, like a doorbell, is sent on the ping virtqueue to
consume existing compressed data. The ping message's offset field is
set to the proper offset into the shared-mem object.
\item Host: The ping message arrives on the host and the offset is resolved to
a physical address and then, if possible, the physical address to a host
pointer. Since the memory is now backed, the host pointer is also
resolved.
\item Host: Codec implementation decodes the video and puts the decoded frames
to either a host-side display library (thus with no further guest
communication necessary), or puts the raw decompressed frame to a
further offset in the host buffer that the guest knows about.
\item Guest: Continue downloading video streams and hitting the doorbell, or
optionally, wait until the host is done first. If scheduling is not that
big of an impact, this can be done without even any further VM exit, by
the host writing to an agreed memory location when decoding is done,
then the guest uses a polling sleep(N) where N is the correctly tuned
timeout such that only a few poll spins are necessary.
\item Guest: Or, the host can send back on the event virtqueue \field{revents}
and the guest can perform a blocking read() for it.
\end{enumerate}
The unique / interesting aspects of virtio-hostmem are demonstrated:
\begin{enumerate}
\item During instance creation the host was allowed to reject the request if
the codec device did not exist on host.
\item The host can expose a codec library buffer directly to the guest, allowing the guest to write into it with zero copy and the host to decompress again without copying.
\item Large bidirectional transfers are possible with zero copy.
\item Large bidirectional transfers are possible without scatterlists, because
the memory is always physically contiguous.
\item It is not necessary to use socket datagrams or data streams to
communicate the ping messages; they can be raw structs fresh off the
virtqueue.
\item After decoding, the guest has the option but not the requirement to wait
for the host round trip, allowing for async operation of the codec.
\item The guest has the option but not the requirement to wait for the host
round trip, allowing for async operation of the codec.
\end{enumerate}