Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_ss_spi.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_SS_SPI_H__
6 #define __QM_SS_SPI_H__
7 
8 #include "qm_common.h"
9 #include "qm_sensor_regs.h"
10 /**
11  * SPI peripheral driver for Sensor Subsystem.
12  *
13  * @defgroup groupSSSPI SS SPI
14  * @{
15  */
16 
17 /**
18  * QM Sensor SPI frame size type
19  */
20 typedef enum {
21  QM_SS_SPI_FRAME_SIZE_4_BIT = 3, /**< 4 bit frame. */
22  QM_SS_SPI_FRAME_SIZE_5_BIT, /**< 5 bit frame. */
23  QM_SS_SPI_FRAME_SIZE_6_BIT, /**< 6 bit frame. */
24  QM_SS_SPI_FRAME_SIZE_7_BIT, /**< 7 bit frame. */
25  QM_SS_SPI_FRAME_SIZE_8_BIT, /**< 8 bit frame. */
26  QM_SS_SPI_FRAME_SIZE_9_BIT, /**< 9 bit frame. */
27  QM_SS_SPI_FRAME_SIZE_10_BIT, /**< 10 bit frame. */
28  QM_SS_SPI_FRAME_SIZE_11_BIT, /**< 11 bit frame. */
29  QM_SS_SPI_FRAME_SIZE_12_BIT, /**< 12 bit frame. */
30  QM_SS_SPI_FRAME_SIZE_13_BIT, /**< 13 bit frame. */
31  QM_SS_SPI_FRAME_SIZE_14_BIT, /**< 14 bit frame. */
32  QM_SS_SPI_FRAME_SIZE_15_BIT, /**< 15 bit frame. */
33  QM_SS_SPI_FRAME_SIZE_16_BIT, /**< 16 bit frame. */
34 #if HAS_SS_SPI_32BIT
35  QM_SS_SPI_FRAME_SIZE_17_BIT, /**< 17 bit frame. */
36  QM_SS_SPI_FRAME_SIZE_18_BIT, /**< 18 bit frame. */
37  QM_SS_SPI_FRAME_SIZE_19_BIT, /**< 19 bit frame. */
38  QM_SS_SPI_FRAME_SIZE_20_BIT, /**< 20 bit frame. */
39  QM_SS_SPI_FRAME_SIZE_21_BIT, /**< 21 bit frame. */
40  QM_SS_SPI_FRAME_SIZE_22_BIT, /**< 22 bit frame. */
41  QM_SS_SPI_FRAME_SIZE_23_BIT, /**< 23 bit frame. */
42  QM_SS_SPI_FRAME_SIZE_24_BIT, /**< 24 bit frame. */
43  QM_SS_SPI_FRAME_SIZE_25_BIT, /**< 25 bit frame. */
44  QM_SS_SPI_FRAME_SIZE_26_BIT, /**< 26 bit frame. */
45  QM_SS_SPI_FRAME_SIZE_27_BIT, /**< 27 bit frame. */
46  QM_SS_SPI_FRAME_SIZE_28_BIT, /**< 28 bit frame. */
47  QM_SS_SPI_FRAME_SIZE_29_BIT, /**< 29 bit frame. */
48  QM_SS_SPI_FRAME_SIZE_30_BIT, /**< 30 bit frame. */
49  QM_SS_SPI_FRAME_SIZE_31_BIT, /**< 31 bit frame. */
50  QM_SS_SPI_FRAME_SIZE_32_BIT /**< 32 bit frame. */
51 #endif /* HAS_SS_SPI_32BIT */
53 
54 /**
55  * SPI transfer mode type.
56  */
57 typedef enum {
58  /**
59  * Transmit & Receive mode.
60  *
61  * This mode synchronously receives and transmits data during the
62  * transfer. rx_len and tx_len buffer need to be the same length.
63  */
65 
66  /**
67  * Transmit-Only mode.
68  *
69  * This mode only transmits data. The rx buffer is not accessed and
70  * rx_len need to be set to 0.
71  */
73 
74  /**
75  * Receive-Only mode.
76  *
77  * This mode only receives data. The tx buffer is not accessed and
78  * tx_len need to be set to 0.
79  */
81 
82  /**
83  * EEPROM-Read Mode.
84  *
85  * This mode transmits the data stored in the tx buffer (EEPROM
86  * address). After the transmit is completed it populates the rx buffer
87  * (EEPROM data) with received data.
88  */
91 
92 /**
93  * SPI Bus Mode Type
94  */
95 typedef enum {
96  QM_SS_SPI_BMODE_0 = 0, /**< Clock Polarity = 0, Clock Phase = 0. */
97  QM_SS_SPI_BMODE_1, /**< Clock Polarity = 0, Clock Phase = 1. */
98  QM_SS_SPI_BMODE_2, /**< Clock Polarity = 1, Clock Phase = 0. */
99  QM_SS_SPI_BMODE_3 /**< Clock Polarity = 1, Clock Phase = 1. */
101 
102 /**
103  * SPI Slave select type.
104  *
105  * Slave selects can be combined by logical OR.
106  */
107 typedef enum {
108  QM_SS_SPI_SS_DISABLED = 0, /**< Slave select disable. */
109  QM_SS_SPI_SS_0 = BIT(0), /**< Slave select 0. */
110  QM_SS_SPI_SS_1 = BIT(1), /**< Slave select 1. */
111  QM_SS_SPI_SS_2 = BIT(2), /**< Slave select 2. */
112  QM_SS_SPI_SS_3 = BIT(3) /**< Slave select 3. */
114 
115 /**
116  * SPI status
117  */
118 typedef enum {
119  QM_SS_SPI_IDLE, /**< SPI device is not in use. */
120  QM_SS_SPI_BUSY, /**< SPI device is busy. */
121  QM_SS_SPI_RX_OVERFLOW, /**< RX transfer has overflown. */
122 #if HAS_SS_SPI_VERBOSE_ERROR
123  QM_SS_SPI_TX_OVERFLOW, /**< TX transfer has overflown. */
124  QM_SS_SPI_RX_UNDERFLOW /**< RX transfer has underflown. */
125 #endif /* HAS_SS_SPI_VERBOSE_ERROR */
127 
128 /**
129 * SPI configuration type.
130 */
131 
132 typedef struct {
133  qm_ss_spi_frame_size_t frame_size; /**< Frame Size */
134  qm_ss_spi_tmode_t transfer_mode; /**< Transfer mode (enum) */
135  qm_ss_spi_bmode_t bus_mode; /**< Bus mode (enum) */
136 
137  /**
138  * SCK = SPI_clock/clk_divider.
139  * A value of 0 will disable SCK. The LSB of this value is ignored.
140  */
141  uint16_t clk_divider;
143 
144 /**
145  * SPI asynchronous transfer type.
146  *
147  * If the frame size is 8 bits or less, 1 byte is needed per data frame. If the
148  * frame size is 9-16 bits, 2 bytes are needed per data frame and frames of more
149  * than 16 bits require 4 bytes. In each case, the least significant bits are
150  * sent while the extra bits are discarded. The most significant bits of the
151  * frame are sent first.
152  */
153 typedef struct {
154  void *tx; /**< Write data. */
155  void *rx; /**< Read data. */
156  uint16_t tx_len; /**< Number of data frames to write. */
157  uint16_t rx_len; /**< Number of data frames to read. */
158 
159  /**
160  * Transfer callback.
161  *
162  * Called after all data is transmitted/received or if the driver
163  * detects an error during the SPI transfer.
164  *
165  * @param[in] data The callback user data.
166  * @param[in] error 0 on success.
167  * Negative @ref errno for possible error codes.
168  * @param[in] status The SPI module status.
169  * @param[in] len The amount of frames transmitted.
170  */
171  void (*callback)(void *data, int error, qm_ss_spi_status_t status,
172  uint16_t len);
173  void *callback_data; /**< Callback user data */
175 
176 /**
177  * SPI synchronous transfer type.
178  *
179  * If the frame size is 8 bits or less, 1 byte is needed per data frame. If the
180  * frame size is 9-16 bits, 2 bytes are needed per data frame and frames of more
181  * than 16 bits require 4 bytes. In each case, the least significant bits are
182  * sent while the extra bits are discarded. The most significant bits of the
183  * frame are sent first.
184  */
185 typedef struct {
186  void *tx; /**< Write data. */
187  void *rx; /**< Read data. */
188  uint16_t tx_len; /**< Number of data frames to write. */
189  uint16_t rx_len; /**< Number of data frames to read. */
191 
192 /**
193  * Set SPI configuration.
194  *
195  * Change the configuration of a SPI module.
196  * This includes transfer mode, bus mode, clock divider and data frame size.
197  *
198  * This operation is permitted only when the SPI module is disabled.
199  *
200  * @param [in] spi SPI module identifier.
201  * @param [in] cfg New configuration for SPI. This must not be NULL.
202  *
203  * @return Standard errno return type for QMSI.
204  * @retval 0 on success.
205  * @retval Negative @ref errno for possible error codes.
206  */
207 int qm_ss_spi_set_config(const qm_ss_spi_t spi,
208  const qm_ss_spi_config_t *const cfg);
209 
210 /**
211  * Set Slave Select lines.
212  *
213  * Select which slaves to perform SPI transmissions on. Select lines can be
214  * combined using the | operator. It is only suggested to use this functionality
215  * in TX only mode. This operation is permitted only when a SPI transfer is not
216  * already in progress; the caller should check that by retrieving the device
217  * status.
218  *
219  * @param[in] spi SPI module identifier.
220  * @param[in] ss Select lines to enable when performing transfers.
221  *
222  * @return Standard errno return type for QMSI.
223  * @retval 0 on success.
224  * @retval Negative @ref errno for possible error codes.
225  */
226 int qm_ss_spi_slave_select(const qm_ss_spi_t spi,
227  const qm_ss_spi_slave_select_t ss);
228 
229 /**
230  * Get SPI bus status.
231  *
232  * @param[in] spi SPI module identifier.
233  * @param[out] status Reference to the variable where to store the current SPI
234  * bus status (QM_SS_SPI_BUSY if a transfer is in progress
235  * or QM_SS_SPI_IDLE if SPI device is IDLE).
236  * This must not be NULL.
237  *
238  * @return Standard errno return type for QMSI.
239  * @retval 0 on success.
240  * @retval Negative @ref errno for possible error codes.
241  */
242 int qm_ss_spi_get_status(const qm_ss_spi_t spi,
243  qm_ss_spi_status_t *const status);
244 
245 /**
246  * Perform a blocking SPI transfer.
247  *
248  * This is a blocking synchronous call. If transfer mode is full duplex
249  * (QM_SS_SPI_TMOD_TX_RX) tx_len and rx_len must be equal. Similarly, for
250  * transmit-only transfers (QM_SS_SPI_TMOD_TX) rx_len must be 0, while for
251  * receive-only transfers (QM_SS_SPI_TMOD_RX) tx_len must be 0.
252  *
253  * @param[in] spi SPI module identifier.
254  * @param[in] xfer Structure containing transfer information.
255  * This must not be NULL.
256  * @param[out] status Reference to the variable where to store the SPI status
257  * at the end of the transfer.
258  *
259  * @return Standard errno return type for QMSI.
260  * @retval 0 on success.
261  * @retval Negative @ref errno for possible error codes.
262  */
263 int qm_ss_spi_transfer(const qm_ss_spi_t spi,
264  const qm_ss_spi_transfer_t *const xfer,
265  qm_ss_spi_status_t *const status);
266 
267 /**
268  * Initiate an interrupt based SPI transfer.
269  *
270  * Perform an interrupt based SPI transfer. If transfer mode is full duplex
271  * (QM_SS_SPI_TMOD_TX_RX), then tx_len and rx_len must be equal. Similarly, for
272  * transmit-only transfers (QM_SS_SPI_TMOD_TX) rx_len must be 0, while for
273  * receive-only transfers (QM_SS_SPI_TMOD_RX) tx_len must be 0. This function is
274  * non blocking.
275  *
276  * @param[in] spi SPI module identifier.
277  * @param[in] xfer Structure containing transfer information.
278  * The structure must not be NULL and must be kept valid until
279  * the transfer is complete.
280  *
281  * @return Standard errno return type for QMSI.
282  * @retval 0 on success.
283  * @retval Negative @ref errno for possible error codes.
284  */
285 int qm_ss_spi_irq_transfer(const qm_ss_spi_t spi,
286  const qm_ss_spi_async_transfer_t *const xfer);
287 
288 /**
289  * Terminate SPI IRQ transfer.
290  *
291  * Terminate the current IRQ SPI transfer.
292  * This function will trigger complete callbacks even
293  * if the transfer is not completed.
294  *
295  * @param[in] spi SPI module identifier.
296  *
297  * @return Standard errno return type for QMSI.
298  * @retval 0 on success.
299  * @retval Negative @ref errno for possible error codes.
300  */
302 
303 /**
304  * Save SS SPI context.
305  *
306  * Saves the configuration of the specified SS SPI peripheral
307  * before entering sleep.
308  *
309  * @param[in] spi SPI controller identifier.
310  * @param[out] ctx SPI context structure. This must not be NULL.
311  *
312  * @return Standard errno return type for QMSI.
313  * @retval 0 on success.
314  * @retval Negative @ref errno for possible error codes.
315  */
316 int qm_ss_spi_save_context(const qm_ss_spi_t spi,
317  qm_ss_spi_context_t *const ctx);
318 
319 /**
320  * Restore SS SPI context.
321  *
322  * Restore the configuration of the specified SS SPI peripheral
323  * after exiting sleep.
324  *
325  * @param[in] spi SPI controller identifier.
326  * @param[in] ctx SPI context structure. This must not be NULL.
327  *
328  * @return Standard errno return type for QMSI.
329  * @retval 0 on success.
330  * @retval Negative @ref errno for possible error codes.
331  */
333  const qm_ss_spi_context_t *const ctx);
334 
335 /**
336  * @}
337  */
338 
339 #endif /* __QM_SS_SPI_H__ */
qm_ss_spi_slave_select_t
SPI Slave select type.
Definition: qm_ss_spi.h:107
void * tx
Write data.
Definition: qm_ss_spi.h:154
Transmit & Receive mode.
Definition: qm_ss_spi.h:64
SPI configuration type.
Definition: qm_ss_spi.h:132
int qm_ss_spi_irq_transfer_terminate(const qm_ss_spi_t spi)
Terminate SPI IRQ transfer.
Definition: qm_ss_spi.c:257
Slave select 0.
Definition: qm_ss_spi.h:109
Clock Polarity = 1, Clock Phase = 1.
Definition: qm_ss_spi.h:99
int qm_ss_spi_irq_transfer(const qm_ss_spi_t spi, const qm_ss_spi_async_transfer_t *const xfer)
Initiate an interrupt based SPI transfer.
Definition: qm_ss_spi.c:206
uint16_t tx_len
Number of data frames to write.
Definition: qm_ss_spi.h:156
Sensor Subsystem SPI context type.
TX transfer has overflown.
Definition: qm_ss_spi.h:123
uint16_t tx_len
Number of data frames to write.
Definition: qm_ss_spi.h:188
SPI asynchronous transfer type.
Definition: qm_ss_spi.h:153
int qm_ss_spi_set_config(const qm_ss_spi_t spi, const qm_ss_spi_config_t *const cfg)
Set SPI configuration.
Definition: qm_ss_spi.c:65
int qm_ss_spi_get_status(const qm_ss_spi_t spi, qm_ss_spi_status_t *const status)
Get SPI bus status.
Definition: qm_ss_spi.c:111
int qm_ss_spi_slave_select(const qm_ss_spi_t spi, const qm_ss_spi_slave_select_t ss)
Set Slave Select lines.
Definition: qm_ss_spi.c:96
EEPROM-Read Mode.
Definition: qm_ss_spi.h:89
Receive-Only mode.
Definition: qm_ss_spi.h:80
int qm_ss_spi_transfer(const qm_ss_spi_t spi, const qm_ss_spi_transfer_t *const xfer, qm_ss_spi_status_t *const status)
Perform a blocking SPI transfer.
Definition: qm_ss_spi.c:126
RX transfer has underflown.
Definition: qm_ss_spi.h:124
SPI device is busy.
Definition: qm_ss_spi.h:120
Slave select 2.
Definition: qm_ss_spi.h:111
Slave select disable.
Definition: qm_ss_spi.h:108
qm_ss_spi_tmode_t transfer_mode
Transfer mode (enum)
Definition: qm_ss_spi.h:134
void * tx
Write data.
Definition: qm_ss_spi.h:186
qm_ss_spi_frame_size_t
QM Sensor SPI frame size type.
Definition: qm_ss_spi.h:20
qm_ss_spi_tmode_t
SPI transfer mode type.
Definition: qm_ss_spi.h:57
Slave select 3.
Definition: qm_ss_spi.h:112
Clock Polarity = 1, Clock Phase = 0.
Definition: qm_ss_spi.h:98
SPI device is not in use.
Definition: qm_ss_spi.h:119
int qm_ss_spi_save_context(const qm_ss_spi_t spi, qm_ss_spi_context_t *const ctx)
Save SS SPI context.
Definition: qm_ss_spi.c:469
Clock Polarity = 0, Clock Phase = 0.
Definition: qm_ss_spi.h:96
qm_ss_spi_bmode_t
SPI Bus Mode Type.
Definition: qm_ss_spi.h:95
Transmit-Only mode.
Definition: qm_ss_spi.h:72
qm_ss_spi_frame_size_t frame_size
Frame Size.
Definition: qm_ss_spi.h:133
uint16_t clk_divider
SCK = SPI_clock/clk_divider.
Definition: qm_ss_spi.h:141
int qm_ss_spi_restore_context(const qm_ss_spi_t spi, const qm_ss_spi_context_t *const ctx)
Restore SS SPI context.
Definition: qm_ss_spi.c:478
uint16_t rx_len
Number of data frames to read.
Definition: qm_ss_spi.h:157
void * rx
Read data.
Definition: qm_ss_spi.h:155
void * rx
Read data.
Definition: qm_ss_spi.h:187
qm_ss_spi_t
Sensor Subsystem SPI modules.
void * callback_data
Callback user data.
Definition: qm_ss_spi.h:173
Slave select 1.
Definition: qm_ss_spi.h:110
qm_ss_spi_status_t
SPI status.
Definition: qm_ss_spi.h:118
SPI synchronous transfer type.
Definition: qm_ss_spi.h:185
RX transfer has overflown.
Definition: qm_ss_spi.h:121
uint16_t rx_len
Number of data frames to read.
Definition: qm_ss_spi.h:189
Clock Polarity = 0, Clock Phase = 1.
Definition: qm_ss_spi.h:97
qm_ss_spi_bmode_t bus_mode
Bus mode (enum)
Definition: qm_ss_spi.h:135