From 7c20cb0cbebf1247bdc33fac24a0f8794b40cc7f Mon Sep 17 00:00:00 2001
From: Yonghua Huang <yonghua.huang@intel.com>
Date: Wed, 31 Oct 2018 00:57:18 +0800
Subject: [PATCH] hv: revise interfaces description in vpic

Add comments for APIs:
 - vpic_set_irq()
 - vpic_pending_intr()
 - vpic_intr_accepted()

Tracked-On: #1595
Signed-off-by: Yonghua Huang <yonghua.huang@intel.com>
---
 hypervisor/dm/vpic.c                     | 33 +++++++++++++---
 hypervisor/include/arch/x86/guest/vpic.h | 49 ++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 6 deletions(-)

diff --git a/hypervisor/dm/vpic.c b/hypervisor/dm/vpic.c
index 2df715cb0..a7bec0a69 100644
--- a/hypervisor/dm/vpic.c
+++ b/hypervisor/dm/vpic.c
@@ -439,12 +439,14 @@ static void vpic_set_pinstate(struct acrn_vpic *vpic, uint8_t pin,
 }
 
 /**
- * @pre irq < NR_VPIC_PINS_TOTAL
- * @pre operation value shall be one of the folllowing values:
- *	GSI_SET_HIGH
- *	GSI_SET_LOW
- *	GSI_RAISING_PULSE
- *	GSI_FALLING_PULSE
+ * @brief Set vPIC 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
+ *
+ * @return void
  */
 void vpic_set_irq(struct vm *vm, uint32_t irq, uint32_t operation)
 {
@@ -513,6 +515,15 @@ void vpic_get_irq_trigger(struct vm *vm, uint32_t irq,
 	}
 }
 
+/**
+ * @brief Get pending virtual interrupts for vPIC.
+ *
+ * @param[in]    vm     Pointer to target VM
+ * @param[inout] vecptr Pointer to vector buffer and will be filled
+ *			with eligible vector if any.
+ *
+ * @return void.
+ */
 void vpic_pending_intr(struct vm *vm, uint32_t *vecptr)
 {
 	struct acrn_vpic *vpic;
@@ -566,6 +577,16 @@ static void vpic_pin_accepted(struct i8259_reg_state *i8259, uint8_t pin)
 	}
 }
 
+/**
+ * @brief Accept virtual interrupt for vPIC.
+ *
+ * @param[in] vm     Pointer to target VM
+ * @param[in] vector Target virtual interrupt vector
+ *
+ * @return void
+ *
+ * @pre vm != NULL
+ */
 void vpic_intr_accepted(struct vm *vm, uint32_t vector)
 {
 	struct acrn_vpic *vpic;
diff --git a/hypervisor/include/arch/x86/guest/vpic.h b/hypervisor/include/arch/x86/guest/vpic.h
index 1ee64929a..fdc0ba94b 100644
--- a/hypervisor/include/arch/x86/guest/vpic.h
+++ b/hypervisor/include/arch/x86/guest/vpic.h
@@ -30,6 +30,13 @@
 #ifndef VPIC_H
 #define VPIC_H
 
+/**
+ * @file vpic.h
+ *
+ * @brief public APIs for virtual PIC
+ */
+
+
 #define	ICU_IMR_OFFSET	1U
 
 /* Initialization control word 1. Written to even address. */
@@ -121,12 +128,54 @@ struct acrn_vpic {
 
 void vpic_init(struct vm *vm);
 
+/**
+ * @brief virtual PIC
+ *
+ * @addtogroup acrn_vpic ACRN vPIC
+ * @{
+ */
+
+/**
+ * @brief Set vPIC 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
+ *
+ * @return void
+ */
 void vpic_set_irq(struct vm *vm, uint32_t irq, uint32_t operation);
 
+/**
+ * @brief Get pending virtual interrupts for vPIC.
+ *
+ * @param[in]    vm     Pointer to target VM
+ * @param[inout] vecptr Pointer to vector buffer and will be filled
+ *			with eligible vector if any.
+ *
+ * @return void.
+ */
 void vpic_pending_intr(struct vm *vm, uint32_t *vecptr);
+
+/**
+ * @brief Accept virtual interrupt for vPIC.
+ *
+ * @param[in] vm     Pointer to target VM
+ * @param[in] vector Target virtual interrupt vector
+ *
+ * @return void
+ *
+ * @pre vm != NULL
+ */
 void vpic_intr_accepted(struct vm *vm, uint32_t vector);
 void vpic_get_irq_trigger(struct vm *vm, uint32_t irq,
 	enum vpic_trigger *trigger);
 uint32_t vpic_pincount(void);
 
+/**
+ * @}
+ */
+/* End of acrn_vpic */
+
 #endif /* VPIC_H */