ChibiOS/HAL 9.0.0
hal_i2s.h
Go to the documentation of this file.
1/*
2 ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15*/
16
17/**
18 * @file hal_i2s.h
19 * @brief I2S Driver macros and structures.
20 *
21 * @addtogroup I2S
22 * @{
23 */
24
25#ifndef HAL_I2S_H
26#define HAL_I2S_H
27
28#if (HAL_USE_I2S == TRUE) || defined(__DOXYGEN__)
29
30/*===========================================================================*/
31/* Driver constants. */
32/*===========================================================================*/
33
34/**
35 * @name I2S modes
36 * @{
37 */
38#define I2S_MODE_SLAVE 0
39#define I2S_MODE_MASTER 1
40/** @} */
41
42/*===========================================================================*/
43/* Driver pre-compile time settings. */
44/*===========================================================================*/
45
46/*===========================================================================*/
47/* Derived constants and error checks. */
48/*===========================================================================*/
49
50/*===========================================================================*/
51/* Driver data structures and types. */
52/*===========================================================================*/
53
54/**
55 * @brief Driver state machine possible states.
56 */
57typedef enum {
58 I2S_UNINIT = 0, /**< Not initialized. */
59 I2S_STOP = 1, /**< Stopped. */
60 I2S_READY = 2, /**< Ready. */
61 I2S_ACTIVE = 3, /**< Active. */
62 I2S_COMPLETE = 4 /**< Transmission complete. */
64
65/**
66 * @brief Type of a structure representing an I2S driver.
67 */
69
70/**
71 * @brief Type of a structure representing an I2S driver configuration.
72 */
74
75/**
76 * @brief I2S notification callback type.
77 *
78 * @param[in] i2sp pointer to the @p I2SDriver object
79 */
80typedef void (*i2scallback_t)(I2SDriver *i2sp);
81
82/* Including the low level driver header, it exports information required
83 for completing types.*/
84#include "hal_i2s_lld.h"
85
86/**
87 * @brief Structure representing an I2S driver.
88 */
90 /**
91 * @brief Driver state.
92 */
94 /**
95 * @brief Current configuration data.
96 */
98 /* End of the mandatory fields.*/
100};
101
102/**
103 * @brief Driver configuration structure.
104 */
106 /**
107 * @brief Transmission buffer pointer.
108 * @note Can be @p NULL if TX is not required.
109 */
110 const void *tx_buffer;
111 /**
112 * @brief Receive buffer pointer.
113 * @note Can be @p NULL if RX is not required.
114 */
116 /**
117 * @brief TX and RX buffers size as number of samples.
118 */
119 size_t size;
120 /**
121 * @brief Callback function called during streaming.
122 */
124 /* End of the mandatory fields.*/
126};
127
128/*===========================================================================*/
129/* Driver macros. */
130/*===========================================================================*/
131
132/**
133 * @name Macro Functions
134 * @{
135 */
136/**
137 * @brief Buffer state.
138 * @note This function is meant to be called from the SPI callback only.
139 *
140 * @param[in] i2sp pointer to the @p I2SDriver object
141 * @return The buffer state.
142 * @retval false if the driver filled/sent the first half of the
143 * buffer.
144 * @retval true if the driver filled/sent the second half of the
145 * buffer.
146 *
147 * @special
148 */
149#define i2sIsBufferComplete(i2sp) ((bool)((i2sp)->state == I2S_COMPLETE))
150
151/**
152 * @brief Starts a I2S data exchange.
153 *
154 * @param[in] i2sp pointer to the @p I2SDriver object
155 *
156 * @iclass
157 */
158#define i2sStartExchangeI(i2sp) { \
159 i2s_lld_start_exchange(i2sp); \
160 (i2sp)->state = I2S_ACTIVE; \
161}
162
163/**
164 * @brief Stops the ongoing data exchange.
165 * @details The ongoing data exchange, if any, is stopped, if the driver
166 * was not active the function does nothing.
167 *
168 * @param[in] i2sp pointer to the @p I2SDriver object
169 *
170 * @iclass
171 */
172#define i2sStopExchangeI(i2sp) { \
173 i2s_lld_stop_exchange(i2sp); \
174 (i2sp)->state = I2S_READY; \
175}
176
177/**
178 * @brief Common ISR code, half buffer event.
179 * @details This code handles the portable part of the ISR code:
180 * - Callback invocation.
181 * .
182 * @note This macro is meant to be used in the low level drivers
183 * implementation only.
184 *
185 * @param[in] i2sp pointer to the @p I2CDriver object
186 *
187 * @notapi
188 */
189#define _i2s_isr_half_code(i2sp) { \
190 if ((i2sp)->config->end_cb != NULL) { \
191 (i2sp)->config->end_cb(i2sp); \
192 } \
193}
194
195/**
196 * @brief Common ISR code.
197 * @details This code handles the portable part of the ISR code:
198 * - Callback invocation.
199 * - Driver state transitions.
200 * .
201 * @note This macro is meant to be used in the low level drivers
202 * implementation only.
203 *
204 * @param[in] i2sp pointer to the @p I2CDriver object
205 *
206 * @notapi
207 */
208#define _i2s_isr_full_code(i2sp) { \
209 if ((i2sp)->config->end_cb) { \
210 (i2sp)->state = I2S_COMPLETE; \
211 (i2sp)->config->end_cb(i2sp); \
212 if ((i2sp)->state == I2S_COMPLETE) { \
213 (i2sp)->state = I2S_ACTIVE; \
214 } \
215 } \
216}
217/** @} */
218
219/*===========================================================================*/
220/* External declarations. */
221/*===========================================================================*/
222
223#ifdef __cplusplus
224extern "C" {
225#endif
226 void i2sInit(void);
227 void i2sObjectInit(I2SDriver *i2sp);
228 msg_t i2sStart(I2SDriver *i2sp, const I2SConfig *config);
229 void i2sStop(I2SDriver *i2sp);
230 void i2sStartExchange(I2SDriver *i2sp);
231 void i2sStopExchange(I2SDriver *i2sp);
232#ifdef __cplusplus
233}
234#endif
235
236#endif /* HAL_USE_I2S == TRUE */
237
238#endif /* HAL_I2S_H */
239
240/** @} */
void i2sInit(void)
I2S Driver initialization.
Definition hal_i2s.c:56
#define i2s_lld_config_fields
Low level fields of the I2S configuration structure.
Definition hal_i2s_lld.h:74
struct hal_i2s_config I2SConfig
Type of a structure representing an I2S driver configuration.
Definition hal_i2s.h:73
void i2sStopExchange(I2SDriver *i2sp)
Stops the ongoing data exchange.
Definition hal_i2s.c:162
void i2sObjectInit(I2SDriver *i2sp)
Initializes the standard part of a I2SDriver structure.
Definition hal_i2s.c:68
void i2sStartExchange(I2SDriver *i2sp)
Starts a I2S data exchange.
Definition hal_i2s.c:143
struct hal_i2s_driver I2SDriver
Type of a structure representing an I2S driver.
Definition hal_i2s.h:68
#define i2s_lld_driver_fields
Low level fields of the I2S driver structure.
Definition hal_i2s_lld.h:67
msg_t i2sStart(I2SDriver *i2sp, const I2SConfig *config)
Configures and activates the I2S peripheral.
Definition hal_i2s.c:83
void(* i2scallback_t)(I2SDriver *i2sp)
I2S notification callback type.
Definition hal_i2s.h:80
void i2sStop(I2SDriver *i2sp)
Deactivates the I2S peripheral.
Definition hal_i2s.c:120
i2sstate_t
Driver state machine possible states.
Definition hal_i2s.h:57
@ I2S_STOP
Definition hal_i2s.h:59
@ I2S_ACTIVE
Definition hal_i2s.h:61
@ I2S_UNINIT
Definition hal_i2s.h:58
@ I2S_READY
Definition hal_i2s.h:60
@ I2S_COMPLETE
Definition hal_i2s.h:62
int32_t msg_t
Type of a message.
Definition osal.h:159
PLATFORM I2S subsystem low level driver header.
Driver configuration structure.
Definition hal_i2s.h:105
i2scallback_t end_cb
Callback function called during streaming.
Definition hal_i2s.h:123
size_t size
TX and RX buffers size as number of samples.
Definition hal_i2s.h:119
void * rx_buffer
Receive buffer pointer.
Definition hal_i2s.h:115
const void * tx_buffer
Transmission buffer pointer.
Definition hal_i2s.h:110
Structure representing an I2S driver.
Definition hal_i2s.h:89
i2sstate_t state
Driver state.
Definition hal_i2s.h:93
const I2SConfig * config
Current configuration data.
Definition hal_i2s.h:97