Documentation/virt/acrn/io-request.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 I/O request handling
   4 ====================
   5
   6 An I/O request of a User VM, which is constructed by the hypervisor, is
   7 distributed by the ACRN Hypervisor Service Module to an I/O client
   8 corresponding to the address range of the I/O request. Details of I/O request
   9 handling are described in the following sections.
  10
  11 1. I/O request
  12 --------------
  13
  14 For each User VM, there is a shared 4-KByte memory region used for I/O requests
  15 communication between the hypervisor and Service VM. An I/O request is a
  16 256-byte structure buffer, which is 'struct acrn_io_request', that is filled by
  17 an I/O handler of the hypervisor when a trapped I/O access happens in a User
  18 VM. ACRN userspace in the Service VM first allocates a 4-KByte page and passes
  19 the GPA (Guest Physical Address) of the buffer to the hypervisor. The buffer is
  20 used as an array of 16 I/O request slots with each I/O request slot being 256
  21 bytes. This array is indexed by vCPU ID.
  22
  23 2. I/O clients
  24 --------------
  25
  26 An I/O client is responsible for handling User VM I/O requests whose accessed
  27 GPA falls in a certain range. Multiple I/O clients can be associated with each
  28 User VM. There is a special client associated with each User VM, called the
  29 default client, that handles all I/O requests that do not fit into the range of
  30 any other clients. The ACRN userspace acts as the default client for each User
  31 VM.
  32
  33 Below illustration shows the relationship between I/O requests shared buffer,
  34 I/O requests and I/O clients.
  35
  36 ::
  37
  38      +------------------------------------------------------+
  39      |                                       Service VM     |
  40      |+--------------------------------------------------+  |
  41      ||      +----------------------------------------+  |  |
  42      ||      | shared page            ACRN userspace  |  |  |
  43      ||      |    +-----------------+  +------------+ |  |  |
  44      ||   +----+->| acrn_io_request |<-+  default   | |  |  |
  45      ||   |  | |  +-----------------+  | I/O client | |  |  |
  46      ||   |  | |  |       ...       |  +------------+ |  |  |
  47      ||   |  | |  +-----------------+                 |  |  |
  48      ||   |  +-|--------------------------------------+  |  |
  49      ||---|----|-----------------------------------------|  |
  50      ||   |    |                             kernel      |  |
  51      ||   |    |            +----------------------+     |  |
  52      ||   |    |            | +-------------+  HSM |     |  |
  53      ||   |    +--------------+             |      |     |  |
  54      ||   |                 | | I/O clients |      |     |  |
  55      ||   |                 | |             |      |     |  |
  56      ||   |                 | +-------------+      |     |  |
  57      ||   |                 +----------------------+     |  |
  58      |+---|----------------------------------------------+  |
  59      +----|-------------------------------------------------+
  60           |
  61      +----|-------------------------------------------------+
  62      |  +-+-----------+                                     |
  63      |  | I/O handler |              ACRN Hypervisor        |
  64      |  +-------------+                                     |
  65      +------------------------------------------------------+
  66
  67 3. I/O request state transition
  68 -------------------------------
  69
  70 The state transitions of an ACRN I/O request are as follows.
  71
  72 ::
  73
  74    FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
  75
  76 - FREE: this I/O request slot is empty
  77 - PENDING: a valid I/O request is pending in this slot
  78 - PROCESSING: the I/O request is being processed
  79 - COMPLETE: the I/O request has been processed
  80
  81 An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
  82 ACRN userspace are in charge of processing the others.
  83
  84 4. Processing flow of I/O requests
  85 ----------------------------------
  86
  87 a. The I/O handler of the hypervisor will fill an I/O request with PENDING
  88    state when a trapped I/O access happens in a User VM.
  89 b. The hypervisor makes an upcall, which is a notification interrupt, to
  90    the Service VM.
  91 c. The upcall handler schedules a worker to dispatch I/O requests.
  92 d. The worker looks for the PENDING I/O requests, assigns them to different
  93    registered clients based on the address of the I/O accesses, updates
  94    their state to PROCESSING, and notifies the corresponding client to handle.
  95 e. The notified client handles the assigned I/O requests.
  96 f. The HSM updates I/O requests states to COMPLETE and notifies the hypervisor
  97    of the completion via hypercalls.