linux-user: Add support for btrfs ioctls used to manage quota
[qemu.git] / 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.
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.