From 7c3c6ea442566ea5d5b0ac394a2d60b55fb232c8 Mon Sep 17 00:00:00 2001 From: Xiangyang Wu Date: Wed, 31 Oct 2018 11:24:31 +0800 Subject: [PATCH] HV:MM:add API docs This patch adds more comment to describe functions that are interfaces to the other modules in the hypervisor. The comments are in doxygen-style for document generation. V1-->V2: Rebase Tracked-On: #1595 Signed-off-by: Xiangyang Wu --- hypervisor/include/arch/x86/guest/guest.h | 69 ++++++++- hypervisor/include/arch/x86/mmu.h | 167 +++++++++++++++++++++- hypervisor/include/arch/x86/mtrr.h | 41 +++++- hypervisor/include/arch/x86/pgtable.h | 31 +++- 4 files changed, 294 insertions(+), 14 deletions(-) diff --git a/hypervisor/include/arch/x86/guest/guest.h b/hypervisor/include/arch/x86/guest/guest.h index 5b6d56ca0..063cfaddf 100644 --- a/hypervisor/include/arch/x86/guest/guest.h +++ b/hypervisor/include/arch/x86/guest/guest.h @@ -3,7 +3,11 @@ * * SPDX-License-Identifier: BSD-3-Clause */ - +/** + * @file guest.h + * + * @brief Data transferring between hypervisor and VM + */ #ifndef GUEST_H #define GUEST_H @@ -142,8 +146,24 @@ int general_sw_loader(struct vm *vm); typedef int (*vm_sw_loader_t)(struct vm *vm); extern vm_sw_loader_t vm_sw_loader; - -/* @pre Caller(Guest) should make sure gpa is continuous. +/** + * @brief Data transfering between hypervisor and VM + * + * @defgroup acrn_mem ACRN Memory Management + * @{ + */ +/** + * @brief Copy data from VM GPA space to HV address space + * + * @param[in] vm The pointer that points to VM data structure + * @param[in] h_ptr The pointer that points the start HV address + * of HV memory region which data is stored in + * @param[out] gpa The start GPA address of GPA memory region which data + * will be copied into + * @param[in] size The size (bytes) of GPA memory region which data is + * stored in + * + * @pre Caller(Guest) should make sure gpa is continuous. * - gpa from hypercall input which from kernel stack is gpa continuous, not * support kernel stack from vmap * - some other gpa from hypercall parameters, VHM should make sure it's @@ -151,7 +171,18 @@ extern vm_sw_loader_t vm_sw_loader; * @pre Pointer vm is non-NULL */ int copy_from_gpa(struct vm *vm, void *h_ptr, uint64_t gpa, uint32_t size); -/* @pre Caller(Guest) should make sure gpa is continuous. +/** + * @brief Copy data from HV address space to VM GPA space + * + * @param[in] vm The pointer that points to VM data structure + * @param[in] h_ptr The pointer that points the start HV address + * of HV memory region which data is stored in + * @param[out] gpa The start GPA address of GPA memory region which data + * will be copied into + * @param[in] size The size (bytes) of GPA memory region which data will be + * copied into + * + * @pre Caller(Guest) should make sure gpa is continuous. * - gpa from hypercall input which from kernel stack is gpa continuous, not * support kernel stack from vmap * - some other gpa from hypercall parameters, VHM should make sure it's @@ -159,12 +190,40 @@ int copy_from_gpa(struct vm *vm, void *h_ptr, uint64_t gpa, uint32_t size); * @pre Pointer vm is non-NULL */ int copy_to_gpa(struct vm *vm, void *h_ptr, uint64_t gpa, uint32_t size); +/** + * @brief Copy data from VM GVA space to HV address space + * + * @param[in] vcpu The pointer that points to vcpu data structure + * @param[out] h_ptr The pointer that returns the start HV address + * of HV memory region which data will be copied to + * @param[in] gva The start GVA address of GVA memory region which data + * is stored in + * @param[in] size The size (bytes) of GVA memory region which data is + * stored in + * @param[out] err_code The page fault flags + * @param[out] fault_addr The GVA address that causes a page fault + */ int copy_from_gva(struct vcpu *vcpu, void *h_ptr, uint64_t gva, uint32_t size, uint32_t *err_code, uint64_t *fault_addr); +/** + * @brief Copy data from HV address space to VM GVA space + * + * @param[in] vcpu The pointer that points to vcpu data structure + * @param[in] h_ptr The pointer that points the start HV address + * of HV memory region which data is stored in + * @param[out] gva The start GVA address of GVA memory region which data + * will be copied into + * @param[in] size The size (bytes) of GVA memory region which data will + * be copied into + * @param[out] err_code The page fault flags + * @param[out] fault_addr The GVA address that causes a page fault + */ int copy_to_gva(struct vcpu *vcpu, void *h_ptr, uint64_t gva, uint32_t size, uint32_t *err_code, uint64_t *fault_addr); extern struct acrn_vcpu_regs vm0_boot_context; - +/** + * @} + */ #endif /* !ASSEMBLER */ #endif /* GUEST_H*/ diff --git a/hypervisor/include/arch/x86/mmu.h b/hypervisor/include/arch/x86/mmu.h index 1fa9eee7f..2fe65d49c 100644 --- a/hypervisor/include/arch/x86/mmu.h +++ b/hypervisor/include/arch/x86/mmu.h @@ -3,10 +3,19 @@ * * SPDX-License-Identifier: BSD-3-Clause */ - +/** + * @file mmu.h + * + * @brief APIs for Memory Management module + */ #ifndef MMU_H #define MMU_H - +/** + * @brief Memory Management + * + * @defgroup acrn_mem ACRN Memory Management + * @{ + */ /** The flag that indicates that the page fault was caused by a non present * page. */ @@ -54,11 +63,25 @@ static inline uint64_t round_page_down(uint64_t addr) return (addr & CPU_PAGE_MASK); } -/* Represent the 4 levels of translation tables in IA-32e paging mode */ +/** + * @brief Page tables level in IA32 paging mode + */ enum _page_table_level { + /** + * @brief The PML4 level in the page tables + */ IA32E_PML4 = 0, + /** + * @brief The Page-Directory-Pointer-Table level in the page tables + */ IA32E_PDPT = 1, + /** + * @brief The Page-Directory level in the page tables + */ IA32E_PD = 2, + /** + * @brief The Page-Table level in the page tables + */ IA32E_PT = 3, }; @@ -69,18 +92,74 @@ enum _page_table_level { void sanitize_pte_entry(uint64_t *ptep); void sanitize_pte(uint64_t *pt_page); +/** + * @brief MMU paging enable + * + * @return None + */ void enable_paging(void); +/** + * @brief Supervisor-mode execution prevention (SMEP) enable + * + * @return None + */ void enable_smep(void); +/** + * @brief MMU page tables initialization + * + * @return None + */ void init_paging(void); void mmu_add(uint64_t *pml4_page, uint64_t paddr_base, uint64_t vaddr_base, uint64_t size, uint64_t prot, const struct memory_ops *mem_ops); void mmu_modify_or_del(uint64_t *pml4_page, uint64_t vaddr_base, uint64_t size, uint64_t prot_set, uint64_t prot_clr, const struct memory_ops *mem_ops, uint32_t type); +/** + * @brief EPT and VPID capability checking + * + * @return 0 - on success + * @return -ENODEV - Don't support EPT or VPID capability + */ int check_vmx_mmu_cap(void); +/** + * @brief VPID allocation + * + * @return 0 - VPID overflow + * @return more than 0 - the valid VPID + */ uint16_t allocate_vpid(void); +/** + * @brief Specified signle VPID flush + * + * @param[in] vpid the specified VPID + * + * @return None + */ void flush_vpid_single(uint16_t vpid); +/** + * @brief All VPID flush + * + * @return None + */ void flush_vpid_global(void); +/** + * @brief Guest-physical mappings and combined mappings invalidation + * + * @param[in] vcpu the pointer that points the vcpu data structure + * + * @return None + */ void invept(const struct vcpu *vcpu); +/** + * @brief Host-physical address continous checking + * + * @param[in] vm the pointer that points the VM data structure + * @param[in] gpa_arg the start GPA address of the guest memory region + * @param[in] size_arg the size of the guest memory region + * + * @return true - The HPA of the guest memory region is continuous + * @return false - The HPA of the guest memory region is non-continuous + */ bool check_continuous_hpa(struct vm *vm, uint64_t gpa_arg, uint64_t size_arg); /** *@pre (pml4_page != NULL) && (pg_size != NULL) @@ -128,33 +207,115 @@ static inline void clflush(volatile void *p) #define INVALID_HPA (0x1UL << 52U) #define INVALID_GPA (0x1UL << 52U) /* External Interfaces */ +/** + * @brief EPT page tables destroy + * + * @param[inout] vm the pointer that points to VM data structure + * + * @return None + */ void destroy_ept(struct vm *vm); /** + * @brief Translating from guest-physical address to host-physcial address + * + * @param[in] vm the pointer that points to VM data structure + * @param[in] gpa the specified guest-physical address + * * @return INVALID_HPA - the HPA of parameter gpa is unmapping * @return hpa - the HPA of parameter gpa is hpa */ uint64_t gpa2hpa(struct vm *vm, uint64_t gpa); /** + * @brief Translating from guest-physical address to host-physcial address + * + * @param[in] vm the pointer that points to VM data structure + * @param[in] gpa the specified guest-physical address + * @param[out] size the pointer that returns the page size of + * the page in which the gpa is + * * @return INVALID_HPA - the HPA of parameter gpa is unmapping * @return hpa - the HPA of parameter gpa is hpa */ uint64_t local_gpa2hpa(struct vm *vm, uint64_t gpa, uint32_t *size); /** + * @brief Translating from host-physical address to guest-physical address for VM0 + * + * @param[in] hpa the specified host-physical address + * * @pre: the gpa and hpa are identical mapping in SOS. */ uint64_t vm0_hpa2gpa(uint64_t hpa); +/** + * @brief Guest-physical memory region mapping + * + * @param[in] vm the pointer that points to VM data structure + * @param[in] pml4_page The physical address of The EPTP + * @param[in] hpa The specified start host physical address of host + * physical memory region that GPA will be mapped + * @param[in] gpa The specified start guest physical address of guest + * physical memory region that needs to be mapped + * @param[in] size The size of guest physical memory region that needs + * to be mapped + * @param[in] prot_orig The specified memory access right and memory type + * + * @return None + */ void ept_mr_add(struct vm *vm, uint64_t *pml4_page, uint64_t hpa, uint64_t gpa, uint64_t size, uint64_t prot_orig); +/** + * @brief Guest-physical memory page access right or memory type updating + * + * @param[in] vm the pointer that points to VM data structure + * @param[in] pml4_page The physical address of The EPTP + * @param[in] gpa The specified start guest physical address of guest + * physical memory region whoes mapping needs to be updated + * @param[in] size The size of guest physical memory region + * @param[in] prot_set The specified memory access right and memory type + * that will be set + * @param[in] prot_clr The specified memory access right and memory type + * that will be cleared + * + * @return None + */ void ept_mr_modify(struct vm *vm, uint64_t *pml4_page, uint64_t gpa, uint64_t size, uint64_t prot_set, uint64_t prot_clr); /** + * @brief Guest-physical memory region unmapping + * + * @param[in] vm the pointer that points to VM data structure + * @param[in] pml4_page The physical address of The EPTP + * @param[in] gpa The specified start guest physical address of guest + * physical memory region whoes mapping needs to be deleted + * @param[in] size The size of guest physical memory region + * + * @return None + * * @pre [gpa,gpa+size) has been mapped into host physical memory region */ void ept_mr_del(struct vm *vm, uint64_t *pml4_page, uint64_t gpa, uint64_t size); +/** + * @brief EPT violation handling + * + * @param[in] vcpu the pointer that points to vcpu data structure + * + * @return -EINVAL - fail to handle the EPT violation + * @return 0 - Success to handle the EPT violation + */ int ept_violation_vmexit_handler(struct vcpu *vcpu); +/** + * @brief EPT misconfiguration handling + * + * @param[in] vcpu the pointer that points to vcpu data structure + * + * @return -EINVAL - fail to handle the EPT misconfig + * @return 0 - Success to handle the EPT misconfig + */ int ept_misconfig_vmexit_handler(__unused struct vcpu *vcpu); +/** + * @} + */ #endif /* ASSEMBLER not defined */ #endif /* MMU_H */ diff --git a/hypervisor/include/arch/x86/mtrr.h b/hypervisor/include/arch/x86/mtrr.h index 3045e3fe1..d299a0ef1 100644 --- a/hypervisor/include/arch/x86/mtrr.h +++ b/hypervisor/include/arch/x86/mtrr.h @@ -2,10 +2,19 @@ * Copyright (C) <2018> Intel Corporation * SPDX-License-Identifier: BSD-3-Clause */ - +/** + * @file mtrr.h + * + * @brief MTRR Virtualization + */ #ifndef MTRR_H #define MTRR_H - +/** + * @brief MTRR Virtualization + * + * @addtogroup acrn_mem ACRN Memory Management + * @{ + */ #define FIXED_RANGE_MTRR_NUM 11U #define MTRR_SUB_RANGE_NUM 8U @@ -44,8 +53,34 @@ struct mtrr_state { union mtrr_fixed_range_reg fixed_range[FIXED_RANGE_MTRR_NUM]; }; +/** + * @brief Virtual MTRR MSR write + * + * @param[inout] vcpu The pointer that points VCPU data structure + * @param[in] msr Virtual MTRR MSR Address + * @param[in] value The value that will be writen into virtual MTRR MSR + * + * @return None + */ void mtrr_wrmsr(struct vcpu *vcpu, uint32_t msr, uint64_t value); +/** + * @brief Virtual MTRR MSR read + * + * @param[in] vcpu The pointer that points VCPU data structure + * @param[in] msr Virtual MTRR MSR Address + * + * @return unsigned long integer - The specified virtual MTRR MSR value + */ uint64_t mtrr_rdmsr(const struct vcpu *vcpu, uint32_t msr); +/** + * @brief Virtual MTRR initialization + * + * @param[inout] vcpu The pointer that points VCPU data structure + * + * @return None + */ void init_mtrr(struct vcpu *vcpu); - +/** + * @} + */ #endif /* MTRR_H */ diff --git a/hypervisor/include/arch/x86/pgtable.h b/hypervisor/include/arch/x86/pgtable.h index 7c4f5f6b2..b0570c917 100644 --- a/hypervisor/include/arch/x86/pgtable.h +++ b/hypervisor/include/arch/x86/pgtable.h @@ -3,7 +3,11 @@ * * SPDX-License-Identifier: BSD-3-Clause */ - +/** + * @file pgtable.h + * + * @brief Address translation and page table operations + */ #ifndef PGTABLE_H #define PGTABLE_H @@ -66,13 +70,31 @@ #define PML4E_PFN_MASK 0x0000FFFFFFFFF000UL #define PDPTE_PFN_MASK 0x0000FFFFFFFFF000UL #define PDE_PFN_MASK 0x0000FFFFFFFFF000UL - +/** + * @brief Address space translation + * + * @addtogroup acrn_mem ACRN Memory Management + * @{ + */ /* hpa <--> hva, now it is 1:1 mapping */ +/** + * @brief Translate host-physical address to host-virtual address + * + * @param[in] x The specified host-physical address + * + * @return void pointer - The host-virtual address + */ static inline void *hpa2hva(uint64_t x) { return (void *)x; } - +/** + * @brief Translate host-virtual address to host-physical address + * + * @param[in] x The specified host-virtual address + * + * @return unsigned long integer - The host-physical address + */ static inline uint64_t hva2hpa(void *x) { return (uint64_t)x; @@ -159,4 +181,7 @@ static inline uint64_t pdpte_large(uint64_t pdpte) return pdpte & PAGE_PSE; } +/** + * @} + */ #endif /* PGTABLE_H */