docs/specs/ivshmem-spec.rst

5 The Inter-VM shared memory device (ivshmem) is designed to share a
7 and the host.  In order for all guests to be able to pick up the
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
14 In the latter case, the device can additionally interrupt its peers, and
17 For information on configuring the ivshmem device on the QEMU
20 The ivshmem PCI device's guest interface
23 The device has vendor ID 1af4, device ID 1110, revision 1.  Before
29 The ivshmem PCI device has two or three BARs:
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
43   kernel driver to handle interrupts.  Requires the device to be
46 Before QEMU 2.6.0, BAR2 can initially be invalid if the device is
48 the ivshmem server provided the shared memory.  These devices have PCI
49 revision 0 rather than 1.  Guest software should wait for the
53 Revision 0 of the device is not capable to tell guest software whether
59 BAR 0 contains the following registers:
78 Software should only access the registers as specified in column
82 In revision 0 of the device, Interrupt Status and Mask Register
83 together control the legacy INTx interrupt when the device has no
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
87 is received.  Reading the register clears it.
89 IVPosition Register: if the device is not configured for interrupts,
90 this is zero.  Else, it is the device's ID (between 0 and 65535).
92 Before QEMU 2.6.0, the register may read -1 for a short while after
95 There is no good way for software to find out whether the device is
100 The written value's high 16 bits are the ID of the peer to interrupt,
103 If the device is not configured for interrupts, the write is ignored.
105 If the interrupt hasn't completed setup, the write is ignored.  The
109 If the peer with the requested ID isn't connected, or it has fewer
110 interrupt vectors connected, the write is ignored.  The device is not
114 The peer's interrupt for this vector then becomes pending.  There is
115 no way for software to clear the pending bit, and a polling mode of
118 If the peer is a revision 0 device without MSI-X capability, its
120 masked by the Interrupt Mask register.  The device is not capable to
121 communicate the interrupt vector to guest software then.
124 different events have occurred.  The semantics of interrupt vectors
125 are left to the application.
130 When configured for interrupts, the peers share eventfd objects in
131 addition to shared memory.  The shared resources are managed by an
134 The ivshmem server
137 The server listens on a UNIX domain socket.
139 For each new client that connects to the server, the server
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
152 The first client to connect to the server receives ID zero.
154 When a client disconnects from the server, the server sends disconnect
155 notifications to the other clients.
157 The next section describes the protocol in detail.
159 If the server terminates without sending disconnect notifications for
160 its connected clients, the clients can elect to continue.  They can
163 no way for the clients to connect to a restarted server.  The device
164 is not capable to tell guest software whether the server is still up.
167 production.  It assumes all clients use the same number of interrupt
173 The ivshmem Client-Server Protocol
177 server.  This section details the protocol between the two.
179 The connection is one-way: the server sends messages to the client.
182 client and server close the connection on error.
184 Note: QEMU currently doesn't close the connection right on error, but
185 only when the character device is destroyed.
187 On connect, the server sends the following messages in order:
189 1. The protocol version number, currently zero.  The client should
190    close the connection on receipt of versions it can't handle.
192 2. The client's ID.  This is unique among all clients of this server.
193    IDs must be between 0 and 65535, because the Doorbell register
196 3. The number -1, accompanied by the file descriptor for the shared
200    a peer ID (number between 0 and 65535 other than the client's ID),
202    descriptor.  These are for interrupting the peer with that ID using
203    vector 0,..,N-1, in order.  If the client is configured for fewer
204    vectors, it closes the extra file descriptors.  If it is configured
205    for more, the extra vectors remain unconnected.
207 5. Interrupt setup.  This is the client's own ID, repeated N times.
210    order.  If the client is configured for fewer vectors, it closes
211    the extra file descriptors.  If it is configured for more, the
214 From then on, the server sends these kinds of messages:
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
228 * The protocol is poorly designed.
230 The ivshmem Client-Client Protocol
235 from the server, as explained in the previous section.
237 To interrupt a peer, the device writes the 8-byte integer 1 in native
238 byte order to the respective file descriptor.
240 To receive an interrupt, the device reads and discards as many 8-byte