docs/specs/ivshmem-spec.rst

2 Device Specification for Inter-VM shared memory device
5 The Inter-VM shared memory device (ivshmem) is designed to share a
6 memory region between multiple QEMU processes running different guests
8 shared memory area, it is modeled by QEMU as a PCI device exposing
17 For information on configuring the ivshmem device on the QEMU
24 QEMU 2.6.0, it had revision 0.
27 --------
31 - BAR0 holds device registers (256 Byte MMIO)
32 - BAR1 holds MSI-X table and PBA (only ivshmem-doorbell)
33 - BAR2 maps the shared memory object
37 - If you only need the shared memory part, BAR2 suffices.  This way,
41 - If you additionally need the capability for peers to interrupt each
46 Before QEMU 2.6.0, BAR2 can initially be invalid if the device is
50 IVPosition register (described below) to become non-negative before
57 --------------------
72         8     4   read-only   0 or ID   IVPosition
73        12     4   write-only      N/A   Doorbell
84 MSI-X capability: INTx is asserted when the bit-wise AND of Status and
85 Mask is non-zero and the device has no MSI-X capability.  Interrupt
92 Before QEMU 2.6.0, the register may read -1 for a short while after
105 If the interrupt hasn't completed setup, the write is ignored.  The
106 device is not capable to tell guest software whether setup is
118 If the peer is a revision 0 device without MSI-X capability, its
123 With multiple MSI-X vectors, different vectors can be used to indicate
135 ------------------
141 - picks an ID,
142 - creates eventfd file descriptors for the interrupt vectors,
143 - sends the ID and the file descriptor for the shared memory to the
145 - sends connect notifications for the new client to the other clients
147 - sends connect notifications for the other clients to the new client,
149 - sends interrupt setup messages to the new client (these contain file
166 Example server code is in contrib/ivshmem-server/.  Not to be used in
170 A standalone client is in contrib/ivshmem-client/.  It can be useful
173 The ivshmem Client-Server Protocol
174 ----------------------------------
179 The connection is one-way: the server sends messages to the client.
180 Each message consists of a single 8 byte little-endian signed number,
184 Note: QEMU currently doesn't close the connection right on error, but
196 3. The number -1, accompanied by the file descriptor for the shared
203    vector 0,..,N-1, in order.  If the client is configured for fewer
207 5. Interrupt setup.  This is the client's own ID, repeated N times.
209    for receiving interrupts from peers using vector 0,..,N-1, in
218   - If the number comes with a file descriptor, it's a connection
221   - Else, it's a disconnection notification for the peer with that ID.
225 * The protocol changed incompatibly in QEMU 2.5.  Before, messages
230 The ivshmem Client-Client Protocol
231 ----------------------------------
237 To interrupt a peer, the device writes the 8-byte integer 1 in native
240 To receive an interrupt, the device reads and discards as many 8-byte