2 * Copyright (c) 2013-2016 ARM Limited. All rights reserved.
\r
4 * SPDX-License-Identifier: Apache-2.0
\r
6 * Licensed under the Apache License, Version 2.0 (the License); you may
\r
7 * not use this file except in compliance with the License.
\r
8 * You may obtain a copy of the License at
\r
10 * http://www.apache.org/licenses/LICENSE-2.0
\r
12 * Unless required by applicable law or agreed to in writing, software
\r
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
\r
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
15 * See the License for the specific language governing permissions and
\r
16 * limitations under the License.
\r
18 * $Date: 9. Dec 2014
\r
21 * Project: SAI (Serial Audio Interface) Driver definitions
\r
29 #ifndef __DRIVER_SAI_H
\r
30 #define __DRIVER_SAI_H
\r
32 #include "Driver_Common.h"
\r
34 #define ARM_SAI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,00) /* API version */
\r
37 /****** SAI Control Codes *****/
\r
39 #define ARM_SAI_CONTROL_Msk (0xFFU)
\r
40 #define ARM_SAI_CONFIGURE_TX (0x01U) ///< Configure Transmitter; arg1 and arg2 provide additional configuration
\r
41 #define ARM_SAI_CONFIGURE_RX (0x02U) ///< Configure Receiver; arg1 and arg2 provide additional configuration
\r
42 #define ARM_SAI_CONTROL_TX (0x03U) ///< Control Transmitter; arg1.0: 0=disable (default), 1=enable; arg1.1: mute
\r
43 #define ARM_SAI_CONTROL_RX (0x04U) ///< Control Receiver; arg1.0: 0=disable (default), 1=enable
\r
44 #define ARM_SAI_MASK_SLOTS_TX (0x05U) ///< Mask Transmitter slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default
\r
45 #define ARM_SAI_MASK_SLOTS_RX (0x06U) ///< Mask Receiver slots; arg1 = mask (bit: 0=active, 1=inactive); all configured slots are active by default
\r
46 #define ARM_SAI_ABORT_SEND (0x07U) ///< Abort \ref ARM_SAI_Send
\r
47 #define ARM_SAI_ABORT_RECEIVE (0x08U) ///< Abort \ref ARM_SAI_Receive
\r
49 /*----- SAI Control Codes: Configuration Parameters: Mode -----*/
\r
50 #define ARM_SAI_MODE_Pos 8
\r
51 #define ARM_SAI_MODE_Msk (1U << ARM_SAI_MODE_Pos)
\r
52 #define ARM_SAI_MODE_MASTER (1U << ARM_SAI_MODE_Pos) ///< Master Mode
\r
53 #define ARM_SAI_MODE_SLAVE (0U << ARM_SAI_MODE_Pos) ///< Slave Mode (default)
\r
55 /*----- SAI Control Codes: Configuration Parameters: Synchronization -----*/
\r
56 #define ARM_SAI_SYNCHRONIZATION_Pos 9
\r
57 #define ARM_SAI_SYNCHRONIZATION_Msk (1U << ARM_SAI_SYNCHRONIZATION_Pos)
\r
58 #define ARM_SAI_ASYNCHRONOUS (0U << ARM_SAI_SYNCHRONIZATION_Pos) ///< Asynchronous (default)
\r
59 #define ARM_SAI_SYNCHRONOUS (1U << ARM_SAI_SYNCHRONIZATION_Pos) ///< Synchronous
\r
61 /*----- SAI Control Codes: Configuration Parameters: Protocol -----*/
\r
62 #define ARM_SAI_PROTOCOL_Pos 10
\r
63 #define ARM_SAI_PROTOCOL_Msk (7U << ARM_SAI_PROTOCOL_Pos)
\r
64 #define ARM_SAI_PROTOCOL_USER (0U << ARM_SAI_PROTOCOL_Pos) ///< User defined (default)
\r
65 #define ARM_SAI_PROTOCOL_I2S (1U << ARM_SAI_PROTOCOL_Pos) ///< I2S
\r
66 #define ARM_SAI_PROTOCOL_MSB_JUSTIFIED (2U << ARM_SAI_PROTOCOL_Pos) ///< MSB (left) justified
\r
67 #define ARM_SAI_PROTOCOL_LSB_JUSTIFIED (3U << ARM_SAI_PROTOCOL_Pos) ///< LSB (right) justified
\r
68 #define ARM_SAI_PROTOCOL_PCM_SHORT (4U << ARM_SAI_PROTOCOL_Pos) ///< PCM with short frame
\r
69 #define ARM_SAI_PROTOCOL_PCM_LONG (5U << ARM_SAI_PROTOCOL_Pos) ///< PCM with long frame
\r
70 #define ARM_SAI_PROTOCOL_AC97 (6U << ARM_SAI_PROTOCOL_Pos) ///< AC'97
\r
72 /*----- SAI Control Codes: Configuration Parameters: Data Size -----*/
\r
73 #define ARM_SAI_DATA_SIZE_Pos 13
\r
74 #define ARM_SAI_DATA_SIZE_Msk (0x1FU << ARM_SAI_DATA_SIZE_Pos)
\r
75 #define ARM_SAI_DATA_SIZE(n) ((((n)-1)&0x1FU) << ARM_SAI_DATA_SIZE_Pos) ///< Data size in bits (8..32)
\r
77 /*----- SAI Control Codes: Configuration Parameters: Bit Order -----*/
\r
78 #define ARM_SAI_BIT_ORDER_Pos 18
\r
79 #define ARM_SAI_BIT_ORDER_Msk (1U << ARM_SAI_BIT_ORDER_Pos)
\r
80 #define ARM_SAI_MSB_FIRST (0U << ARM_SAI_BIT_ORDER_Pos) ///< Data is transferred with MSB first (default)
\r
81 #define ARM_SAI_LSB_FIRST (1U << ARM_SAI_BIT_ORDER_Pos) ///< Data is transferred with LSB first; User Protocol only (ignored otherwise)
\r
83 /*----- SAI Control Codes: Configuration Parameters: Mono Mode -----*/
\r
84 #define ARM_SAI_MONO_MODE (1U << 19) ///< Mono Mode (only for I2S, MSB/LSB justified)
\r
86 /*----- SAI Control Codes:Configuration Parameters: Companding -----*/
\r
87 #define ARM_SAI_COMPANDING_Pos 20
\r
88 #define ARM_SAI_COMPANDING_Msk (3U << ARM_SAI_COMPANDING_Pos)
\r
89 #define ARM_SAI_COMPANDING_NONE (0U << ARM_SAI_COMPANDING_Pos) ///< No compading (default)
\r
90 #define ARM_SAI_COMPANDING_A_LAW (2U << ARM_SAI_COMPANDING_Pos) ///< A-Law companding
\r
91 #define ARM_SAI_COMPANDING_U_LAW (3U << ARM_SAI_COMPANDING_Pos) ///< u-Law companding
\r
93 /*----- SAI Control Codes: Configuration Parameters: Clock Polarity -----*/
\r
94 #define ARM_SAI_CLOCK_POLARITY_Pos 23
\r
95 #define ARM_SAI_CLOCK_POLARITY_Msk (1U << ARM_SAI_CLOCK_POLARITY_Pos)
\r
96 #define ARM_SAI_CLOCK_POLARITY_0 (0U << ARM_SAI_CLOCK_POLARITY_Pos) ///< Drive on falling edge, Capture on rising edge (default)
\r
97 #define ARM_SAI_CLOCK_POLARITY_1 (1U << ARM_SAI_CLOCK_POLARITY_Pos) ///< Drive on rising edge, Capture on falling edge
\r
99 /*----- SAI Control Codes: Configuration Parameters: Master Clock Pin -----*/
\r
100 #define ARM_SAI_MCLK_PIN_Pos 24
\r
101 #define ARM_SAI_MCLK_PIN_Msk (3U << ARM_SAI_MCLK_PIN_Pos)
\r
102 #define ARM_SAI_MCLK_PIN_INACTIVE (0U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK not used (default)
\r
103 #define ARM_SAI_MCLK_PIN_OUTPUT (1U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK is output (Master only)
\r
104 #define ARM_SAI_MCLK_PIN_INPUT (2U << ARM_SAI_MCLK_PIN_Pos) ///< MCLK is input (Master only)
\r
107 /****** SAI Configuration (arg1) *****/
\r
109 /*----- SAI Configuration (arg1): Frame Length -----*/
\r
110 #define ARM_SAI_FRAME_LENGTH_Pos 0
\r
111 #define ARM_SAI_FRAME_LENGTH_Msk (0x3FFU << ARM_SAI_FRAME_LENGTH_Pos)
\r
112 #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
\r
114 /*----- SAI Configuration (arg1): Frame Sync Width -----*/
\r
115 #define ARM_SAI_FRAME_SYNC_WIDTH_Pos 10
\r
116 #define ARM_SAI_FRAME_SYNC_WIDTH_Msk (0xFFU << ARM_SAI_FRAME_SYNC_WIDTH_Pos)
\r
117 #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)
\r
119 /*----- SAI Configuration (arg1): Frame Sync Polarity -----*/
\r
120 #define ARM_SAI_FRAME_SYNC_POLARITY_Pos 18
\r
121 #define ARM_SAI_FRAME_SYNC_POLARITY_Msk (1U << ARM_SAI_FRAME_SYNC_POLARITY_Pos)
\r
122 #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)
\r
123 #define ARM_SAI_FRAME_SYNC_POLARITY_LOW (1U << ARM_SAI_FRAME_SYNC_POLARITY_Pos) ///< Frame Sync is active low; User Protocol only (ignored otherwise)
\r
125 /*----- SAI Configuration (arg1): Frame Sync Early -----*/
\r
126 #define ARM_SAI_FRAME_SYNC_EARLY (1U << 19) ///< Frame Sync one bit before the first bit of the frame; User Protocol only (ignored otherwise)
\r
128 /*----- SAI Configuration (arg1): Slot Count -----*/
\r
129 #define ARM_SAI_SLOT_COUNT_Pos 20
\r
130 #define ARM_SAI_SLOT_COUNT_Msk (0x1FU << ARM_SAI_SLOT_COUNT_Pos)
\r
131 #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)
\r
133 /*----- SAI Configuration (arg1): Slot Size -----*/
\r
134 #define ARM_SAI_SLOT_SIZE_Pos 25
\r
135 #define ARM_SAI_SLOT_SIZE_Msk (3U << ARM_SAI_SLOT_SIZE_Pos)
\r
136 #define ARM_SAI_SLOT_SIZE_DEFAULT (0U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size is equal to data size (default)
\r
137 #define ARM_SAI_SLOT_SIZE_16 (1U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size = 16 bits; User Protocol only (ignored otherwise)
\r
138 #define ARM_SAI_SLOT_SIZE_32 (3U << ARM_SAI_SLOT_SIZE_Pos) ///< Slot size = 32 bits; User Protocol only (ignored otherwise)
\r
140 /*----- SAI Configuration (arg1): Slot Offset -----*/
\r
141 #define ARM_SAI_SLOT_OFFSET_Pos 27
\r
142 #define ARM_SAI_SLOT_OFFSET_Msk (0x1FU << ARM_SAI_SLOT_OFFSET_Pos)
\r
143 #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)
\r
145 /****** SAI Configuration (arg2) *****/
\r
147 /*----- SAI Control Codes: Configuration Parameters: Audio Frequency (Master only) -----*/
\r
148 #define ARM_SAI_AUDIO_FREQ_Msk (0x0FFFFFU) ///< Audio frequency mask
\r
150 /*----- SAI Control Codes: Configuration Parameters: Master Clock Prescaler (Master only and MCLK Pin) -----*/
\r
151 #define ARM_SAI_MCLK_PRESCALER_Pos 20
\r
152 #define ARM_SAI_MCLK_PRESCALER_Msk (0xFFFU << ARM_SAI_MCLK_PRESCALER_Pos)
\r
153 #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)
\r
156 /****** SAI specific error codes *****/
\r
157 #define ARM_SAI_ERROR_SYNCHRONIZATION (ARM_DRIVER_ERROR_SPECIFIC - 1) ///< Specified Synchronization not supported
\r
158 #define ARM_SAI_ERROR_PROTOCOL (ARM_DRIVER_ERROR_SPECIFIC - 2) ///< Specified Protocol not supported
\r
159 #define ARM_SAI_ERROR_DATA_SIZE (ARM_DRIVER_ERROR_SPECIFIC - 3) ///< Specified Data size not supported
\r
160 #define ARM_SAI_ERROR_BIT_ORDER (ARM_DRIVER_ERROR_SPECIFIC - 4) ///< Specified Bit order not supported
\r
161 #define ARM_SAI_ERROR_MONO_MODE (ARM_DRIVER_ERROR_SPECIFIC - 5) ///< Specified Mono mode not supported
\r
162 #define ARM_SAI_ERROR_COMPANDING (ARM_DRIVER_ERROR_SPECIFIC - 6) ///< Specified Companding not supported
\r
163 #define ARM_SAI_ERROR_CLOCK_POLARITY (ARM_DRIVER_ERROR_SPECIFIC - 7) ///< Specified Clock polarity not supported
\r
164 #define ARM_SAI_ERROR_AUDIO_FREQ (ARM_DRIVER_ERROR_SPECIFIC - 8) ///< Specified Audio frequency not supported
\r
165 #define ARM_SAI_ERROR_MCLK_PIN (ARM_DRIVER_ERROR_SPECIFIC - 9) ///< Specified MCLK Pin setting not supported
\r
166 #define ARM_SAI_ERROR_MCLK_PRESCALER (ARM_DRIVER_ERROR_SPECIFIC - 10) ///< Specified MCLK Prescaler not supported
\r
167 #define ARM_SAI_ERROR_FRAME_LENGHT (ARM_DRIVER_ERROR_SPECIFIC - 11) ///< Specified Frame length not supported
\r
168 #define ARM_SAI_ERROR_FRAME_SYNC_WIDTH (ARM_DRIVER_ERROR_SPECIFIC - 12) ///< Specified Frame Sync width not supported
\r
169 #define ARM_SAI_ERROR_FRAME_SYNC_POLARITY (ARM_DRIVER_ERROR_SPECIFIC - 13) ///< Specified Frame Sync polarity not supported
\r
170 #define ARM_SAI_ERROR_FRAME_SYNC_EARLY (ARM_DRIVER_ERROR_SPECIFIC - 14) ///< Specified Frame Sync early not supported
\r
171 #define ARM_SAI_ERROR_SLOT_COUNT (ARM_DRIVER_ERROR_SPECIFIC - 15) ///< Specified Slot count not supported
\r
172 #define ARM_SAI_ERROR_SLOT_SIZE (ARM_DRIVER_ERROR_SPECIFIC - 16) ///< Specified Slot size not supported
\r
173 #define ARM_SAI_ERROR_SLOT_OFFESET (ARM_DRIVER_ERROR_SPECIFIC - 17) ///< Specified Slot offset not supported
\r
179 typedef struct _ARM_SAI_STATUS {
\r
180 uint32_t tx_busy : 1; ///< Transmitter busy flag
\r
181 uint32_t rx_busy : 1; ///< Receiver busy flag
\r
182 uint32_t tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation)
\r
183 uint32_t rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation)
\r
184 uint32_t frame_error : 1; ///< Sync Frame error detected (cleared on start of next send/receive operation)
\r
188 /****** SAI Event *****/
\r
189 #define ARM_SAI_EVENT_SEND_COMPLETE (1U << 0) ///< Send completed
\r
190 #define ARM_SAI_EVENT_RECEIVE_COMPLETE (1U << 1) ///< Receive completed
\r
191 #define ARM_SAI_EVENT_TX_UNDERFLOW (1U << 2) ///< Transmit data not available
\r
192 #define ARM_SAI_EVENT_RX_OVERFLOW (1U << 3) ///< Receive data overflow
\r
193 #define ARM_SAI_EVENT_FRAME_ERROR (1U << 4) ///< Sync Frame error in Slave mode (optional)
\r
196 // Function documentation
\r
198 \fn ARM_DRIVER_VERSION ARM_SAI_GetVersion (void)
\r
199 \brief Get driver version.
\r
200 \return \ref ARM_DRIVER_VERSION
\r
202 \fn ARM_SAI_CAPABILITIES ARM_SAI_GetCapabilities (void)
\r
203 \brief Get driver capabilities.
\r
204 \return \ref ARM_SAI_CAPABILITIES
\r
206 \fn int32_t ARM_SAI_Initialize (ARM_SAI_SignalEvent_t cb_event)
\r
207 \brief Initialize SAI Interface.
\r
208 \param[in] cb_event Pointer to \ref ARM_SAI_SignalEvent
\r
209 \return \ref execution_status
\r
211 \fn int32_t ARM_SAI_Uninitialize (void)
\r
212 \brief De-initialize SAI Interface.
\r
213 \return \ref execution_status
\r
215 \fn int32_t ARM_SAI_PowerControl (ARM_POWER_STATE state)
\r
216 \brief Control SAI Interface Power.
\r
217 \param[in] state Power state
\r
218 \return \ref execution_status
\r
220 \fn int32_t ARM_SAI_Send (const void *data, uint32_t num)
\r
221 \brief Start sending data to SAI transmitter.
\r
222 \param[in] data Pointer to buffer with data to send to SAI transmitter
\r
223 \param[in] num Number of data items to send
\r
224 \return \ref execution_status
\r
226 \fn int32_t ARM_SAI_Receive (void *data, uint32_t num)
\r
227 \brief Start receiving data from SAI receiver.
\r
228 \param[out] data Pointer to buffer for data to receive from SAI receiver
\r
229 \param[in] num Number of data items to receive
\r
230 \return \ref execution_status
\r
232 \fn uint32_t ARM_SAI_GetTxCount (void)
\r
233 \brief Get transmitted data count.
\r
234 \return number of data items transmitted
\r
236 \fn uint32_t ARM_SAI_GetRxCount (void)
\r
237 \brief Get received data count.
\r
238 \return number of data items received
\r
240 \fn int32_t ARM_SAI_Control (uint32_t control, uint32_t arg1, uint32_t arg2)
\r
241 \brief Control SAI Interface.
\r
242 \param[in] control Operation
\r
243 \param[in] arg1 Argument 1 of operation (optional)
\r
244 \param[in] arg2 Argument 2 of operation (optional)
\r
245 \return common \ref execution_status and driver specific \ref sai_execution_status
\r
247 \fn ARM_SAI_STATUS ARM_SAI_GetStatus (void)
\r
248 \brief Get SAI status.
\r
249 \return SAI status \ref ARM_SAI_STATUS
\r
251 \fn void ARM_SAI_SignalEvent (uint32_t event)
\r
252 \brief Signal SAI Events.
\r
253 \param[in] event \ref SAI_events notification mask
\r
257 typedef void (*ARM_SAI_SignalEvent_t) (uint32_t event); ///< Pointer to \ref ARM_SAI_SignalEvent : Signal SAI Event.
\r
261 \brief SAI Driver Capabilities.
\r
263 typedef struct _ARM_SAI_CAPABILITIES {
\r
264 uint32_t asynchronous : 1; ///< supports asynchronous Transmit/Receive
\r
265 uint32_t synchronous : 1; ///< supports synchronous Transmit/Receive
\r
266 uint32_t protocol_user : 1; ///< supports user defined Protocol
\r
267 uint32_t protocol_i2s : 1; ///< supports I2S Protocol
\r
268 uint32_t protocol_justified : 1; ///< supports MSB/LSB justified Protocol
\r
269 uint32_t protocol_pcm : 1; ///< supports PCM short/long frame Protocol
\r
270 uint32_t protocol_ac97 : 1; ///< supports AC'97 Protocol
\r
271 uint32_t mono_mode : 1; ///< supports Mono mode
\r
272 uint32_t companding : 1; ///< supports Companding
\r
273 uint32_t mclk_pin : 1; ///< supports MCLK (Master Clock) pin
\r
274 uint32_t event_frame_error : 1; ///< supports Frame error event: \ref ARM_SAI_EVENT_FRAME_ERROR
\r
275 } ARM_SAI_CAPABILITIES;
\r
279 \brief Access structure of the SAI Driver.
\r
281 typedef struct _ARM_DRIVER_SAI {
\r
282 ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_SAI_GetVersion : Get driver version.
\r
283 ARM_SAI_CAPABILITIES (*GetCapabilities) (void); ///< Pointer to \ref ARM_SAI_GetCapabilities : Get driver capabilities.
\r
284 int32_t (*Initialize) (ARM_SAI_SignalEvent_t cb_event); ///< Pointer to \ref ARM_SAI_Initialize : Initialize SAI Interface.
\r
285 int32_t (*Uninitialize) (void); ///< Pointer to \ref ARM_SAI_Uninitialize : De-initialize SAI Interface.
\r
286 int32_t (*PowerControl) (ARM_POWER_STATE state); ///< Pointer to \ref ARM_SAI_PowerControl : Control SAI Interface Power.
\r
287 int32_t (*Send) (const void *data, uint32_t num); ///< Pointer to \ref ARM_SAI_Send : Start sending data to SAI Interface.
\r
288 int32_t (*Receive) ( void *data, uint32_t num); ///< Pointer to \ref ARM_SAI_Receive : Start receiving data from SAI Interface.
\r
289 uint32_t (*GetTxCount) (void); ///< Pointer to \ref ARM_SAI_GetTxCount : Get transmitted data count.
\r
290 uint32_t (*GetRxCount) (void); ///< Pointer to \ref ARM_SAI_GetRxCount : Get received data count.
\r
291 int32_t (*Control) (uint32_t control, uint32_t arg1, uint32_t arg2); ///< Pointer to \ref ARM_SAI_Control : Control SAI Interface.
\r
292 ARM_SAI_STATUS (*GetStatus) (void); ///< Pointer to \ref ARM_SAI_GetStatus : Get SAI status.
\r
293 } const ARM_DRIVER_SAI;
\r
295 #endif /* __DRIVER_SAI_H */
\r
begriffs.com / projects / cmsis / blob