Commit c619a804 authored by Shuo Liu's avatar Shuo Liu Committed by Greg Kroah-Hartman
Browse files

docs: acrn: Introduce ACRN 

Add documentation on the following aspects of ACRN:

  1) A brief introduction on the architecture of ACRN.
  2) I/O request handling in ACRN.
  3) CPUID functions of ACRN.

To learn more about ACRN, please go to ACRN project website
https://projectacrn.org, or the documentation page
https://projectacrn.github.io/

.

Cc: Dave Hansen <dave.hansen@intel.com>
Cc: Sen Christopherson <sean.j.christopherson@intel.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Fengwei Yin <fengwei.yin@intel.com>
Cc: Zhi Wang <zhi.a.wang@intel.com>
Cc: Zhenyu Wang <zhenyuw@linux.intel.com>
Cc: Yu Wang <yu1.wang@intel.com>
Cc: Reinette Chatre <reinette.chatre@intel.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: default avatarZhi Wang <zhi.a.wang@intel.com>
Reviewed-by: default avatarReinette Chatre <reinette.chatre@intel.com>
Reviewed-by: default avatarBorislav Petkov <bp@suse.de>
Signed-off-by: default avatarShuo Liu <shuo.a.liu@intel.com>
Link: https://lore.kernel.org/r/20210207031040.49576-2-shuo.a.liu@intel.com


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent b212658a

Documentation/virt/acrn/cpuid.rst

0 → 100644
+46 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



===============

ACRN CPUID bits

===============



A guest VM running on an ACRN hypervisor can check some of its features using

CPUID.



ACRN cpuid functions are:



function: 0x40000000



returns::



   eax = 0x40000010

   ebx = 0x4e524341

   ecx = 0x4e524341

   edx = 0x4e524341



Note that this value in ebx, ecx and edx corresponds to the string

"ACRNACRNACRN". The value in eax corresponds to the maximum cpuid function

present in this leaf, and will be updated if more functions are added in the

future.



function: define ACRN_CPUID_FEATURES (0x40000001)



returns::



          ebx, ecx, edx

          eax = an OR'ed group of (1 << flag)



where ``flag`` is defined as below:



================================= =========== ================================

flag                              value       meaning

================================= =========== ================================

ACRN_FEATURE_PRIVILEGED_VM        0           guest VM is a privileged VM

================================= =========== ================================



function: 0x40000010



returns::



          ebx, ecx, edx

          eax = (Virtual) TSC frequency in kHz.

Documentation/virt/acrn/index.rst

0 → 100644
+12 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



===============

ACRN Hypervisor

===============



.. toctree::

   :maxdepth: 1



   introduction

   io-request

   cpuid

Documentation/virt/acrn/introduction.rst

0 → 100644
+43 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



ACRN Hypervisor Introduction

============================



The ACRN Hypervisor is a Type 1 hypervisor, running directly on bare-metal

hardware. It has a privileged management VM, called Service VM, to manage User

VMs and do I/O emulation.



ACRN userspace is an application running in the Service VM that emulates

devices for a User VM based on command line configurations. ACRN Hypervisor

Service Module (HSM) is a kernel module in the Service VM which provides

hypervisor services to the ACRN userspace.



Below figure shows the architecture.



::



                Service VM                    User VM

      +----------------------------+  |  +------------------+

      |        +--------------+    |  |  |                  |

      |        |ACRN userspace|    |  |  |                  |

      |        +--------------+    |  |  |                  |

      |-----------------ioctl------|  |  |                  |   ...

      |kernel space   +----------+ |  |  |                  |

      |               |   HSM    | |  |  | Drivers          |

      |               +----------+ |  |  |                  |

      +--------------------|-------+  |  +------------------+

  +---------------------hypercall----------------------------------------+

  |                         ACRN Hypervisor                              |

  +----------------------------------------------------------------------+

  |                          Hardware                                    |

  +----------------------------------------------------------------------+



ACRN userspace allocates memory for the User VM, configures and initializes the

devices used by the User VM, loads the virtual bootloader, initializes the

virtual CPU state and handles I/O request accesses from the User VM. It uses

ioctls to communicate with the HSM. HSM implements hypervisor services by

interacting with the ACRN Hypervisor via hypercalls. HSM exports a char device

interface (/dev/acrn_hsm) to userspace.



The ACRN hypervisor is open for contribution from anyone. The source repo is

available at https://github.com/projectacrn/acrn-hypervisor.

Documentation/virt/acrn/io-request.rst

0 → 100644
+97 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



I/O request handling

====================



An I/O request of a User VM, which is constructed by the hypervisor, is

distributed by the ACRN Hypervisor Service Module to an I/O client

corresponding to the address range of the I/O request. Details of I/O request

handling are described in the following sections.



1. I/O request

--------------



For each User VM, there is a shared 4-KByte memory region used for I/O requests

communication between the hypervisor and Service VM. An I/O request is a

256-byte structure buffer, which is 'struct acrn_io_request', that is filled by

an I/O handler of the hypervisor when a trapped I/O access happens in a User

VM. ACRN userspace in the Service VM first allocates a 4-KByte page and passes

the GPA (Guest Physical Address) of the buffer to the hypervisor. The buffer is

used as an array of 16 I/O request slots with each I/O request slot being 256

bytes. This array is indexed by vCPU ID.



2. I/O clients

--------------



An I/O client is responsible for handling User VM I/O requests whose accessed

GPA falls in a certain range. Multiple I/O clients can be associated with each

User VM. There is a special client associated with each User VM, called the

default client, that handles all I/O requests that do not fit into the range of

any other clients. The ACRN userspace acts as the default client for each User

VM.



Below illustration shows the relationship between I/O requests shared buffer,

I/O requests and I/O clients.



::



     +------------------------------------------------------+

     |                                       Service VM     |

     |+--------------------------------------------------+  |

     ||      +----------------------------------------+  |  |

     ||      | shared page            ACRN userspace  |  |  |

     ||      |    +-----------------+  +------------+ |  |  |

     ||   +----+->| acrn_io_request |<-+  default   | |  |  |

     ||   |  | |  +-----------------+  | I/O client | |  |  |

     ||   |  | |  |       ...       |  +------------+ |  |  |

     ||   |  | |  +-----------------+                 |  |  |

     ||   |  +-|--------------------------------------+  |  |

     ||---|----|-----------------------------------------|  |

     ||   |    |                             kernel      |  |

     ||   |    |            +----------------------+     |  |

     ||   |    |            | +-------------+  HSM |     |  |

     ||   |    +--------------+             |      |     |  |

     ||   |                 | | I/O clients |      |     |  |

     ||   |                 | |             |      |     |  |

     ||   |                 | +-------------+      |     |  |

     ||   |                 +----------------------+     |  |

     |+---|----------------------------------------------+  |

     +----|-------------------------------------------------+

          |

     +----|-------------------------------------------------+

     |  +-+-----------+                                     |

     |  | I/O handler |              ACRN Hypervisor        |

     |  +-------------+                                     |

     +------------------------------------------------------+



3. I/O request state transition

-------------------------------



The state transitions of an ACRN I/O request are as follows.



::



   FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...



- FREE: this I/O request slot is empty

- PENDING: a valid I/O request is pending in this slot

- PROCESSING: the I/O request is being processed

- COMPLETE: the I/O request has been processed



An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and

ACRN userspace are in charge of processing the others.



4. Processing flow of I/O requests

----------------------------------



a. The I/O handler of the hypervisor will fill an I/O request with PENDING

   state when a trapped I/O access happens in a User VM.

b. The hypervisor makes an upcall, which is a notification interrupt, to

   the Service VM.

c. The upcall handler schedules a worker to dispatch I/O requests.

d. The worker looks for the PENDING I/O requests, assigns them to different

   registered clients based on the address of the I/O accesses, updates

   their state to PROCESSING, and notifies the corresponding client to handle.

e. The notified client handles the assigned I/O requests.

f. The HSM updates I/O requests states to COMPLETE and notifies the hypervisor

   of the completion via hypercalls.

Documentation/virt/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -12,6 +12,7 @@ Linux Virtualization Support 
   paravirt_ops

   guest-halt-polling

   ne_overview

   acrn/index



.. only:: html and subproject