0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 I/O request handling
0004 ====================
0005
0006 An I/O request of a User VM, which is constructed by the hypervisor, is
0007 distributed by the ACRN Hypervisor Service Module to an I/O client
0008 corresponding to the address range of the I/O request. Details of I/O request
0009 handling are described in the following sections.
0010
0011 1. I/O request
0012 --------------
0013
0014 For each User VM, there is a shared 4-KByte memory region used for I/O requests
0015 communication between the hypervisor and Service VM. An I/O request is a
0016 256-byte structure buffer, which is 'struct acrn_io_request', that is filled by
0017 an I/O handler of the hypervisor when a trapped I/O access happens in a User
0018 VM. ACRN userspace in the Service VM first allocates a 4-KByte page and passes
0019 the GPA (Guest Physical Address) of the buffer to the hypervisor. The buffer is
0020 used as an array of 16 I/O request slots with each I/O request slot being 256
0021 bytes. This array is indexed by vCPU ID.
0022
0023 2. I/O clients
0024 --------------
0025
0026 An I/O client is responsible for handling User VM I/O requests whose accessed
0027 GPA falls in a certain range. Multiple I/O clients can be associated with each
0028 User VM. There is a special client associated with each User VM, called the
0029 default client, that handles all I/O requests that do not fit into the range of
0030 any other clients. The ACRN userspace acts as the default client for each User
0031 VM.
0032
0033 Below illustration shows the relationship between I/O requests shared buffer,
0034 I/O requests and I/O clients.
0035
0036 ::
0037
0038 +------------------------------------------------------+
0039 | Service VM |
0040 |+--------------------------------------------------+ |
0041 || +----------------------------------------+ | |
0042 || | shared page ACRN userspace | | |
0043 || | +-----------------+ +------------+ | | |
0044 || +----+->| acrn_io_request |<-+ default | | | |
0045 || | | | +-----------------+ | I/O client | | | |
0046 || | | | | ... | +------------+ | | |
0047 || | | | +-----------------+ | | |
0048 || | +-|--------------------------------------+ | |
0049 ||---|----|-----------------------------------------| |
0050 || | | kernel | |
0051 || | | +----------------------+ | |
0052 || | | | +-------------+ HSM | | |
0053 || | +--------------+ | | | |
0054 || | | | I/O clients | | | |
0055 || | | | | | | |
0056 || | | +-------------+ | | |
0057 || | +----------------------+ | |
0058 |+---|----------------------------------------------+ |
0059 +----|-------------------------------------------------+
0060 |
0061 +----|-------------------------------------------------+
0062 | +-+-----------+ |
0063 | | I/O handler | ACRN Hypervisor |
0064 | +-------------+ |
0065 +------------------------------------------------------+
0066
0067 3. I/O request state transition
0068 -------------------------------
0069
0070 The state transitions of an ACRN I/O request are as follows.
0071
0072 ::
0073
0074 FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
0075
0076 - FREE: this I/O request slot is empty
0077 - PENDING: a valid I/O request is pending in this slot
0078 - PROCESSING: the I/O request is being processed
0079 - COMPLETE: the I/O request has been processed
0080
0081 An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
0082 ACRN userspace are in charge of processing the others.
0083
0084 4. Processing flow of I/O requests
0085 ----------------------------------
0086
0087 a. The I/O handler of the hypervisor will fill an I/O request with PENDING
0088 state when a trapped I/O access happens in a User VM.
0089 b. The hypervisor makes an upcall, which is a notification interrupt, to
0090 the Service VM.
0091 c. The upcall handler schedules a worker to dispatch I/O requests.
0092 d. The worker looks for the PENDING I/O requests, assigns them to different
0093 registered clients based on the address of the I/O accesses, updates
0094 their state to PROCESSING, and notifies the corresponding client to handle.
0095 e. The notified client handles the assigned I/O requests.
0096 f. The HSM updates I/O requests states to COMPLETE and notifies the hypervisor
0097 of the completion via hypercalls.
