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 <xiangyang.wu@linux.intel.com>

Author: Xiangyang Wu

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,29 +146,84 @@ 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
  *   continuous
  * @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
  *   continuous
  * @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*/

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 */

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 */