From f23606a4c38daafb02d86a70b8a7fd47d45fb297 Mon Sep 17 00:00:00 2001
From: Yonghua Huang <yonghua.huang@intel.com>
Date: Wed, 31 Oct 2018 02:13:07 +0800
Subject: [PATCH] hv: revise interfaces description in vioapic

 Add comments for APIs:
 - vioapic_set_irq();
 - vioapic_set_irq_nolock();

Tracked-On: #1595
Signed-off-by: Yonghua Huang <yonghua.huang@intel.com>
---
 hypervisor/dm/vioapic.c                     | 31 +++++++++-----
 hypervisor/include/arch/x86/guest/vioapic.h | 45 +++++++++++++++++++++
 2 files changed, 65 insertions(+), 11 deletions(-)

diff --git a/hypervisor/dm/vioapic.c b/hypervisor/dm/vioapic.c
index d72642652..cac24c127 100644
--- a/hypervisor/dm/vioapic.c
+++ b/hypervisor/dm/vioapic.c
@@ -112,13 +112,18 @@ vioapic_set_pinstate(struct acrn_vioapic *vioapic, uint16_t pin, uint32_t level)
 }
 
 /**
+ * @brief Set vIOAPIC IRQ line status.
+ *
+ * Similar with vioapic_set_irq(),but would not make sure
+ * operation be done with ioapic lock.
+ *
+ * @param[in] vm        Pointer to target VM
+ * @param[in] irq       Target IRQ number
+ * @param[in] operation Action options: GSI_SET_HIGH/GSI_SET_LOW/
+ *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
+ *
  * @pre irq < vioapic_pincount(vm)
- * @pre operation value shall be one of the folllowing values:
- *	GSI_SET_HIGH
- *	GSI_SET_LOW
- *	GSI_RAISING_PULSE
- *	GSI_FALLING_PULSE
- * @pre call with vioapic lock
+ * @return void
  */
 void
 vioapic_set_irq_nolock(struct vm *vm, uint32_t irq, uint32_t operation)
@@ -152,12 +157,16 @@ vioapic_set_irq_nolock(struct vm *vm, uint32_t irq, uint32_t operation)
 }
 
 /**
+ * @brief Set vIOAPIC IRQ line status.
+ *
+ * @param[in] vm        Pointer to target VM
+ * @param[in] irq       Target IRQ number
+ * @param[in] operation Action options: GSI_SET_HIGH/GSI_SET_LOW/
+ *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
+ *
  * @pre irq < vioapic_pincount(vm)
- * @pre operation value shall be one of the folllowing values:
- *	GSI_SET_HIGH
- *	GSI_SET_LOW
- *	GSI_RAISING_PULSE
- *	GSI_FALLING_PULSE
+ *
+ * @return void
  */
 void
 vioapic_set_irq(struct vm *vm, uint32_t irq, uint32_t operation)
diff --git a/hypervisor/include/arch/x86/guest/vioapic.h b/hypervisor/include/arch/x86/guest/vioapic.h
index 36f60722c..bccb908f8 100644
--- a/hypervisor/include/arch/x86/guest/vioapic.h
+++ b/hypervisor/include/arch/x86/guest/vioapic.h
@@ -31,6 +31,12 @@
 #ifndef VIOAPIC_H
 #define VIOAPIC_H
 
+/**
+ * @file vioapic.h
+ *
+ * @brief public APIs for virtual I/O APIC
+ */
+
 #include <apicreg.h>
 
 #define	VIOAPIC_BASE	0xFEC00000UL
@@ -53,7 +59,42 @@ void    vioapic_init(struct vm *vm);
 void	vioapic_cleanup(const struct acrn_vioapic *vioapic);
 void	vioapic_reset(struct acrn_vioapic *vioapic);
 
+
+/**
+ * @brief virtual I/O APIC
+ *
+ * @addtogroup acrn_vioapic ACRN vIOAPIC
+ * @{
+ */
+
+/**
+ * @brief Set vIOAPIC IRQ line status.
+ *
+ * @param[in] vm        Pointer to target VM
+ * @param[in] irq       Target IRQ number
+ * @param[in] operation Action options: GSI_SET_HIGH/GSI_SET_LOW/
+ *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
+ *
+ * @pre irq < vioapic_pincount(vm)
+ *
+ * @return void
+ */
 void	vioapic_set_irq(struct vm *vm, uint32_t irq, uint32_t operation);
+
+/**
+ * @brief Set vIOAPIC IRQ line status.
+ *
+ * Similar with vioapic_set_irq(),but would not make sure
+ * operation be done with ioapic lock.
+ *
+ * @param[in] vm        Pointer to target VM
+ * @param[in] irq       Target IRQ number
+ * @param[in] operation Action options: GSI_SET_HIGH/GSI_SET_LOW/
+ *			GSI_RAISING_PULSE/GSI_FALLING_PULSE
+ *
+ * @pre irq < vioapic_pincount(vm)
+ * @return void
+ */
 void	vioapic_set_irq_nolock(struct vm *vm, uint32_t irq, uint32_t operation);
 void	vioapic_update_tmr(struct vcpu *vcpu);
 
@@ -66,4 +107,8 @@ int		vioapic_mmio_access_handler(struct io_request *io_req, void *handler_privat
 void get_vioapic_info(char *str_arg, size_t str_max, uint16_t vmid);
 #endif /* HV_DEBUG */
 
+/**
+ * @}
+ */
+/* End of acrn_vioapic */
 #endif /* VIOAPIC_H */