From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41956) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1agxmP-0006j9-QV for qemu-devel@nongnu.org; Fri, 18 Mar 2016 13:01:48 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1agxmH-000846-8O for qemu-devel@nongnu.org; Fri, 18 Mar 2016 13:01:41 -0400 Received: from mx1.redhat.com ([209.132.183.28]:48580) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1agxmH-00083p-0D for qemu-devel@nongnu.org; Fri, 18 Mar 2016 13:01:33 -0400 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by mx1.redhat.com (Postfix) with ESMTPS id 8FDC264D11 for ; Fri, 18 Mar 2016 17:01:32 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-34.ams2.redhat.com [10.36.116.34]) by int-mx14.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id u2IH1TbU006587 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Fri, 18 Mar 2016 13:01:31 -0400 From: Markus Armbruster Date: Fri, 18 Mar 2016 18:00:57 +0100 Message-Id: <1458320487-19603-11-git-send-email-armbru@redhat.com> In-Reply-To: <1458320487-19603-1-git-send-email-armbru@redhat.com> References: <1458320487-19603-1-git-send-email-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Subject: [Qemu-devel] [PULL 10/40] ivshmem: Rewrite specification document List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org This started as an attempt to update ivshmem_device_spec.txt for clarity, accuracy and completeness while working on its code, and quickly became a full rewrite. Since the diff would be useless anyway, I'm using the opportunity to rename the file to ivshmem-spec.txt. I tried hard to ensure the new text contradicts neither the old text nor the code. If the new text contradicts the old text but not the code, it's probably a bug in the old text. If the new text contradicts both, its probably a bug in the new text. Signed-off-by: Markus Armbruster Reviewed-by: Marc-Andr=C3=A9 Lureau Message-Id: <1458066895-20632-11-git-send-email-armbru@redhat.com> --- docs/specs/ivshmem-spec.txt | 243 +++++++++++++++++++++++++++++++= ++++++ docs/specs/ivshmem_device_spec.txt | 161 ------------------------ 2 files changed, 243 insertions(+), 161 deletions(-) create mode 100644 docs/specs/ivshmem-spec.txt delete mode 100644 docs/specs/ivshmem_device_spec.txt diff --git a/docs/specs/ivshmem-spec.txt b/docs/specs/ivshmem-spec.txt new file mode 100644 index 0000000..0e9185a --- /dev/null +++ b/docs/specs/ivshmem-spec.txt @@ -0,0 +1,243 @@ +=3D Device Specification for Inter-VM shared memory device =3D + +The Inter-VM shared memory device (ivshmem) is designed to share a +memory region between multiple QEMU processes running different guests +and the host. In order for all guests to be able to pick up the +shared memory area, it is modeled by QEMU as a PCI device exposing +said memory to the guest as a PCI BAR. + +The device can use a shared memory object on the host directly, or it +can obtain one from an ivshmem server. + +In the latter case, the device can additionally interrupt its peers, and +get interrupted by its peers. + + +=3D=3D Configuring the ivshmem PCI device =3D=3D + +There are two basic configurations: + +- Just shared memory: -device ivshmem,shm=3DNAME,... + + This uses shared memory object NAME. + +- Shared memory plus interrupts: -device ivshmem,chardev=3DCHR,vectors=3D= N,... + + An ivshmem server must already be running on the host. The device + connects to the server's UNIX domain socket via character device + CHR. + + Each peer gets assigned a unique ID by the server. IDs must be + between 0 and 65535. + + Interrupts are message-signaled by default (MSI-X). With msi=3Doff + the device has no MSI-X capability, and uses legacy INTx instead. + vectors=3DN configures the number of vectors to use. + +For more details on ivshmem device properties, see The QEMU Emulator +User Documentation (qemu-doc.*). + + +=3D=3D The ivshmem PCI device's guest interface =3D=3D + +The device has vendor ID 1af4, device ID 1110, revision 0. + +=3D=3D=3D PCI BARs =3D=3D=3D + +The ivshmem PCI device has two or three BARs: + +- BAR0 holds device registers (256 Byte MMIO) +- BAR1 holds MSI-X table and PBA (only when using MSI-X) +- BAR2 maps the shared memory object + +There are two ways to use this device: + +- If you only need the shared memory part, BAR2 suffices. This way, + you have access to the shared memory in the guest and can use it as + you see fit. Memnic, for example, uses ivshmem this way from guest + user space (see http://dpdk.org/browse/memnic). + +- If you additionally need the capability for peers to interrupt each + other, you need BAR0 and, if using MSI-X, BAR1. You will most + likely want to write a kernel driver to handle interrupts. Requires + the device to be configured for interrupts, obviously. + +If the device is configured for interrupts, BAR2 is initially invalid. +It becomes safely accessible only after the ivshmem server provided +the shared memory. Guest software should wait for the IVPosition +register (described below) to become non-negative before accessing +BAR2. + +The device is not capable to tell guest software whether it is +configured for interrupts. + +=3D=3D=3D PCI device registers =3D=3D=3D + +BAR 0 contains the following registers: + + Offset Size Access On reset Function + 0 4 read/write 0 Interrupt Mask + bit 0: peer interrupt + bit 1..31: reserved + 4 4 read/write 0 Interrupt Status + bit 0: peer interrupt + bit 1..31: reserved + 8 4 read-only 0 or -1 IVPosition + 12 4 write-only N/A Doorbell + bit 0..15: vector + bit 16..31: peer ID + 16 240 none N/A reserved + +Software should only access the registers as specified in column +"Access". Reserved bits should be ignored on read, and preserved on +write. + +Interrupt Status and Mask Register together control the legacy INTx +interrupt when the device has no MSI-X capability: INTx is asserted +when the bit-wise AND of Status and Mask is non-zero and the device +has no MSI-X capability. Interrupt Status Register bit 0 becomes 1 +when an interrupt request from a peer is received. Reading the +register clears it. + +IVPosition Register: if the device is not configured for interrupts, +this is zero. Else, it's -1 for a short while after reset, then +changes to the device's ID (between 0 and 65535). + +There is no good way for software to find out whether the device is +configured for interrupts. A positive IVPosition means interrupts, +but zero could be either. The initial -1 cannot be reliably observed. + +Doorbell Register: writing this register requests to interrupt a peer. +The written value's high 16 bits are the ID of the peer to interrupt, +and its low 16 bits select an interrupt vector. + +If the device is not configured for interrupts, the write is ignored. + +If the interrupt hasn't completed setup, the write is ignored. The +device is not capable to tell guest software whether setup is +complete. Interrupts can regress to this state on migration. + +If the peer with the requested ID isn't connected, or it has fewer +interrupt vectors connected, the write is ignored. The device is not +capable to tell guest software what peers are connected, or how many +interrupt vectors are connected. + +If the peer doesn't use MSI-X, its Interrupt Status register is set to +1. This asserts INTx unless masked by the Interrupt Mask register. +The device is not capable to communicate the interrupt vector to guest +software then. + +If the peer uses MSI-X, the interrupt for this vector becomes pending. +There is no way for software to clear the pending bit, and a polling +mode of operation is therefore impossible with MSI-X. + +With multiple MSI-X vectors, different vectors can be used to indicate +different events have occurred. The semantics of interrupt vectors +are left to the application. + + +=3D=3D Interrupt infrastructure =3D=3D + +When configured for interrupts, the peers share eventfd objects in +addition to shared memory. The shared resources are managed by an +ivshmem server. + +=3D=3D=3D The ivshmem server =3D=3D=3D + +The server listens on a UNIX domain socket. + +For each new client that connects to the server, the server +- picks an ID, +- creates eventfd file descriptors for the interrupt vectors, +- sends the ID and the file descriptor for the shared memory to the + new client, +- sends connect notifications for the new client to the other clients + (these contain file descriptors for sending interrupts), +- sends connect notifications for the other clients to the new client, + and +- sends interrupt setup messages to the new client (these contain file + descriptors for receiving interrupts). + +When a client disconnects from the server, the server sends disconnect +notifications to the other clients. + +The next section describes the protocol in detail. + +If the server terminates without sending disconnect notifications for +its connected clients, the clients can elect to continue. They can +communicate with each other normally, but won't receive disconnect +notification on disconnect, and no new clients can connect. There is +no way for the clients to connect to a restarted server. The device +is not capable to tell guest software whether the server is still up. + +Example server code is in contrib/ivshmem-server/. Not to be used in +production. It assumes all clients use the same number of interrupt +vectors. + +A standalone client is in contrib/ivshmem-client/. It can be useful +for debugging. + +=3D=3D=3D The ivshmem Client-Server Protocol =3D=3D=3D + +An ivshmem device configured for interrupts connects to an ivshmem +server. This section details the protocol between the two. + +The connection is one-way: the server sends messages to the client. +Each message consists of a single 8 byte little-endian signed number, +and may be accompanied by a file descriptor via SCM_RIGHTS. Both +client and server close the connection on error. + +On connect, the server sends the following messages in order: + +1. The protocol version number, currently zero. The client should + close the connection on receipt of versions it can't handle. + +2. The client's ID. This is unique among all clients of this server. + IDs must be between 0 and 65535, because the Doorbell register + provides only 16 bits for them. + +3. The number -1, accompanied by the file descriptor for the shared + memory. + +4. Connect notifications for existing other clients, if any. This is + a peer ID (number between 0 and 65535 other than the client's ID), + repeated N times. Each repetition is accompanied by one file + descriptor. These are for interrupting the peer with that ID using + vector 0,..,N-1, in order. If the client is configured for fewer + vectors, it closes the extra file descriptors. If it is configured + for more, the extra vectors remain unconnected. + +5. Interrupt setup. This is the client's own ID, repeated N times. + Each repetition is accompanied by one file descriptor. These are + for receiving interrupts from peers using vector 0,..,N-1, in + order. If the client is configured for fewer vectors, it closes + the extra file descriptors. If it is configured for more, the + extra vectors remain unconnected. + +From then on, the server sends these kinds of messages: + +6. Connection / disconnection notification. This is a peer ID. + + - If the number comes with a file descriptor, it's a connection + notification, exactly like in step 4. + + - Else, it's a disconnection notification for the peer with that ID. + +Known bugs: + +* The protocol changed incompatibly in QEMU 2.5. Before, messages + were native endian long, and there was no version number. + +* The protocol is poorly designed. + +=3D=3D=3D The ivshmem Client-Client Protocol =3D=3D=3D + +An ivshmem device configured for interrupts receives eventfd file +descriptors for interrupting peers and getting interrupted by peers +from the server, as explained in the previous section. + +To interrupt a peer, the device writes the 8-byte integer 1 in native +byte order to the respective file descriptor. + +To receive an interrupt, the device reads and discards as many 8-byte +integers as it can. diff --git a/docs/specs/ivshmem_device_spec.txt b/docs/specs/ivshmem_devi= ce_spec.txt deleted file mode 100644 index d318d65..0000000 --- a/docs/specs/ivshmem_device_spec.txt +++ /dev/null @@ -1,161 +0,0 @@ - -Device Specification for Inter-VM shared memory device ------------------------------------------------------- - -The Inter-VM shared memory device is designed to share a memory region (= created -on the host via the POSIX shared memory API) between multiple QEMU proce= sses -running different guests. In order for all guests to be able to pick up = the -shared memory area, it is modeled by QEMU as a PCI device exposing said = memory -to the guest as a PCI BAR. -The memory region does not belong to any guest, but is a POSIX memory ob= ject on -the host. The host can access this shared memory if needed. - -The device also provides an optional communication mechanism between gue= sts -sharing the same memory object. More details about that in the section '= Guest to -guest communication' section. - - -The Inter-VM PCI device ------------------------ - -From the VM point of view, the ivshmem PCI device supports three BARs. - -- BAR0 is a 1 Kbyte MMIO region to support registers and interrupts when= MSI is - not used. -- BAR1 is used for MSI-X when it is enabled in the device. -- BAR2 is used to access the shared memory object. - -It is your choice how to use the device but you must choose between two -behaviors : - -- basically, if you only need the shared memory part, you will map BAR2. - This way, you have access to the shared memory in guest and can use it= as you - see fit (memnic, for example, uses it in userland - http://dpdk.org/browse/memnic). - -- BAR0 and BAR1 are used to implement an optional communication mechanis= m - through interrupts in the guests. If you need an event mechanism betwe= en the - guests accessing the shared memory, you will most likely want to write= a - kernel driver that will handle interrupts. See details in the section = 'Guest - to guest communication' section. - -The behavior is chosen when starting your QEMU processes: -- no communication mechanism needed, the first QEMU to start creates the= shared - memory on the host, subsequent QEMU processes will use it. - -- communication mechanism needed, an ivshmem server must be started befo= re any - QEMU processes, then each QEMU process connects to the server unix soc= ket. - -For more details on the QEMU ivshmem parameters, see qemu-doc documentat= ion. - - -Guest to guest communication ----------------------------- - -This section details the communication mechanism between the guests acce= ssing -the ivhsmem shared memory. - -*ivshmem server* - -This server code is available in qemu.git/contrib/ivshmem-server. - -The server must be started on the host before any guest. -It creates a shared memory object then waits for clients to connect on a= unix -socket. All the messages are little-endian int64_t integer. - -For each client (QEMU process) that connects to the server: -- the server sends a protocol version, if client does not support it, th= e client - closes the communication, -- the server assigns an ID for this client and sends this ID to him as t= he first - message, -- the server sends a fd to the shared memory object to this client, -- the server creates a new set of host eventfds associated to the new cl= ient and - sends this set to all already connected clients, -- finally, the server sends all the eventfds sets for all clients to the= new - client. - -The server signals all clients when one of them disconnects. - -The client IDs are limited to 16 bits because of the current implementat= ion (see -Doorbell register in 'PCI device registers' subsection). Hence only 6553= 6 -clients are supported. - -All the file descriptors (fd to the shared memory, eventfds for each cli= ent) -are passed to clients using SCM_RIGHTS over the server unix socket. - -Apart from the current ivshmem implementation in QEMU, an ivshmem client= has -been provided in qemu.git/contrib/ivshmem-client for debug. - -*QEMU as an ivshmem client* - -At initialisation, when creating the ivshmem device, QEMU first receives= a -protocol version and closes communication with server if it does not mat= ch. -Then, QEMU gets its ID from the server then makes it available through B= AR0 -IVPosition register for the VM to use (see 'PCI device registers' subsec= tion). -QEMU then uses the fd to the shared memory to map it to BAR2. -eventfds for all other clients received from the server are stored to im= plement -BAR0 Doorbell register (see 'PCI device registers' subsection). -Finally, eventfds assigned to this QEMU process are used to send interru= pts in -this VM. - -*PCI device registers* - -From the VM point of view, the ivshmem PCI device supports 4 registers o= f -32-bits each. - -enum ivshmem_registers { - IntrMask =3D 0, - IntrStatus =3D 4, - IVPosition =3D 8, - Doorbell =3D 12 -}; - -The first two registers are the interrupt mask and status registers. Ma= sk and -status are only used with pin-based interrupts. They are unused with MS= I -interrupts. - -Status Register: The status register is set to 1 when an interrupt occur= s. - -Mask Register: The mask register is bitwise ANDed with the interrupt sta= tus -and the result will raise an interrupt if it is non-zero. However, sinc= e 1 is -the only value the status will be set to, it is only the first bit of th= e mask -that has any effect. Therefore interrupts can be masked by setting the = first -bit to 0 and unmasked by setting the first bit to 1. - -IVPosition Register: The IVPosition register is read-only and reports th= e -guest's ID number. The guest IDs are non-negative integers. When using= the -server, since the server is a separate process, the VM ID will only be s= et when -the device is ready (shared memory is received from the server and acces= sible -via the device). If the device is not ready, the IVPosition will return= -1. -Applications should ensure that they have a valid VM ID before accessing= the -shared memory. - -Doorbell Register: To interrupt another guest, a guest must write to th= e -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 t= he 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 while regular interrupt= s 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 th= e lower -16-bits of the Doorbell register results is arbitrary and will trigger a= n -interrupt in the destination guest. - -Message Signalled Interrupts - -An ivshmem device may support multiple MSI vectors. If so, the lower 16= -bits -written to the Doorbell register must be between 0 and the maximum numbe= r of -vectors the guest supports. The lower 16 bits written to the doorbell i= s the -MSI vector that will be raised in the destination guest. The number of = MSI -vectors is configurable but it is set when the VM is started. - -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 tha= n the -interrupt itself should be communicated via the shared memory region. D= evices -supporting multiple MSI vectors can use different vectors to indicate di= fferent -events have occurred. The semantics of interrupt vectors are left to th= e -user's discretion. --=20 2.4.3