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
9 said memory to the guest as a PCI BAR.
11 The device can use a shared memory object on the host directly, or it
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,
38   you have access to the shared memory in the guest and can use it as
41 - If you additionally need the capability for peers to interrupt each
48 the ivshmem server provided the shared memory.  These devices have PCI
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
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
131 addition to shared memory.  The shared resources are managed by an
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,
196 3. The number -1, accompanied by the file descriptor for the shared
197    memory.
203    vector 0,..,N-1, in order.  If the client is configured for fewer
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.
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