1 /**
2 \defgroup spi_interface_gr SPI Interface
3 \brief Driver API for SPI Bus Peripheral (%Driver_SPI.h)
4 \details
5 The <b>Serial Peripheral Interface Bus</b> (SPI) implements a synchronous serial bus for data exchange. In microcontroller (MCU) applications,
6 the interface is often used to connect peripheral components at board (PCB) level. SPI devices can operate as Master (SCLK and SS are outputs) or
7 Slave (SCLK and SS are inputs). Wikipedia offers more information about
8 the <a href="https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus" target="_blank"><b>Serial Peripheral Interface Bus</b></a>.
9
10 <b>Block Diagram</b>
11
12 The SPI Driver API defines a <b>SPI</b> interface for middleware components. The SPI Driver supports multiple
13 slaves, but if only one slave is connected, then the Slave Select signal can be omitted.
14
15
16 \image html SPI_Master1Slaves.png "SPI Master connected to a single slave"
17
18
19 <p> </p>
20 \image html SPI_Master3Slaves.png "SPI Master connected to 3 slaves"
21
22 The SPI Driver functions control the following SPI signal lines.
23
24 Signal | Name | Description
25 -------|-------------------------------------|------------------------------------------------------------------------------
26 SS | Slave Select (active low) | Selects the slave. This signal can be part of the SPI peripheral or implemented using a GPIO pin.
27 MOSI | Master Out, Slave In | MOSI output of the Master connects to MOSI input of the Slave.
28 SCLK | Serial Clock | Serial clock output from Master. Controls the transfer speed and when data are sent and read.
29 MISO | Master In, Slave Out | MISO input of the Master connects to MISO output of the Slave.
30
31
32 <b>SPI API</b>
33
34 The following header files define the Application Programming Interface (API) for the SPI interface:
35 - \b %Driver_SPI.h : Driver API for SPI Bus Peripheral
36
37 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
38 peripherals of the microcontroller family.
39
40
41 <b>Driver Functions</b>
42
43 The driver functions are published in the access struct as explained in \ref DriverFunctions
44 - \ref ARM_DRIVER_SPI : access struct for SPI driver functions
45
46
47 <b>Example Code</b>
48
49 The following example code shows the usage of the SPI interface.
50
51 \include SPI_Demo.c
52
53 @{
54 */
55
56
57 /**
58 \struct ARM_DRIVER_SPI
59 \details
60 The functions of the SPI driver are accessed by function pointers exposed by this structure.
61 Refer to \ref DriverFunctions for overview information.
62
63 Each instance of a SPI interface provides such an access structure.
64 The instance is identified by a postfix number in the symbol name of the access structure, for example:
65 - \b Driver_SPI0 is the name of the access struct of the first instance (no. 0).
66 - \b Driver_SPI1 is the name of the access struct of the second instance (no. 1).
67
68 A middleware configuration setting allows connecting the middleware to a specific driver instance \b %Driver_SPI<i>n</i>.
69 The default is \token{0}, which connects a middleware to the first instance of a driver.
70 **************************************************************************************************************************/
71
72 /**
73 \struct ARM_SPI_CAPABILITIES
74 \details
75 A SPI driver can be implemented with different capabilities.
76 The data fields of this structure encode the capabilities implemented by this driver.
77
78 <b>Returned by:</b>
79 - \ref ARM_SPI_GetCapabilities
80 **************************************************************************************************************************/
81
82 /**
83 \struct ARM_SPI_STATUS
84 \details
85 Structure with information about the status of the SPI. The data fields encode busy flag and error flags.
86
87 <b>Returned by:</b>
88 - \ref ARM_SPI_GetStatus
89 *****************************************************************************************************************/
90
91
92 /**
93 \typedef ARM_SPI_SignalEvent_t
94 \details
95 Provides the typedef for the callback function \ref ARM_SPI_SignalEvent.
96
97 <b>Parameter for:</b>
98 - \ref ARM_SPI_Initialize
99 *******************************************************************************************************************/
100
101 /**
102 \defgroup spi_execution_status SPI Status Error Codes
103 \ingroup spi_interface_gr
104 \brief Negative values indicate errors (SPI has specific codes in addition to common \ref execution_status).
105 \details
106 The SPI driver has additional status error codes that are listed below.
107 Note that the SPI driver also returns the common \ref execution_status.
108
109 @{
110 \def ARM_SPI_ERROR_MODE
111 The \b mode requested with the function \ref ARM_SPI_Control is not supported by this driver.
112
113 \def ARM_SPI_ERROR_FRAME_FORMAT
114 The <b>frame format</b> requested with the function \ref ARM_SPI_Control is not supported by this driver.
115
116 \def ARM_SPI_ERROR_DATA_BITS
117 The number of <b>data bits</b> requested with the function \ref ARM_SPI_Control is not supported by this driver.
118
119 \def ARM_SPI_ERROR_BIT_ORDER
120 The <b>bit order</b> requested with the function \ref ARM_SPI_Control is not supported by this driver.
121
122 \def ARM_SPI_ERROR_SS_MODE
123 The <b>slave select mode</b> requested with the function \ref ARM_SPI_Control is not supported by this driver.
124 @}
125 */
126
127 /**
128 \defgroup SPI_events SPI Events
129 \ingroup spi_interface_gr
130 \brief The SPI driver generates call back events that are notified via the function \ref ARM_SPI_SignalEvent.
131 \details
132 This section provides the event values for the \ref ARM_SPI_SignalEvent callback function.
133
134 The following call back notification events are generated:
135 @{
136 \def ARM_SPI_EVENT_TRANSFER_COMPLETE
137 \def ARM_SPI_EVENT_DATA_LOST
138 \def ARM_SPI_EVENT_MODE_FAULT
139 @}
140 */
141
142 //
143 // Functions
144 //
145
ARM_SPI_GetVersion(void)146 ARM_DRIVER_VERSION ARM_SPI_GetVersion (void) {
147 return { 0, 0 };
148 }
149 /**
150 \fn ARM_DRIVER_VERSION ARM_SPI_GetVersion (void)
151 \details
152 The function \b ARM_SPI_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
153 - API version is the version of the CMSIS-Driver specification used to implement this driver.
154 - Driver version is source code version of the actual driver implementation.
155
156 Example:
157 \code
158 extern ARM_DRIVER_SPI Driver_SPI0;
159 ARM_DRIVER_SPI *drv_info;
160
161 void setup_spi (void) {
162 ARM_DRIVER_VERSION version;
163
164 drv_info = &Driver_SPI0;
165 version = drv_info->GetVersion ();
166 if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
167 // error handling
168 return;
169 }
170 }
171 \endcode
172 **************************************************************************************************************************/
173
ARM_SPI_GetCapabilities(void)174 ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities (void) {
175 return { 0 };
176 }
177 /**
178 \fn ARM_SPI_CAPABILITIES ARM_SPI_GetCapabilities (void)
179 \details
180 The function \b ARM_SPI_GetCapabilities returns information about the capabilities in this driver implementation.
181 The data fields of the structure \ref ARM_SPI_CAPABILITIES encode various capabilities, for example
182 supported modes.
183
184 Example:
185 \code
186 extern ARM_DRIVER_SPI Driver_SPI0;
187 ARM_DRIVER_SPI *drv_info;
188
189 void read_capabilities (void) {
190 ARM_SPI_CAPABILITIES drv_capabilities;
191
192 drv_info = &Driver_SPI0;
193 drv_capabilities = drv_info->GetCapabilities ();
194 // interrogate capabilities
195
196 }
197 \endcode
198
199 **************************************************************************************************************************/
200
ARM_SPI_Initialize(ARM_SPI_SignalEvent_t cb_event)201 int32_t ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event) {
202 return ARM_DRIVER_OK;
203 }
204 /**
205 \fn int32_t ARM_SPI_Initialize (ARM_SPI_SignalEvent_t cb_event)
206 \details
207 The function \b ARM_SPI_Initialize initializes the SPI interface.
208
209 The parameter \em cb_event is a pointer to the \ref ARM_SPI_SignalEvent callback function; use a NULL pointer
210 when no callback signals are required.
211
212 The function is called when the middleware component starts operation and performs the following:
213 - Initializes the resources needed for the SPI interface.
214 - Registers the \ref ARM_SPI_SignalEvent callback function.
215
216
217 \b Example:
218 - see \ref spi_interface_gr - Driver Functions
219
220 **************************************************************************************************************************/
221
ARM_SPI_Uninitialize(void)222 int32_t ARM_SPI_Uninitialize (void) {
223 return ARM_DRIVER_OK;
224 }
225 /**
226 \fn int32_t ARM_SPI_Uninitialize (void)
227 \details
228 The function \b ARM_SPI_Uninitialize de-initializes the resources of SPI interface.
229
230 It is called when the middleware component stops operation and releases the software resources used by the interface.
231 **************************************************************************************************************************/
232
ARM_SPI_PowerControl(ARM_POWER_STATE state)233 int32_t ARM_SPI_PowerControl (ARM_POWER_STATE state) {
234 return ARM_DRIVER_OK;
235 }
236 /**
237 \fn int32_t ARM_SPI_PowerControl (ARM_POWER_STATE state)
238 \details
239 The function \b ARM_SPI_PowerControl controls the power modes of the SPI interface.
240
241 The parameter \em state sets the operation and can have the following values:
242 - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
243 Can be called multiple times. If the peripheral is already in this mode the function performs
244 no operation and returns with \ref ARM_DRIVER_OK.
245 - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
246 - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
247
248 Refer to \ref CallSequence for more information.
249 **************************************************************************************************************************/
250
ARM_SPI_Send(const void * data,uint32_t num)251 int32_t ARM_SPI_Send (const void *data, uint32_t num) {
252 return ARM_DRIVER_OK;
253 }
254 /**
255 \fn int32_t ARM_SPI_Send (const void *data, uint32_t num)
256 \details
257 This function \b ARM_SPI_Send is used to send data to the SPI transmitter (received data is ignored).
258
259 The parameter \em data specifies the data buffer. \n
260 The parameter \em num specifies the number of items to send. \n
261 The item size is defined by the data type, which depends on the configured number of data bits.
262
263 Data type is:
264 - \em uint8_t when configured for 1..8 data bits
265 - \em uint16_t when configured for 9..16 data bits
266 - \em uint32_t when configured for 17..32 data bits
267
268 Calling the function \b ARM_SPI_Send only starts the send operation.
269 When in slave mode, the operation is only registered and started when the master starts the transfer.
270 The function is non-blocking and returns as soon as the driver has started the operation
271 (driver typically configures DMA or the interrupt system for continuous transfer).
272 During the operation it is not allowed to call this function or any other data transfer function again.
273 Also the data buffer must stay allocated and the contents of unsent data must not be modified.
274 When send operation is completed (requested number of items sent), the \ref ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated.
275 Progress of send operation can also be monitored by reading the number of items already sent by calling \ref ARM_SPI_GetDataCount.
276
277 Status of the transmitter can also be monitored by calling the \ref ARM_SPI_GetStatus and checking the \em busy data field,
278 which indicates if transmission is still in progress or pending.
279
280 When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer,
281 then the SPI mode changes to inactive and the \ref ARM_SPI_EVENT_MODE_FAULT event is generated (instead of \ref ARM_SPI_EVENT_TRANSFER_COMPLETE).
282
283 When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master,
284 then the \ref ARM_SPI_EVENT_DATA_LOST event is generated.
285
286 Send operation can be aborted by calling \ref ARM_SPI_Control with \ref ARM_SPI_ABORT_TRANSFER as the control parameter.
287 **************************************************************************************************************************/
288
ARM_SPI_Receive(void * data,uint32_t num)289 int32_t ARM_SPI_Receive (void *data, uint32_t num) {
290 return ARM_DRIVER_OK;
291 }
292 /**
293 \fn int32_t ARM_SPI_Receive (void *data, uint32_t num)
294 \details
295 The function \b ARM_SPI_Receive is used to receive data
296 (transmits the default value as specified by \ref ARM_SPI_Control with \ref ARM_SPI_SET_DEFAULT_TX_VALUE as control parameter).
297
298 The parameter \em data specifies the data buffer. \n
299 The parameter \em num specifies the number of items to receive. \n
300 The item size is defined by the data type, which depends on the configured number of data bits.
301
302 Data type is:
303 - \em uint8_t when configured for 1..8 data bits
304 - \em uint16_t when configured for 9..16 data bits
305 - \em uint32_t when configured for 17..32 data bits
306
307 Calling the function \b ARM_SPI_Receive only starts the receive operation.
308 The function is non-blocking and returns as soon as the driver has started the operation
309 (driver typically configures DMA or the interrupt system for continuous transfer).
310 When in slave mode, the operation is only registered and started when the master starts the transfer.
311 During the operation it is not allowed to call this function or any other data transfer function again. Also the data buffer must stay allocated.
312 When receive operation is completed (requested number of items received), the \ref ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated.
313 Progress of receive operation can also be monitored by reading the number of items already received by calling \ref ARM_SPI_GetDataCount.
314
315 Status of the receiver can also be monitored by calling the \ref ARM_SPI_GetStatus and checking the \em busy data field,
316 which indicates if reception is still in progress or pending.
317
318 When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer,
319 then the SPI mode changes to inactive and the \ref ARM_SPI_EVENT_MODE_FAULT event is generated (instead of \ref ARM_SPI_EVENT_TRANSFER_COMPLETE).
320
321 When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master,
322 then the \ref ARM_SPI_EVENT_DATA_LOST event is generated.
323
324 Receive operation can be aborted by calling \ref ARM_SPI_Control with \ref ARM_SPI_ABORT_TRANSFER as the control parameter.
325 **************************************************************************************************************************/
326
ARM_SPI_Transfer(const void * data_out,void * data_in,uint32_t num)327 int32_t ARM_SPI_Transfer (const void *data_out, void *data_in, uint32_t num) {
328 return ARM_DRIVER_OK;
329 }
330 /**
331 \fn int32_t ARM_SPI_Transfer (const void *data_out, void *data_in, uint32_t num)
332 \details
333 The function \b ARM_SPI_Transfer transfers data via SPI. It synchronously sends data to the SPI transmitter and receives data from the SPI receiver.
334
335 The parameter \em data_out is a pointer to the buffer with data to send. \n
336 The parameter \em data_in is a pointer to the buffer which receives data. \n
337 The parameter \em num specifies the number of items to transfer. \n
338 The item size is defined by the data type which depends on the configured number of data bits.
339
340 Data type is:
341 - \em uint8_t when configured for 1..8 data bits
342 - \em uint16_t when configured for 9..16 data bits
343 - \em uint32_t when configured for 17..32 data bits
344
345 Calling the function \b ARM_SPI_Transfer only starts the transfer operation.
346 The function is non-blocking and returns as soon as the driver has started the operation
347 (driver typically configures DMA or the interrupt system for continuous transfer).
348 When in slave mode, the operation is only registered and started when the master starts the transfer.
349 During the operation it is not allowed to call this function or any other data transfer function again.
350 Also the data buffers must stay allocated and the contents of unsent data must not be modified.
351 When transfer operation is completed (requested number of items transferred), the \ref ARM_SPI_EVENT_TRANSFER_COMPLETE event is generated.
352 Progress of transfer operation can also be monitored by reading the number of items already transferred by calling \ref ARM_SPI_GetDataCount.
353
354 Status of the transmitter and receiver can also be monitored by calling the \ref ARM_SPI_GetStatus and checking the \em busy flag.
355
356 When in master mode and configured to monitor slave select and the slave select gets deactivated during transfer,
357 then the SPI mode changes to inactive and the \ref ARM_SPI_EVENT_MODE_FAULT event is generated (instead of \ref ARM_SPI_EVENT_TRANSFER_COMPLETE).
358
359 When in slave mode but send/receive/transfer operation is not started and data is sent/requested by the master,
360 then the \ref ARM_SPI_EVENT_DATA_LOST event is generated.
361
362 Transfer operation can also be aborted by calling \ref ARM_SPI_Control with \ref ARM_SPI_ABORT_TRANSFER as the control parameter.
363 **************************************************************************************************************************/
364
ARM_SPI_GetDataCount(void)365 uint32_t ARM_SPI_GetDataCount (void) {
366 return 0;
367 }
368 /**
369 \fn uint32_t ARM_SPI_GetDataCount (void)
370 \details
371 The function \b ARM_SPI_GetDataCount returns the number of currently transferred data items
372 during \ref ARM_SPI_Send, \ref ARM_SPI_Receive and \ref ARM_SPI_Transfer operation.
373 *****************************************************************************************************************/
374
ARM_SPI_Control(uint32_t control,uint32_t arg)375 int32_t ARM_SPI_Control (uint32_t control, uint32_t arg) {
376 return ARM_DRIVER_OK;
377 }
378 /**
379 \fn int32_t ARM_SPI_Control (uint32_t control, uint32_t arg)
380 \details
381 The function \b ARM_SPI_Control controls the SPI interface settings and executes various operations.
382
383 The parameter \em control is a bit mask that specifies various operations.
384 - Controls form different categories can be ORed.
385 - If one control is omitted, then the default value of that category is used.
386 - Miscellaneous controls cannot be combined.
387
388 The parameter \em arg provides (depending on the parameter \em control) additional information, for example the Bus Speed.
389
390
391 <table class="cmtable" summary="">
392 <tr><th> Parameter \em control </th>
393 <th style="text-align:right"> Bit </th>
394 <th> Category </th>
395 <th> Description
396 </th></tr>
397 <tr><td> \ref ARM_SPI_MODE_INACTIVE </td>
398 <td rowspan="3" style="text-align:right"> 0..7 </td>
399 <td rowspan="3"> \anchor spi_mode_tab Mode Controls </td>
400 <td> Set SPI to inactive.
401 </td></tr>
402 <tr><td> \ref ARM_SPI_MODE_MASTER </td>
403 <td> Set the SPI Master (Output on MOSI, and the Input on MISO); \em arg = Bus Speed in \token{bps}
404 </td></tr>
405 <tr><td> \ref ARM_SPI_MODE_SLAVE </td>
406 <td> Set the SPI Slave (Output on MISO, and the Input on MOSI)
407 </td></tr>
408 <tr><td> \ref ARM_SPI_CPOL0_CPHA0 (default) </td>
409 <td rowspan="6" style="text-align:right"> 8..11 </td>
410 <td rowspan="6"> Clock Polarity <br> (Frame Format) </td><td> CPOL=\token{0} and CPHA=\token{0}: Clock Polarity 0, Clock Phase 0 </td>
411 </tr>
412 <tr><td> \ref ARM_SPI_CPOL0_CPHA1 </td>
413 <td> CPOL=\token{0} and CPHA=\token{1}: Clock Polarity 0, Clock Phase 1
414 </td></tr>
415 <tr><td> \ref ARM_SPI_CPOL1_CPHA0 </td>
416 <td> CPOL=\token{1} and CPHA=\token{0}: Clock Polarity 1, Clock Phase 0
417 </td></tr>
418 <tr><td> \ref ARM_SPI_CPOL1_CPHA1 </td>
419 <td> CPOL=\token{1} and CPHA=\token{1}: Clock Polarity 1, Clock Phase 1
420 </td></tr>
421 <tr><td> \ref ARM_SPI_TI_SSI </td>
422 <td> Specifies that the frame format corresponds to the Texas Instruments Frame Format
423 </td></tr>
424 <tr><td> \ref ARM_SPI_MICROWIRE </td>
425 <td> Specifies that the frame format corresponds to the National Semiconductor Microwire Frame Format
426 </td></tr>
427 <tr><td> \ref ARM_SPI_DATA_BITS(n) </td>
428 <td style="text-align:right"> 12..17 </td>
429 <td> Data Bits </td>
430 <td> Set the number of bits per SPI frame; range for \em n = \token{1..32}.
431 This is the minimum required parameter.
432 </td></tr>
433 <tr><td> \ref ARM_SPI_MSB_LSB (default) </td>
434 <td rowspan="2" style="text-align:right"> 18 </td>
435 <td rowspan="2"> Bit Order </td>
436 <td> Set the bit order from MSB to LSB
437 </td></tr>
438 <tr><td> \ref ARM_SPI_LSB_MSB </td>
439 <td> Set the bit order from LSB to MSB
440 </td></tr>
441 <tr><td nowrap>\ref ARM_SPI_SS_MASTER_UNUSED (default) </td>
442 <td rowspan="6" style="text-align:right"> 19..21 </td>
443 <td rowspan="6"> Slave Select
444 <br>when Master
445 <div style="min-height:200px"> </div>
446 Must be used with the corresponding master or slave controls from category <a href="#spi_mode_tab"><b>Mode Controls</b></a>.
447 <div style="min-height:200px"> </div>
448 Slave Select
449 <br>when Slave
450 </td>
451 <td>Set the Slave Select mode for the master to <b>Not used</b>. Used with Mode Control ARM_SPI_MODE_MASTER.
452 Master does not drive or monitor the SS line. For example, when connecting to a single slave,
453 which has the SS line connected to a fixed low level.
454 </td></tr>
455 <tr><td>\ref ARM_SPI_SS_MASTER_SW</td>
456 <td>Set the Slave Select mode for the master to <b>Software controlled</b>. Used with Mode Control ARM_SPI_MODE_MASTER.
457 The Slave Select line is configured as output and controlled via the Miscellaneous Control \ref ARM_SPI_CONTROL_SS.
458 By default, the line it is not active (high), and is not affected by transfer-, send-, or receive functions.
459 </td></tr>
460 <tr><td>\ref ARM_SPI_SS_MASTER_HW_OUTPUT</td>
461 <td>Set the Slave Select mode for the master to <b>Hardware controlled Output</b>. Used with Mode Control ARM_SPI_MODE_MASTER.
462 The Slave Select line is configured as output and controlled by hardware.
463 The line gets activated or deactivated automatically by the hardware for transfers and is not controlled by the Miscellaneous Control \ref ARM_SPI_CONTROL_SS.
464 When exactly the line is activated or deactivated is hardware dependent. Typically, the hardware will activate the line before starting the transfer
465 and deactivate it after the transfer completes. Some hardware will keep the line active as long as the SPI stays master.
466 \note Some devices require that the SS signal is strictly defined regarding transfers. Refer to the documentation of your device.
467 </td></tr>
468 <tr>
469 <td>\ref ARM_SPI_SS_MASTER_HW_INPUT</td>
470 <td>Set the Slave Select mode for the master to <b>Hardware monitored Input</b>. Used with Mode Control ARM_SPI_MODE_MASTER.
471 Used in multi-master configuration where a master does not drive the Slave Select when driving the bus, but rather monitors it.
472 When another master activates this line, the active master backs off. This is called Mode Fault. Slave Select is configured as input
473 and hardware only monitors the line. When the line is activated externally while we are master,
474 it presents a Mode Fault (\ref ARM_SPI_EVENT_MODE_FAULT) and the SPI switches to inactive mode.
475 </td></tr>
476 <tr><td>\ref ARM_SPI_SS_SLAVE_HW (default)</td>
477 <td>Set the Slave Select mode for the slave to <b>Hardware monitored</b>. Used with Mode Control ARM_SPI_MODE_SLAVE.
478 Hardware monitors the Slave Select line and accepts transfers only when the line is active. Transfers are ignored while the Slave Select line is inactive.
479 </td></tr>
480 <tr><td>\ref ARM_SPI_SS_SLAVE_SW</td>
481 <td>Set the Slave Select mode for the slave to <b>Software controlled</b>. Used with Mode Control ARM_SPI_MODE_SLAVE.
482 Used only when the Slave Select line is not used. For example, when a single master and slave are connected in the system
483 then the Slave Select line is not needed. Software controls if the slave is responding or not (by default it is not responding).
484 Software enables or disables transfers by using the Miscellaneous Control \ref ARM_SPI_CONTROL_SS.
485 </td></tr>
486 <tr><td> \ref ARM_SPI_SET_BUS_SPEED </td>
487 <td rowspan="5" style="text-align:right"> 0..21 </td>
488 <td rowspan="5"> Miscellaneous Controls <br>(cannot be ORed)</td>
489 <td>Set the bus speed; \em arg= Bus Speed in \token{bps}
490 </td></tr>
491 <tr><td> \ref ARM_SPI_GET_BUS_SPEED </td>
492 <td> Get the bus speed; Return values >= \token{0} represent the bus speed in \token{bps}. Negative values are \ref spi_execution_status.
493 </td></tr>
494 <tr><td> \ref ARM_SPI_SET_DEFAULT_TX_VALUE </td>
495 <td> Set the default transmission value; the parameter \em arg sets the value
496 </td></tr>
497 <tr><td> \ref ARM_SPI_CONTROL_SS </td>
498 <td> Control the Slave Select signal (SS); the values for the parameter \em arg are: \token{ARM_SPI_SS_INACTIVE; ARM_SPI_SS_ACTIVE}
499 </td></tr>
500 <tr><td> \ref ARM_SPI_ABORT_TRANSFER </td>
501 <td> Abort the current data transfer
502 </td></tr>
503 </table>
504
505
506
507 \b Example
508
509 \code
510 extern ARM_DRIVER_SPI Driver_SPI0;
511
512 // configure: SPI master | clock polarity=1, clock phase=1 | bits per frame=16 | bus speed : 1000000
513 status = Driver_SPI0.Control(ARM_SPI_MODE_MASTER |
514 ARM_SPI_CPOL1_CPHA1 |
515 ARM_SPI_DATA_BITS(16), 1000000);
516 \endcode
517 *****************************************************************************************************************/
518
ARM_SPI_GetStatus(void)519 ARM_SPI_STATUS ARM_SPI_GetStatus (void) {
520 return { 0 };
521 }
522 /**
523 \fn ARM_SPI_STATUS ARM_SPI_GetStatus (void)
524 \details
525 The function \b ARM_SPI_GetStatus returns the current SPI interface status.
526 *****************************************************************************************************************/
527
ARM_SPI_SignalEvent(uint32_t event)528 void ARM_SPI_SignalEvent (uint32_t event) {
529 // function body
530 }
531 /**
532 \fn void ARM_SPI_SignalEvent (uint32_t event)
533 \details
534 The function \b ARM_SPI_SignalEvent is a callback function registered by the function \ref ARM_SPI_Initialize.
535
536 The parameter \em event indicates one or more events that occurred during driver operation.
537 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
538
539 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
540 data fields of the structure \ref ARM_SPI_CAPABILITIES, which can be retrieved with the function \ref ARM_SPI_GetCapabilities.
541
542 The following events can be generated:
543
544 <table class="cmtable" summary="">
545 <tr>
546 <th> Parameter \em event </th><th> Bit </th><th> Description </th>
547 <th> supported when ARM_SPI_CAPABILITIES </th>
548 </tr>
549 <tr>
550 <td> \ref ARM_SPI_EVENT_TRANSFER_COMPLETE </td><td> 0 </td><td> Occurs after call to \ref ARM_SPI_Send, \ref ARM_SPI_Receive,
551 or \ref ARM_SPI_Transfer
552 to indicate that all the data has been transferred.
553 The driver is ready for the next transfer operation. </td>
554 <td> <i>always supported</i> </td>
555 </tr>
556 <tr>
557 <td> \ref ARM_SPI_EVENT_DATA_LOST </td><td> 1 </td><td> Occurs in slave mode when data is requested/sent by master
558 but send/receive/transfer operation has not been started and
559 indicates that data is lost. Occurs also in master mode when
560 driver cannot transfer data fast enough. </td>
561 <td> <i>always supported</i> </td>
562 </tr>
563 <tr>
564 <td> \ref ARM_SPI_EVENT_MODE_FAULT </td><td> 2 </td><td> Occurs in master mode when Slave Select is deactivated and
565 indicates Master Mode Fault.
566 The driver is ready for the next transfer operation. </td>
567 <td> data field \em event_mode_fault = \token{1} </td>
568 </tr>
569 </table>
570 **************************************************************************************************************************/
571
572
573 /**
574 \defgroup SPI_control SPI Control Codes
575 \ingroup spi_interface_gr
576 \brief Many parameters of the SPI driver are configured using the \ref ARM_SPI_Control function.
577 \details
578 @{
579 The various SPI control codes define:
580
581 - \ref spi_mode_ctrls specifies SPI mode
582 - \ref spi_frame_format_ctrls defines the frame format
583 - \ref spi_data_bits_ctrls defines the number of data bits
584 - \ref spi_bit_order_ctrls defines the bit order
585 - \ref spi_slave_select_mode_ctrls specifies slave select mode
586 - \ref spi_misc_ctrls specifies additional miscellaneous controls
587
588 Refer to the \ref ARM_SPI_Control function for further details.
589 */
590
591 /**
592 \defgroup spi_mode_ctrls SPI Mode Controls
593 \ingroup SPI_control
594 \brief Specifies SPI mode.
595 \details
596 @{
597 \def ARM_SPI_MODE_INACTIVE
598 \sa ARM_SPI_Control
599 \def ARM_SPI_MODE_MASTER
600 \sa ARM_SPI_Control
601 \def ARM_SPI_MODE_SLAVE
602 \sa ARM_SPI_Control
603 @}
604 */
605
606 /**
607 \defgroup spi_frame_format_ctrls SPI Frame Format
608 \ingroup SPI_control
609 \brief Defines the frame format.
610 \details
611 @{
612 \def ARM_SPI_CPOL0_CPHA0
613 \sa ARM_SPI_Control
614 \def ARM_SPI_CPOL0_CPHA1
615 \sa ARM_SPI_Control
616 \def ARM_SPI_CPOL1_CPHA0
617 \sa ARM_SPI_Control
618 \def ARM_SPI_CPOL1_CPHA1
619 \sa ARM_SPI_Control
620 \def ARM_SPI_TI_SSI
621 \sa ARM_SPI_Control
622 \def ARM_SPI_MICROWIRE
623 \sa ARM_SPI_Control
624 @}
625 */
626
627 /**
628 \defgroup spi_data_bits_ctrls SPI Data Bits
629 \ingroup SPI_control
630 \brief Defines the number of data bits.
631 \details
632 @{
633 \def ARM_SPI_DATA_BITS(n)
634 \sa ARM_SPI_Control
635 @}
636 */
637
638 /**
639 \defgroup spi_bit_order_ctrls SPI Bit Order
640 \ingroup SPI_control
641 \brief Defines the bit order.
642 \details
643 @{
644 \def ARM_SPI_MSB_LSB
645 \sa ARM_SPI_Control
646 \def ARM_SPI_LSB_MSB
647 \sa ARM_SPI_Control
648 @}
649 */
650
651 /**
652 \defgroup spi_slave_select_mode_ctrls SPI Slave Select Mode
653 \ingroup SPI_control
654 \brief Specifies SPI slave select mode.
655 \details
656 \b SPI \b Slave \b Select \b Mode configures the behavior of the \b Slave \b Select \b (SS) signal. The configuration is
657 separate for \b Master (ARM_SPI_SS_MASTER_*) and for \b Slave (\ref ARM_SPI_SS_SLAVE_HW, \ref ARM_SPI_SS_SLAVE_SW). The
658 active configuration depends on the current state (Master/Slave).
659
660 @{
661 \def ARM_SPI_SS_MASTER_UNUSED
662 An SPI master does not drive or monitor the SS line. For example, when connecting to a single slave, the SS line can be connected
663 to a fixed low level.
664 \sa ARM_SPI_Control
665 \def ARM_SPI_SS_MASTER_SW
666 SS is configured as an output and controlled via \ref ARM_SPI_Control (\ref ARM_SPI_CONTROL_SS). By default, it is not active
667 (high). It is activated (low) by \ref ARM_SPI_Control (\ref ARM_SPI_CONTROL_SS, \ref ARM_SPI_SS_ACTIVE) and deactivated by
668 \ref ARM_SPI_Control (\ref ARM_SPI_CONTROL_SS, \ref ARM_SPI_SS_INACTIVE). It is not affected by transfer/send/receive
669 functions.
670 \sa ARM_SPI_Control
671 \def ARM_SPI_SS_MASTER_HW_OUTPUT
672 Here, SS is configured as an output. It will be automatically activated/deactivated for the transfers by hardware (not
673 controlled by \ref ARM_SPI_Control (\ref ARM_SPI_CONTROL_SS)). The activation/deactivation of the line is completely hardware
674 dependent. Typically, the hardware will activate it before starting a transfer and deactivate it after a transfer completes.
675 Some hardware will keep the line active as long as the SPI stays master. Due to different hardware behavior, this mode is
676 typically not useful because certain devices require that the SS signal is strictly defined with regards to transfers.
677 \sa ARM_SPI_Control
678 \def ARM_SPI_SS_MASTER_HW_INPUT
679 This is normally used in a multi-master configuration, where a master does not drive the SS line when driving the bus but only
680 monitors it. When another master activates this line, the active master backs off. This is called \b mode \b fault. SS is
681 configured as input and the hardware only monitors it. When it is externally deactivated while being the master, it presents
682 a mode fault and the SPI switches to \b inactive mode.
683 \sa ARM_SPI_Control
684 \def ARM_SPI_SS_SLAVE_HW
685 Hardware monitors the SS line and accepts transfers only when SS line is activate. Transfers while SS is not active are
686 ignored.
687 \sa ARM_SPI_Control
688 \def ARM_SPI_SS_SLAVE_SW
689 Used only when SS line is not used. For example, when a single master and slave are connected in a system, the SS line is not
690 needed (reduces the number of lines and pins used). Slave responses are controlled by software (by default, it is not
691 responding). Software enables/disables transfers by calling \ref ARM_SPI_Control (\ref ARM_SPI_CONTROL_SS, \ref ARM_SPI_SS_ACTIVE / \ref ARM_SPI_SS_INACTIVE).
692 \sa ARM_SPI_Control
693 @}
694 */
695
696 /**
697 \defgroup spi_misc_ctrls SPI Miscellaneous Controls
698 \ingroup SPI_control
699 \brief Specifies additional miscellaneous controls.
700 \details
701 @{
702 \def ARM_SPI_SET_BUS_SPEED
703 \sa ARM_SPI_Control
704 \def ARM_SPI_GET_BUS_SPEED
705 \sa ARM_SPI_Control
706 \def ARM_SPI_SET_DEFAULT_TX_VALUE
707 \sa ARM_SPI_Control
708 \def ARM_SPI_CONTROL_SS
709 \sa ARM_SPI_Control
710 \def ARM_SPI_ABORT_TRANSFER
711 \sa ARM_SPI_Control
712 @}
713 */
714
715 /**
716 @}
717 */
718 // end group SPI_control
719
720 /**
721 \defgroup spi_ss_signals SPI Slave Select Signal definitions
722 \ingroup spi_interface_gr
723 \brief Specifies SPI Slave Select Signal definitions.
724 \details
725 @{
726 \def ARM_SPI_SS_INACTIVE
727 \sa ARM_SPI_Control
728 \def ARM_SPI_SS_ACTIVE
729 \sa ARM_SPI_Control
730 @}
731 */
732
733 /**
734 @}
735 */
736 // End SPI Interface
737
