From 3d4cc0bff5d5992d8953b420e4b5a99b97fd7ed3 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Fri, 5 Jun 2020 15:48:06 -0700 Subject: [PATCH] doc: edit ivshmem hld doc Signed-off-by: David B. Kinder --- doc/developer-guides/hld/ivshmem-hld.rst | 104 ++++++++++++++--------- 1 file changed, 62 insertions(+), 42 deletions(-) diff --git a/doc/developer-guides/hld/ivshmem-hld.rst b/doc/developer-guides/hld/ivshmem-hld.rst index 000a7540d..d609cb279 100644 --- a/doc/developer-guides/hld/ivshmem-hld.rst +++ b/doc/developer-guides/hld/ivshmem-hld.rst @@ -3,10 +3,10 @@ ACRN Shared Memory Based Inter-VM Communication ############################################### -To support inter virtual machines communication based on shared memory -mechanism, ACRN device model/hypervisor emulate a virtual PCI device -(Called ``ivshmem`` device) to expose the base address and size of shared -memory. +ACRN supports inter-virtual machine communication based on a shared +memory mechanism, The ACRN device model and hypervisor emulate a virtual +PCI device (called an ``ivshmem`` device) to expose the base address and +size of this shared memory. Inter-VM Communication Overview ******************************* @@ -17,28 +17,33 @@ Inter-VM Communication Overview ACRN shared memory based inter-vm communication architecture -Two solutions of ivshmem device: dm-land and hypervisor-land. For dm-land, -the ivshmem device emulated in acrn device model and its shared memory region -is allocated from the Service VM's memory space. For hypervisor-land, it is -emulated in hypervisor and the shared memory regions are reserved in hypervisor's -memory space. The former solution only supports interactive between post-launched -VMs and the latter one can work for both pre-launched and post-launched VMs. The -hypervisor-land solution is WIP, plan to support in the near future. +The ``ivshmem`` device is emulated in the ACRN device model (dm-land) +and its shared memory region is allocated from the Service VM's memory +space. This solution only supports communication between post-launched +VMs. -- Ivshmem dm – The ivshmem device model implements register virtualization +.. note:: In a future implementation, the ``ivshmem`` device could + instead be emulated in the hypervisor (hypervisor-land) and the shared + memory regions reserved in the hypervisor's memory space. This solution + would work for both pre-launched and post-launched VMs. + + +ivshmem dm: + The ivshmem device model implements register virtualization and shared memory mapping. Will support notification/interrupt mechanism in future. -- Ivshmem server – A daemon for inter-VM notification capability, - currently, it has not been implemented, so the inter-VM communication - doesn’t support notification mechanism. +ivshmem server: + A daemon for inter-VM notification capability, + This is currently not implemented, so the inter-VM communication + doesn't support a notification mechanism. Ivshmem Device Introduction *************************** -The ivshmem device is a virtual standard PCI device, it consists of two -BARs(BAR0 and BAR2), one is used for emulate interrupt related registers, -another one is used for exposing shared memory region. The ivshmem device +The ``ivshmem`` device is a virtual standard PCI device consisting of +two Base Address Registers (BARs): BAR0 is used for emulating interrupt related registers, +and BAR2 is used for exposing shared memory region. The ``ivshmem`` device doesn't support any extra capabilities. Configuration Space Definition @@ -58,36 +63,51 @@ Configuration Space Definition MMIO Registers Definition -+---------------------------+----------+-------+-----------------------------------------------------------------------------------------------------------------------+ -| Register | Offset | RW | Description | -+===========================+==========+=======+=======================================================================================================================+ -| IVSHMEM\_IRQ\_MASK\_REG | 0x0 | R/W | Interrupt Status register is used for legacy interrupt. | -| | | | | -| | | | Currently, the ivshmem doesn’t support interrupt, so this is reserved. | -+---------------------------+----------+-------+-----------------------------------------------------------------------------------------------------------------------+ -| IVSHMEM\_IRQ\_STA\_REG | 0x4 | R/W | Interrupt Mask register is used for legacy interrupt. | -| | | | | -| | | | Currently, the ivshmem doesn’t support interrupt, so this is reserved. | -+---------------------------+----------+-------+-----------------------------------------------------------------------------------------------------------------------+ -| IVSHMEM\_IV\_POS\_REG | 0x8 | RO | Inter VM Position register is used to identify VM ID, currently its value is zero. | -+---------------------------+----------+-------+-----------------------------------------------------------------------------------------------------------------------+ -| IVSHMEM\_DOORBELL\_REG | 0xc | WO | Doorbell register is used to trigger an interrupt to the peer VM. Currently, the ivshmem doesn’t support interrupt. | -+---------------------------+----------+-------+-----------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Register + - Offset + - Read/Write + - Description + * - IVSHMEM\_IRQ\_MASK\_REG + - 0x0 + - R/W + - Interrupt Status register is used for legacy interrupt. + ivshmem doesn't support interrupts, so this is reserved. + * - IVSHMEM\_IRQ\_STA\_REG + - 0x4 + - R/W + - Interrupt Mask register is used for legacy interrupt. + ivshmem doesn't support interrupts, so this is reserved. + * - IVSHMEM\_IV\_POS\_REG + - 0x8 + - RO + - Inter-VM Position register is used to identify the VM ID. + Currently its value is zero. + * - IVSHMEM\_DOORBELL\_REG + - 0xC + - WO + - Doorbell register is used to trigger an interrupt to the peer VM. + ivshmem doesn't support interrupts. Usage ***** -To support two post-launched VMs communication via ivshmem device, user -needs to add below line as acrn-dm boot parameter. +To support two post-launched VMs communicating via an ``ivshmem`` device, +add this line as an acrn-dm boot parameter:: -***-s slot, ivshmem, shm\_name,shm\_size*** + -s slot, ivshmem, shm_name, shm_size -- -s slot – Specify the virtual PCI slot number +where -- ivshmem – Virtual PCI device name +- ``-s slot`` - Specify the virtual PCI slot number -- shm\_name – Specify a shared memory name, post-launched VMs with the - same *shm\_name* share a shared memory region. +- ``ivshmem`` - Virtual PCI device name -- shm\_size – Specify a shared memory size, two communicating VMs need - to define the same size. +- ``shm_name`` - Specify a shared memory name. Post-launched VMs with the + same ``shm_name`` share a shared memory region. + +- ``shm_size`` - Specify a shared memory size. The two communicating + VMs must define the same size.