1 /* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup PCIE 11 * @{ 12 * 13 * @brief Declares standard APIs of basic Peripheral Component Interconnect Express (PCIE) capabilities. 14 * 15 * You can use this module to access the PCIE and enable the driver to operate an PCIE device. 16 * These capabilities include read and write the PCIE configuration Space. 17 * 18 * @since 1.0 19 */ 20 21 /** 22 * @file pcie_if.h 23 * 24 * @brief Declares the standard PCIE interface functions. 25 * 26 * @since 1.0 27 */ 28 29 #ifndef PCIE_IF_H 30 #define PCIE_IF_H 31 32 #include "platform_if.h" 33 34 #ifdef __cplusplus 35 #if __cplusplus 36 extern "C" { 37 #endif 38 #endif /* __cplusplus */ 39 40 enum PcieTransferMode { 41 PCIE_CONFIG = 0, 42 PCIE_MEM, 43 PCIE_IO, 44 }; 45 46 enum PcieDmaDir { 47 PCIE_DMA_FROM_DEVICE = 0, 48 PCIE_DMA_TO_DEVICE, 49 }; 50 51 typedef int32_t (*PcieCallbackFunc)(DevHandle handle); 52 53 /** 54 * @brief Opens an PCIE controller with a specified bus number. 55 * 56 * Before using the PCIE interface, you can obtain the device handle of the PCIE controller 57 * by calling {@link PcieOpen}. This function is used in pair with {@link PcieClose}. 58 * 59 * @param busNum Indicates the bus number. 60 * 61 * @return Returns the device handle {@link DevHandle} of the PCIE controller if the operation is successful; 62 * returns <b>NULL</b> otherwise. 63 * 64 * @since 1.0 65 */ 66 DevHandle PcieOpen(uint16_t busNum); 67 68 /** 69 * @brief Reads a given length of data from the PCIE configuration Space. 70 * 71 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 72 * @param pos Indicates the start address of the data to read. 73 * @param data Indicates the pointer to the data to read. 74 * @param len Indicates the length of the data to read. 75 * @param mode Indicates the transfer mode of the data to read. 76 * 77 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 78 * 79 * @since 1.0 80 */ 81 int32_t PcieRead(DevHandle handle, uint32_t mode, uint32_t pos, uint8_t *data, uint32_t len); 82 83 /** 84 * @brief Writes a given length of data into the PCIE configuration Space. 85 * 86 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 87 * @param pos Indicates the start address of the data to write. 88 * @param data Indicates the pointer to the data to write. 89 * @param len Indicates the length of the data to write. 90 * @param mode Indicates the transfer mode of the data to read. 91 * 92 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 93 * 94 * @since 1.0 95 */ 96 int32_t PcieWrite(DevHandle handle, uint32_t mode, uint32_t pos, uint8_t *data, uint32_t len); 97 98 /** 99 * @brief DMA mapping for device. 100 * 101 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 102 * @param cb Indicates the callback function. 103 * @param addr Indicates the address of source memory. 104 * @param len Indicates the length of memory. 105 * @param dir Indicates the data flow direction, <b>0</b> means device to DMA and <b>1</b> means DMA to device. 106 * 107 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 108 * 109 * @since 1.0 110 */ 111 int32_t PcieDmaMap(DevHandle handle, PcieCallbackFunc cb, uintptr_t addr, uint32_t len, uint8_t dir); 112 113 /** 114 * @brief Unmapping DMA for device. 115 * 116 * After the DMA is used, you can ummap it by calling {@link PcieDmaUnmap}. 117 * This function is used in pair with {@link PcieDmaMap}. 118 * 119 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 120 * 121 * @since 1.0 122 */ 123 void PcieDmaUnmap(DevHandle handle, uintptr_t addr, uint32_t len, uint8_t dir); 124 125 /** 126 * @brief Register an interrupt callback function for device. 127 * 128 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 129 * @param cb Indicates the callback function. 130 * 131 * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails. 132 * 133 * @since 1.0 134 */ 135 int32_t PcieRegisterIrq(DevHandle handle, PcieCallbackFunc cb); 136 137 /** 138 * @brief Unregister the interrupt callback function for device. 139 * 140 * After the callback function is used, you can unregister it by calling {@link PcieUnregisterIrq}. 141 * This function is used in pair with {@link PcieRegisterIrq}. 142 * 143 * @param handle Indicates the pointer to the device handle of the PCIE controller obtained by {@link PcieOpen}. 144 * 145 * @since 1.0 146 */ 147 void PcieUnregisterIrq(DevHandle handle); 148 149 /** 150 * @brief Closes an PCIE controller. 151 * 152 * After the PCIE interface is used, you can close the PCIE controller by calling {@link PcieClose}. 153 * This function is used in pair with {@link PcieOpen}. 154 * 155 * @param handle Indicates the pointer to the device handle of the PCIE controller. 156 * 157 * @since 1.0 158 */ 159 void PcieClose(DevHandle handle); 160 161 #ifdef __cplusplus 162 #if __cplusplus 163 } 164 #endif 165 #endif /* __cplusplus */ 166 167 #endif /* PCIE_IF_H */ 168