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 <shiqing.gao@intel.com>

Author: shiqingg

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
-
-   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. */
+.. doxygengroup:: ioapic_ext_apis
+   :project: Project ACRN
+   :content-only:
 
-   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
-
-   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. */
+.. doxygengroup:: lapic_ext_apis
+   :project: Project ACRN
+   :content-only:
 
-   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
-
-   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. */
+.. doxygengroup:: phys_int_ext_apis
+   :project: Project ACRN
+   :content-only:
 
-   void init_interrupt(uint16_t pcpu_id)
-      /*  To do interrupt initialization for a cpu, will be called for
-       *  each physical cpu.
-       */

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:
-
-.. 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 Definition:
 
-   /* 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
-
-   /* 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)
+.. doxygengroup:: ept_mem_access_right
+   :project: Project ACRN
+   :content-only:
 
-   /* EPT memory access right is read/write and executable */
-   define EPT_RWX (EPT_RD | EPT_WR | EPT_EXE)
 
 Interfaces Design
 =================

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

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

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