`@return` is dedicated for brief description of return values, not for comments
stating actual return values. In addition, sphinx + breathe does not join
multiple adjacent `@return`. This results in multiple `Return` sections in the
generated document, which is confusing.
This patch replaces `@return` with `@retval` for the lists of return
values. Adjacent `@retval` can be joined into one list by breathe.
v1 -> v2:
* Replace return value descriptions like `negative` and `positive` with
expressions like `<0` and `>0` in `@retval`.
* Keep the list of `@retval` comprehensive, even when there is a `@return` to
generally describe what the return value means.
* Drop duplicated `@return` when it does not give more information than the
`@retval` list.
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
It is preferred to state the absence of a return value explicitly in the
doxygen-stile comments. Currently there are different styles of doing this,
including:
@return None
@return NULL
@return void
@return N/A
This patch unifies the above with `@return None`.
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
This patch introduce a new mode of IO request completion, polling mode.
Now, the sketch of ioreq process can be,
A. UOS vcpu0 generate PIO/MMIO ->
B. pcpu1(vcpu0 of UOS) trap into HV ->
C. pcpu1 build ioreq, send IPI and enter idle ->
D.1 pcpu0(vcpu0 of SOS) response IPI,
D.2 pcpu0 handle the ioreq in HV, kernel, DM,
D.3 pcpu0 mark ioreq as complete,
D.4 pcpu0 hypercall to enter HV ->
E.1 pcpu0 send IPI to wake pcpu1 up
E.2 UOS vcpu0 continue running
With this change, it skips D.4, E.1 steps. In step C, pcpu1 will enter a
polling ioreq state idle after send out the IPI.
It can save about ~5000 cpu cycles.
In polling mode, we do the polling in idle instead of pause cpu all the
time. It will consume more power. A better way is to use monitor/mwait
instructions which can put cpu into a sleep state with monitoring a
memory address. Unfortunately, APL has bug with monitor. We can gather
all ioreqs state into one monitorable memory and take advantage of
monitor/mwait for future platform.
The way polling or notification is per VM. We can config VMs in
different mode. By default, IO request completion will use notification
mode for all VMs. We can switch it by Kconfig.
Tracked-On: #1821
Signed-off-by: Shuo Liu <shuo.a.liu@intel.com>
Reviewed-by: Eddie Dong <eddie.dong@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
An I/O handler is not linked to the I/O access size, so in searching for
the registered I/O handler, don't need to check the I/O request's access
size.
In struct vm_io_handler_desc, change fields addr and len to port_start and
port_end respectively to adapt to this change.
Tracked-On: #1815
Signed-off-by: Zide Chen <zide.chen@intel.com>
Reviewed-by: Li, Fei1 <fei1.li@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
ioreqs acrossing VM reset is meaningless. So we reset their status when
VM reset.
Please note, device model and service os need to handle various ioreqs
pending status in emergency reset condition carefully. Otherwises, the
post processing of such ioreqs might overwrite this reset.
Tracked-On: projectacrn#1821
Signed-off-by: Shuo Liu <shuo.a.liu@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
-- Config MAX_EMULATED_MMIO_REGIONS 16 in Kconfig
-- Add emulated mmio array and emulated mmio regions
in vm structure
-- Remove mmio list in vm structure
-- Remove unregister_mmio_emulation_handler and
vioapic_cleanup APIs
Tracked-On: #861
Signed-off-by: Mingqiang Chi <mingqiang.chi@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
-- Add emulated port io index
-- Add emulated pio array in vm structure
-- Remove port list in vm structure
-- Remove free_io_emulation_resource/register_io_handler/
create_io_handler APIs
v2-->v3:
-- not add 'is_emulated', check len == 0U
-- Check if io_read/io_write handler is NULL before calling
-- Replace ENUM with MACRO for emulated pio index to avoid
MISRA-C violations
v1-->v2:
-- Remove EMUL_PIO_NUM in Kconfig, add emulated pio index
for PIC/PCI/UART/RTC/PM
Tracked-On: #861
Signed-off-by: Mingqiang Chi <mingqiang.chi@intel.com>
Reviewed-by: Jason Chen CJ <jason.cj.chen@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
For data structure types "struct vm", its name is identical
with variable name in the same scope. This is a MISRA C violation.
Naming convention rule:If the data structure type is used by multi
modules, its corresponding logic resource is exposed to external
components (such as SOS, UOS), and its name meaning is simplistic
(such as vcpu, vm), its name needs prefix "acrn_".
The following udpates are made:
struct vm *vm-->struct acrn_vm *vm
Tracked-On: #861
Signed-off-by: Xiangyang Wu <xiangyang.wu@linux.intel.com>
For data structure types "struct vcpu", its name is identical
with variable name in the same scope. This is a MISRA C violation.
Naming convention rule:If the data structure type is used by multi
modules, its corresponding logic resource is exposed to external
components (such as SOS, UOS), and its name meaning is simplistic
(such as vcpu, vm), its name needs prefix "acrn_".
The following udpates are made:
struct vcpu *vcpu-->struct acrn_vcpu *vcpu
Tracked-On: #861
Signed-off-by: Xiangyang Wu <xiangyang.wu@linux.intel.com>
This patch adds more comments to describe the structures and functions that are
public to the other components in the hypervisor. The comments are in
doxygen-style for document generation.
v2 -> v3:
* Reformat the flow in the doc for vhm_io_request.
v1 -> v2:
* Fix typos and inconsistencies in the comments.
* Wrap the text-based diagram in the doc for vhm_request in @verbatim
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
commit 026ae83bd5 ("hv: include: fix 'Unused procedure parameter'")
removed the then unused parameter handler_private_data from
hv_mem_io_handler_t because MISRA-C requires that there should be no
unused parameters in functions.
This patch removes vcpu from the parameter list as well since this may
not be used by all users. Also it brings back handler_private_data which
is more flexible. For example, vioapic_mmio_access_handler() can use it
to pass vcpu pointer.
Tracked-On: #861
Signed-off-by: dongshen <dongsheng.x.zhang@intel.com>
Signed-off-by: Zide Chen <zide.chen@intel.com>
Reviewed-by: Li, Fei1 <fei1.li@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
Fix violations whose parameter can be read-only.
This patch only fix the parameter whose name is vcpu.
Tracked-On: #861
Signed-off-by: Huihuang Shi <huihuang.shi@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
Fix violations for function whose parameter can be read-only.
Tracked-On: #861
Signed-off-by: Huihuang Shi <huihuang.shi@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
MISRA-C requires that there should be no unused parameters in
functions.
This patch removes the unused parameters that is not being used
unconditionally.
Tracked-On: #861
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
MISRA-C requires that there should be no unused parameters in
functions.
In some cases, we will keep the unused parameters.
vmexit handler is one example. It is used as function pointer.
Some of the vmexit handlers use the input parameter 'vcpu', some of
them don't. We still need to keep the unused parameters 'vcpu' for
those handlers don't use 'vcpu'.
This patch removes the unused parameters that is not being used
unconditionally.
v1 -> v2:
* remove the non-implemented API 'vlapic_id_write_handler'
Tracked-On: #861
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Now the DM has adopted the new VHM request state transitions and
REQ_STATE_FAILED is obsolete since neither VHM nor kernel mediators will set the
state to FAILED.
This patch drops the definition to REQ_STATE_FAILED in the hypervisor, makes
''processed'' unsigned to make the compiler happy about typing and simplifies
error handling in the following ways.
* (dm_)emulate_(pio|mmio)_post no longer returns an error code, by introducing a
constraint that these functions must be called after an I/O request
completes (which is the case in the current design) and assuming
handlers/VHM/DM will always give a value for reads (typically all 1's if the
requested address is invalid).
* emulate_io() now returns a positive value IOREQ_PENDING to indicate that the
request is sent to VHM. This mitigates a potential race between
dm_emulate_pio() and pio_instr_vmexit_handler() which can cause
emulate_pio_post() being called twice for the same request.
* Remove the ''processed'' member in io_request. Previously this mirrors the
state of the VHM request which terminates at either COMPLETE or FAILED. After
the FAILED state is removed, the terminal state will always be constantly
COMPLETE. Thus the mirrored ''processed'' member is no longer useful.
Note that emulate_instruction() will always succeed after a reshuffle, and this
patch takes that assumption in advance. This does not hurt as that returned
value is not currently handled.
This patch makes it explicit that I/O emulation is not expected to fail. One
issue remains, though, which occurs when a non-aligned cross-boundary access
happens. Currently the hypervisor, VHM and DM adopts different policy:
* Hypervisor: inject #GP if it detects that the access crossed boundary
* VHM: deliver to DM if the access does not complete falls in the range of a
client
* DM: a handler covering part of the to-be-accessed region is picked and
assertion failure can be triggered.
A high-level design covering all these components (in addition to instruction
emulation) is needed for this. Thus this patch does not yet cover the issue.
Tracked-On: #875
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Fix the parameter name mismatch between API declaration and definition.
v2 -> v3:
* Fix two more violations which are missed in previous report.
shell_puts and console_write
v1 -> v2:
* Replace 'ret_desc' with 'desc'
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
Reviewed-by: Junjie Mao <junjie.mao@intel.com>
Add the parameter identifier for typedef function pointer.
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
There are some functions for the post work of I/O emulation. This patch moves
these functions to io.c for clarity. No functional change introduced.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
This is the counterpart to the PIO emulation side.
1. ept_violation_vmexit_handler (entry point for handling vmexit on EPT instruction):
Extract mmio address, size, direction and value (for write only), fill in an
I/O request, invoke do_io to handle that and emulate_pio_post for
post-processing.
2. emulate_io
Handle the given I/O request, either completed by registered MMIO handlers
or sent to VHM.
3. emulate_mmio_post:
Update guest registers after the emulation is done.
v2 -> v3:
* Rename: emulate_mmio_by_handler -> hv_emulate_mmio.
* Inline the original hv_emulate_mmio.
* No longer check alignment. The handlers are responsible for handling
unaligned accesses.
v1 -> v2:
* Rename: do_io -> emulate_io.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
This patch refactors how I/O instructions are emulated, in order for a unify the
I/O emulation path. The major control flow includes:
1. pio_instr_vmexit_handler (entry point for handling vmexit on I/O instruction):
Extract port address, register size, direction and value (for write only),
fill in an I/O request (of type io_request), invokes do_io to handle that
and update the guest registers if the request has been successfully handled
when do_io returns.
2. emulate_io:
Handle the given I/O request. The request is handled or sent to VHM if it
returns 0 (the actual status can be found in io_req->processed). On errors a
negative error code is returned.
3. emulate_pio_by_handler:
Look for the PIO handler for the given request and invoke that
handler. Return 0 if a proper handler is found and invoked (the status of
the emulation can be found in io_req->processed), -EIO when the request
spans across devices, and -ENODEV when no handler is found.
4. emulate_pio_post:
Update guest registers after the emulation is done. Currently this can
happen either right after do_io() or after the vcpu is resumed. Status check
on the I/O request and follow-up actions on failure will also go here.
Note:
Currently do_io can return 0 with io_req->processed being REQ_STATE_PENDING if
the request is sent to VHM for further processing. In this case the current vcpu
will be paused after handling this vm_exit, and dm_emulate_pio_post will be
invoked to do the rest after this vcpu is resumed. When vcpus are scheduled back
to exactly where they are scheduled out later, do_io should be responsible for
the post_work and the processing of do_io results shall be mostly the same.
v2 -> v3:
* Rename: emulate_pio_by_handler -> hv_emulate_pio.
* Properly mask the value passed to port I/O handler.
v1 -> v2:
* Rename: do_io -> emulate_io.
* Rename io_instr_vmexit_handler -> pio_instr_vmexit_handler to reflect the
fact that it handles port I/O only.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Misra c required parameter should not changed in the scope
of function,use local variable to replace it.
Signed-off-by: Huihuang Shi <huihuang.shi@intel.com>
Reviewed-by: Junjie Mao <junjie.mao@intel.com>
The current struct vcpu has two members, namely 'struct vhm_request req' and
'struct mem_io mmio', that hold similar info, including the address, direction, size,
value and status of mmio reqeusts.
As a step towards a unified framework for both MMIO/PIO, this patch unifies
these two members by a tailored version of vhm_reqeust, mostly with the reserved
fields dropped. The definitions to request types, directions and process status
are reused.
Handling errors during emulations will be revisited after the I/O emulation
paths are unified. Thus for this patch the mmio.mmio_status in inherited by
io_req.processed which is not yet properly processed.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
Currently the I/O emulation structures and interfaces are scattered among mmu.h,
io.h and guest.h, and tangled with other interfaces there. This patch moves the
former to a separate header ioreq.h.
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>
