begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_SPI.c

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