From 474496fc0e6fb031b445c4c14fb633a3683be448 Mon Sep 17 00:00:00 2001 From: Shiqing Gao Date: Tue, 7 May 2019 16:52:39 +0800 Subject: [PATCH] doc: remove hard-coded interfaces in .rst files This patch removes hard-coded interfaces in .rst files and refers to the definition via doxygen style comments. This patch mainly focus on Hypervisor part. Other parts will be covered in seperate patches. Tracked-On: #1595 Signed-off-by: Shiqing Gao --- doc/developer-guides/hld/hv-interrupt.rst | 91 +++---------------- doc/developer-guides/hld/hv-memmgt.rst | 54 ++--------- .../hld/hv-virt-interrupt.rst | 9 +- hypervisor/include/arch/x86/guest/vcpu.h | 47 +++++++++- hypervisor/include/arch/x86/ioapic.h | 26 ++++++ hypervisor/include/arch/x86/irq.h | 57 ++++++++---- hypervisor/include/arch/x86/lapic.h | 63 +++++++++++-- hypervisor/include/arch/x86/pgtable.h | 70 +++++++++++++- 8 files changed, 255 insertions(+), 162 deletions(-) diff --git a/doc/developer-guides/hld/hv-interrupt.rst b/doc/developer-guides/hld/hv-interrupt.rst index 424bec8d7..681498ba1 100644 --- a/doc/developer-guides/hld/hv-interrupt.rst +++ b/doc/developer-guides/hld/hv-interrupt.rst @@ -386,71 +386,29 @@ IOAPIC The following APIs are external interfaces for IOAPIC related operations. -.. code-block:: c +.. doxygengroup:: ioapic_ext_apis + :project: Project ACRN + :content-only: - void ioapic_get_rte(uint32_t irq, union ioapic_rte *rte) - /* get the redirection table entry of an irq. */ - - void ioapic_set_rte(uint32_t irq, union ioapic_rte rte) - /* Set the redirection table entry of an irq. */ - - uint32_t pin_to_irq(uint8_t pin) - /* Get irq num from physical irq pin num */ - - void suspend_ioapic(void) - /* Suspended ioapic, mainly save the RTEs. */ - - void resume_ioapic(void) - /* Resume ioapic, mainly restore the RTEs. */ - - int get_ioapic_info(char *str_arg, int str_max_len) - /* Dump information of ioapic for debug, such as irq num, pin, - * RTE, vector, trigger mode etc. For debugging only. - */ LAPIC ===== The following APIs are external interfaces for LAPIC related operations. -.. code-block:: c +.. doxygengroup:: lapic_ext_apis + :project: Project ACRN + :content-only: - void write_lapic_reg32(uint32_t offset, uint32_t value) - /* Write to lapic register. */ - - void early_init_lapic(void) - /* To get the local apic base addr, map lapic registers and check the - * xAPIC/x2APIC capability. - */ - - void save_lapic(struct lapic_regs *regs) - /* Save context of lapic before entering s3. */ - - void restore_lapic(struct lapic_regs *regs) - /* Restore context of lapic when resume from s3. */ - - void resume_lapic(void) - /* Resume lapic by setting the apic base addr and restore the registers. */ - - uint8_t get_cur_lapic_id(void) - /* Get the lapic id. */ IPI === The following APIs are external interfaces for IPI related operations. -.. code-block:: c - - void send_startup_ipi(enum intr_cpu_startup_shorthand cpu_startup_shorthand, - uint16_t dest_pcpu_id, uint64_t cpu_startup_start_address) - /* Send an SIPI to a specific cpu, to notify the cpu to start booting. */ - - void send_dest_ipi(uint32_t dest, uint32_t vector, uint32_t dest_mode) - /* Send an IPI to a specific cpu with dest mode specified. */ - - void send_single_ipi(uint16_t pcpu_id, uint32_t vector) - /* Send an IPI to a specific cpu with physical dest mode. */ +.. doxygengroup:: ipi_ext_apis + :project: Project ACRN + :content-only: Physical Interrupt @@ -459,32 +417,7 @@ Physical Interrupt The following APIs are external interfaces for physical interrupt related operations. -.. code-block:: c +.. doxygengroup:: phys_int_ext_apis + :project: Project ACRN + :content-only: - int32_t request_irq(uint32_t req_irq, irq_action_t action_fn, void *priv_data, - uint32_t flags) - /* Request interrupt num if not specified, and register irq action for the - * specified/allocated irq. - */ - - void free_irq(uint32_t irq) - /* Free irq num and unregister the irq action. */ - - void set_irq_trigger_mode(uint32_t irq, bool is_level_triggered) - /* Set the irq trigger mode: edge-triggered or level-triggered */ - - uint32_t irq_to_vector(uint32_t irq) - /* Convert irq num to vector */ - - void get_cpu_interrupt_info(char *str_arg, int str_max) - /* To dump interrupt statistics info, such as irq num, vector, - * irq count on each physical cpu. - */ - - void dispatch_interrupt(struct intr_excp_ctx *ctx) - /* To dispatch an interrupt, an action callback will be called if registered. */ - - void init_interrupt(uint16_t pcpu_id) - /* To do interrupt initialization for a cpu, will be called for - * each physical cpu. - */ diff --git a/doc/developer-guides/hld/hv-memmgt.rst b/doc/developer-guides/hld/hv-memmgt.rst index 57e2b7512..e7ba8c64b 100644 --- a/doc/developer-guides/hld/hv-memmgt.rst +++ b/doc/developer-guides/hld/hv-memmgt.rst @@ -165,20 +165,6 @@ of physical memory management. Data Flow of Hypervisor Physical Memory Management -Data Structure Design -===================== - -The page tables operation type: - -.. code-block:: c - - enum _page_table_type { - - PTT_HOST = 0, /* Operations for MMU page tables */ - PTT_EPT = 1, /* Operations for EPT page tables */ - PAGETABLE_TYPE_UNKNOWN, /* Page tables operation type is unknown */ - }; - Interfaces Design ================= @@ -354,44 +340,18 @@ the memory virtualization unit. Data Structure Design ===================== -EPT Memory Type Data Definition: +EPT Memory Type Definition: -.. code-block:: c - - /* EPT memory type is specified in bits 5:3 of the last EPT - * paging-structure entry */ - #define EPT_MT_SHIFT 3U - - /* EPT memory type is uncacheable */ - #define EPT_UNCACHED (0UL << EPT_MT_SHIFT) - - /* EPT memory type is write combining */ - #define EPT_WC (1UL << EPT_MT_SHIFT) - - /* EPT memory type is write through */ - #define EPT_WT (4UL << EPT_MT_SHIFT) - - /* EPT memory type is write protected */ - #define EPT_WP (5UL << EPT_MT_SHIFT) - - /* EPT memory type is write back */ - #define EPT_WB (6UL << EPT_MT_SHIFT) +.. doxygengroup:: ept_mem_type + :project: Project ACRN + :content-only: EPT Memory Access Right Definition: -.. code-block:: c +.. doxygengroup:: ept_mem_access_right + :project: Project ACRN + :content-only: - /* EPT memory access right is read-only */ - #define EPT_RD (1UL << 0U) - - /* EPT memory access right is read/write */ - #define EPT_WR (1UL << 1U) - - /* EPT memory access right is executable */ - #define EPT_EXE (1UL << 2U) - - /* EPT memory access right is read/write and executable */ - define EPT_RWX (EPT_RD | EPT_WR | EPT_EXE) Interfaces Design ================= diff --git a/doc/developer-guides/hld/hv-virt-interrupt.rst b/doc/developer-guides/hld/hv-virt-interrupt.rst index cf0df9837..49185a8af 100644 --- a/doc/developer-guides/hld/hv-virt-interrupt.rst +++ b/doc/developer-guides/hld/hv-virt-interrupt.rst @@ -45,12 +45,9 @@ requests such as flush EPT. The eventid supported for virtual interrupt injection includes: -.. code-block:: c - - #define ACRN_REQUEST_EXCP 0 /* request for exception injection */ - #define ACRN_REQUEST_EVENT 1 /* vLAPIC event */ - #define ACRN_REQUEST_EXTINT 2 /* external interrupt from vPIC */ - #define ACRN_REQUEST_NMI 3 /* non-maskable interrupt */ +.. doxygengroup:: virt_int_injection + :project: Project ACRN + :content-only: The *vcpu_make_request* is necessary for a virtual interrupt diff --git a/hypervisor/include/arch/x86/guest/vcpu.h b/hypervisor/include/arch/x86/guest/vcpu.h index 26d8f2442..f2091fa66 100644 --- a/hypervisor/include/arch/x86/guest/vcpu.h +++ b/hypervisor/include/arch/x86/guest/vcpu.h @@ -71,14 +71,59 @@ /* * VCPU related APIs */ + +/** + * @defgroup virt_int_injection Event ID supported for virtual interrupt injection + * + * This is a group that includes Event ID supported for virtual interrupt injection. + * + * @{ + */ + +/** + * @brief Request for exception injection + */ #define ACRN_REQUEST_EXCP 0U + +/** + * @brief Request for vLAPIC event + */ #define ACRN_REQUEST_EVENT 1U + +/** + * @brief Request for external interrupt from vPIC + */ #define ACRN_REQUEST_EXTINT 2U + +/** + * @brief Request for non-maskable interrupt + */ #define ACRN_REQUEST_NMI 3U + +/** + * @brief Request for EOI exit bitmap update + */ #define ACRN_REQUEST_EOI_EXIT_BITMAP_UPDATE 4U + +/** + * @brief Request for EPT flush + */ #define ACRN_REQUEST_EPT_FLUSH 5U + +/** + * @brief Request for triple fault + */ #define ACRN_REQUEST_TRP_FAULT 6U -#define ACRN_REQUEST_VPID_FLUSH 7U /* flush vpid tlb */ + +/** + * @brief Request for VPID TLB flush + */ +#define ACRN_REQUEST_VPID_FLUSH 7U + +/** + * @} + */ +/* End of virt_int_injection */ #define save_segment(seg, SEG_NAME) \ { \ diff --git a/hypervisor/include/arch/x86/ioapic.h b/hypervisor/include/arch/x86/ioapic.h index fe2468bd1..249a890bd 100644 --- a/hypervisor/include/arch/x86/ioapic.h +++ b/hypervisor/include/arch/x86/ioapic.h @@ -25,10 +25,20 @@ uint32_t ioapic_irq_to_pin(uint32_t irq); int32_t init_ioapic_id_info(void); uint8_t ioapic_irq_to_ioapic_id(uint32_t irq); +/** + * @defgroup ioapic_ext_apis IOAPIC External Interfaces + * + * This is a group that includes IOAPIC External Interfaces. + * + * @{ + */ + /** * @brief Get irq num from pin num * * @param[in] pin The pin number + * + * @return irq number */ uint32_t ioapic_pin_to_irq(uint32_t pin); @@ -54,9 +64,25 @@ void ioapic_set_rte(uint32_t irq, union ioapic_rte rte); */ void ioapic_get_rte(uint32_t irq, union ioapic_rte *rte); +/** + * @brief Suspend ioapic + * + * Suspend ioapic, mainly save the RTEs. + */ void suspend_ioapic(void); + +/** + * @brief Resume ioapic + * + * Resume ioapic, mainly restore the RTEs. + */ void resume_ioapic(void); +/** + * @} + */ +/* End of ioapic_ext_apis */ + void ioapic_gsi_mask_irq(uint32_t irq); void ioapic_gsi_unmask_irq(uint32_t irq); diff --git a/hypervisor/include/arch/x86/irq.h b/hypervisor/include/arch/x86/irq.h index 1b2da09fc..84cbafd9c 100644 --- a/hypervisor/include/arch/x86/irq.h +++ b/hypervisor/include/arch/x86/irq.h @@ -90,7 +90,6 @@ void smp_call_function(uint64_t mask, smp_call_func_t func, void *data); void init_default_irqs(uint16_t cpu_id); void dispatch_exception(struct intr_excp_ctx *ctx); -void dispatch_interrupt(const struct intr_excp_ctx *ctx); void setup_notification(void); void setup_posted_intr_notification(void); @@ -101,14 +100,6 @@ extern spurious_handler_t spurious_handler; uint32_t alloc_irq_num(uint32_t req_irq); uint32_t alloc_irq_vector(uint32_t irq); - -/** - * @brief Get vector number of an interupt from irq number - * - * @param[in] irq The irq_num to convert - */ -uint32_t irq_to_vector(uint32_t irq); - /* RFLAGS */ #define HV_ARCH_VCPU_RFLAGS_IF (1UL<<9U) #define HV_ARCH_VCPU_RFLAGS_RF (1UL<<16U) @@ -219,15 +210,6 @@ int32_t interrupt_window_vmexit_handler(struct acrn_vcpu *vcpu); int32_t external_interrupt_vmexit_handler(struct acrn_vcpu *vcpu); int32_t acrn_handle_pending_request(struct acrn_vcpu *vcpu); -/** - * @brief Initialize the interrupt - * - * To do interrupt initialization for a cpu, will be called for each physical cpu. - * - * @param[in] pcpu_id The id of physical cpu to initialize - */ -void init_interrupt(uint16_t pcpu_id); - void cancel_event_injection(struct acrn_vcpu *vcpu); extern uint64_t irq_alloc_bitmap[IRQ_ALLOC_BITMAP_SIZE]; @@ -255,6 +237,14 @@ struct irq_desc { #endif }; +/** + * @defgroup phys_int_ext_apis Physical Interrupt External Interfaces + * + * This is a group that includes Physical Interrupt External Interfaces. + * + * @{ + */ + /** * @brief Request an interrupt * @@ -295,6 +285,37 @@ void free_irq(uint32_t irq); */ void set_irq_trigger_mode(uint32_t irq, bool is_level_triggered); +/** + * @brief Get vector number of an interrupt from irq number + * + * @param[in] irq The irq_num to convert + * + * @return vector number + */ +uint32_t irq_to_vector(uint32_t irq); + +/** + * @brief Dispatch interrupt + * + * To dispatch an interrupt, an action callback will be called if registered. + * + * @param ctx Pointer to interrupt exception context + */ +void dispatch_interrupt(const struct intr_excp_ctx *ctx); + +/** + * @brief Initialize interrupt + * + * To do interrupt initialization for a cpu, will be called for each physical cpu. + * + * @param[in] pcpu_id The id of physical cpu to initialize + */ +void init_interrupt(uint16_t pcpu_id); + +/** + * @} + */ +/* End of phys_int_ext_apis */ /** * @} diff --git a/hypervisor/include/arch/x86/lapic.h b/hypervisor/include/arch/x86/lapic.h index 57e0f1f01..5e490b8c4 100644 --- a/hypervisor/include/arch/x86/lapic.h +++ b/hypervisor/include/arch/x86/lapic.h @@ -76,22 +76,67 @@ union apic_icr { }; /** - * @brief Save context of lapic + * @defgroup lapic_ext_apis LAPIC External Interfaces + * + * This is a group that includes LAPIC External Interfaces. + * + * @{ + */ + +/** + * @brief Save context of LAPIC * * @param[inout] regs Pointer to struct lapic_regs to hold the - * context of current lapic + * context of current LAPIC */ void save_lapic(struct lapic_regs *regs); + +/** + * @brief Enable LAPIC in x2APIC mode + * + * Enable LAPIC in x2APIC mode via MSR writes. + * + */ void early_init_lapic(void); + +/** + * @brief Suspend LAPIC + * + * Suspend LAPIC by getting the APIC base addr and saving the registers. + */ +void suspend_lapic(void); + +/** + * @brief Resume LAPIC + * + * Resume LAPIC by setting the APIC base addr and restoring the registers. + */ +void resume_lapic(void); + +/** + * @brief Get the LAPIC ID + * + * Get the LAPIC ID via MSR read. + * + * @return LAPIC ID + */ +uint32_t get_cur_lapic_id(void); + +/** + * @} + */ +/* End of lapic_ext_apis */ + void init_lapic(uint16_t pcpu_id); void send_lapic_eoi(void); /** - * @brief Get the lapic id + * @defgroup ipi_ext_apis IPI External Interfaces * - * @return lapic id + * This is a group that includes IPI External Interfaces. + * + * @{ */ -uint32_t get_cur_lapic_id(void); /** * @brief Send an SIPI to a specific cpu @@ -124,6 +169,11 @@ void send_dest_ipi_mask(uint32_t dest_mask, uint32_t vector); */ void send_single_ipi(uint16_t pcpu_id, uint32_t vector); +/** + * @} + */ +/* End of ipi_ext_apis */ + /** * @brief Send an INIT signal to a single pCPU * @@ -133,7 +183,4 @@ void send_single_ipi(uint16_t pcpu_id, uint32_t vector); */ void send_single_init(uint16_t pcpu_id); -void suspend_lapic(void); -void resume_lapic(void); - #endif /* INTR_LAPIC_H */ diff --git a/hypervisor/include/arch/x86/pgtable.h b/hypervisor/include/arch/x86/pgtable.h index d16e524ae..41e539b89 100644 --- a/hypervisor/include/arch/x86/pgtable.h +++ b/hypervisor/include/arch/x86/pgtable.h @@ -31,23 +31,87 @@ #define PAGE_CACHE_UC_MINUS PAGE_PCD #define PAGE_CACHE_UC (PAGE_PCD | PAGE_PWT) +/** + * @defgroup ept_mem_access_right EPT Memory Access Right + * + * This is a group that includes EPT Memory Access Right Definitions. + * + * @{ + */ + +/** + * @brief EPT memory access right is read-only. + */ #define EPT_RD (1UL << 0U) + +/** + * @brief EPT memory access right is read/write. + */ #define EPT_WR (1UL << 1U) + +/** + * @brief EPT memory access right is executable. + */ #define EPT_EXE (1UL << 2U) + +/** + * @brief EPT memory access right is read/write and executable. + */ +#define EPT_RWX (EPT_RD | EPT_WR | EPT_EXE) + +/** + * @} + */ +/* End of ept_mem_access_right */ + +/** + * @defgroup ept_mem_type EPT Memory Type + * + * This is a group that includes EPT Memory Type Definitions. + * + * @{ + */ + +/** + * @brief EPT memory type is specified in bits 5:3 of the EPT paging-structure entry. + */ #define EPT_MT_SHIFT 3U + +/** + * @brief EPT memory type is uncacheable. + */ #define EPT_UNCACHED (0UL << EPT_MT_SHIFT) + +/** + * @brief EPT memory type is write combining. + */ #define EPT_WC (1UL << EPT_MT_SHIFT) + +/** + * @brief EPT memory type is write through. + */ #define EPT_WT (4UL << EPT_MT_SHIFT) + +/** + * @brief EPT memory type is write protected. + */ #define EPT_WP (5UL << EPT_MT_SHIFT) + +/** + * @brief EPT memory type is write back. + */ #define EPT_WB (6UL << EPT_MT_SHIFT) + +/** + * @} + */ +/* End of ept_mem_type */ + #define EPT_MT_MASK (7UL << EPT_MT_SHIFT) /* VTD: Second-Level Paging Entries: Snoop Control */ #define EPT_SNOOP_CTRL (1UL << 11U) #define EPT_VE (1UL << 63U) -#define EPT_RWX (EPT_RD | EPT_WR | EPT_EXE) - - #define PML4E_SHIFT 39U #define PTRS_PER_PML4E 512UL #define PML4E_SIZE (1UL << PML4E_SHIFT)