docs/specs/ivshmem-spec.txt

   1 = Device Specification for Inter-VM shared memory device =
   2
   3 The Inter-VM shared memory device (ivshmem) is designed to share a
   4 memory region between multiple QEMU processes running different guests
   5 and the host.  In order for all guests to be able to pick up the
   6 shared memory area, it is modeled by QEMU as a PCI device exposing
   7 said memory to the guest as a PCI BAR.
   8
   9 The device can use a shared memory object on the host directly, or it
  10 can obtain one from an ivshmem server.
  11
  12 In the latter case, the device can additionally interrupt its peers, and
  13 get interrupted by its peers.
  14
  15
  16 == Configuring the ivshmem PCI device ==
  17
  18 There are two basic configurations:
  19
  20 - Just shared memory:
  21
  22       -device ivshmem-plain,memdev=HMB,...
  23
  24   This uses host memory backend HMB.  It should have option "share"
  25   set.
  26
  27 - Shared memory plus interrupts:
  28
  29       -device ivshmem-doorbell,chardev=CHR,vectors=N,...
  30
  31   An ivshmem server must already be running on the host.  The device
  32   connects to the server's UNIX domain socket via character device
  33   CHR.
  34
  35   Each peer gets assigned a unique ID by the server.  IDs must be
  36   between 0 and 65535.
  37
  38   Interrupts are message-signaled (MSI-X).  vectors=N configures the
  39   number of vectors to use.
  40
  41 For more details on ivshmem device properties, see The QEMU Emulator
  42 User Documentation (qemu-doc.*).
  43
  44
  45 == The ivshmem PCI device's guest interface ==
  46
  47 The device has vendor ID 1af4, device ID 1110, revision 1.  Before
  48 QEMU 2.6.0, it had revision 0.
  49
  50 === PCI BARs ===
  51
  52 The ivshmem PCI device has two or three BARs:
  53
  54 - BAR0 holds device registers (256 Byte MMIO)
  55 - BAR1 holds MSI-X table and PBA (only ivshmem-doorbell)
  56 - BAR2 maps the shared memory object
  57
  58 There are two ways to use this device:
  59
  60 - If you only need the shared memory part, BAR2 suffices.  This way,
  61   you have access to the shared memory in the guest and can use it as
  62   you see fit.  Memnic, for example, uses ivshmem this way from guest
  63   user space (see http://dpdk.org/browse/memnic).
  64
  65 - If you additionally need the capability for peers to interrupt each
  66   other, you need BAR0 and BAR1.  You will most likely want to write a
  67   kernel driver to handle interrupts.  Requires the device to be
  68   configured for interrupts, obviously.
  69
  70 Before QEMU 2.6.0, BAR2 can initially be invalid if the device is
  71 configured for interrupts.  It becomes safely accessible only after
  72 the ivshmem server provided the shared memory.  These devices have PCI
  73 revision 0 rather than 1.  Guest software should wait for the
  74 IVPosition register (described below) to become non-negative before
  75 accessing BAR2.
  76
  77 Revision 0 of the device is not capable to tell guest software whether
  78 it is configured for interrupts.
  79
  80 === PCI device registers ===
  81
  82 BAR 0 contains the following registers:
  83
  84     Offset  Size  Access      On reset  Function
  85         0     4   read/write        0   Interrupt Mask
  86                                         bit 0: peer interrupt (rev 0)
  87                                                reserved       (rev 1)
  88                                         bit 1..31: reserved
  89         4     4   read/write        0   Interrupt Status
  90                                         bit 0: peer interrupt (rev 0)
  91                                                reserved       (rev 1)
  92                                         bit 1..31: reserved
  93         8     4   read-only   0 or ID   IVPosition
  94        12     4   write-only      N/A   Doorbell
  95                                         bit 0..15: vector
  96                                         bit 16..31: peer ID
  97        16   240   none            N/A   reserved
  98
  99 Software should only access the registers as specified in column
 100 "Access".  Reserved bits should be ignored on read, and preserved on
 101 write.
 102
 103 In revision 0 of the device, Interrupt Status and Mask Register
 104 together control the legacy INTx interrupt when the device has no
 105 MSI-X capability: INTx is asserted when the bit-wise AND of Status and
 106 Mask is non-zero and the device has no MSI-X capability.  Interrupt
 107 Status Register bit 0 becomes 1 when an interrupt request from a peer
 108 is received.  Reading the register clears it.
 109
 110 IVPosition Register: if the device is not configured for interrupts,
 111 this is zero.  Else, it is the device's ID (between 0 and 65535).
 112
 113 Before QEMU 2.6.0, the register may read -1 for a short while after
 114 reset.  These devices have PCI revision 0 rather than 1.
 115
 116 There is no good way for software to find out whether the device is
 117 configured for interrupts.  A positive IVPosition means interrupts,
 118 but zero could be either.
 119
 120 Doorbell Register: writing this register requests to interrupt a peer.
 121 The written value's high 16 bits are the ID of the peer to interrupt,
 122 and its low 16 bits select an interrupt vector.
 123
 124 If the device is not configured for interrupts, the write is ignored.
 125
 126 If the interrupt hasn't completed setup, the write is ignored.  The
 127 device is not capable to tell guest software whether setup is
 128 complete.  Interrupts can regress to this state on migration.
 129
 130 If the peer with the requested ID isn't connected, or it has fewer
 131 interrupt vectors connected, the write is ignored.  The device is not
 132 capable to tell guest software what peers are connected, or how many
 133 interrupt vectors are connected.
 134
 135 The peer's interrupt for this vector then becomes pending.  There is
 136 no way for software to clear the pending bit, and a polling mode of
 137 operation is therefore impossible.
 138
 139 If the peer is a revision 0 device without MSI-X capability, its
 140 Interrupt Status register is set to 1.  This asserts INTx unless
 141 masked by the Interrupt Mask register.  The device is not capable to
 142 communicate the interrupt vector to guest software then.
 143
 144 With multiple MSI-X vectors, different vectors can be used to indicate
 145 different events have occurred.  The semantics of interrupt vectors
 146 are left to the application.
 147
 148
 149 == Interrupt infrastructure ==
 150
 151 When configured for interrupts, the peers share eventfd objects in
 152 addition to shared memory.  The shared resources are managed by an
 153 ivshmem server.
 154
 155 === The ivshmem server ===
 156
 157 The server listens on a UNIX domain socket.
 158
 159 For each new client that connects to the server, the server
 160 - picks an ID,
 161 - creates eventfd file descriptors for the interrupt vectors,
 162 - sends the ID and the file descriptor for the shared memory to the
 163   new client,
 164 - sends connect notifications for the new client to the other clients
 165   (these contain file descriptors for sending interrupts),
 166 - sends connect notifications for the other clients to the new client,
 167   and
 168 - sends interrupt setup messages to the new client (these contain file
 169   descriptors for receiving interrupts).
 170
 171 The first client to connect to the server receives ID zero.
 172
 173 When a client disconnects from the server, the server sends disconnect
 174 notifications to the other clients.
 175
 176 The next section describes the protocol in detail.
 177
 178 If the server terminates without sending disconnect notifications for
 179 its connected clients, the clients can elect to continue.  They can
 180 communicate with each other normally, but won't receive disconnect
 181 notification on disconnect, and no new clients can connect.  There is
 182 no way for the clients to connect to a restarted server.  The device
 183 is not capable to tell guest software whether the server is still up.
 184
 185 Example server code is in contrib/ivshmem-server/.  Not to be used in
 186 production.  It assumes all clients use the same number of interrupt
 187 vectors.
 188
 189 A standalone client is in contrib/ivshmem-client/.  It can be useful
 190 for debugging.
 191
 192 === The ivshmem Client-Server Protocol ===
 193
 194 An ivshmem device configured for interrupts connects to an ivshmem
 195 server.  This section details the protocol between the two.
 196
 197 The connection is one-way: the server sends messages to the client.
 198 Each message consists of a single 8 byte little-endian signed number,
 199 and may be accompanied by a file descriptor via SCM_RIGHTS.  Both
 200 client and server close the connection on error.
 201
 202 Note: QEMU currently doesn't close the connection right on error, but
 203 only when the character device is destroyed.
 204
 205 On connect, the server sends the following messages in order:
 206
 207 1. The protocol version number, currently zero.  The client should
 208    close the connection on receipt of versions it can't handle.
 209
 210 2. The client's ID.  This is unique among all clients of this server.
 211    IDs must be between 0 and 65535, because the Doorbell register
 212    provides only 16 bits for them.
 213
 214 3. The number -1, accompanied by the file descriptor for the shared
 215    memory.
 216
 217 4. Connect notifications for existing other clients, if any.  This is
 218    a peer ID (number between 0 and 65535 other than the client's ID),
 219    repeated N times.  Each repetition is accompanied by one file
 220    descriptor.  These are for interrupting the peer with that ID using
 221    vector 0,..,N-1, in order.  If the client is configured for fewer
 222    vectors, it closes the extra file descriptors.  If it is configured
 223    for more, the extra vectors remain unconnected.
 224
 225 5. Interrupt setup.  This is the client's own ID, repeated N times.
 226    Each repetition is accompanied by one file descriptor.  These are
 227    for receiving interrupts from peers using vector 0,..,N-1, in
 228    order.  If the client is configured for fewer vectors, it closes
 229    the extra file descriptors.  If it is configured for more, the
 230    extra vectors remain unconnected.
 231
 232 From then on, the server sends these kinds of messages:
 233
 234 6. Connection / disconnection notification.  This is a peer ID.
 235
 236   - If the number comes with a file descriptor, it's a connection
 237     notification, exactly like in step 4.
 238
 239   - Else, it's a disconnection notification for the peer with that ID.
 240
 241 Known bugs:
 242
 243 * The protocol changed incompatibly in QEMU 2.5.  Before, messages
 244   were native endian long, and there was no version number.
 245
 246 * The protocol is poorly designed.
 247
 248 === The ivshmem Client-Client Protocol ===
 249
 250 An ivshmem device configured for interrupts receives eventfd file
 251 descriptors for interrupting peers and getting interrupted by peers
 252 from the server, as explained in the previous section.
 253
 254 To interrupt a peer, the device writes the 8-byte integer 1 in native
 255 byte order to the respective file descriptor.
 256
 257 To receive an interrupt, the device reads and discards as many 8-byte
 258 integers as it can.