1 /* 2 * Copyright (C) 2018-2022 Intel Corporation. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef ASSIGN_H 8 #define ASSIGN_H 9 10 #include <types.h> 11 #include <ptdev.h> 12 13 /** 14 * @file assign.h 15 * 16 * @brief public APIs for Passthrough Interrupt Remapping 17 */ 18 19 /** 20 * @brief VT-d 21 * 22 * @defgroup acrn_passthrough ACRN Passthrough 23 * @{ 24 */ 25 26 /** 27 * @brief Acknowledge a virtual interrupt for passthrough device. 28 * 29 * Acknowledge a virtual legacy interrupt for a passthrough device. 30 * 31 * @param[in] vm pointer to acrn_vm 32 * @param[in] virt_gsi virtual GSI number associated with the passthrough device 33 * @param[in] vgsi_ctlr INTX_CTLR_IOAPIC or INTX_CTLR_PIC 34 * 35 * @pre vm != NULL 36 * 37 */ 38 void ptirq_intx_ack(struct acrn_vm *vm, uint32_t virt_gsi, enum intx_ctlr vgsi_ctlr); 39 40 /** 41 * @brief MSI/MSI-x remapping for passthrough device. 42 * 43 * Main entry for PCI device assignment with MSI and MSI-X. 44 * MSI can up to 8 vectors and MSI-X can up to 1024 Vectors. 45 * 46 * @param[in] vm pointer to acrn_vm 47 * @param[in] virt_bdf virtual bdf associated with the passthrough device 48 * @param[in] phys_bdf virtual bdf associated with the passthrough device 49 * @param[in] entry_nr indicate coming vectors, entry_nr = 0 means first vector 50 * @param[in] info structure used for MSI/MSI-x remapping 51 * @param[in] irte_idx caller can pass a valid IRTE index, otherwise, use INVALID_IRTE_ID 52 * 53 * @return 54 * - 0: on success 55 * - \p -ENODEV: 56 * - for Service VM, the entry already be held by others 57 * - for User VM, no pre-hold mapping found. 58 * 59 * @pre vm != NULL 60 * @pre info != NULL 61 * 62 */ 63 int32_t ptirq_prepare_msix_remap(struct acrn_vm *vm, uint16_t virt_bdf, uint16_t phys_bdf, 64 uint16_t entry_nr, struct msi_info *info, uint16_t irte_idx); 65 66 67 /** 68 * @brief INTx remapping for passthrough device. 69 * 70 * Set up the remapping of the given virtual pin for the given vm. 71 * This is the main entry for PCI/Legacy device assignment with INTx, calling from vIOAPIC or vPIC. 72 * 73 * @param[in] vm pointer to acrn_vm 74 * @param[in] virt_gsi virtual GSI number associated with the passthrough device 75 * @param[in] vgsi_ctlr INTX_CTLR_IOAPIC or INTX_CTLR_PIC 76 * 77 * @return 78 * - 0: on success 79 * - \p -ENODEV: 80 * - for Service VM, the entry already be held by others 81 * - for User VM, no pre-hold mapping found. 82 * 83 * @pre vm != NULL 84 * 85 */ 86 int32_t ptirq_intx_pin_remap(struct acrn_vm *vm, uint32_t virt_gsi, enum intx_ctlr vgsi_ctlr); 87 88 /** 89 * @brief Add an interrupt remapping entry for INTx as pre-hold mapping. 90 * 91 * Except Service VM, Device Model should call this function to pre-hold ptdev intx 92 * The entry is identified by phys_pin, one entry vs. one phys_pin. 93 * Currently, one phys_pin can only be held by one pin source (vPIC or vIOAPIC). 94 * 95 * @param[in] vm pointer to acrn_vm 96 * @param[in] virt_gsi virtual pin number associated with the passthrough device 97 * @param[in] phys_gsi physical pin number associated with the passthrough device 98 * @param[in] pic_pin true for pic, false for ioapic 99 * 100 * @return 101 * - 0: on success 102 * - \p -EINVAL: invalid virt_pin value 103 * - \p -ENODEV: failed to add the remapping entry 104 * 105 * @pre vm != NULL 106 * 107 */ 108 int32_t ptirq_add_intx_remapping(struct acrn_vm *vm, uint32_t virt_gsi, uint32_t phys_gsi, bool pic_pin); 109 110 /** 111 * @brief Remove an interrupt remapping entry for INTx. 112 * 113 * Deactivate & remove mapping entry of the given virt gsi for given vm or 114 * phys gsi assigned to this vm. 115 * 116 * @param[in] vm pointer to acrn_vm 117 * @param[in] gsi virtual gsi number or physical gsi number associated with the passthrough device 118 * @param[in] pic_pin true for pic, false for ioapic 119 * @param[in] is_phy_gsi true if gsi is physical, false if gsi is virtual 120 * 121 * @pre vm != NULL 122 * 123 */ 124 void ptirq_remove_intx_remapping(const struct acrn_vm *vm, uint32_t gsi, bool pic_pin, bool is_phy_gsi); 125 126 /** 127 * @brief Remove interrupt remapping entry/entries for MSI/MSI-x. 128 * 129 * Remove the mapping of given number of vectors of the given virtual BDF for the given vm. 130 * 131 * @param[in] vm pointer to acrn_vm 132 * @param[in] phys_bdf physical bdf associated with the passthrough device 133 * @param[in] vector_count number of vectors 134 * 135 * @pre vm != NULL 136 * 137 */ 138 void ptirq_remove_msix_remapping(const struct acrn_vm *vm, uint16_t phys_bdf, uint32_t vector_count); 139 140 /** 141 * @brief Remove all interrupt remappings for INTx which are defined in VM config. 142 * 143 * Deactivate & remove all mapping entries of the virt_gsis defined in VM config for given vm. 144 * 145 * @param[in] vm pointer to acrn_vm 146 * 147 * @pre vm != NULL 148 * 149 */ 150 void ptirq_remove_configured_intx_remappings(const struct acrn_vm *vm); 151 152 /** 153 * @} 154 */ 155 156 #endif /* ASSIGN_H */ 157