From 7947b4dae8acc80e4b8674ef054184ad4c1dd492 Mon Sep 17 00:00:00 2001 From: Shuo A Liu Date: Wed, 7 Jul 2021 09:42:17 +0800 Subject: [PATCH] doc: Adapt documents to new HSM driver Tracked-On: #6282 Signed-off-by: Shuo A Liu --- devicemodel/include/public/hsm_ioctl_defs.h | 29 ++++---- doc/.known-issues/doc/dupdecl.conf | 3 + doc/developer-guides/hld/hld-devicemodel.rst | 66 ++++++++++--------- .../hld/hld-power-management.rst | 8 +-- doc/developer-guides/hld/hv-io-emulation.rst | 13 ++-- 5 files changed, 63 insertions(+), 56 deletions(-) diff --git a/devicemodel/include/public/hsm_ioctl_defs.h b/devicemodel/include/public/hsm_ioctl_defs.h index 853bb1ec0..8b5ef4b99 100644 --- a/devicemodel/include/public/hsm_ioctl_defs.h +++ b/devicemodel/include/public/hsm_ioctl_defs.h @@ -224,20 +224,7 @@ struct acrn_ioreq_notify { #define ACRN_PLATFORM_LAPIC_IDS_MAX 64 /** - * struct acrn_platform_info - Information of a platform from hypervisor - * @hw.cpu_num: Physical CPU number of the platform - * @hw.version: Version of this structure - * @hw.l2_cat_shift: Order of the number of threads sharing L2 cache - * @hw.l3_cat_shift: Order of the number of threads sharing L3 cache - * @hw.lapic_ids: IDs of LAPICs of all threads - * @hw.reserved: Reserved for alignment and should be 0 - * @sw.max_vcpus_per_vm: Maximum number of vCPU of a VM - * @sw.max_vms: Maximum number of VM - * @sw.vm_config_size: Size of configuration of a VM - * @sw.vm_configss_addr: Memory address which user space provided to - * store the VM configurations - * @sw.max_kata_containers: Maximum number of VM for Kata containers - * @sw.reserved: Reserved for alignment and should be 0 + * @brief - Information of a platform from hypervisor * * If vm_configs_addr is provided, the driver uses a bounce buffer (kmalloced * for continuous memory region) to fetch VM configurations data from the @@ -245,19 +232,33 @@ struct acrn_ioreq_notify { */ struct acrn_platform_info { struct { + /** Physical CPU number of the platform */ __u16 cpu_num; + /** Version of this structure */ __u16 version; + /** Order of the number of threads sharing L2 cache */ __u32 l2_cat_shift; + /** Order of the number of threads sharing L3 cache */ __u32 l3_cat_shift; + /** IDs of LAPICs of all threads */ __u8 lapic_ids[ACRN_PLATFORM_LAPIC_IDS_MAX]; + /** Reserved for alignment and should be 0 */ __u8 reserved[52]; } hw; struct { + /** Maximum number of vCPU of a VM */ __u16 max_vcpus_per_vm; + /** Maximum number of VM */ __u16 max_vms; + /** Size of configuration of a VM */ __u32 vm_config_size; + + /** Memory address which user space provided to + * store the VM configurations + */ void *vm_configs_addr; + /** Maximum number of VM for Kata containers */ __u64 max_kata_containers; __u8 reserved[104]; } sw; diff --git a/doc/.known-issues/doc/dupdecl.conf b/doc/.known-issues/doc/dupdecl.conf index 15092e9a9..500ba2a90 100644 --- a/doc/.known-issues/doc/dupdecl.conf +++ b/doc/.known-issues/doc/dupdecl.conf @@ -12,3 +12,6 @@ # ^(?P[-._/\w]+/hld/[-._/\w]+.rst):(?P[0-9]+): WARNING: Duplicate C[\+]* declaration, .* ^Declaration is .* +# +^(?P[-._/\w]+/api/[-._/\w]+.rst):(?P[0-9]+): WARNING: Duplicate C[\+]* declaration, .* +^Declaration is .* diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst index 35a169275..a0621ca84 100644 --- a/doc/developer-guides/hld/hld-devicemodel.rst +++ b/doc/developer-guides/hld/hld-devicemodel.rst @@ -232,46 +232,52 @@ DM Initialization .. code-block:: c - vm_loop(struct vmctx *ctx) - { - int error; + vm_loop(struct vmctx *ctx) + { + int error; - ctx->ioreq_client = vm_create_ioreq_client(ctx); - assert(ctx->ioreq_client > 0); + ctx->ioreq_client = vm_create_ioreq_client(ctx); + if (ctx->ioreq_client < 0) { + pr_err("%s, failed to create IOREQ.\n", __func__); + return; + } - error = vm_run(ctx); - assert(error == 0); + if (vm_run(ctx) != 0) { + pr_err("%s, failed to run VM.\n", __func__); + return; + } - while (1) { - int vcpu_id; - struct vhm_request *vhm_req; + while (1) { + int vcpu_id; + struct acrn_io_request *io_req; - error = vm_attach_ioreq_client(ctx); - if (error) - break; + error = vm_attach_ioreq_client(ctx); + if (error) + break; - for (vcpu_id = 0; vcpu_id < 4; vcpu_id++) { - vhm_req = &vhm_req_buf[vcpu_id]; - if ((atomic_load(&vhm_req->processed) == REQ_STATE_PROCESSING) - && (vhm_req->client == ctx->ioreq_client)) - handle_vmexit(ctx, vhm_req, vcpu_id); - } + for (vcpu_id = 0; vcpu_id < guest_ncpus; vcpu_id++) { + io_req = &ioreq_buf[vcpu_id]; + if ((atomic_load(&io_req->processed) == ACRN_IOREQ_STATE_PROCESSING) + && !io_req->kernel_handled) + handle_vmexit(ctx, io_req, vcpu_id); + } - if (VM_SUSPEND_FULL_RESET == vm_get_suspend_mode() || + if (VM_SUSPEND_FULL_RESET == vm_get_suspend_mode() || VM_SUSPEND_POWEROFF == vm_get_suspend_mode()) { break; - } + } - if (VM_SUSPEND_SYSTEM_RESET == vm_get_suspend_mode()) { - vm_system_reset(ctx); - } + /* RTVM can't be reset */ + if ((VM_SUSPEND_SYSTEM_RESET == vm_get_suspend_mode()) && (!is_rtvm)) { + vm_system_reset(ctx); + } - if (VM_SUSPEND_SUSPEND == vm_get_suspend_mode()) { - vm_suspend_resume(ctx); - } - } - printf("VM loop exit\n"); - } + if (VM_SUSPEND_SUSPEND == vm_get_suspend_mode()) { + vm_suspend_resume(ctx); + } + } + pr_err("VM loop exit\n"); + } - **Mevent Dispatch Loop**: It's the final loop of the main acrn-dm thread. mevent dispatch will do polling for potential async diff --git a/doc/developer-guides/hld/hld-power-management.rst b/doc/developer-guides/hld/hld-power-management.rst index 21e75ad81..3ea3728ea 100644 --- a/doc/developer-guides/hld/hld-power-management.rst +++ b/doc/developer-guides/hld/hld-power-management.rst @@ -26,7 +26,7 @@ Hypervisor module named CPU state table: .. code-block:: c - struct cpu_px_data { + struct cpu_pstate_data { uint64_t core_frequency; /* megahertz */ uint64_t power; /* milliWatts */ uint64_t transition_latency; /* microseconds */ @@ -35,7 +35,7 @@ Hypervisor module named CPU state table: uint64_t status; /* success indicator */ } __attribute__((aligned(8))); - struct acpi_generic_address { + struct acrn_acpi_generic_address { uint8_t space_id; uint8_t bit_width; uint8_t bit_offset; @@ -43,8 +43,8 @@ Hypervisor module named CPU state table: uint64_t address; } __attribute__((aligned(8))); - struct cpu_cx_data { - struct acpi_generic_address cx_reg; + struct cpu_cstate_data { + struct acrn_acpi_generic_address cx_reg; uint8_t type; uint32_t latency; uint64_t power; diff --git a/doc/developer-guides/hld/hv-io-emulation.rst b/doc/developer-guides/hld/hv-io-emulation.rst index e45ac0d82..8baa0457a 100644 --- a/doc/developer-guides/hld/hv-io-emulation.rst +++ b/doc/developer-guides/hld/hv-io-emulation.rst @@ -265,23 +265,20 @@ Data Structures and Interfaces External Interfaces =================== -The following structures represent an I/O request. *struct vhm_request* +The following structures represent an I/O request. *struct acrn_io_request* is the main structure and the others are detailed representations of I/O requests of different kinds. -.. doxygenstruct:: mmio_request +.. doxygenstruct:: acrn_mmio_request :project: Project ACRN -.. doxygenstruct:: pio_request +.. doxygenstruct:: acrn_pio_request :project: Project ACRN -.. doxygenstruct:: pci_request +.. doxygenstruct:: acrn_pci_request :project: Project ACRN -.. doxygenunion:: vhm_io_request - :project: Project ACRN - -.. doxygenstruct:: vhm_request +.. doxygenstruct:: acrn_io_request :project: Project ACRN For hypercalls related to I/O emulation, refer to `I/O Emulation in the Hypervisor`_.