From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41607) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WxxjR-0006CT-Kv for qemu-devel@nongnu.org; Fri, 20 Jun 2014 08:15:55 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WxxjM-0003dK-0c for qemu-devel@nongnu.org; Fri, 20 Jun 2014 08:15:49 -0400 Received: from mail-wg0-f49.google.com ([74.125.82.49]:57409) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WxxjL-0003d8-Rr for qemu-devel@nongnu.org; Fri, 20 Jun 2014 08:15:43 -0400 Received: by mail-wg0-f49.google.com with SMTP id y10so3564103wgg.8 for ; Fri, 20 Jun 2014 05:15:43 -0700 (PDT) From: David Marchand Date: Fri, 20 Jun 2014 14:15:31 +0200 Message-Id: <1403266532-13231-2-git-send-email-david.marchand@6wind.com> In-Reply-To: <1403266532-13231-1-git-send-email-david.marchand@6wind.com> References: <1403266532-13231-1-git-send-email-david.marchand@6wind.com> Subject: [Qemu-devel] [PATCH 1/2] docs: update ivshmem device spec List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: pbonzini@redhat.com, claudio.fontana@huawei.com, kvm@vger.kernel.org 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 --- 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