doc: passthru: add structure and API docs

This patch adds more comments to describe the structures and functions of vtd
that are public to the other components in the hypervisor. The comments are in
doxygen-style for document generation.

Tracked-On: #1595
Signed-off-by: Binbin Wu <binbin.wu@intel.com>
Reviewed-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>

hypervisor/arch/x86/assign.c

@@ -532,8 +532,6 @@ void ptdev_intx_ack(struct acrn_vm *vm, uint8_t virt_pin,
  * We use entry_nr to indicate coming vectors
  * entry_nr = 0 means first vector
  * user must provide bdf and entry_nr
- *
- * This function is called by SOS pci MSI config routine through hcall
  */
 int ptdev_msix_remap(struct acrn_vm *vm, uint16_t virt_bdf,
 		uint16_t entry_nr, struct ptdev_msi_info *info)

hypervisor/include/arch/x86/assign.h

@@ -9,18 +9,157 @@
 
 #include <ptdev.h>
 
-void ptdev_intx_ack(struct acrn_vm *vm, uint8_t virt_pin,
+/**
-		enum ptdev_vpin_source vpin_src);
+ * @file assign.h
-int ptdev_msix_remap(struct acrn_vm *vm, uint16_t virt_bdf,
+ *
-		uint16_t entry_nr, struct ptdev_msi_info *info);
+ * @brief public APIs for Passthrough Interrupt Remapping
-int ptdev_intx_pin_remap(struct acrn_vm *vm, uint8_t virt_pin,
+ */
-		enum ptdev_vpin_source vpin_src);
+
-int ptdev_add_intx_remapping(struct acrn_vm *vm, uint8_t virt_pin, uint8_t phys_pin,
+/**
-		bool pic_pin);
+ * @brief VT-d
+ *
+ * @defgroup acrn_passthrough ACRN Passthrough
+ * @{
+ */
+
+/**
+ * @brief Acknowledge a virtual interrupt for passthrough device.
+ *
+ * Acknowledge a virtual legacy interrupt for a passthrough device.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_pin virtual pin number associated with the passthrough device
+ * @param[in] vpin_src ioapic or pic
+ *
+ * @return None
+ *
+ * @pre vm != NULL
+ *
+ */
+void ptdev_intx_ack(struct acrn_vm *vm, uint8_t virt_pin, enum ptdev_vpin_source vpin_src);
+
+/**
+ * @brief MSI/MSI-x remapping for passthrough device.
+ *
+ * Main entry for PCI device assignment with MSI and MSI-X.
+ * MSI can up to 8 vectors and MSI-X can up to 1024 Vectors.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_bdf virtual bdf associated with the passthrough device
+ * @param[in] entry_nr indicate coming vectors, entry_nr = 0 means first vector
+ * @param[in] info structure used for MSI/MSI-x remapping
+ *
+ * @return
+ *    - 0: on success
+ *    - \p -ENODEV:
+ *      - for SOS, the entry already be held by others
+ *      - for UOS, no pre-hold mapping found.
+ *
+ * @pre vm != NULL
+ * @pre info != NULL
+ *
+ */
+int ptdev_msix_remap(struct acrn_vm *vm, uint16_t virt_bdf, uint16_t entry_nr, struct ptdev_msi_info *info);
+
+
+/**
+ * @brief INTx remapping for passthrough device.
+ *
+ * Set up the remapping of the given virtual pin for the given vm.
+ * This is the main entry for PCI/Legacy device assignment with INTx, calling from vIOAPIC or vPIC.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_pin virtual pin number associated with the passthrough device
+ * @param[in] vpin_src ioapic or pic
+ *
+ * @return
+ *    - 0: on success
+ *    - \p -ENODEV:
+ *      - for SOS, the entry already be held by others
+ *      - for UOS, no pre-hold mapping found.
+ *
+ * @pre vm != NULL
+ *
+ */
+int ptdev_intx_pin_remap(struct acrn_vm *vm, uint8_t virt_pin, enum ptdev_vpin_source vpin_src);
+
+/**
+ * @brief Add an interrupt remapping entry for INTx as pre-hold mapping.
+ *
+ * Except vm0, Device Model should call this function to pre-hold ptdev intx
+ * The entry is identified by phys_pin, one entry vs. one phys_pin.
+ * Currently, one phys_pin can only be held by one pin source (vPIC or vIOAPIC).
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_pin virtual pin number associated with the passthrough device
+ * @param[in] phys_pin physical pin number associated with the passthrough device
+ * @param[in] pic_pin true for pic, false for ioapic
+ *
+ * @return
+ *    - 0: on success
+ *    - \p -EINVAL: invalid virt_pin value
+ *    - \p -ENODEV: failed to add the remapping entry
+ *
+ * @pre vm != NULL
+ *
+ */
+int ptdev_add_intx_remapping(struct acrn_vm *vm, uint8_t virt_pin, uint8_t phys_pin, bool pic_pin);
+
+/**
+ * @brief Remove an interrupt remapping entry for INTx.
+ *
+ * Deactivate & remove mapping entry of the given virt_pin for given vm.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_pin virtual pin number associated with the passthrough device
+ * @param[in] pic_pin true for pic, false for ioapic
+ *
+ * @return None
+ *
+ * @pre vm != NULL
+ *
+ */
 void ptdev_remove_intx_remapping(const struct acrn_vm *vm, uint8_t virt_pin, bool pic_pin);
-int ptdev_add_msix_remapping(struct acrn_vm *vm, uint16_t virt_bdf,
+
-	uint16_t phys_bdf, uint32_t vector_count);
+/**
-void ptdev_remove_msix_remapping(const struct acrn_vm *vm, uint16_t virt_bdf,
+ * @brief Add interrupt remapping entry/entries for MSI/MSI-x as pre-hold mapping.
-		uint32_t vector_count);
+ *
+ * Add pre-hold mapping of the given number of vectors between the given physical and virtual BDF for the given vm.
+ * Except vm0, Device Model should call this function to pre-hold ptdev MSI/MSI-x.
+ * The entry is identified by phys_bdf:msi_idx, one entry vs. one phys_bdf:msi_idx.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_bdf virtual bdf associated with the passthrough device
+ * @param[in] phys_bdf physical bdf associated with the passthrough device
+ * @param[in] vector_count number of vectors
+ *
+ * @return
+ *    - 0: on success
+ *    - \p -ENODEV: failed to add the remapping entry
+ *
+ * @pre vm != NULL
+ *
+ */
+int ptdev_add_msix_remapping(struct acrn_vm *vm, uint16_t virt_bdf, uint16_t phys_bdf, uint32_t vector_count);
+
+/**
+ * @brief Remove interrupt remapping entry/entries for MSI/MSI-x.
+ *
+ * Remove the mapping of given number of vectors of the given virtual BDF for the given vm.
+ *
+ * @param[in] vm pointer to acrn_vm
+ * @param[in] virt_bdf virtual bdf associated with the passthrough device
+ * @param[in] vector_count number of vectors
+ *
+ * @return None
+ *
+ * @pre vm != NULL
+ *
+ */
+void ptdev_remove_msix_remapping(const struct acrn_vm *vm, uint16_t virt_bdf, uint32_t vector_count);
+
+/**
+  * @}
+  */
 
 #endif /* ASSIGN_H */