Merge remote-tracking branch 'remotes/kevin/tags/for-upstream' into staging
[qemu.git] / docs / specs / ivshmem_device_spec.txt
1
2 Device Specification for Inter-VM shared memory device
3 ------------------------------------------------------
4
5 The Inter-VM shared memory device is designed to share a region of memory to
6 userspace in multiple virtual guests.  The memory region does not belong to any
7 guest, but is a POSIX memory object on the host.  Optionally, the device may
8 support sending interrupts to other guests sharing the same memory region.
9
10
11 The Inter-VM PCI device
12 -----------------------
13
14 *BARs*
15
16 The device supports three BARs.  BAR0 is a 1 Kbyte MMIO region to support
17 registers.  BAR1 is used for MSI-X when it is enabled in the device.  BAR2 is
18 used to map the shared memory object from the host.  The size of BAR2 is
19 specified when the guest is started and must be a power of 2 in size.
20
21 *Registers*
22
23 The device currently supports 4 registers of 32-bits each.  Registers
24 are used for synchronization between guests sharing the same memory object when
25 interrupts are supported (this requires using the shared memory server).
26
27 The server assigns each VM an ID number and sends this ID number to the QEMU
28 process when the guest starts.
29
30 enum ivshmem_registers {
31     IntrMask = 0,
32     IntrStatus = 4,
33     IVPosition = 8,
34     Doorbell = 12
35 };
36
37 The first two registers are the interrupt mask and status registers.  Mask and
38 status are only used with pin-based interrupts.  They are unused with MSI
39 interrupts.
40
41 Status Register: The status register is set to 1 when an interrupt occurs.
42
43 Mask Register: The mask register is bitwise ANDed with the interrupt status
44 and the result will raise an interrupt if it is non-zero.  However, since 1 is
45 the only value the status will be set to, it is only the first bit of the mask
46 that has any effect.  Therefore interrupts can be masked by setting the first
47 bit to 0 and unmasked by setting the first bit to 1.
48
49 IVPosition Register: The IVPosition register is read-only and reports the
50 guest's ID number.  The guest IDs are non-negative integers.  When using the
51 server, since the server is a separate process, the VM ID will only be set when
52 the device is ready (shared memory is received from the server and accessible via
53 the device).  If the device is not ready, the IVPosition will return -1.
54 Applications should ensure that they have a valid VM ID before accessing the
55 shared memory.
56
57 Doorbell Register:  To interrupt another guest, a guest must write to the
58 Doorbell register.  The doorbell register is 32-bits, logically divided into
59 two 16-bit fields.  The high 16-bits are the guest ID to interrupt and the low
60 16-bits are the interrupt vector to trigger.  The semantics of the value
61 written to the doorbell depends on whether the device is using MSI or a regular
62 pin-based interrupt.  In short, MSI uses vectors while regular interrupts set the
63 status register.
64
65 Regular Interrupts
66
67 If regular interrupts are used (due to either a guest not supporting MSI or the
68 user specifying not to use them on startup) then the value written to the lower
69 16-bits of the Doorbell register results is arbitrary and will trigger an
70 interrupt in the destination guest.
71
72 Message Signalled Interrupts
73
74 A ivshmem device may support multiple MSI vectors.  If so, the lower 16-bits
75 written to the Doorbell register must be between 0 and the maximum number of
76 vectors the guest supports.  The lower 16 bits written to the doorbell is the
77 MSI vector that will be raised in the destination guest.  The number of MSI
78 vectors is configurable but it is set when the VM is started.
79
80 The important thing to remember with MSI is that it is only a signal, no status
81 is set (since MSI interrupts are not shared).  All information other than the
82 interrupt itself should be communicated via the shared memory region.  Devices
83 supporting multiple MSI vectors can use different vectors to indicate different
84 events have occurred.  The semantics of interrupt vectors are left to the
85 user's discretion.
86
87
88 Usage in the Guest
89 ------------------
90
91 The shared memory device is intended to be used with the provided UIO driver.
92 Very little configuration is needed.  The guest should map BAR0 to access the
93 registers (an array of 32-bit ints allows simple writing) and map BAR2 to
94 access the shared memory region itself.  The size of the shared memory region
95 is specified when the guest (or shared memory server) is started.  A guest may
96 map the whole shared memory region or only part of it.