1 /* 2 * Copyright 2021 MindMotion Microelectronics Co., Ltd. 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef __HAL_I2C_H__ 9 #define __HAL_I2C_H__ 10 11 #include "hal_common.h" 12 13 /*! 14 * @addtogroup I2C 15 * @{ 16 */ 17 18 /*! 19 * @addtogroup I2C_INT 20 * @{ 21 */ 22 #define I2C_INT_RX_UNDER I2C_RAWISR_RXUNDER_MASK /*!< Assert when attempting to read the RX fifo, even it is empty. */ 23 #define I2C_INT_RX_NOTEMPTY I2C_RAWISR_RXFULL_MASK /*!< Assert when the data in RX fifo is available. */ 24 #define I2C_INT_TX_EMPTY I2C_RAWISR_TXEMPTY_MASK /*!< When working as master, this bit asserts if the data count is under or equal to the tx threshold. */ 25 #define I2C_INT_TX_ABORT I2C_RAWISR_TXABRT_MASK /*!< Assert when transmit abort. */ 26 #define I2C_INT_ACTIVE I2C_RAWISR_ACTIV_MASK /*!< Assert when the i2c bus is active, while the clocks are transfered. */ 27 #define I2C_INT_STOP I2C_RAWISR_STOP_MASK /*!< Assert when detecting a STOP on the i2c bus, no mater working as master or slave. */ 28 #define I2C_INT_START I2C_RAWISR_START_MASK /*!< Assert when detecting a START on the i2c bus, no matter working as master or slave. */ 29 /*! 30 * @} 31 */ 32 33 /*! 34 * @addtogroup I2C_STATUS 35 * @{ 36 */ 37 #define I2C_STATUS_ACTIVE I2C_SR_ACTIV_MASK /*!< I2C bus is active. */ 38 #define I2C_STATUS_TX_EMPTY I2C_SR_TFE_MASK /*!< I2C tx fifo is empty. */ 39 #define I2C_STATUS_RX_NOTEMPTY I2C_SR_RFNE_MASK /*!< I2C rx fifo is not empty. */ 40 /*! 41 * @} 42 */ 43 44 /*! 45 * @brief I2C baudrate type. 46 */ 47 typedef enum 48 { 49 I2C_BaudRate_50K = 50000u, /*!< Specify operate at the speed of 50K. */ 50 I2C_BaudRate_100K = 100000u, /*!< Specify operate at the speed of 100K. */ 51 } I2C_BaudRate_Type; 52 53 /*! 54 * @brief I2C transmission direction type. 55 */ 56 typedef enum 57 { 58 I2C_Direction_Tx = 0u, /*!< Specify I2C transmission direction as tx. */ 59 I2C_Direction_Rx = 1u, /*!< Specify I2C transmission direction as rx. */ 60 } I2C_Direction_Type; 61 62 /*! 63 * @brief Define the callback function called when the I2C master transfer is abort. 64 */ 65 typedef void (*I2C_Callback_1_Type)(void *param); 66 67 /*! 68 * @brief This type of structure instance is used to keep the settings when calling the @ref I2C_MasterXfer() to transfer the I2C address and data. 69 */ 70 typedef struct 71 { 72 uint16_t TargetAddr; /*!< Specify I2C target device address. */ 73 I2C_Direction_Type Direction; /*!< specify transmission direction. */ 74 uint8_t *TxBuf; /*!< Specify the tx buffer array. */ 75 uint32_t TxIdx; /*!< Specify the number of data currently sent. */ 76 uint8_t TxLen; /*!< Specify the tx data len. */ 77 uint8_t *RxBuf; /*!< Specify the rx buffer array. */ 78 uint32_t RxIdx; /*!< Specify the number of data currently receive. */ 79 uint8_t RxLen; /*!< Specify the rx data len. */ 80 uint32_t WaitTimes; /*!< Specify the time limit for wait to the flag to be generated. If the required flag is not generated after this time, considered as timeout. */ 81 I2C_Callback_1_Type DoneCallback; /*!< Callback function, called when the i2c transmit is done. */ 82 I2C_Callback_1_Type AbortCallback; /*!< Callback function, called when the i2c transmit is abort. */ 83 } I2C_MasterXfer_Type; 84 85 /*! 86 * @brief This type of structure instance is used to keep the settings when calling the @ref I2C_InitMaster() to initialize the I2C master module. 87 */ 88 typedef struct 89 { 90 uint32_t ClockFreqHz; /*!< Specify bus clock frequency. */ 91 I2C_BaudRate_Type BaudRate; /*!< Specify the I2C communication baud rate. */ 92 } I2C_Master_Init_Type; 93 94 /*! 95 * @brief Initialize the I2C master module. 96 * 97 * @param I2Cx I2C instance. 98 * @param init Pointer to the master initialization structure. See to @ref I2C_Master_Init_Type. 99 * @return The initialize succeed return true, the misconfiguration of speed or baud rate return false. 100 */ 101 bool I2C_InitMaster(I2C_Type * I2Cx, I2C_Master_Init_Type * init); 102 103 /*! 104 * @brief Enabel the I2C module. 105 * 106 * @param I2Cx I2C instance. 107 * @param enable 'true' to enable the module, 'false' to disable the module. 108 * @return None. 109 */ 110 void I2C_Enable(I2C_Type *I2Cx, bool enable); 111 112 /*! 113 * @brief Set the I2C target device address that matches the slave device. 114 * 115 * @param I2Cx I2C instance. 116 * @param addr I2C target device address. 117 * @return None. 118 */ 119 void I2C_SetTargetAddr(I2C_Type * I2Cx, uint8_t addr); 120 121 /*! 122 * @brief Get I2C target device address. 123 * 124 * @param I2Cx I2C instance. 125 * @return I2C target device addr. 126 */ 127 uint16_t I2C_GetTargetAddr(I2C_Type * I2Cx); 128 129 /*! 130 * @brief Put the data into transmiter buffer of the I2C module. 131 * 132 * @param I2Cx I2C instance. 133 * @param val Data value to be send through the transmiter. 134 * @return None. 135 */ 136 void I2C_PutData(I2C_Type * I2Cx, uint8_t val); 137 138 /*! 139 * @brief Control read-write bit to prepare for data acquisition. 140 * 141 * @param I2Cx I2C instance. 142 * @return None. 143 */ 144 void I2C_PrepareToGetData(I2C_Type * I2Cx); 145 146 /*! 147 * @brief Get the data from receiver buffer of the I2C module. 148 * 149 * @param I2Cx I2C instance. 150 * @return Data received by I2C bus. 151 */ 152 uint8_t I2C_GetData(I2C_Type * I2Cx); 153 154 /*! 155 * @brief Get the current status flags of the I2C module. 156 * 157 * @param I2Cx I2C instance. 158 * @return Status flags. See to @ref I2C_STATUS. 159 */ 160 uint32_t I2C_GetStatus(I2C_Type * I2Cx); 161 162 /*! 163 * @brief Prepare for the stop, when transfer finish. 164 * 165 * @param I2Cx I2C instance. 166 * @return None. 167 */ 168 void I2C_Stop(I2C_Type * I2Cx); 169 170 /*! 171 * @brief Enable interrupts of I2C module. 172 * 173 * @param I2Cx I2C instance. 174 * @param interrupts Interrupt code masks. See to @ref I2C_INT. 175 * @param enable 'true' to enable the indicated interrupts, 'false' to disable the indicated interrupts. 176 * @return None. 177 */ 178 void I2C_EnableInterrupts(I2C_Type * I2Cx, uint32_t interrupts, bool enable); 179 180 /*! 181 * @brief Read the current enabled interrupts the I2C module. 182 * 183 * @param I2Cx I2C instance. 184 * @return The mask codes enabled interrupts. See to @ref I2C_INT. 185 */ 186 uint32_t I2C_GetEnabledInterrupts(I2C_Type * I2Cx); 187 188 /*! 189 * @brief Get the I2C interrupt status flags of the I2C module. 190 * 191 * @param I2Cx I2C instance. 192 * @return Interrupt status flags. See to @ref I2C_INT. 193 */ 194 uint32_t I2C_GetInterruptStatus(I2C_Type * I2Cx); 195 196 /*! 197 * @brief Clear the I2C interrupt status flags of the I2C module. 198 * 199 * @param I2Cx I2C instance. 200 * @param interrupts The mask codes of the indicated interrupt flags to be cleared. 201 * @return None. 202 */ 203 void I2C_ClearInterruptStatus(I2C_Type * I2Cx, uint32_t interrupts); 204 205 /*! 206 * @brief I2C master interrupt transfer of the I2C module. 207 * 208 * @param I2Cx I2C instance. 209 * @param xfer Pointer to the I2C master transimt structure. See to @ref I2C_MasterXfer_Type. 210 * @return None. 211 */ 212 void I2C_MasterXfer(I2C_Type * I2Cx, I2C_MasterXfer_Type * xfer); 213 214 /*! 215 * @brief I2C master transfer interrupt handler. 216 * 217 * @param I2Cx I2C instance. 218 * @param xfer Pointer to the I2C master transimt structure. See to @ref I2C_MasterXfer_Type. 219 * @param interrupts Interrupt status flags. See to @ref I2C_INT. 220 * @return None. 221 */ 222 void I2C_MasterXferHandler(I2C_Type * I2Cx, I2C_MasterXfer_Type * xfer, uint32_t interrupts); 223 224 /*! 225 * @brief I2C master write polling. 226 * 227 * @param I2Cx I2C instance. 228 * @param xfer Pointer to the I2C master transimt structure. See to @ref I2C_MasterXfer_Type. 229 * @return 'true' to I2C write polling succeed, 'false' to I2C write polling failed. 230 */ 231 bool I2C_MasterWriteBlocking(I2C_Type * I2Cx, I2C_MasterXfer_Type * xfer); 232 233 /*! 234 * @brief I2C master read polling. 235 * 236 * @param I2Cx I2C instance. 237 * @param xfer Pointer to the I2C master transimt structure. See to @ref I2C_MasterXfer_Type. 238 * @return 'true' to I2C read polling succeed, 'false' to I2C read polling failed. 239 */ 240 bool I2C_MasterReadBlocking(I2C_Type * I2Cx, I2C_MasterXfer_Type * xfer); 241 242 /*! 243 *@} 244 */ 245 246 #endif /* __HAL_I2C_H__ */ 247 248