Quentin Roche / ST_I2S

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   X_NUCLEO_CCA02M1

Fork of ST_I2S by ST

drivers/I2S.h@17:7a4a4631672c, 2017-01-26 (annotated)

Committer:
Wolfgang Betz
Date:
Thu Jan 26 10:37:27 2017 +0100
Revision:
17:7a4a4631672c
Parent:
16:04e1abb4cca3
Child:
19:ef6ef1795e30
Remove `namespace mbed`

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Wolfgang Betz 0:752e74bf5ef1 1 #ifndef MBED_I2S_H
Wolfgang Betz 0:752e74bf5ef1 2 #define MBED_I2S_H
Wolfgang Betz 0:752e74bf5ef1 3
Wolfgang Betz 0:752e74bf5ef1 4 #include "platform/platform.h"
Wolfgang Betz 0:752e74bf5ef1 5
Wolfgang Betz 0:752e74bf5ef1 6 #if DEVICE_I2S
Wolfgang Betz 0:752e74bf5ef1 7
Wolfgang Betz 0:752e74bf5ef1 8 #include "platform/PlatformMutex.h"
Wolfgang Betz 1:f90318e0923b 9 #include "hal/stm_i2s_api.h"
Wolfgang Betz 0:752e74bf5ef1 10 #include "platform/SingletonPtr.h"
Wolfgang Betz 0:752e74bf5ef1 11
Wolfgang Betz 0:752e74bf5ef1 12 #include "platform/CThunk.h"
Wolfgang Betz 1:f90318e0923b 13 #include "hal/stm_dma_api.h"
Wolfgang Betz 0:752e74bf5ef1 14 #include "platform/CircularBuffer.h"
Wolfgang Betz 0:752e74bf5ef1 15 #include "platform/FunctionPointer.h"
Wolfgang Betz 0:752e74bf5ef1 16 #include "platform/Transaction.h"
Wolfgang Betz 0:752e74bf5ef1 17
Wolfgang Betz 0:752e74bf5ef1 18 #include "events/EventQueue.h"
Wolfgang Betz 0:752e74bf5ef1 19
Wolfgang Betz 0:752e74bf5ef1 20 /** A I2S Master/Slave, used for communicating with I2S slave/master devices
Wolfgang Betz 0:752e74bf5ef1 21 *
Wolfgang Betz 0:752e74bf5ef1 22 * The default format is set to master transmission mode, one-shot (i.e. not circular)
Wolfgang Betz 0:752e74bf5ef1 23 * 16 data bits & 16 bits per frame, clock polarity 0,
Wolfgang Betz 0:752e74bf5ef1 24 * protocol PHILIPS, and a clock frequency of 44.1kHz
Wolfgang Betz 0:752e74bf5ef1 25 *
Wolfgang Betz 0:752e74bf5ef1 26 * TODO: "direct" PDM support
Wolfgang Betz 0:752e74bf5ef1 27 *
Wolfgang Betz 0:752e74bf5ef1 28 * Most I2S devices will also require Reset signals. These
Wolfgang Betz 0:752e74bf5ef1 29 * can be controlled using <DigitalOut> pins
Wolfgang Betz 0:752e74bf5ef1 30 *
Wolfgang Betz 0:752e74bf5ef1 31 * @Note Synchronization level: Thread safe
Wolfgang Betz 0:752e74bf5ef1 32 *
Wolfgang Betz 0:752e74bf5ef1 33 */
Wolfgang Betz 10:1a612c2e4a85 34 class I2S {
Wolfgang Betz 0:752e74bf5ef1 35
Wolfgang Betz 10:1a612c2e4a85 36 public:
Wolfgang Betz 10:1a612c2e4a85 37 /** Create a I2S master connected to the specified pins
Wolfgang Betz 10:1a612c2e4a85 38 *
Wolfgang Betz 10:1a612c2e4a85 39 * @param dpin I2S data input/output pin
Wolfgang Betz 10:1a612c2e4a85 40 * @param clk I2S clock output pin
Wolfgang Betz 10:1a612c2e4a85 41 * @param wsel I2S word select output pin (might be NC for PDM sources)
Wolfgang Betz 10:1a612c2e4a85 42 * @param fdpin I2S data input pin (for full-duplex operation, default = NC)
Wolfgang Betz 10:1a612c2e4a85 43 * @param mck I2S master clock output (additional pin when needed for some external audio devices, default = NC)
Wolfgang Betz 10:1a612c2e4a85 44 *
Wolfgang Betz 10:1a612c2e4a85 45 * @Note It is up to the application programmer to not generate at the same time two I2S instances with the
Wolfgang Betz 10:1a612c2e4a85 46 * same pin (NC excluded) for one of the parameters, otherwise the correct operation of this class cannot be
Wolfgang Betz 10:1a612c2e4a85 47 * guaranteed (e.g. things like SPI/I2S clock enabling and above all disabling might not work correctly)!
Wolfgang Betz 10:1a612c2e4a85 48 */
Wolfgang Betz 10:1a612c2e4a85 49 I2S(PinName dpin, PinName clk, PinName wsel, PinName fdpin = NC, PinName mck = NC);
Wolfgang Betz 0:752e74bf5ef1 50
Wolfgang Betz 10:1a612c2e4a85 51 /** Configure the data transmission format
Wolfgang Betz 10:1a612c2e4a85 52 *
Wolfgang Betz 10:1a612c2e4a85 53 * @param dbits Number of data bits per I2S frame (16, 24, or 32)
Wolfgang Betz 10:1a612c2e4a85 54 * @param fbits Number of bits per I2S frame (16 or 32)
Wolfgang Betz 10:1a612c2e4a85 55 * @param polarity Clock polarity (either 0/low or 1/high, default = 0)
Wolfgang Betz 10:1a612c2e4a85 56 * @return Zero if the usage was set, -1 if a transaction is on-going
Wolfgang Betz 10:1a612c2e4a85 57 */
Wolfgang Betz 10:1a612c2e4a85 58 int format(int dbits, int fbits, int polarity = 0);
Wolfgang Betz 0:752e74bf5ef1 59
Wolfgang Betz 10:1a612c2e4a85 60 /** Set the i2s audio frequency
Wolfgang Betz 10:1a612c2e4a85 61 *
Wolfgang Betz 10:1a612c2e4a85 62 * @param hz audio frequency in hz
Wolfgang Betz 10:1a612c2e4a85 63 * @return Zero if the usage was set, -1 if a transaction is on-going
Wolfgang Betz 10:1a612c2e4a85 64 */
Wolfgang Betz 10:1a612c2e4a85 65 int audio_frequency(unsigned int hz);
Wolfgang Betz 0:752e74bf5ef1 66
Wolfgang Betz 13:fa1b24df9025 67 /** Get the i2s audio frequency
Wolfgang Betz 13:fa1b24df9025 68 *
Wolfgang Betz 13:fa1b24df9025 69 * @return Currently set audio frequency
Wolfgang Betz 13:fa1b24df9025 70 */
Wolfgang Betz 13:fa1b24df9025 71 unsigned int get_audio_frequency(void) {
Wolfgang Betz 16:04e1abb4cca3 72 return _hz;
Wolfgang Betz 13:fa1b24df9025 73 }
Wolfgang Betz 13:fa1b24df9025 74
Wolfgang Betz 10:1a612c2e4a85 75 /** Set the i2s bus protocol
Wolfgang Betz 10:1a612c2e4a85 76 *
Wolfgang Betz 10:1a612c2e4a85 77 * @param protocol I2S protocol to be used
Wolfgang Betz 10:1a612c2e4a85 78 * @return Zero if the usage was set, -1 if a transaction is on-going
Wolfgang Betz 10:1a612c2e4a85 79 */
Wolfgang Betz 10:1a612c2e4a85 80 int set_protocol(i2s_bitorder_t protocol);
Wolfgang Betz 0:752e74bf5ef1 81
Wolfgang Betz 10:1a612c2e4a85 82 /** Set the i2s mode
Wolfgang Betz 10:1a612c2e4a85 83 *
Wolfgang Betz 10:1a612c2e4a85 84 * @param mode I2S mode to be used
Wolfgang Betz 10:1a612c2e4a85 85 * @param circular I2S should read/write buffers continuously (in circular mode)
Wolfgang Betz 10:1a612c2e4a85 86 * @return Zero if the usage was set, -1 if a transaction is on-going
Wolfgang Betz 10:1a612c2e4a85 87 */
Wolfgang Betz 10:1a612c2e4a85 88 int set_mode(i2s_mode_t mode, bool circular);
Wolfgang Betz 0:752e74bf5ef1 89
Wolfgang Betz 10:1a612c2e4a85 90 /** Start non-blocking I2S transfer as configured with above methods
Wolfgang Betz 10:1a612c2e4a85 91 *
Wolfgang Betz 10:1a612c2e4a85 92 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
Wolfgang Betz 10:1a612c2e4a85 93 * no transmission will be set up
Wolfgang Betz 10:1a612c2e4a85 94 * @param tx_length The length of TX buffer in bytes
Wolfgang Betz 10:1a612c2e4a85 95 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
Wolfgang Betz 10:1a612c2e4a85 96 * received data will be ignored
Wolfgang Betz 10:1a612c2e4a85 97 * @param rx_length The length of RX buffer in bytes
Wolfgang Betz 10:1a612c2e4a85 98 * @param callback The event callback function
Wolfgang Betz 10:1a612c2e4a85 99 * @param event The logical OR of events to notify. Look at i2s hal header file for I2S events.
Wolfgang Betz 10:1a612c2e4a85 100 * @return Zero if the transfer has started (or been queued), or
Wolfgang Betz 10:1a612c2e4a85 101 * -1 if I2S peripheral is busy (or out of resources)
Wolfgang Betz 10:1a612c2e4a85 102 */
Wolfgang Betz 10:1a612c2e4a85 103 template<typename Type>
Wolfgang Betz 17:7a4a4631672c 104 int transfer(const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const mbed::event_callback_t& callback, int event) {
Wolfgang Betz 10:1a612c2e4a85 105 int ret = 0;
Wolfgang Betz 0:752e74bf5ef1 106
Wolfgang Betz 10:1a612c2e4a85 107 lock();
Wolfgang Betz 10:1a612c2e4a85 108
Wolfgang Betz 10:1a612c2e4a85 109 if (i2s_active(&_i2s)
Wolfgang Betz 0:752e74bf5ef1 110 #if TRANSACTION_QUEUE_SIZE_I2S
Wolfgang Betz 10:1a612c2e4a85 111 || !_transaction_buffer.empty()
Wolfgang Betz 0:752e74bf5ef1 112 #endif
Wolfgang Betz 10:1a612c2e4a85 113 ) {
Wolfgang Betz 10:1a612c2e4a85 114 ret = queue_transfer(tx_buffer, tx_length, rx_buffer, rx_length, callback, event);
Wolfgang Betz 10:1a612c2e4a85 115 } else {
Wolfgang Betz 10:1a612c2e4a85 116 start_transfer(tx_buffer, tx_length, rx_buffer, rx_length, callback, event);
Wolfgang Betz 9:c4c2240e06d6 117 }
Wolfgang Betz 10:1a612c2e4a85 118
Wolfgang Betz 10:1a612c2e4a85 119 unlock();
Wolfgang Betz 10:1a612c2e4a85 120 return ret;
Wolfgang Betz 10:1a612c2e4a85 121 }
Wolfgang Betz 0:752e74bf5ef1 122
Wolfgang Betz 10:1a612c2e4a85 123 /** Abort the on-going I2S transfer, and continue with transfer's in the queue if any.
Wolfgang Betz 10:1a612c2e4a85 124 */
Wolfgang Betz 10:1a612c2e4a85 125 void abort_transfer();
Wolfgang Betz 0:752e74bf5ef1 126
Wolfgang Betz 10:1a612c2e4a85 127 /** Clear the transaction buffer
Wolfgang Betz 10:1a612c2e4a85 128 */
Wolfgang Betz 10:1a612c2e4a85 129 void clear_transfer_buffer();
Wolfgang Betz 0:752e74bf5ef1 130
Wolfgang Betz 10:1a612c2e4a85 131 /** Clear the transaction buffer and abort on-going transfer.
Wolfgang Betz 10:1a612c2e4a85 132 */
Wolfgang Betz 10:1a612c2e4a85 133 void abort_all_transfers();
Wolfgang Betz 0:752e74bf5ef1 134
Wolfgang Betz 10:1a612c2e4a85 135 /** Get transfer status
Wolfgang Betz 10:1a612c2e4a85 136 *
Wolfgang Betz 10:1a612c2e4a85 137 * @return -1 if a transaction is on-going, zero otherwise
Wolfgang Betz 10:1a612c2e4a85 138 */
Wolfgang Betz 10:1a612c2e4a85 139 int get_transfer_status();
Wolfgang Betz 0:752e74bf5ef1 140
Wolfgang Betz 10:1a612c2e4a85 141 /** Get internal module id
Wolfgang Betz 10:1a612c2e4a85 142 *
Wolfgang Betz 10:1a612c2e4a85 143 * @return internal module id
Wolfgang Betz 10:1a612c2e4a85 144 */
Wolfgang Betz 10:1a612c2e4a85 145 unsigned int get_module();
Wolfgang Betz 0:752e74bf5ef1 146
Wolfgang Betz 10:1a612c2e4a85 147 /** Configure DMA priority for transfers
Wolfgang Betz 10:1a612c2e4a85 148 *
Wolfgang Betz 10:1a612c2e4a85 149 * @param prio The DMA priority to be used
Wolfgang Betz 10:1a612c2e4a85 150 * @return Zero if the usage was set, -1 if a transaction is on-going
Wolfgang Betz 10:1a612c2e4a85 151 */
Wolfgang Betz 10:1a612c2e4a85 152 int set_dma_priority(i2s_dma_prio_t prio);
Davide Aliprandi 4:21603d68bcf7 153
Wolfgang Betz 10:1a612c2e4a85 154 /** Harmonize the frequencies of the given I2S objects so that they are
Wolfgang Betz 16:04e1abb4cca3 155 * the exact multiple one of the other. It can be useful whenever two I2S
Wolfgang Betz 10:1a612c2e4a85 156 * peripherals have to work together and no drift is allowed between them.
Wolfgang Betz 10:1a612c2e4a85 157 *
Wolfgang Betz 10:1a612c2e4a85 158 * @param dev_i2s_1 reference to the first I2S object.
Wolfgang Betz 10:1a612c2e4a85 159 * @param dev_i2s_2 reference to the second I2S object.
Wolfgang Betz 10:1a612c2e4a85 160 * @return Zero if the frequencies have been harmonized correctly, -1
Wolfgang Betz 10:1a612c2e4a85 161 * otherwise.
Wolfgang Betz 10:1a612c2e4a85 162 */
Wolfgang Betz 10:1a612c2e4a85 163 static int harmonize(I2S &dev_i2s_1, I2S &dev_i2s_2);
Wolfgang Betz 0:752e74bf5ef1 164
Wolfgang Betz 0:752e74bf5ef1 165
Wolfgang Betz 10:1a612c2e4a85 166 /** Bottom-half & transactions event queue for all I2S objects
Wolfgang Betz 10:1a612c2e4a85 167 * Must be used by application programmer to schedule/execute bottom-halves
Wolfgang Betz 10:1a612c2e4a85 168 * (i.e. transfer event callback functions) and automatically start queued
Wolfgang Betz 10:1a612c2e4a85 169 * transactions (i.e. transfers), e.g. by calling `events::EventQueue::dispatch_forever()`! */
Wolfgang Betz 16:04e1abb4cca3 170 static events::EventQueue i2s_bh_queue;
Wolfgang Betz 10:1a612c2e4a85 171
Wolfgang Betz 10:1a612c2e4a85 172 protected:
Wolfgang Betz 16:04e1abb4cca3 173 /** Acquire exclusive access to this I2S bus
Wolfgang Betz 16:04e1abb4cca3 174 */
Wolfgang Betz 16:04e1abb4cca3 175 virtual void lock(void);
Wolfgang Betz 16:04e1abb4cca3 176
Wolfgang Betz 16:04e1abb4cca3 177 /** Release exclusive access to this I2S bus
Wolfgang Betz 16:04e1abb4cca3 178 */
Wolfgang Betz 16:04e1abb4cca3 179 virtual void unlock(void);
Wolfgang Betz 16:04e1abb4cca3 180
Wolfgang Betz 10:1a612c2e4a85 181 /** I2S TX DMA IRQ handler
Wolfgang Betz 10:1a612c2e4a85 182 *
Wolfgang Betz 10:1a612c2e4a85 183 */
Wolfgang Betz 10:1a612c2e4a85 184 void irq_handler_asynch_tx(void);
Wolfgang Betz 0:752e74bf5ef1 185
Wolfgang Betz 10:1a612c2e4a85 186 /** I2S RX DMA IRQ handler
Wolfgang Betz 10:1a612c2e4a85 187 *
Wolfgang Betz 10:1a612c2e4a85 188 */
Wolfgang Betz 10:1a612c2e4a85 189 void irq_handler_asynch_rx(void);
Wolfgang Betz 0:752e74bf5ef1 190
Wolfgang Betz 10:1a612c2e4a85 191 /** Add a transfer to the queue
Wolfgang Betz 10:1a612c2e4a85 192 * @param data Transaction data
Wolfgang Betz 10:1a612c2e4a85 193 * @return Zero if a transfer was added to the queue, or -1 if the queue is full
Wolfgang Betz 10:1a612c2e4a85 194 */
Wolfgang Betz 10:1a612c2e4a85 195 int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length,
Wolfgang Betz 17:7a4a4631672c 196 const mbed::event_callback_t& callback, int event);
Wolfgang Betz 10:1a612c2e4a85 197
Wolfgang Betz 10:1a612c2e4a85 198 /** Configures a callback, i2s peripheral and initiate a new transfer
Wolfgang Betz 10:1a612c2e4a85 199 *
Wolfgang Betz 10:1a612c2e4a85 200 * @param data Transaction data
Wolfgang Betz 10:1a612c2e4a85 201 */
Wolfgang Betz 10:1a612c2e4a85 202 void start_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length,
Wolfgang Betz 17:7a4a4631672c 203 const mbed::event_callback_t& callback, int event);
Wolfgang Betz 0:752e74bf5ef1 204
Wolfgang Betz 10:1a612c2e4a85 205 class I2sBhHandler {
Wolfgang Betz 10:1a612c2e4a85 206 friend class I2S;
Wolfgang Betz 0:752e74bf5ef1 207
Wolfgang Betz 17:7a4a4631672c 208 static void i2s_defer_function(const mbed::event_callback_t& bottom_half, int event) {
Wolfgang Betz 10:1a612c2e4a85 209 i2s_bh_queue.call(bottom_half, event);
Wolfgang Betz 10:1a612c2e4a85 210 }
Wolfgang Betz 0:752e74bf5ef1 211
Wolfgang Betz 17:7a4a4631672c 212 static void i2s_defer_function(const mbed::Callback<void()>& bottom_half) {
Wolfgang Betz 10:1a612c2e4a85 213 i2s_bh_queue.call(bottom_half);
Wolfgang Betz 10:1a612c2e4a85 214 }
Wolfgang Betz 10:1a612c2e4a85 215 };
Wolfgang Betz 0:752e74bf5ef1 216
Wolfgang Betz 0:752e74bf5ef1 217 #if TRANSACTION_QUEUE_SIZE_I2S
Wolfgang Betz 10:1a612c2e4a85 218 /** Start a new transaction
Wolfgang Betz 10:1a612c2e4a85 219 *
Wolfgang Betz 10:1a612c2e4a85 220 * @param data Transaction data
Wolfgang Betz 10:1a612c2e4a85 221 */
Wolfgang Betz 17:7a4a4631672c 222 void start_transaction(mbed::transaction_t *data);
Wolfgang Betz 0:752e74bf5ef1 223
Wolfgang Betz 10:1a612c2e4a85 224 /** Dequeue a transaction
Wolfgang Betz 10:1a612c2e4a85 225 *
Wolfgang Betz 10:1a612c2e4a85 226 */
Wolfgang Betz 10:1a612c2e4a85 227 void dequeue_transaction();
Wolfgang Betz 0:752e74bf5ef1 228
Wolfgang Betz 17:7a4a4631672c 229 mbed::CircularBuffer<mbed::Transaction<I2S>, TRANSACTION_QUEUE_SIZE_I2S> _transaction_buffer;
Wolfgang Betz 0:752e74bf5ef1 230 #endif // TRANSACTION_QUEUE_SIZE_I2S
Wolfgang Betz 0:752e74bf5ef1 231
Wolfgang Betz 10:1a612c2e4a85 232 public:
Wolfgang Betz 10:1a612c2e4a85 233 virtual ~I2S() {
Wolfgang Betz 10:1a612c2e4a85 234 /* betzw - TODO: cleanup has still to be revised completely! */
Wolfgang Betz 10:1a612c2e4a85 235 abort_all_transfers();
Wolfgang Betz 10:1a612c2e4a85 236 i2s_free(&_i2s);
Wolfgang Betz 10:1a612c2e4a85 237 }
Davide Aliprandi 4:21603d68bcf7 238
Wolfgang Betz 10:1a612c2e4a85 239 protected:
Wolfgang Betz 10:1a612c2e4a85 240 i2s_t _i2s;
Davide Aliprandi 4:21603d68bcf7 241
Wolfgang Betz 10:1a612c2e4a85 242 CThunk<I2S> _irq_tx;
Wolfgang Betz 10:1a612c2e4a85 243 CThunk<I2S> _irq_rx;
Wolfgang Betz 17:7a4a4631672c 244 mbed::event_callback_t _callback;
Wolfgang Betz 10:1a612c2e4a85 245 i2s_dma_prio_t _priority; // DMA priority
Wolfgang Betz 0:752e74bf5ef1 246
Wolfgang Betz 10:1a612c2e4a85 247 void acquire(void);
Wolfgang Betz 0:752e74bf5ef1 248
Wolfgang Betz 10:1a612c2e4a85 249 static I2S *_owner;
Wolfgang Betz 10:1a612c2e4a85 250 static SingletonPtr<PlatformMutex> _mutex;
Wolfgang Betz 0:752e74bf5ef1 251
Wolfgang Betz 10:1a612c2e4a85 252 int _dbits;
Wolfgang Betz 10:1a612c2e4a85 253 int _fbits;
Wolfgang Betz 10:1a612c2e4a85 254 int _polarity;
Wolfgang Betz 10:1a612c2e4a85 255 i2s_bitorder_t _protocol;
Wolfgang Betz 10:1a612c2e4a85 256 i2s_mode_t _mode;
Wolfgang Betz 10:1a612c2e4a85 257 bool _circular;
Wolfgang Betz 10:1a612c2e4a85 258 unsigned int _hz;
Wolfgang Betz 10:1a612c2e4a85 259 };
Wolfgang Betz 0:752e74bf5ef1 260
Wolfgang Betz 17:7a4a4631672c 261 #endif // DEVICE_I2S
Wolfgang Betz 0:752e74bf5ef1 262
Wolfgang Betz 17:7a4a4631672c 263 #endif // MBED_I2S_H