From patchwork Wed Apr 7 22:51:58 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Cam Macdonell X-Patchwork-Id: 49674 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 24A4AB7D16 for ; Thu, 8 Apr 2010 09:22:05 +1000 (EST) Received: from localhost ([127.0.0.1]:54999 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NzeZN-0000p3-5N for incoming@patchwork.ozlabs.org; Wed, 07 Apr 2010 19:22:01 -0400 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Nze6i-0006V1-QP for qemu-devel@nongnu.org; Wed, 07 Apr 2010 18:52:25 -0400 Received: from [140.186.70.92] (port=36116 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Nze6g-0006U2-Rf for qemu-devel@nongnu.org; Wed, 07 Apr 2010 18:52:23 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Nze6a-0003ye-1D for qemu-devel@nongnu.org; Wed, 07 Apr 2010 18:52:22 -0400 Received: from fleet.cs.ualberta.ca ([129.128.22.22]:44394) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Nze6Z-0003xj-Pw for qemu-devel@nongnu.org; Wed, 07 Apr 2010 18:52:15 -0400 Received: from localhost.localdomain (st-brides.cs.ualberta.ca [129.128.23.21]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp-auth.cs.ualberta.ca (Postfix) with ESMTP id 77F8F2800A; Wed, 7 Apr 2010 16:52:03 -0600 (MDT) From: Cam Macdonell To: kvm@vger.kernel.org Date: Wed, 7 Apr 2010 16:51:58 -0600 Message-Id: <1270680720-8457-2-git-send-email-cam@cs.ualberta.ca> X-Mailer: git-send-email 1.6.0.6 In-Reply-To: <1270680720-8457-1-git-send-email-cam@cs.ualberta.ca> References: <1270680720-8457-1-git-send-email-cam@cs.ualberta.ca> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) Cc: Cam Macdonell , qemu-devel@nongnu.org Subject: [Qemu-devel] [PATCH v4 1/3] Device specification for shared memory PCI device X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org --- docs/specs/ivshmem_device_spec.txt | 85 ++++++++++++++++++++++++++++++++++++ 1 files changed, 85 insertions(+), 0 deletions(-) create mode 100644 docs/specs/ivshmem_device_spec.txt diff --git a/docs/specs/ivshmem_device_spec.txt b/docs/specs/ivshmem_device_spec.txt new file mode 100644 index 0000000..9895782 --- /dev/null +++ b/docs/specs/ivshmem_device_spec.txt @@ -0,0 +1,85 @@ + +Device Specification for Inter-VM shared memory device +------------------------------------------------------ + +The Inter-VM shared memory device is designed to share a region of memory to +userspace in multiple virtual guests. The memory region does not belong to any +guest, but is a POSIX memory object on the host. Optionally, the device may +support sending interrupts to other guests sharing the same memory region. + +The Inter-VM PCI device +----------------------- + +BARs + +The device supports three BARs. BAR0 is a 1 Kbyte MMIO region to support +registers. BAR1 is used for MSI-X when it is enabled in the device. BAR2 is +used to map the shared memory object from the host. The size of BAR2 is +specified when the guest is started and must be a power of 2 in size. + +Registers + +The device currently supports 4 registers of 32-bits each. Registers +are used for synchronization between guests sharing the same memory object when +interrupts are supported (this requires using the shared memory server). + +The server assigns each VM an ID number and sends this ID number to the Qemu +process when the guest starts. + +enum ivshmem_registers { + IntrMask = 0, + IntrStatus = 4, + IVPosition = 8, + Doorbell = 12 +}; + +The first two registers are the interrupt mask and status registers. Mask and +status are only used with pin-based interrupts. They are unused with MSI +interrupts. The IVPosition register is read-only and reports the guest's ID +number. To interrupt another guest, a guest must write to the Doorbell +register. The doorbell register is 32-bits, logically divided into two 16-bit +fields. The high 16-bits are the guest ID to interrupt and the low 16-bits are +the interrupt vector to trigger. + +The semantics of the value written to the doorbell depends on whether the +device is using MSI or a regular pin-based interrupt. In short, MSI uses +vectors and regular interrupts set the status register. + +Regular Interrupts +------------------ + +If regular interrupts are used (due to either a guest not supporting MSI or the +user specifying not to use them on startup) then the value written to the lower +16-bits of the Doorbell register results is arbitrary and will trigger an +interrupt in the destination guest. + +An interrupt is also generated when a new guest accesses the shared memory +region. A status of (2^32 - 1) indicates that a new guest has joined. + +Message Signalled Interrupts +---------------------------- + +A ivshmem device may support multiple MSI vectors. If so, the lower 16-bits +written to the Doorbell register must be between 1 and the maximum number of +vectors the guest supports. The lower 16 bits written to the doorbell is the +MSI vector that will be raised in the destination guest. The number of MSI +vectors can vary but it is set when the VM is started, however vector 0 is +used to notify that a new guest has joined. Guests should not use vector 0 for +any other purpose. + +The important thing to remember with MSI is that it is only a signal, no status +is set (since MSI interrupts are not shared). All information other than the +interrupt itself should be communicated via the shared memory region. Devices +supporting multiple MSI vectors can use different vectors to indicate different +events have occurred. The semantics of interrupt vectors are left to the +user's discretion. + +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.