doc: edit ivshmem hld doc

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
yakuizhao · Jun 5, 2020 · 3d4cc0b · 3d4cc0b
1 parent 19c50a1
commit 3d4cc0b
Showing 1 changed file with 62 additions and 42 deletions.
diff --git 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***
+where
 
--  -s slot – Specify the virtual PCI slot number
+-  ``-s slot`` - Specify the virtual PCI slot number
 
--  ivshmem – Virtual PCI device name
+-  ``ivshmem`` - Virtual PCI device name
 
--  shm\_name – Specify a shared memory name, post-launched VMs with the
-   same *shm\_name* share a shared memory region.
+-  ``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, two communicating VMs need
-   to define the same size.
+-  ``shm_size`` - Specify a shared memory size. The two communicating
+   VMs must define the same size.