Add some notes on the parts needed to use ivshmem devices: more specifically, explain the purpose of an ivshmem server and the basic concept to use the ivshmem devices in guests. Signed-off-by: David Marchand <david.marchand@xxxxxxxxx> --- docs/specs/ivshmem_device_spec.txt | 41 ++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/specs/ivshmem_device_spec.txt b/docs/specs/ivshmem_device_spec.txt index 667a862..7d2b73f 100644 --- a/docs/specs/ivshmem_device_spec.txt +++ b/docs/specs/ivshmem_device_spec.txt @@ -85,12 +85,41 @@ events have occurred. The semantics of interrupt vectors are left to the user's discretion. +IVSHMEM host services +--------------------- + +This part is optional (see *Usage in the Guest* section below). + +To handle notifications between users of a ivshmem device, a ivshmem server has +been added. This server is responsible for creating the shared memory and +creating a set of eventfds for each users of the shared memory. It behaves as a +proxy between the different ivshmem clients (QEMU): giving the shared memory fd +to each client, allocating eventfds to new clients and broadcasting to all +clients when a client disappears. + +Apart from the current ivshmem implementation in QEMU, a ivshmem client can be +written for debug, for development purposes, or to implement notifications +between host and guests. + + Usage in the Guest ------------------ -The shared memory device is intended to be used with the provided UIO driver. -Very little configuration is needed. The guest should map BAR0 to access the -registers (an array of 32-bit ints allows simple writing) and map BAR2 to -access the shared memory region itself. The size of the shared memory region -is specified when the guest (or shared memory server) is started. A guest may -map the whole shared memory region or only part of it. +The guest should map BAR0 to access the registers (an array of 32-bit ints +allows simple writing) and map BAR2 to access the shared memory region itself. +The size of the shared memory region is specified when the guest (or shared +memory server) is started. A guest may map the whole shared memory region or +only part of it. + +ivshmem provides an optional notification mechanism through eventfds handled by +QEMU that will trigger interrupts in guests. This mechanism is enabled when +using a ivshmem-server which must be started prior to VMs and which serves as a +proxy for exchanging eventfds. + +It is your choice how to use the ivshmem device. +- the simple way, you don't need anything else than what is already in QEMU. + You can map the shared memory in guest, then use it in userland as you see fit + (memnic for example works this way http://dpdk.org/browse/memnic), +- the more advanced way, basically, if you want an event mechanism between the + VMs using your ivshmem device. In this case, then you will most likely want to + write a kernel driver that will handle interrupts. -- 1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe kvm" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
