github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-26 07:21:37 +00:00
Code Issues Projects Releases Wiki Activity

doc: remove hard-coded interfaces in .rst files

Browse Source 
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 <shiqing.gao@intel.com>
This commit is contained in:
Shiqing Gao 2019-05-07 16:52:39 +08:00 committed by David Kinder
parent ffb924542b
commit 474496fc0e
8 changed files with 255 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
doc/developer-guides/hld/hv-interrupt.rst
View File

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

54
doc/developer-guides/hld/hv-memmgt.rst
View File

@ -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
=================

9
doc/developer-guides/hld/hv-virt-interrupt.rst
View File

@ -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

47
hypervisor/include/arch/x86/guest/vcpu.h
View File

@ -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) \
{ \

26
hypervisor/include/arch/x86/ioapic.h
View File

@ -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);

57
hypervisor/include/arch/x86/irq.h
View File

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

63
hypervisor/include/arch/x86/lapic.h
View File

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

70
hypervisor/include/arch/x86/pgtable.h
View File

@ -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)