1 /* 2 * ========================================================== 3 * 4 * Copyright (C) 2020 QuickLogic Corporation 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * File : eoss3_hal_i2s.h 16 * Purpose : This file contains API declaration for I2S Rx/Tx 17 * 18 * =========================================================== 19 * 20 */ 21 #ifndef __EOSS3_HAL_I2S_H_ 22 #define __EOSS3_HAL_I2S_H_ 23 #include <stdint.h> 24 25 /** 26 * @brief return value definitions 27 */ 28 #define HAL_I2S_RET_VAL (0x0) 29 #define HAL_I2S_RET_VAL_ERROR (0x20) 30 31 #define HAL_I2S_SUCCESS (HAL_I2S_RET_VAL + 0x0) 32 33 #define HAL_I2S_ERROR (HAL_I2S_RET_VAL_ERROR + 0x1) 34 #define HAL_I2S_TX_ERROR (HAL_I2S_RET_VAL_ERROR + 0x2) 35 #define HAL_I2S_RX_ERROR (HAL_I2S_RET_VAL_ERROR + 0x3) 36 #define HAL_I2S_TIME_OUT_ERROR (HAL_I2S_RET_VAL_ERROR + 0x4) 37 #define HAL_I2S_BAD_PARAMETER (HAL_I2S_RET_VAL_ERROR + 0x5) 38 #define HAL_I2S_INVALID_STATE (HAL_I2S_RET_VAL_ERROR + 0x6) 39 40 41 /** 42 * @brief I2S Stereo/Mono selection. 43 */ 44 #define I2S_CHANNELS_STEREO 0x0 /* Stereo channel */ 45 #define I2S_CHANNELS_MONO 0x1 /* Mono channel */ 46 47 /** 48 * @brief I2S Mono Left/ Mono Right selection. 49 */ 50 #define I2S_CHANNEL_MONO_LEFT 0x0 /* Mono Left channel */ 51 #define I2S_CHANNEL_MONO_RIGHT 0x1 /* Mono Right channel */ 52 53 /** 54 * @brief I2S Master/Slave in use details 55 */ 56 #define I2S_MASTER_ASSP_RX 0x0 /* I2S master in use with Rx */ 57 #define I2S_SLAVE_ASSP_TX 0x1 /* I2S slave in use with Tx */ 58 #define I2S_SLAVE_FABRIC_RX 0x2 /* I2S Slave with Rx on Fabric */ 59 #define I2S_MASTER_SLAVE_MAX 0x3 /* Max number of i2s instances */ 60 61 62 /** 63 * @brief I2S driver structure 64 */ 65 typedef struct 66 { 67 uint8_t sdma_used; /* SDMA used, if not will use normal mode of Tx/Rx */ 68 uint8_t i2s_wd_clk; /* I2S left /right sync clock */ 69 70 71 uint8_t ch_sel; /* Channel select (Stereo/Mono) */ 72 uint8_t mono_sel; /* Mono Left/Right Selection */ 73 } I2S_Config_t; 74 75 /** 76 * @brief HAL_I2S_Cb_Handler_t I2S driver call back. Callback gets called after completion of Tx/Rx. 77 * 78 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S. 79 * 80 * @param[in] p_data_received Pointer to the buffer with received data, 81 * or NULL if the handler is for Tx only. 82 * @param[out] p_data_to_send Pointer to the buffer with data sent 83 * ,or NULL if the handler is for Rx only. 84 * @param[in] buffer_size Buffer size in bytes, Length of data received and/or sent. 85 * This value is always equal to half the size of 86 * the buffers set by the call ql_i2s_data_tx_rx_start function. 87 * Since it uses ping pong buffer mechanism. 88 * 89 */ 90 typedef void (* HAL_I2S_Cb_Handler_t)(uint8_t i2s_id_sel, uint32_t const * p_data_received, 91 uint32_t * p_data_to_send, 92 uint16_t buffer_size); 93 94 /** 95 * @brief HAL_I2S_Init Function for initializing the I2S driver. 96 * 97 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S. 98 * 99 * @param[in] p_i2s_cfg Pointer to the structure with initial configuration. 100 * 101 * @param[in] handler callback for getting a callback once done with Rx/Tx. 102 * 103 * @retval HAL_I2S_SUCCESS in case of success, HAL_I2S_ERROR in case of 104 * failure. 105 */ 106 uint32_t HAL_I2S_Init (uint8_t i2s_id_sel, I2S_Config_t *p_i2s_cfg, HAL_I2S_Cb_Handler_t handler); 107 108 /** 109 * @brief HAL_I2S_TX_RX_Buffer Function for starting the Tx/Rx over I2S 110 * 111 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S. 112 * 113 * @param[in] p_rx_buffer receive buffer in case of RX otherwise NULL 114 * 115 * @param[in] p_tx_buffer transmit buffer in case of RX otherwise NULL 116 * 117 * @param[in] buffer_size Tx/Rx buffer size in Bytes (ping pong buffer mechanism) 118 * 119 * @retval HAL_I2S_SUCCESS in case of success, else other error value defined 120 * above. 121 */ 122 uint32_t HAL_I2S_TX_RX_Buffer (uint8_t i2s_id_sel, uint32_t * p_rx_buffer, 123 uint32_t * p_tx_buffer, 124 uint16_t buffer_size); 125 /** 126 * @brief HAL_I2S_Stop Function for stopping the ongoing Rx/Tx 127 * 128 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S 129 * 130 * @retval HAL_I2S_SUCCESS on success else HAL_I2S_ERROR. 131 */ 132 uint32_t HAL_I2S_Stop (uint8_t i2s_id_sel); 133 134 /** 135 * @brief HAL_I2S_Uninit Function to undo the init 136 * 137 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S 138 * 139 * @retval HAL_I2S_SUCCESS on success else HAL_I2S_ERROR. 140 */ 141 uint32_t HAL_I2S_Uninit(uint8_t i2s_id_sel); 142 143 /** 144 * @brief function pointers declaration to register for each i2s driver 145 */ 146 typedef uint32_t (* i2s_init)(I2S_Config_t *p_i2s_cfg, 147 HAL_I2S_Cb_Handler_t handler); 148 149 typedef uint32_t (* i2s_buffer)(uint32_t * p_rx_buffer, 150 uint32_t * p_tx_buffer, 151 uint16_t buffer_size); 152 153 typedef void (* i2s_stop)(void); 154 typedef void (* i2s_uninit)(void); 155 156 /** 157 * @brief function pointers for each i2s driver 158 */ 159 typedef struct 160 { 161 uint8_t i2s_state; /* to maintain state of each i2s */ 162 163 i2s_init initfn; 164 i2s_buffer bufferfn; 165 i2s_stop stopfn; 166 i2s_uninit un_initfn; 167 } I2S_Drv_t; 168 169 /** 170 * @brief HAL_I2S_register_driver i2s slave/master drivers should register 171 * their function using this function 172 * @param[in] i2s_id_sel I2S ID which is a identifier for the I2S 173 * 174 * @param[in] i2s_drv_fn function pointers to be passed here from i2s drivers 175 * 176 * @retval HAL_I2S_SUCCESS on success else HAL_I2S_ERROR. 177 */ 178 179 uint32_t HAL_I2S_Register_Driver(uint8_t i2s_id_sel, I2S_Drv_t i2s_drv_fn); 180 #endif /* !__EOSS3_HAL_I2S_H_ */
