1 /* ----------------------------------------------------------------------------- 2 * SPDX-License-Identifier: Zlib 3 * Copyright (c) 2013-2014 ARM Ltd. 4 * 5 * This software is provided 'as-is', without any express or implied warranty. 6 * In no event will the authors be held liable for any damages arising from 7 * the use of this software. Permission is granted to anyone to use this 8 * software for any purpose, including commercial applications, and to alter 9 * it and redistribute it freely, subject to the following restrictions: 10 * 11 * 1. The origin of this software must not be misrepresented; you must not 12 * claim that you wrote the original software. If you use this software in 13 * a product, an acknowledgment in the product documentation would be 14 * appreciated but is not required. 15 * 16 * 2. Altered source versions must be plainly marked as such, and must not be 17 * misrepresented as being the original software. 18 * 19 * 3. This notice may not be removed or altered from any source distribution. 20 * 21 * 22 * $Date: 9. Dec 2014 23 * $Revision: V1.00 24 * 25 * Project: SAI (Serial Audio Interface) Driver definitions 26 * -------------------------------------------------------------------------- */ 27 28 /* History: 29 * Version 1.00 30 * Initial release 31 */ 32 33 #ifndef __DRIVER_SAI_H 34 #define __DRIVER_SAI_H 35 36 #include "Driver_Common.h" 37 38 #define ARM_SAI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,00) /* API version */ 39 40 41 /****** SAI Control Codes *****/ 42 43 #define ARM_SAI_CONTROL_Msk (0xFFU) 44 #define ARM_SAI_CONFIGURE_TX (0x01U) ///< Configure Transmitter; arg1 and arg2 provide additional configuration 45 #define ARM_SAI_CONFIGURE_RX (0x02U) ///< Configure Receiver; arg1 and arg2 provide additional configuration 46 #define ARM_SAI_CONTROL_TX (0x03U) ///< Control Transmitter; arg1.0: 0=disable (default), 1=enable; arg1.1: mute 47 #define ARM_SAI_CONTROL_RX (0x04U) ///< Control Receiver; arg1.0: 0=disable (default), 1=enable 48 #define ARM_SAI_MASK_SLOTS_TX (0x05U) ///< Mask Transmitter slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default 49 #define ARM_SAI_MASK_SLOTS_RX (0x06U) ///< Mask Receiver slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default 50 #define ARM_SAI_ABORT_SEND (0x07U) ///< Abort \ref ARM_SAI_Send 51 #define ARM_SAI_ABORT_RECEIVE (0x08U) ///< Abort \ref ARM_SAI_Receive 52 53 /*----- SAI Control Codes: Configuration Parameters: Mode -----*/ 54 #define ARM_SAI_MODE_Pos 8 55 #define ARM_SAI_MODE_Msk (1U << ARM_SAI_MODE_Pos) 56 #define ARM_SAI_MODE_MASTER (1U << ARM_SAI_MODE_Pos) ///< Master Mode 57 #define ARM_SAI_MODE_SLAVE (0U << ARM_SAI_MODE_Pos) ///< Slave Mode (default) 58 59 /*----- SAI Control Codes: Configuration Parameters: Synchronization -----*/ 60 #define ARM_SAI_SYNCHRONIZATION_Pos 9 61 #define ARM_SAI_SYNCHRONIZATION_Msk (1U << ARM_SAI_SYNCHRONIZATION_Pos) 62 #define ARM_SAI_ASYNCHRONOUS (0U << ARM_SAI_SYNCHRONIZATION_Pos) ///< Asynchronous (default) 63 #define ARM_SAI_SYNCHRONOUS (1U << ARM_SAI_SYNCHRONIZATION_Pos) ///< Synchronous 64 65 /*----- SAI Control Codes: Configuration Parameters: Protocol -----*/ 66 #define ARM_SAI_PROTOCOL_Pos 10 67 #define ARM_SAI_PROTOCOL_Msk (7U << ARM_SAI_PROTOCOL_Pos) 68 #define ARM_SAI_PROTOCOL_USER (0U << ARM_SAI_PROTOCOL_Pos) ///< User defined (default) 69 #define ARM_SAI_PROTOCOL_I2S (1U << ARM_SAI_PROTOCOL_Pos) ///< I2S 70 #define ARM_SAI_PROTOCOL_MSB_JUSTIFIED (2U << ARM_SAI_PROTOCOL_Pos) ///< MSB (left) justified 71 #define ARM_SAI_PROTOCOL_LSB_JUSTIFIED (3U << ARM_SAI_PROTOCOL_Pos) ///< LSB (right) justified 72 #define ARM_SAI_PROTOCOL_PCM_SHORT (4U << ARM_SAI_PROTOCOL_Pos) ///< PCM with short frame 73 #define ARM_SAI_PROTOCOL_PCM_LONG (5U << ARM_SAI_PROTOCOL_Pos) ///< PCM with long frame 74 #define ARM_SAI_PROTOCOL_AC97 (6U << ARM_SAI_PROTOCOL_Pos) ///< AC'97 75 76 /*----- SAI Control Codes: Configuration Parameters: Data Size -----*/ 77 #define ARM_SAI_DATA_SIZE_Pos 13 78 #define ARM_SAI_DATA_SIZE_Msk (0x1FU << ARM_SAI_DATA_SIZE_Pos) 79 #define ARM_SAI_DATA_SIZE(n) ((((n)-1)&0x1FU) << ARM_SAI_DATA_SIZE_Pos) ///< Data size in bits (8..32) 80 81 /*----- SAI Control Codes: Configuration Parameters: Bit Order -----*/ 82 #define ARM_SAI_BIT_ORDER_Pos 18 83 #define ARM_SAI_BIT_ORDER_Msk (1U << ARM_SAI_BIT_ORDER_Pos) 84 #define ARM_SAI_MSB_FIRST (0U << ARM_SAI_BIT_ORDER_Pos) ///< Data is transferred with MSB first (default) 85 #define ARM_SAI_LSB_FIRST (1U << ARM_SAI_BIT_ORDER_Pos) ///< Data is transferred with LSB first; User Protocol only (ignored otherwise) 86 87 /*----- SAI Control Codes: Configuration Parameters: Mono Mode -----*/ 88 #define ARM_SAI_MONO_MODE (1U << 19) ///< Mono Mode (only for I2S, MSB/LSB justified) 89 90 /*----- SAI Control Codes:Configuration Parameters: Companding -----*/ 91 #define ARM_SAI_COMPANDING_Pos 20 92 #define ARM_SAI_COMPANDING_Msk (3U << ARM_SAI_COMPANDING_Pos) 93 #define ARM_SAI_COMPANDING_NONE (0U << ARM_SAI_COMPANDING_Pos) ///< No compading (default) 94 #define ARM_SAI_COMPANDING_A_LAW (2U << ARM_SAI_COMPANDING_Pos) ///< A-Law companding 95 #define ARM_SAI_COMPANDING_U_LAW (3U << ARM_SAI_COMPANDING_Pos) ///< u-Law companding 96 97 /*----- SAI Control Codes: Configuration Parameters: Clock Polarity -----*/ 98 #define ARM_SAI_CLOCK_POLARITY_Pos 23 99 #define ARM_SAI_CLOCK_POLARITY_Msk (1U << ARM_SAI_CLOCK_POLARITY_Pos) 100 #define ARM_SAI_CLOCK_POLARITY_0 (0U << ARM_SAI_CLOCK_POLARITY_Pos) ///< Drive on falling edge, Capture on rising edge (default) 101 #define ARM_SAI_CLOCK_POLARITY_1 (1U << ARM_SAI_CLOCK_POLARITY_Pos) ///< Drive on rising edge, Capture on falling edge 102 103 /*----- SAI Control Codes: Configuration Parameters: Master Clock Pin -----*/ 104 #define ARM_SAI_MCLK_PIN_Pos 24 105 #define ARM_SAI_MCLK_PIN_Msk (3U << ARM_SAI_MCLK_PIN_Pos) 106 #define ARM_SAI_MCLK_PIN_INACTIVE (0U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK not used (default) 107 #define ARM_SAI_MCLK_PIN_OUTPUT (1U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK is output (Master only) 108 #define ARM_SAI_MCLK_PIN_INPUT (2U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK is input (Master only) 109 110 111 /****** SAI Configuration (arg1) *****/ 112 113 /*----- SAI Configuration (arg1): Frame Length -----*/ 114 #define ARM_SAI_FRAME_LENGTH_Pos 0 115 #define ARM_SAI_FRAME_LENGTH_Msk (0x3FFU << ARM_SAI_FRAME_LENGTH_Pos) 116 #define ARM_SAI_FRAME_LENGTH(n) ((((n)-1)&0x3FFU) << ARM_SAI_FRAME_LENGTH_Pos) ///< Frame length in bits (8..1024); default depends on protocol and data 117 118 /*----- SAI Configuration (arg1): Frame Sync Width -----*/ 119 #define ARM_SAI_FRAME_SYNC_WIDTH_Pos 10 120 #define ARM_SAI_FRAME_SYNC_WIDTH_Msk (0xFFU << ARM_SAI_FRAME_SYNC_WIDTH_Pos) 121 #define ARM_SAI_FRAME_SYNC_WIDTH(n) ((((n)-1)&0xFFU) << ARM_SAI_FRAME_SYNC_WIDTH_Pos) ///< Frame Sync width in bits (1..256); default=1; User Protocol only (ignored otherwise) 122 123 /*----- SAI Configuration (arg1): Frame Sync Polarity -----*/ 124 #define ARM_SAI_FRAME_SYNC_POLARITY_Pos 18 125 #define ARM_SAI_FRAME_SYNC_POLARITY_Msk (1U << ARM_SAI_FRAME_SYNC_POLARITY_Pos) 126 #define ARM_SAI_FRAME_SYNC_POLARITY_HIGH (0U << ARM_SAI_FRAME_SYNC_POLARITY_Pos) ///< Frame Sync is active high (default); User Protocol only (ignored otherwise) 127 #define ARM_SAI_FRAME_SYNC_POLARITY_LOW (1U << ARM_SAI_FRAME_SYNC_POLARITY_Pos) ///< Frame Sync is active low; User Protocol only (ignored otherwise) 128 129 /*----- SAI Configuration (arg1): Frame Sync Early -----*/ 130 #define ARM_SAI_FRAME_SYNC_EARLY (1U << 19) ///< Frame Sync one bit before the first bit of the frame; User Protocol only (ignored otherwise) 131 132 /*----- SAI Configuration (arg1): Slot Count -----*/ 133 #define ARM_SAI_SLOT_COUNT_Pos 20 134 #define ARM_SAI_SLOT_COUNT_Msk (0x1FU << ARM_SAI_SLOT_COUNT_Pos) 135 #define ARM_SAI_SLOT_COUNT(n) ((((n)-1)&0x1FU) << ARM_SAI_SLOT_COUNT_Pos) ///< Number of slots in frame (1..32); default=1; User Protocol only (ignored otherwise) 136 137 /*----- SAI Configuration (arg1): Slot Size -----*/ 138 #define ARM_SAI_SLOT_SIZE_Pos 25 139 #define ARM_SAI_SLOT_SIZE_Msk (3U << ARM_SAI_SLOT_SIZE_Pos) 140 #define ARM_SAI_SLOT_SIZE_DEFAULT (0U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size is equal to data size (default) 141 #define ARM_SAI_SLOT_SIZE_16 (1U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size = 16 bits; User Protocol only (ignored otherwise) 142 #define ARM_SAI_SLOT_SIZE_32 (3U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size = 32 bits; User Protocol only (ignored otherwise) 143 144 /*----- SAI Configuration (arg1): Slot Offset -----*/ 145 #define ARM_SAI_SLOT_OFFSET_Pos 27 146 #define ARM_SAI_SLOT_OFFSET_Msk (0x1FU << ARM_SAI_SLOT_OFFSET_Pos) 147 #define ARM_SAI_SLOT_OFFSET(n) (((n)&0x1FU) << ARM_SAI_SLOT_OFFSET_Pos) ///< Offset of first data bit in slot (0..31); default=0; User Protocol only (ignored otherwise) 148 149 /****** SAI Configuration (arg2) *****/ 150 151 /*----- SAI Control Codes: Configuration Parameters: Audio Frequency (Master only) -----*/ 152 #define ARM_SAI_AUDIO_FREQ_Msk (0x0FFFFFU) ///< Audio frequency mask 153 154 /*----- SAI Control Codes: Configuration Parameters: Master Clock Prescaler (Master only and MCLK Pin) -----*/ 155 #define ARM_SAI_MCLK_PRESCALER_Pos 20 156 #define ARM_SAI_MCLK_PRESCALER_Msk (0xFFFU << ARM_SAI_MCLK_PRESCALER_Pos) 157 #define ARM_SAI_MCLK_PRESCALER(n) ((((n)-1)&0xFFFU) << ARM_SAI_MCLK_PRESCALER_Pos) ///< MCLK prescaler; Audio_frequency = MCLK/n; n = 1..4096 (default=1) 158 159 160 /****** SAI specific error codes *****/ 161 #define ARM_SAI_ERROR_SYNCHRONIZATION (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Specified Synchronization not supported 162 #define ARM_SAI_ERROR_PROTOCOL (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Specified Protocol not supported 163 #define ARM_SAI_ERROR_DATA_SIZE (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Specified Data size not supported 164 #define ARM_SAI_ERROR_BIT_ORDER (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Specified Bit order not supported 165 #define ARM_SAI_ERROR_MONO_MODE (ARM_DRIVER_ERROR_SPECIFIC - 5) ///< Specified Mono mode not supported 166 #define ARM_SAI_ERROR_COMPANDING (ARM_DRIVER_ERROR_SPECIFIC - 6) ///< Specified Companding not supported 167 #define ARM_SAI_ERROR_CLOCK_POLARITY (ARM_DRIVER_ERROR_SPECIFIC - 7) ///< Specified Clock polarity not supported 168 #define ARM_SAI_ERROR_AUDIO_FREQ (ARM_DRIVER_ERROR_SPECIFIC - 8) ///< Specified Audio frequency not supported 169 #define ARM_SAI_ERROR_MCLK_PIN (ARM_DRIVER_ERROR_SPECIFIC - 9) ///< Specified MCLK Pin setting not supported 170 #define ARM_SAI_ERROR_MCLK_PRESCALER (ARM_DRIVER_ERROR_SPECIFIC - 10) ///< Specified MCLK Prescaler not supported 171 #define ARM_SAI_ERROR_FRAME_LENGHT (ARM_DRIVER_ERROR_SPECIFIC - 11) ///< Specified Frame length not supported 172 #define ARM_SAI_ERROR_FRAME_SYNC_WIDTH (ARM_DRIVER_ERROR_SPECIFIC - 12) ///< Specified Frame Sync width not supported 173 #define ARM_SAI_ERROR_FRAME_SYNC_POLARITY (ARM_DRIVER_ERROR_SPECIFIC - 13) ///< Specified Frame Sync polarity not supported 174 #define ARM_SAI_ERROR_FRAME_SYNC_EARLY (ARM_DRIVER_ERROR_SPECIFIC - 14) ///< Specified Frame Sync early not supported 175 #define ARM_SAI_ERROR_SLOT_COUNT (ARM_DRIVER_ERROR_SPECIFIC - 15) ///< Specified Slot count not supported 176 #define ARM_SAI_ERROR_SLOT_SIZE (ARM_DRIVER_ERROR_SPECIFIC - 16) ///< Specified Slot size not supported 177 #define ARM_SAI_ERROR_SLOT_OFFESET (ARM_DRIVER_ERROR_SPECIFIC - 17) ///< Specified Slot offset not supported 178 179 180 /** 181 \brief SAI Status 182 */ 183 typedef struct _ARM_SAI_STATUS { 184 unsigned int tx_busy : 1; ///< Transmitter busy flag 185 unsigned int rx_busy : 1; ///< Receiver busy flag 186 unsigned int tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation) 187 unsigned int rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation) 188 unsigned int frame_error : 1; ///< Sync Frame error detected (cleared on start of next send/receive operation) 189 } ARM_SAI_STATUS; 190 191 192 /****** SAI Event *****/ 193 #define ARM_SAI_EVENT_SEND_COMPLETE (1U << 0) ///< Send completed 194 #define ARM_SAI_EVENT_RECEIVE_COMPLETE (1U << 1) ///< Receive completed 195 #define ARM_SAI_EVENT_TX_UNDERFLOW (1U << 2) ///< Transmit data not available 196 #define ARM_SAI_EVENT_RX_OVERFLOW (1U << 3) ///< Receive data overflow 197 #define ARM_SAI_EVENT_FRAME_ERROR (1U << 4) ///< Sync Frame error in Slave mode (optional) 198 199 200 // Function documentation 201 /** 202 \fn ARM_DRIVER_VERSION ARM_SAI_GetVersion (void) 203 \brief Get driver version. 204 \return \ref ARM_DRIVER_VERSION 205 206 \fn ARM_SAI_CAPABILITIES ARM_SAI_GetCapabilities (void) 207 \brief Get driver capabilities. 208 \return \ref ARM_SAI_CAPABILITIES 209 210 \fn int32_t ARM_SAI_Initialize (ARM_SAI_SignalEvent_t cb_event) 211 \brief Initialize SAI Interface. 212 \param[in] cb_event Pointer to \ref ARM_SAI_SignalEvent 213 \return \ref execution_status 214 215 \fn int32_t ARM_SAI_Uninitialize (void) 216 \brief De-initialize SAI Interface. 217 \return \ref execution_status 218 219 \fn int32_t ARM_SAI_PowerControl (ARM_POWER_STATE state) 220 \brief Control SAI Interface Power. 221 \param[in] state Power state 222 \return \ref execution_status 223 224 \fn int32_t ARM_SAI_Send (const void *data, uint32_t num) 225 \brief Start sending data to SAI transmitter. 226 \param[in] data Pointer to buffer with data to send to SAI transmitter 227 \param[in] num Number of data items to send 228 \return \ref execution_status 229 230 \fn int32_t ARM_SAI_Receive (void *data, uint32_t num) 231 \brief Start receiving data from SAI receiver. 232 \param[out] data Pointer to buffer for data to receive from SAI receiver 233 \param[in] num Number of data items to receive 234 \return \ref execution_status 235 236 \fn uint32_t ARM_SAI_GetTxCount (void) 237 \brief Get transmitted data count. 238 \return number of data items transmitted 239 240 \fn uint32_t ARM_SAI_GetRxCount (void) 241 \brief Get received data count. 242 \return number of data items received 243 244 \fn int32_t ARM_SAI_Control (uint32_t control, uint32_t arg1, uint32_t arg2) 245 \brief Control SAI Interface. 246 \param[in] control Operation 247 \param[in] arg1 Argument 1 of operation (optional) 248 \param[in] arg2 Argument 2 of operation (optional) 249 \return common \ref execution_status and driver specific \ref sai_execution_status 250 251 \fn ARM_SAI_STATUS ARM_SAI_GetStatus (void) 252 \brief Get SAI status. 253 \return SAI status \ref ARM_SAI_STATUS 254 255 \fn void ARM_SAI_SignalEvent (uint32_t event) 256 \brief Signal SAI Events. 257 \param[in] event \ref SAI_events notification mask 258 \return none 259 */ 260 261 typedef void (*ARM_SAI_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_SAI_SignalEvent : Signal SAI Event. 262 263 264 /** 265 \brief SAI Driver Capabilities. 266 */ 267 typedef struct _ARM_SAI_CAPABILITIES { 268 uint32_t asynchronous : 1; ///< supports asynchronous Transmit/Receive 269 uint32_t synchronous : 1; ///< supports synchronous Transmit/Receive 270 uint32_t protocol_user : 1; ///< supports user defined Protocol 271 uint32_t protocol_i2s : 1; ///< supports I2S Protocol 272 uint32_t protocol_justified : 1; ///< supports MSB/LSB justified Protocol 273 uint32_t protocol_pcm : 1; ///< supports PCM short/long frame Protocol 274 uint32_t protocol_ac97 : 1; ///< supports AC'97 Protocol 275 uint32_t mono_mode : 1; ///< supports Mono mode 276 uint32_t companding : 1; ///< supports Companding 277 uint32_t mclk_pin : 1; ///< supports MCLK (Master Clock) pin 278 uint32_t event_frame_error : 1; ///< supports Frame error event: \ref ARM_SAI_EVENT_FRAME_ERROR 279 } ARM_SAI_CAPABILITIES; 280 281 282 /** 283 \brief Access structure of the SAI Driver. 284 */ 285 typedef struct _ARM_DRIVER_SAI { 286 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_SAI_GetVersion : Get driver version. 287 ARM_SAI_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_SAI_GetCapabilities : Get driver capabilities. 288 int32_t (*Initialize) (ARM_SAI_SignalEvent_t cb_event); ///< Pointer to \ref ARM_SAI_Initialize : Initialize SAI Interface. 289 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_SAI_Uninitialize : De-initialize SAI Interface. 290 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_SAI_PowerControl : Control SAI Interface Power. 291 int32_t (*Send) (const void *data, uint32_t num); ///< Pointer to \ref ARM_SAI_Send : Start sending data to SAI Interface. 292 int32_t (*Receive) ( void *data, uint32_t num); ///< Pointer to \ref ARM_SAI_Receive : Start receiving data from SAI Interface. 293 uint32_t (*GetTxCount) (void); ///< Pointer to \ref ARM_SAI_GetTxCount : Get transmitted data count. 294 uint32_t (*GetRxCount) (void); ///< Pointer to \ref ARM_SAI_GetRxCount : Get received data count. 295 int32_t (*Control) (uint32_t control, uint32_t arg1, uint32_t arg2); ///< Pointer to \ref ARM_SAI_Control : Control SAI Interface. 296 ARM_SAI_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_SAI_GetStatus : Get SAI status. 297 } const ARM_DRIVER_SAI; 298 299 #endif /* __DRIVER_SAI_H */ 300
