stm_i2s_api.h

00001 #ifndef STM_I2S_API_H
00002 #define STM_I2S_API_H
00003 
00004 #include <stdbool.h>
00005 
00006 #include "device.h"
00007 #include "stm_objects.h"
00008 #include "hal/stm_dma_api.h"
00009 #include "hal/buffer.h"
00010 
00011 #if DEVICE_I2S
00012 
00013 #define I2S_EVENT_RX_ERROR         (1 << 1)                                 // 0x2
00014 #define I2S_EVENT_RX_COMPLETE      (1 << 2)                                 // 0x4
00015 #define I2S_EVENT_RX_OVERFLOW      (1 << 3)                                 // 0x8
00016 #define I2S_EVENT_RX_HALF_COMPLETE (1 << 4)                                 // 0x10
00017 
00018 #define I2S_EVENT_TX_ERROR         (I2S_EVENT_RX_ERROR << 8)                // 0x200
00019 #define I2S_EVENT_TX_COMPLETE      (I2S_EVENT_RX_COMPLETE << 8)             // 0x400
00020 #define I2S_EVENT_TX_UNDERRUN      (I2S_EVENT_RX_OVERFLOW << 8)             // 0x800
00021 #define I2S_EVENT_TX_HALF_COMPLETE (I2S_EVENT_RX_HALF_COMPLETE << 8)        // 0x1000
00022 
00023 #define I2S_EVENT_ALL              ((I2S_EVENT_RX_ERROR | I2S_EVENT_RX_COMPLETE | I2S_EVENT_RX_OVERFLOW | I2S_EVENT_RX_HALF_COMPLETE) | \
00024                                     (I2S_EVENT_TX_ERROR | I2S_EVENT_TX_COMPLETE | I2S_EVENT_TX_UNDERRUN | I2S_EVENT_TX_HALF_COMPLETE))
00025 
00026 #define I2S_EVENT_INTERNAL_TRANSFER_COMPLETE (1 << 30) // Internal flag to report that an event occurred
00027 
00028 #define I2S_TX_EVENT                (0x0) // see DMA_TX
00029 #define I2S_RX_EVENT                (0x1) // see DMA_RX
00030 
00031 typedef enum {
00032     PHILIPS,
00033     MSB,
00034     LSB,
00035     PCM_SHORT,
00036     PCM_LONG
00037 } i2s_bitorder_t;
00038 
00039 typedef enum {
00040     SLAVE_TX,
00041     SLAVE_RX,
00042     MASTER_TX,
00043     MASTER_RX
00044 } i2s_mode_t;
00045 
00046 typedef enum {
00047     LOW,
00048     MEDIUM,
00049     HIGH,
00050     URGENT
00051 } i2s_dma_prio_t;
00052 
00053 /** Asynch I2S HAL structure
00054  */
00055 typedef struct {
00056     struct i2s_s i2s;        /**< Target specific I2S structure */
00057     struct dma_s dma;        /**< Target specific DMA structure */
00058     struct buffer_s tx_buff; /**< Tx buffer */
00059     struct buffer_s rx_buff; /**< Rx buffer */
00060 } i2s_t;
00061 
00062 #ifdef __cplusplus
00063 extern "C" {
00064 #endif
00065 
00066 /**
00067  * \defgroup hal_GeneralI2S I2S Configuration Functions
00068  * @{
00069  */
00070 
00071 /** Initialize the I2S peripheral
00072  *
00073  * Configures the pins used by I2S, sets a default format and frequency, and enables the peripheral
00074  * @param[out] obj  The I2S object to initialize
00075  * @param[in]  data I2S data input/output pin
00076  * @param[in]  sclk I2S clock output pin
00077  * @param[in]  wsel I2S word select output pin (might be NC for PDM sources)
00078  * @param[in]  fdpx I2S data input pin (for full-duplex operation, default = NC)
00079  * @param[in]  mclk I2S master clock output pin (default = NC, enables master clock output when not NC)
00080  * @param[in]  mode I2S mode to be applied
00081  */
00082     void i2s_init(i2s_t *obj, PinName data, PinName sclk, PinName wsel, PinName fdpx, PinName mclk, i2s_mode_t mode);
00083 
00084 /** Release a I2S object
00085  *
00086  * TODO: i2s_free is currently unimplemented
00087  * This will require reference counting at the C++ level to be safe
00088  *
00089  * Return the pins owned by the I2S object to their reset state
00090  * Disable the I2S peripheral
00091  * Disable the I2S clock
00092  * @param[in] obj The I2S object to deinitialize
00093  */
00094     void i2s_free(i2s_t *obj);
00095 
00096 /** Configure the I2S format
00097  *
00098  * Set the number of bits per frame, configure clock polarity and phase, shift order and master/slave mode
00099  * @param[in,out] obj   The I2S object to configure
00100  * @param[in]     dbits    Number of data bits per I2S frame (16, 24, or 32)
00101  * @param[in]     fbits    Number of bits per I2S frame (16 or 32)
00102  * @param[in]     polarity Clock polarity (either 0 or 1, default = 0)
00103  */
00104     void i2s_format(i2s_t *obj, int dbits, int fbits, int polarity);
00105 
00106 /** Configure the I2S protocol
00107  *
00108  * @param[in,out] obj      The I2S object to configure
00109  * @param[in]     protocol I2S protocol to be used
00110  */
00111     void i2s_set_protocol(i2s_t *obj, i2s_bitorder_t protocol);
00112 
00113 /** Configure the I2S mode
00114  *
00115  * @param[in,out] obj      The I2S object to configure
00116  * @param[in]     mode     I2S mode to be applied
00117  */
00118     void i2s_set_mode(i2s_t *obj, i2s_mode_t mode);
00119 
00120 /** Set the I2S audio frequency
00121  *
00122  * Actual frequency may differ from the desired frequency due to available dividers and bus clock
00123  * Configures the I2S audio frequency
00124  * @param[in,out] obj The I2S object to configure
00125  * @param[in]     hz  The baud rate in Hz
00126  */
00127     void i2s_audio_frequency(i2s_t *obj, uint32_t hz);
00128 
00129 /**@}*/
00130 /**
00131  * \defgroup SynchI2S Synchronous I2S Hardware Abstraction Layer
00132  * @{
00133  */
00134 
00135 /** Get the module number
00136  *
00137  * @param[in] obj The I2S peripheral to check
00138  * @return The module number
00139  */
00140     uint8_t i2s_get_module(i2s_t *obj);
00141 
00142 /**@}*/
00143 
00144 /**
00145  * \defgroup AsynchI2S Asynchronous I2S Hardware Abstraction Layer
00146  * @{
00147  */
00148 
00149 /** Begin the I2S transfer. Buffer pointers and lengths are specified in tx_buff and rx_buff
00150  *
00151  * @param[in] obj        The I2S object that holds the transfer information
00152  * @param[in] tx         The transmit buffer
00153  * @param[in] tx_length  The number of bytes to transmit
00154  * @param[in] rx         The receive buffer
00155  * @param[in] rx_length  The number of bytes to receive
00156  * @param[in] circular   Enable circular buffer transfer
00157  * @param[in] prio       DMA priority of the transfer
00158  * @param[in] handler_tx I2S tx interrupt handler
00159  * @param[in] handler_rx I2S rx interrupt handler
00160  * @param[in] event      The logical OR of events to be registered
00161  */
00162     void i2s_transfer(i2s_t *obj, void *tx, int tx_length, void *rx, int rx_length,
00163               bool circular, i2s_dma_prio_t prio,
00164               uint32_t handler_tx, uint32_t handler_rx, 
00165               uint32_t event);
00166 
00167 /** The asynchronous IRQ handler
00168  *
00169  * Reads the received values out of the RX FIFO, writes values into the TX FIFO and checks for transfer termination
00170  * conditions, such as buffer overflows or transfer complete.
00171  * @param[in] obj       The I2S object that holds the transfer information
00172  * @param[in] direction From whom is the irq coming (RX or TX)
00173  * @return Event flags if a transfer termination condition was met; otherwise 0.
00174  */
00175     uint32_t i2s_irq_handler_asynch(i2s_t *obj, uint8_t direction);
00176 
00177 /** Attempts to determine if the I2S peripheral is already in use
00178  *
00179  * For each assigned buffer, check
00180  * if the corresponding buffer position is less than the buffer length.  If buffers do not indicate activity, check if
00181  * there are any bytes in the FIFOs.
00182  * @param[in] obj The I2S object to check for activity
00183  * @return Non-zero if the I2S port is active or zero if it is not.
00184  */
00185     uint8_t i2s_active(i2s_t *obj);
00186 
00187 /** Abort an I2S transfer
00188  *
00189  * @param obj The I2S peripheral to stop
00190  */
00191     void i2s_abort_asynch(i2s_t *obj);
00192 
00193 /**
00194  * @brief Harmonize frequencies of two I2S devices
00195  * TODO: doxygen description
00196  *  @return Zero if the frequencies have been harmonized correctly, -1
00197  *          otherwise.
00198  */
00199     int8_t i2s_harmonize(i2s_t *dev_i2s_1, uint32_t *freq_i2s_1, i2s_t *dev_i2s_2, uint32_t *freq_i2s_2);
00200 
00201 /**@}*/
00202 
00203 #ifdef __cplusplus
00204 }
00205 #endif // __cplusplus
00206 
00207 #endif // DEVICE_I2S
00208 
00209 #endif // STM_I2S_API_H