1 /* 2 * Copyright 2021-2023 NXP NXP 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef SPI_IP_H 8 #define SPI_IP_H 9 10 /** 11 * @file Spi_Ip.h 12 * 13 * 14 * @brief SPI/DSPI IP driver header file. 15 * @details SPI/DSPI IP driver header file. 16 17 * @addtogroup SPI_IP_DRIVER Spi Ip Driver 18 * @{ 19 */ 20 21 #ifdef __cplusplus 22 extern "C"{ 23 #endif 24 25 26 27 /*================================================================================================== 28 * INCLUDE FILES 29 * 1) system and project includes 30 * 2) needed interfaces from external units 31 * 3) internal and external interfaces from this unit 32 ==================================================================================================*/ 33 #include "Spi_Ip_Types.h" 34 #ifdef SPI_IP_ENABLE_USER_MODE_SUPPORT 35 #include "Mcal.h" 36 #endif 37 /*================================================================================================== 38 * SOURCE FILE VERSION INFORMATION 39 ==================================================================================================*/ 40 #define SPI_IP_VENDOR_ID 43 41 #define SPI_IP_AR_RELEASE_MAJOR_VERSION 4 42 #define SPI_IP_AR_RELEASE_MINOR_VERSION 7 43 #define SPI_IP_AR_RELEASE_REVISION_VERSION 0 44 #define SPI_IP_SW_MAJOR_VERSION 1 45 #define SPI_IP_SW_MINOR_VERSION 0 46 #define SPI_IP_SW_PATCH_VERSION 0 47 /*================================================================================================== 48 * FILE VERSION CHECKS 49 ==================================================================================================*/ 50 /* Check if Spi_Ip.h and Spi_Ip_Types.h are of the same vendor */ 51 #if (SPI_IP_VENDOR_ID != SPI_IP_TYPES_VENDOR_ID) 52 #error "Spi_Ip.h and Spi_Ip_Types.h have different vendor ids" 53 #endif 54 /* Check if Spi_Ip.h file and Spi_Ip_Types.h file are of the same Autosar version */ 55 #if ((SPI_IP_AR_RELEASE_MAJOR_VERSION != SPI_IP_TYPES_AR_RELEASE_MAJOR_VERSION) || \ 56 (SPI_IP_AR_RELEASE_MINOR_VERSION != SPI_IP_TYPES_AR_RELEASE_MINOR_VERSION) || \ 57 (SPI_IP_AR_RELEASE_REVISION_VERSION != SPI_IP_TYPES_AR_RELEASE_REVISION_VERSION)) 58 #error "AutoSar Version Numbers of Spi_Ip.h and Spi_Ip_Types.h are different" 59 #endif 60 #if ((SPI_IP_SW_MAJOR_VERSION != SPI_IP_TYPES_SW_MAJOR_VERSION) || \ 61 (SPI_IP_SW_MINOR_VERSION != SPI_IP_TYPES_SW_MINOR_VERSION) || \ 62 (SPI_IP_SW_PATCH_VERSION != SPI_IP_TYPES_SW_PATCH_VERSION)) 63 #error "Software Version Numbers of Spi_Ip.h and Spi_Ip_Types.h are different" 64 #endif 65 66 #ifndef DISABLE_MCAL_INTERMODULE_ASR_CHECK 67 /* Check if current file and Mcal header file are of the same Autosar version */ 68 #if ((SPI_IP_AR_RELEASE_MAJOR_VERSION != MCAL_AR_RELEASE_MAJOR_VERSION) || \ 69 (SPI_IP_AR_RELEASE_MINOR_VERSION != MCAL_AR_RELEASE_MINOR_VERSION)) 70 #error "AutoSar Version Numbers of Spi_Ip.h and Mcal.h are different" 71 #endif 72 #endif 73 /*================================================================================================== 74 * CONSTANTS 75 ==================================================================================================*/ 76 /*================================================================================================== 77 * DEFINES AND MACROS 78 ==================================================================================================*/ 79 /*================================================================================================== 80 * ENUMS 81 ==================================================================================================*/ 82 /*================================================================================================== 83 * STRUCTURES AND OTHER TYPEDEFS 84 ==================================================================================================*/ 85 /*================================================================================================== 86 * GLOBAL VARIABLE DECLARATIONS 87 ==================================================================================================*/ 88 #define SPI_START_SEC_CONFIG_DATA_UNSPECIFIED 89 #include "Spi_MemMap.h" 90 /** 91 * @brief Export Post-Build configurations. 92 */ 93 SPI_IP_CONFIG_EXT 94 95 #define SPI_STOP_SEC_CONFIG_DATA_UNSPECIFIED 96 #include "Spi_MemMap.h" 97 /*================================================================================================== 98 * FUNCTION PROTOTYPES 99 ==================================================================================================*/ 100 #define SPI_START_SEC_CODE 101 #include "Spi_MemMap.h" 102 103 /** 104 * @brief SPI/DSPI peripheral initialization. 105 * @details The function initialize the SPI Unit specified in the configuration. 106 * 107 * @param[in] PhyUnitConfigPtr - pointer to the specified SPI Unit configuration. 108 * 109 * @return SPI_IP_STATUS_SUCCESS: Initialization command has been accepted. 110 * SPI_IP_STATUS_FAIL: Initialization command has not been accepted. 111 * @implements Spi_Ip_Init_Activity 112 */ 113 Spi_Ip_StatusType Spi_Ip_Init(const Spi_Ip_ConfigType *PhyUnitConfigPtr); 114 115 /** 116 * @brief SPI/DSPI peripheral deinitialization. 117 * @details The function de-initialize the SPI peripheral instance specified. 118 * All registers of SPI peripheral will be reset. 119 * 120 * @param[in] Instance - SPI peripheral instance number. 121 * 122 * @return SPI_IP_STATUS_SUCCESS: De-initialization command has been accepted. 123 * SPI_IP_STATUS_FAIL: De-initialization command has not been accepted. 124 * @implements Spi_Ip_DeInit_Activity 125 */ 126 Spi_Ip_StatusType Spi_Ip_DeInit(uint8 Instance); 127 128 /** 129 * @brief SPI/DSPI synchronous transmission. 130 * @details This function initializes a synchronous transfer using the bus parameters provided 131 * by external device. 132 * 133 * @param[in] ExternalDevice - pointer to the external device where data is transmitted. 134 * @param[in] TxBuffer - pointer to transmit buffer. 135 * @param[in-out] RxBuffer - pointer to receive buffer. 136 * @param[in] Length - number of bytes to be sent. 137 * @param[in] TimeOut - duration for sending one frame. 138 * 139 * @return SPI_IP_STATUS_SUCCESS: Transmission command has been accepted. 140 * SPI_IP_FIFO_ERROR: Overflow or underflow error occurred. 141 * SPI_IP_STATUS_FAIL: Transmission command has not been accepted. 142 * SPI_IP_TIMEOUT: Timeout error occurred. 143 * 144 * @implements Spi_Ip_SyncTransmit_Activity 145 */ 146 Spi_Ip_StatusType Spi_Ip_SyncTransmit( 147 const Spi_Ip_ExternalDeviceType *ExternalDevice, 148 const uint8 *TxBuffer, 149 uint8 *RxBuffer, 150 uint16 Length, 151 uint32 TimeOut 152 ); 153 154 /** 155 * @brief SPI/DSPI asynchronous transmission. 156 * @details This function initializes an asynchronous transfer using the bus parameters provided 157 * by external device. After Spi_Ip_Init function is called, SPI_IP_POLLING 158 * mode is set as default to change the default mode Spi_Ip_UpdateTransferMode should be called. 159 * 160 * @param[in] ExternalDevice - pointer to the external device where data is transmitted 161 * @param[in] TxBuffer - pointer to transmit buffer. 162 * @param[in-out] RxBuffer - pointer to receive buffer. 163 * @param[in] Length - number of bytes to be sent. 164 * @param[in] EndCallback - callback function is called at the end of transfer. 165 * 166 * @return SPI_IP_STATUS_SUCCESS: Transmission command has been accepted. 167 * SPI_IP_STATUS_FAIL: Transmission command has not been accepted. 168 * @implements Spi_Ip_AsyncTransmit_Activity 169 */ 170 Spi_Ip_StatusType Spi_Ip_AsyncTransmit( 171 const Spi_Ip_ExternalDeviceType *ExternalDevice, 172 const uint8 *TxBuffer, 173 uint8 *RxBuffer, 174 uint16 Length, 175 Spi_Ip_CallbackType EndCallback 176 ); 177 178 #if (SPI_IP_DMA_USED == STD_ON) 179 #if (SPI_IP_ENABLE_DMAFASTTRANSFER_SUPPORT == STD_ON) 180 /** 181 * @brief SPI/DSPI asynchronous transmission fast. 182 * @details This function initializes an asynchronous transmission for multiple transfers session 183 * and CPU used only for processing at the end of sequence transfer. 184 * The list of transfers session is composed of an array of fast transfers settings. 185 * The settings array is defined by the user needs: it contains entries parameters to be configured 186 * for each transfer session as defined in Spi_Ip_FastTransferType. 187 * 188 * How to use this interface: 189 * 1. Use the "Spi_Ip_FastTransferType" to create a list(array) of transfer session. 190 * Each field in Spi_Ip_FastTransferType for each transfer session must be configured. 191 * Note: This feature requires: 192 * a. All parameters in all External Devices used(pointed by ExternalDevice) must be the same in each transfer session except SpiCsIdentifier, SpiCsContinous. 193 * b. In each transfer section, the number of data buffer(Length) is NOT higher than 32767 if SpiDataWidth < 9. 194 * c. Only Master mode is supported(SpiPhyUnit/SpiPhyUnitMode = SPI_MASTER). 195 * d. Make sure that SpiPhyUnit/SpiMaxDmaFastTransfer value must NOT lower than total of transfer sessions. 196 * e. Make sure that number of ScatterGathers configuration in SpiPhyUnit/SpiPhyTxCmdDmaChannel must NOT lower than 197 * total of transfer sessions plus number of time request CS de-assert(KeepCs = FALSE) at the end of transfer session in the list configured. 198 * f. Make sure that number of ScatterGathers configuration in each SpiPhyUnit/SpiPhyTxDmaChannel, SpiPhyRxDmaChannel must NOT lower than total of transfer sessions. 199 * 2. Call the "Spi_Ip_AsyncTransmitFast()" interface. 200 * 201 * Example: 202 * The user shall create the desired configuration list for his specific application. 203 * For example use case: 204 * - Requiring 2 transfers session, keep CS assert at the end of first transfer session. 205 * - Transfer session 1: 206 * + Use SpiExternalDevice_0 with SpiCsIdentifier = PCS0, SpiCsContinous = TRUE. 207 * + Send 5 bytes. Tx buffer is "uint8 u8TxBuffer1[5u]={0,1,2,3,4};". Rx buffer is "uint8 u8RxBuffer1[5u];". 208 * + Keep CS assert at the end of this transfer session. 209 * - Transfer session 2: 210 * + Use SpiExternalDevice_0 with SpiCsIdentifier = PCS0, SpiCsContinous = TRUE. 211 * + Send 10 bytes with default transmit data value is 5. Tx buffer is NULL_PTR. Rx buffer is "uint8 u8RxBuffer2[10u];". 212 * + This is last transfer session, so CS will not kipped by default at the end of last transfer session. 213 * - Configuration example on configuration tool: 214 * + SpiGeneral/SpiEnableDmaFastTransferSupport = true. 215 * + SpiPhyUnit/SpiMaxDmaFastTransfer = 2(2 transfers session). 216 * + Number of ScatterGathers configuration for SpiPhyTxCmdDmaChannel is 3(2 transfers session + 1 time CS de-assert at the end of last transfer session). 217 * + Number of ScatterGathers configuration for SpiPhyTxDmaChannel, SpiPhyRxDmaChannel is 2(2 transfers session). 218 * - Call "UserCallbackFunc" when Fast transfer completed. 219 * - Coding example: 220 * void UserCallbackFunc(uint8 Instance, Spi_Ip_EventType event); 221 * Spi_Ip_FastTransferType aUserFastTransferCfgList[2u] = 222 * { 223 * { 224 * Spi_Ip_DeviceAttributes_SpiExternalDevice_0_BOARD_InitPeripherals, ->Point to External Device 0 configuration generated by configuration tool 225 * u8TxBuffer1, -> Store pointer for Tx buffer 226 * u8RxBuffer1, -> Store pointer for Rx buffer 227 * 0u, -> Default transmit data, don't care due to Tx buffer is not NULL_PTR 228 * 5u, -> Number of bytes to be sent 229 * (boolean)TRUE -> Keep CS signal at the end of this transfer session 230 * }, 231 * { 232 * Spi_Ip_DeviceAttributes_SpiExternalDevice_0_BOARD_InitPeripherals, -> Point to external device configuration 233 * NULL_PTR, -> Store pointer for Tx buffer 234 * u8RxBuffer2, -> Store pointer for Rx buffer 235 * 5u, -> Default transmit data, don't care due to Tx buffer is not NULL_PTR 236 * 10u, -> Number of bytes to be sent 237 * (boolean)FALSE -> Not keep CS signal at the end of this transfer session, don't care this parameter for last transfer 238 * } 239 * }; 240 * Spi_Ip_AsyncTransmitFast(aUserFastTransferCfgList, 2u, &UserCallbackFunc); 241 * 242 * @param[in-out] FastTransferCfg - pointer to the list of transfers section configuration. 243 * @param[in] NumberOfTransfer - number of transfers session in the list is pointed by pFastTransferCfg. 244 * @param[in] EndCallback - callback function is called at the end of sequence transfer. 245 * 246 * @return SPI_IP_STATUS_SUCCESS: Transmission command has been accepted. 247 * SPI_IP_STATUS_FAIL: Transmission command has not been accepted. 248 * @implements Spi_Ip_AsyncTransmitFast_Activity 249 */ 250 Spi_Ip_StatusType Spi_Ip_AsyncTransmitFast( 251 const Spi_Ip_FastTransferType *FastTransferCfg, 252 uint8 NumberOfTransfer, 253 Spi_Ip_CallbackType EndCallback 254 ); 255 #endif 256 #endif 257 258 /** 259 * @brief Get status of HW unit. 260 * @details This function returns the status of the specified SPI Hardware microcontroller peripheral. 261 * 262 * @param[in] Instance - SPI peripheral instance number. 263 * 264 * @return Spi_Ip_HwStatusType 265 * @implements Spi_Ip_GetStatus_Activity 266 */ 267 Spi_Ip_HwStatusType Spi_Ip_GetStatus(uint8 Instance); 268 269 /** 270 * @brief Process transfer in POLLING mode. 271 * @details This function shall polls the SPI interrupts linked to SPI peripheral instance allocated to 272 * the transmission of data to enable the evolution of transmission state machine. 273 * 274 * @param[in] Instance - SPI peripheral instance number. 275 * 276 * @return void 277 * @implements Spi_Ip_ManageBuffers_Activity 278 */ 279 void Spi_Ip_ManageBuffers(uint8 Instance); 280 281 /** 282 * @brief SPI/DSPI change frame size. 283 * @details This function updates frame size of specific external device configuration for next transfers. 284 * 285 * @param[in] ExternalDevice - pointer to the external device configuration. 286 * @param[in] FrameSize - Frame size. 287 * 288 * @return SPI_IP_STATUS_SUCCESS: Setting command has been accepted. 289 * SPI_IP_STATUS_FAIL: Setting command has not been accepted. 290 * @implements Spi_Ip_UpdateFrameSize_Activity 291 */ 292 Spi_Ip_StatusType Spi_Ip_UpdateFrameSize(const Spi_Ip_ExternalDeviceType *ExternalDevice, uint8 FrameSize); 293 294 /** 295 * @brief SPI/DSPI change bit order. 296 * @details This function updates bits order LSB or MSB of specific external device configuration for next transfer. 297 * 298 * @param[in] ExternalDevice - pointer to the external device configuration. 299 * @param[in] Lsb - Data is transferred LSB first or not. 300 * 301 * @return SPI_IP_STATUS_SUCCESS: Setting command has been accepted. 302 * SPI_IP_STATUS_FAIL: Setting command has not been accepted. 303 * @implements Spi_Ip_UpdateLsb_Activity 304 */ 305 Spi_Ip_StatusType Spi_Ip_UpdateLsb(const Spi_Ip_ExternalDeviceType *ExternalDevice, boolean Lsb); 306 307 /** 308 * @brief SPI/DSPI change default transmit data. 309 * @details This function updates default transmit data of specific external device configuration for next transfer. 310 * 311 * @param[in] ExternalDevice - pointer to the external device configuration. 312 * @param[in] DefaultData - New default transmit data. 313 * 314 * @return SPI_IP_STATUS_SUCCESS: Setting command has been accepted. 315 * SPI_IP_STATUS_FAIL: Setting command has not been accepted. 316 * @implements Spi_Ip_UpdateDefaultTransmitData_Activity 317 */ 318 Spi_Ip_StatusType Spi_Ip_UpdateDefaultTransmitData(const Spi_Ip_ExternalDeviceType *ExternalDevice, uint32 DefaultData); 319 320 /** 321 * @brief SPI/DSPI change transfer mode. 322 * @details This function updates the asynchronous mechanism mode for the specified SPI Hardware microcontroller peripheral. 323 * 324 * @param[in] Instance - SPI peripheral instance number. 325 * @param[in] Mode - new mode (interrupt or polling). 326 * 327 * @return SPI_IP_STATUS_SUCCESS: Setting command has been accepted. 328 * SPI_IP_STATUS_FAIL: Setting command has not been accepted. 329 * @implements Spi_Ip_UpdateTransferMode_Activity 330 */ 331 Spi_Ip_StatusType Spi_Ip_UpdateTransferMode(uint8 Instance, Spi_Ip_ModeType Mode); 332 333 /** 334 * @brief SPI/DSPI cancel current asynchronous transmission. 335 * @details This function cancels an asynchronous transmission in progress for the specified SPI Hardware microcontroller peripheral. 336 * 337 * @param[in] Instance - SPI peripheral instance number. 338 * 339 * @return void 340 * @implements Spi_Ip_Cancel_Activity 341 */ 342 void Spi_Ip_Cancel(uint8 Instance); 343 344 #if (SPI_IP_DUAL_CLOCK_MODE == STD_ON) 345 /** 346 * @brief Change clock mode. 347 * @details This function will change clock mode to operate with other clock reference. 348 * 349 * @param[in] Instance - SPI peripheral instance number. 350 * @param[in] ClockMode Clock mode. 351 * 352 * @return SPI_IP_STATUS_SUCCESS: Setting command has been accepted. 353 * SPI_IP_STATUS_FAIL: Setting command has not been accepted. 354 * @implements Spi_Ip_SetClockMode_Activity 355 */ 356 Spi_Ip_StatusType Spi_Ip_SetClockMode(uint8 Instance, Spi_Ip_DualClockModeType ClockMode); 357 #endif 358 359 void Spi_Ip_IrqHandler(uint8 Instance); 360 #if (SPI_IP_DMA_USED == STD_ON) 361 void Spi_Ip_IrqDmaHandler(uint8 Instance); 362 #endif 363 364 #define SPI_STOP_SEC_CODE 365 #include "Spi_MemMap.h" 366 367 #ifdef __cplusplus 368 } 369 #endif 370 371 /** @} */ 372 373 #endif /* SPI_IP_H */ 374
