Search by Tags

SPI with DMA Library API

 

Compare with Revision




Subscribe for this article updates

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  3
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...

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)
void  TegSpiSetWaitMethod (DWORD spiChannel, tSpiWaitMethod method)
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:
kia
Revision:
2420
Date:
2014-10-28 10:05:14 +0100 (Di, 28 Okt 2014)
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*
54MHz Y - - - -
36MHz Y - - - -
27MHz Y - - - -
26MHz Y - Y - -
18MHz Y - - - -
13MHz Y Y Y Y Y
12MHz Y - - - -
6.5MHz Y Y Y Y Y
6MHz Y - - - -
4MHz Y - - - -
3MHz Y - - - -
2MHz Y - - - -
1MHz Y - - - Y
0.812MHz Y Y Y Y Y
0.2MHz Y - Y - Y
0.1MHz Y Y Y Y Y
0.026MHz Y - - - -

*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:

FunctionT20PXA270PXA300PXA310PXA320
GPIO SODIMM Eval 3.1 GPIO SODIMM Eval 3.1 GPIO SODIMM Eval 3.1 GPIO SODIMM Eval 3.1 GPIO SODIMM Eval 3.1
SPI1 CLK X5/1 100 X9-7 23/2 88 X10-33 85/1 88 X10-33 85/1 88 X10-33 83/1 88 X10-33
SPI1 MOSI T2/3 69 X22-21 25/2 92 X10-35 88/6 92 X10-35 88/6 92 X10-35 86/6 92 X10-35
SPI1 MISO T3/3 77 X22-22 26/1 90 X10-34 87/6 90 X10-34 87/6 90 X10-34 85/6 90 X10-34
SPI1 CS0 X6/1 102 X9-9 24/2 86 X10-32 86/1 86 X10-32 86/1 86 X10-32 84/1 86 X10-32
SPI2 CLK A7/3 67 X10-30 19/1 55 X9-5 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI2 MOSI D0/3 88 X10-33 38/2 37 X10-12 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI2 MISO D1/3 90 X10-34 11/2 28 X10-27 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI2 CS0 D3/3 86 X10-32 14/2 63 X9-6 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI3 CLK A6/3 30 X10-28 52/2 73 X10-31 91/1 154 X3-C7 91/1 154 X3-C7 69/2 66 X9-31
SPI3 MOSI B6/3 55 X9-5 35/3 135 X10-40 93/1 158 X3-C8 93/1 158 X3-C8 71/2 57 X9-33
SPI3 MISO B7/3 63 X9-6 82/1 77 X22-22 94/1 160 X3-A9 94/1 160 X3-A9 72/2 61 X9-34
SPI3 CS0 B5/3 28 X10-27 83/1 79 X22-11 92/1 156 X3-A8 92/1 156 X3-A8 70/2 64 X9-32
SPI4 CLK D0/1 88 X10-33 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI4 MOSI D4/1 92 X10-35 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI4 MISO D1/1 90 X10-34 n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a. n.a.
SPI4 CS0 D3/1 86 X10-32 n.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   3

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] spiChannel Selected 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] spiChannel Selected SPI channel (1 to SPI_CHANNELS_MAX)
[in] dataBits Number of Databits [1 to 32]
[in] baudRateDivisor For 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] isSlave True=Slave False=Master
[in] polarity SPI Polarity FALSE: Begin with High
[in] phase SPI Phase FALSE: Data latched on positive edge
[in] dmaEnable TRUE: dma enabled
Return values
TRUE Success
FALSE Failure
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] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[out] buffer Pointer to the receive buffer
[in] numberOfFrames Number 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] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[out] rxBuffer Physical Address of the receive buffer
[in] txBuffer Physical Address of the transmit buffer.
[in] numberOfBytes Size of the transmit and receive buffers in bytes - must be DWORD aligned for PXA
[in] timeout If the receive buffer is not full, the function returns after this timeout. 0 = Infinite timeout
Return values
>0 Number of received bytes
0 Timeout 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] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
void SPIGetLibVersion ( DWORD *  verMaj,
DWORD *  verMin,
DWORD *  build
)

Outputs library version

Parameters
[out] verMaj major version number. Set this parameter to NULL if not required
[out] verMin minor version number. Set this parameter to NULL if not required
[out] build build 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] spiChannel Selected SPI channel (1 to SPI_CHANNELS_MAX)
[in] dataBits Number of Databits [1-32]
[in] clockFrequency Select from Clock Frequency defines above
[in] isSlave True = Slave, False = Master
[in] mode SPI Mode - Select from Mode defines above
[in] pinConfiguration Pointer to SpiPinConfiguration structure,
Set pointer to NULL to use default settings.
Set unused pins to '-1'.
Return values
TRUE Success
FALSE Failure
DWORD SPIReadPolling ( DWORD  spiChannel,
DWORD *  buffer,
DWORD  numberOfFrames,
DWORD  chipSelectID
)

Reads data from SPI in polling mode

Parameters
[in] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[in] buffer Pointer to the receive buffer
[in] numberOfFrames Number of frames to receive
[in] chipSelectID LEGACY - this parameter is ignored.
Return values
Number of 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] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[in] rxBuffer Pointer to the transmit buffer. NULL if you want to transmit only.
[in] txBuffer Pointer to the receive buffer. NULL if you want to receive only.
[in] numberOfFrames Number of frames to transmit
[in] chipSelectID LEGACY - this parameter is ignored.
Return values
>0 Number of transmitted frames
0 Error
DWORD SPIWritePolling ( DWORD  spiChannel,
DWORD *  buffer,
DWORD  numberOfFrames,
DWORD  chipSelectID
)

Writes data to SPI in polling mode

Parameters
[in] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[in] buffer Pointer to the transmit buffer
[in] numberOfFrames Number of frames to transmit
[in] chipSelectID LEGACY - this parameter is ignored.
Return values
>0 Number of transmitted frames
0 Error
void TegSpiSetWaitMethod ( DWORD  spiChannel,
tSpiWaitMethod method
)

Define how the library shall wait to read / write the FIFO.

Parameters
[in] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[in] method "SpiWaitByInterrupt" (Default): increases Spi latency, but leads to low CPU load "SpiWaitByBusyLoop": provides the best SPI performance, but loads the CPU
DWORD WriteSPI ( DWORD  spiChannel,
DWORD *  buffer,
DWORD  numberOfFrames
)

Writes data to SPI in polling mode

Deprecated:
Please use SPIWritePolling.
Parameters
[in] spiChannel Selected SPI channel (1 - SPI_CHANNELS_MAX)
[in] buffer Pointer to the transmit buffer
[in] numberOfFrames Number of frames to transmit
Returns
Number of transmitted frames