Skip to main content

SPI Lib API

danger

this is a legacy library and thus not supported by Toradex anymore. We recommend that you use the new libraries for all Toradex modules. Please see the Toradex CE Libraries and Code Samples for up-to-date information.


Library to manage access to the Colibri's SPI ports. More...

Data Structures

struct  SPIPinConfiguration Pin Configuration data structure for SPI Port.
 

Macros

#define SPI_VER_MAJ   5
 Library Major Version Number. More...
 
#define SPI_VER_MIN   4
 Library Minor Version Number. More...
 
#define SPI_VER_BUILD   0
 Library Build Number. More...
 
#define SPI_MAX_TIMEOUT   (20000)
 Maximum timeout in milliseconds. More...
 
#define SPI_INFINITE_TIMEOUT   (0)
 0 = Infinite (no) timeout More...
 
#define SPI_PXA_MAX_CHANNELS   (4)
 Maximum available PXA SPI Channels. More...
 
#define SPI_T20_MAX_CHANNELS   (4)
 Maximum available T20 SPI Channels. More...
 
#define SPI_T30_MAX_CHANNELS   (6)
 Maximum available T20 SPI Channels. More...
 
#define SPI_MAX_CHANNELS   (6)
 Maximum SPI channels across all modules. More...
 
#define SPI_CLOCK_MAX   54000
 Maximum SPI Clock for Tegra. More...
 
#define SPI_CLOCK_MIN   26
 Minimum SPI Clock for Tegra. More...
 
#define SPI_MASTER   FALSE
 Configure as Master Device. More...
 
#define SPI_SLAVE   TRUE
 Configure as Slave Device. More...
 
#define SPI_MODE_0   0
 Mode 0 - Polarity (CPOL) 0, Phase (CPHA) 0. More...
 
#define SPI_MODE_1   1
 Mode 1 - Polarity (CPOL) 0, Phase (CPHA) 1. More...
 
#define SPI_MODE_2   2
 Mode 2 - Polarity (CPOL) 1, Phase (CPHA) 0. More...
 
#define SPI_MODE_3   3
 Mode 3 - Polarity (CPOL) 1, Phase (CPHA) 1. More...
 
#define SPI_POLARITY_HIGH   FALSE
 SPI Clock Polarity Base High. More...
 
#define SPI_POLARITY_LOW   TRUE
 SPI Clock Polarity Base Low. More...
 
#define SPI_PHASE_HIGH   FALSE
 SPI Clock Edge Active on High Going Edge. More...
 
#define SPI_PHASE_LOW   TRUE
 SPI Clock Edge Active on Low Going Edge. More...
 
#define SPI_DMA_ENABLE   TRUE
 Enable SPI over DMA. More...
 
 
#define SPI_CLOCK_54_MHZ   54000
 SPI Clock Constant for 54MHz. More...
 
#define SPI_CLOCK_36_MHZ   36000
 SPI Clock Constant for 36MHz. More...
 
#define SPI_CLOCK_27_MHZ   27000
 SPI Clock Constant for 27MHz. More...
 
#define SPI_CLOCK_26_MHZ   26000
 SPI Clock Constant for 26MHz. More...
 
#define SPI_CLOCK_18_MHZ   18000
 SPI Clock Constant for 18MHz. More...
 
#define SPI_CLOCK_13_MHZ   13000
 SPI Clock Constant for 13MHz. More...
 
#define SPI_CLOCK_12_MHZ   12000
 SPI Clock Constant for 12MHz. More...
 
#define SPI_CLOCK_6_5_MHZ   6500
 SPI Clock Constant for 6.5MHz. More...
 
#define SPI_CLOCK_6_MHZ   6000
 SPI Clock Constant for 6MHz. More...
 
#define SPI_CLOCK_4_MHZ   4000
 SPI Clock Constant for 4MHz. More...
 
#define SPI_CLOCK_3_MHZ   3000
 SPI Clock Constant for 3MHz. More...
 
#define SPI_CLOCK_2_MHZ   2000
 SPI Clock Constant for 2MHz. More...
 
#define SPI_CLOCK_1_MHZ   1000
 SPI Clock Constant for 1MHz. More...
 
#define SPI_CLOCK_812_KHZ   812
 SPI Clock Constant for 812KHz. More...
 
#define SPI_CLOCK_200_KHZ   200
 SPI Clock Constant for 200KHz. More...
 
#define SPI_CLOCK_100_KHZ   100
 SPI Clock Constant for 100KHz. More...
 
#define SPI_CLOCK_26_KHZ   26
 SPI Clock Constant for 26KHz. More...
 

Typedefs

typedef struct SPIPinConfiguration tSpiPinConfiguration
 Pin Configuration data structure for SPI Port. More...
 

Enumerations

enum  tSpiWaitMethod SpiWaitByBusyLoop
 

Functions

void SPIGetLibVersion (DWORD *verMaj, DWORD *verMin, DWORD *build)
 
BOOL SPIInit (DWORD spiChannel, DWORD dataBits, DWORD clockFrequency, BOOL isSlave, DWORD mode, tSpiPinConfiguration *pinConfiguration)
 
void SPIDeinit (DWORD spiChannel)
 
DWORD SPIReadWritePolling (DWORD spiChannel, DWORD *rxBuffer, DWORD *txBuffer, DWORD numberOfFrames, DWORD chipSelectID)
 
DWORD SPIWritePolling (DWORD spiChannel, DWORD *buffer, DWORD numberOfFrames, DWORD chipSelectID)
 
DWORD SPIReadPolling (DWORD spiChannel, DWORD *buffer, DWORD numberOfFrames, DWORD chipSelectID)
 
BOOL InitSPI (DWORD spiChannel, DWORD dataBits, DWORD baudRateDivisor, BOOL isSlave, BOOL polarity, BOOL phase, BOOL dmaEnable)
 
void DeinitSPI (DWORD spiChannel)
 
DWORD WriteSPI (DWORD spiChannel, DWORD *buffer, DWORD numberOfFrames)
 
DWORD ReadSPI (DWORD spiChannel, DWORD *buffer, DWORD numberOfFrames)
 
DWORD ReadWriteSPI (DWORD spiChannel, DWORD *rxBuffer, DWORD *txBuffer, DWORD numberOfBytes, DWORD timeout)
 

Detailed Description

Library to manage access to the Colibri's SPI ports.
Author
andy.kiser
Revision
2863
Date
2015-06-26 17:18:52 +0200 (Fr, 26 Jun 2015)
Target Platforms:
Colibri Modules
Test:
Tested on: Colibri PXAxxx, T20
if SPIDMADEF is set in the preprocessor, the library is generated using DMA.
Clock setting is ignored when Slave mode selected
FrequencyT20PXA320PXA310PXA300PXA270*
54MHzY----
36MHzY----
27MHzY----
26MHzY-Y--
18MHzY----
13MHzYYYYY
12MHzY----
6.5MHzYYYYY
6MHzY----
4MHzY----
3MHzY----
2MHzY----
1MHzY---Y
0.812MHzYYYYY
0.2MHzY-Y-Y
0.1MHzYYYYY
0.026MHzY----
*The Colibri PXA270 module allows much more frequency settings. Allowed are all 13MHz/x values where x is a value from 1 to 4096.
CPOL 0, CPHA 0 - data is captured on clock rising edge, base value of clock is 0
CPOL 0, CPHA 1 - data is captured on clock falling edge, base value of clock is 0
CPOL 1, CPHA 0 - data is captured on clock falling edge, base value of clock is 1
CPOL 1, CPHA 1 - data is captured on clock rising edge, base value of clock is 1
SODIMM Pins Initialisation Structure - can be used for T20 modules.
The library will validate the SODIMM pin against the SPI Instance.
If valid, the library will set the correct alternate function for the supplied SODIMM pin for the SPI Port.
The library assumes that the supplied configuration combination has no pinmux group conflicts.
The library assumes that the user has ensured all pre-existing pin setups have already been cleared.
For valid options for SPI Signal lines please see the T20 Datasheet
If you require different Pin allocations on a PXA module then, after SPIINIT has been called,
clear the default settings and configure your required settings prior to using any other functions.
If Pin Configuration is passed as a null pointer in SPIInit, then the library will use the default settings.
These are:
Function T20  PXA270  PXA300  PXA310  PXA320 
 GPIOSODIMMEval 3.1GPIOSODIMMEval 3.1GPIOSODIMMEval 3.1GPIOSODIMMEval 3.1GPIOSODIMMEval 3.1
SPI1 CLKX5/1100X9-723/288X10-3385/188X10-3385/188X10-3383/188X10-33
SPI1 MOSIT2/369X22-2125/292X10-3588/692X10-3588/692X10-3586/692X10-35
SPI1 MISOT3/377X22-2226/190X10-3487/690X10-3487/690X10-3485/690X10-34
SPI1 CS0X6/1102X9-924/286X10-3286/186X10-3286/186X10-3284/186X10-32
                
SPI2 CLKA7/367X10-3019/155X9-5n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI2 MOSID0/388X10-3338/237X10-12n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI2 MISOD1/390X10-3411/228X10-27n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI2 CS0D3/386X10-3214/263X9-6n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
                
SPI3 CLKA6/330X10-2852/273X10-3191/1154X3-C791/1154X3-C769/266X9-31
SPI3 MOSIB6/355X9-535/3135X10-4093/1158X3-C893/1158X3-C871/257X9-33
SPI3 MISOB7/363X9-682/177X22-2294/1160X3-A994/1160X3-A972/261X9-34
SPI3 CS0B5/328X10-2783/179X22-1192/1156X3-A892/1156X3-A870/264X9-32
                
SPI4 CLKD0/188X10-33n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI4 MOSID4/192X10-35n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI4 MISOD1/190X10-34n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
SPI4 CS0D3/186X10-32n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.n.a.
n.b. Note the conflict in the T20 default settings between SPI2 & SPI4
SPI4 on T20 is SPI1 on all PXAxxx modules
On power up for T20, SODIMM 104 is configured as SPI3 MISO and SODIMM 131 is configured as SPI3 CS0 and hence will need to be cleared if SPI3 is to be used in anything other than default settings.

Macro Definition Documentation

#define SPI_CLOCK_100_KHZ   100
SPI Clock Constant for 100KHz.
#define SPI_CLOCK_12_MHZ   12000
SPI Clock Constant for 12MHz.
#define SPI_CLOCK_13_MHZ   13000
SPI Clock Constant for 13MHz.
#define SPI_CLOCK_18_MHZ   18000
SPI Clock Constant for 18MHz.
#define SPI_CLOCK_1_MHZ   1000
SPI Clock Constant for 1MHz.
#define SPI_CLOCK_200_KHZ   200
SPI Clock Constant for 200KHz.
#define SPI_CLOCK_26_KHZ   26
SPI Clock Constant for 26KHz.
#define SPI_CLOCK_26_MHZ   26000
SPI Clock Constant for 26MHz.
#define SPI_CLOCK_27_MHZ   27000
SPI Clock Constant for 27MHz.
#define SPI_CLOCK_2_MHZ   2000
SPI Clock Constant for 2MHz.
#define SPI_CLOCK_36_MHZ   36000
SPI Clock Constant for 36MHz.
#define SPI_CLOCK_3_MHZ   3000
SPI Clock Constant for 3MHz.
#define SPI_CLOCK_4_MHZ   4000
SPI Clock Constant for 4MHz.
#define SPI_CLOCK_54_MHZ   54000
SPI Clock Constant for 54MHz.
#define SPI_CLOCK_6_5_MHZ   6500
SPI Clock Constant for 6.5MHz.
#define SPI_CLOCK_6_MHZ   6000
SPI Clock Constant for 6MHz.
#define SPI_CLOCK_812_KHZ   812
SPI Clock Constant for 812KHz.
#define SPI_CLOCK_MAX   54000
Maximum SPI Clock for Tegra.
#define SPI_CLOCK_MIN   26
Minimum SPI Clock for Tegra.
#define SPI_DMA_ENABLE   TRUE
Enable SPI over DMA.
#define SPI_INFINITE_TIMEOUT   (0)
0 = Infinite (no) timeout
#define SPI_MASTER   FALSE
Configure as Master Device.
#define SPI_MAX_CHANNELS   (6)
Maximum SPI channels across all modules.
#define SPI_MAX_TIMEOUT   (20000)
Maximum timeout in milliseconds.
#define SPI_MODE_0   0
Mode 0 - Polarity (CPOL) 0, Phase (CPHA) 0.
#define SPI_MODE_1   1
Mode 1 - Polarity (CPOL) 0, Phase (CPHA) 1.
#define SPI_MODE_2   2
Mode 2 - Polarity (CPOL) 1, Phase (CPHA) 0.
#define SPI_MODE_3   3
Mode 3 - Polarity (CPOL) 1, Phase (CPHA) 1.
#define SPI_PHASE_HIGH   FALSE
SPI Clock Edge Active on High Going Edge.
#define SPI_PHASE_LOW   TRUE
SPI Clock Edge Active on Low Going Edge.
#define SPI_POLARITY_HIGH   FALSE
SPI Clock Polarity Base High.
Deprecated Defines
#define SPI_POLARITY_LOW   TRUE
SPI Clock Polarity Base Low.
#define SPI_PXA_MAX_CHANNELS   (4)
Maximum available PXA SPI Channels.
#define SPI_SLAVE   TRUE
Configure as Slave Device.
#define SPI_T20_MAX_CHANNELS   (4)
Maximum available T20 SPI Channels.
#define SPI_T30_MAX_CHANNELS   (6)
Maximum available T20 SPI Channels.
#define SPI_VER_BUILD   0
Library Build Number.
#define SPI_VER_MAJ   5
Library Major Version Number.
#define SPI_VER_MIN   4
Library Minor Version Number.

Typedef Documentation

typedef struct SPIPinConfiguration tSpiPinConfiguration
Pin Configuration data structure for SPI Port.
Contains Pin Configuration for SPI Port

Enumeration Type Documentation

Enumerator
SpiWaitByInterrupt better overall system performance, bug increased Spi latency
SpiWaitByBusyLoop minimum Spi latency, but occupies CPU while waiting.

Function Documentation

void DeinitSPI(DWORD spiChannel) 
De-Initializes SPI unit.
Calling this function is very important for releasing resources.
Otherwise SPI interrupts will be blocked, and can only be re-activated by resetting the system
Deprecated:
Please use SPIDeinit.
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
BOOL InitSPI(DWORD spiChannel,
  DWORD dataBits,
  DWORD baudRateDivisor,
  BOOL isSlave,
  BOOL polarity,
  BOOL phase,
  BOOL dmaEnable 
 )  
Deprecated FunctionsInitializes SPI unit
Deprecated:
Please use SPIInit
Parameters
[in]spiChannelSelected SPI channel (1 to SPI_CHANNELS_MAX)
[in]dataBitsNumber of Databits [1 to 32]
[in]baudRateDivisorFor PXA270: Serial bit rate = 13MHz/(baudRateDivisor + 1)
(baudRateDivisor Range 0 to 4095) Ignored when Slave
For PXA3xx : the following divisors are valid: 0x00,0x01,0x0F,0x07F are valid.
For PXA310 only: set the MSB of the baudRateDivisor to use 26MHz as a base clock, instead of 13MHz.
For Tegra2: : Serial bit rate = 54MHz /((baudRateDivisor/2)+1); (Range 0-255)
[in]isSlaveTrue=Slave False=Master
[in]polaritySPI Polarity FALSE: Begin with High
[in]phaseSPI Phase FALSE: Data latched on positive edge
[in]dmaEnableTRUE: dma enabled
Return values
TRUESuccess
FALSEFailure
DWORD ReadSPI(DWORD spiChannel,
  DWORD * buffer,
  DWORD numberOfFrames 
 )  
Reads data from SPI in polling mode. The function returns after buffer is full
Deprecated:
Please use SPIReadPolling.
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[out]bufferPointer to the receive buffer
[in]numberOfFramesNumber of frames to receive
Returns
Number of received frames
DWORD ReadWriteSPI(DWORD spiChannel,
  DWORD * rxBuffer,
  DWORD * txBuffer,
  DWORD numberOfBytes,
  DWORD timeout 
 )  
Simultaneously reads and writes data from/to SPI.
The function returns after buffer is full or when a timeout occurs.
Deprecated:
Please use SPIReadWritePolling.
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[out]rxBufferPhysical Address of the receive buffer
[in]txBufferPhysical Address of the transmit buffer.
[in]numberOfBytesSize of the transmit and receive buffers in bytes - must be DWORD aligned for PXA
[in]timeoutIf the receive buffer is not full, the function returns after this timeout. 0 = Infinite timeout
Return values
>0Number of received bytes
0Timeout occured
void SPIDeinit(DWORD spiChannel) 
De-Initializes SPI unit.
Calling this function is very important for cleaning up.
Otherwise SPI interrupts will be blocked, and can only be re-activated by resetting the system
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
void SPIGetLibVersion(DWORD * verMaj,
  DWORD * verMin,
  DWORD * build 
 )  
Outputs library version
Parameters
[out]verMajmajor version number. Set this parameter to NULL if not required
[out]verMinminor version number. Set this parameter to NULL if not required
[out]buildbuild number. Set this parameter to NULL if not required
BOOL SPIInit(DWORD spiChannel,
  DWORD dataBits,
  DWORD clockFrequency,
  BOOL isSlave,
  DWORD mode,
  tSpiPinConfiguration * pinConfiguration 
 )  
Initializes SPI unit
Parameters
[in]spiChannelSelected SPI channel (1 to SPI_CHANNELS_MAX)
[in]dataBitsNumber of Databits [1-32]
[in]clockFrequencySelect from Clock Frequency defines above
[in]isSlaveTrue = Slave, False = Master
[in]modeSPI Mode - Select from Mode defines above
[in]pinConfigurationPointer to SpiPinConfiguration structure,
Set pointer to NULL to use default settings.
Return values
TRUESuccess
FALSEFailure
DWORD SPIReadPolling(DWORD spiChannel,
  DWORD * buffer,
  DWORD numberOfFrames,
  DWORD chipSelectID 
 )  
Reads data from SPI in polling mode
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[in]bufferPointer to the receive buffer
[in]numberOfFramesNumber of frames to receive
[in]chipSelectIDLEGACY - this parameter is ignored.
Return values
Numberof receiveded frames
DWORD SPIReadWritePolling(DWORD spiChannel,
  DWORD * rxBuffer,
  DWORD * txBuffer,
  DWORD numberOfFrames,
  DWORD chipSelectID 
 )  
Writes data to and Reads data from SPI in polling mode
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[in]rxBufferPointer to the transmit buffer. NULL if you want to transmit only.
[in]txBufferPointer to the receive buffer. NULL if you want to receive only.
[in]numberOfFramesNumber of frames to transmit
[in]chipSelectIDLEGACY - this parameter is ignored.
Return values
>0Number of transmitted frames
0Error
DWORD SPIWritePolling(DWORD spiChannel,
  DWORD * buffer,
  DWORD numberOfFrames,
  DWORD chipSelectID 
 )  
Writes data to SPI in polling mode
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[in]bufferPointer to the transmit buffer
[in]numberOfFramesNumber of frames to transmit
[in]chipSelectIDLEGACY - this parameter is ignored.
Return values
>0Number of transmitted frames
0Error
DWORD WriteSPI(DWORD spiChannel,
  DWORD * buffer,
  DWORD numberOfFrames 
 )  
Writes data to SPI in polling mode
Deprecated:
Please use SPIWritePolling.
Parameters
[in]spiChannelSelected SPI channel (1 - SPI_CHANNELS_MAX)
[in]bufferPointer to the transmit buffer
[in]numberOfFramesNumber of frames to transmit
Returns
Number of transmitted frames
Send Feedback!