Unit SPI
From Ultibo.org
Return to Unit Reference
Description
Ultibo SPI interface unit
SPI (Serial Peripheral Interface) is a synchronous serial bus for communication with peripheral components.
The SPI protocol is not defined by any actual standard but some psuedo standards exist with all of the available devices. SPI is a master-slave protocol where the master asserts the chip selectline (CS) to select the slave device before sending data one byte at a time. For every byte written to the bus by the master the selected slave returns a byte as well so for every write there is an equivalent read. SPI can also operate in either 4 wire (standard) or 3 wire(bidirectional) modes.
Due to the lack of formal standards and the range of devices that exist various options are provided to allow setting clock phase and polarity as well chip select polarity.
For the purpose of this interface a device is the SPI controller attached to the local system and may be either a master or a slave. Since the protocol does not include any form of enumeration or identification the interface does not attempt to represent the devices connected to the bus, any driver written to communicate with a connected SPI device should know (or allow configuration of) the chip select for the for the device and the specific message format required for that device.
Constants
SPI specific constants
SPI_* SPI_NAME_PREFIX = 'SPI';
|
Name prefix for SPI Devices |
SPI device type constants
SPI_TYPE_* SPI_TYPE_NONE = 0;
|
SPI device state constants
SPI_STATE_* SPI_STATE_DISABLED = 0;
|
|
SPI_STATE_ENABLED = 1;
|
SPI device flag constants
SPI_FLAG_* SPI_FLAG_NONE = $00000000;
|
|
SPI_FLAG_SLAVE = $00000001;
|
Device is a slave not a master |
SPI_FLAG_4WIRE = $00000002;
|
Device supports 4 wire operation (CS/MISO/MOSI/SCLK) |
SPI_FLAG_3WIRE = $00000004;
|
Device supports 3 wire operation (CS/MIMO/SCLK) |
SPI_FLAG_LOSSI = $00000008;
|
Device supports LoSSI (Low Speed Serial) mode (CS/SCL/SDA) |
SPI_FLAG_CPOL = $00000010;
|
Device supports Clock Polarity setting |
SPI_FLAG_CPHA = $00000020;
|
Device supports Clock Phase setting |
SPI_FLAG_CSPOL = $00000040;
|
Device supports Chip Select Polarity setting |
SPI_FLAG_NO_CS = $00000080;
|
Device supports Chip Select None (CS handled externally) |
SPI_FLAG_DMA = $00000100;
|
Device supports DMA transfers |
SPI transfer flag constants
SPI_TRANSFER_* SPI_TRANSFER_NONE = $00000000;
|
|
SPI_TRANSFER_DMA = $00000001;
|
Use DMA for transfer (Write/Read) (Note: Buffers must be DMA compatible) |
SPI logging constants
SPI_LOG_* SPI_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
SPI debugging messages |
SPI_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
SPI informational messages, such as a device being attached or detached |
SPI_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
SPI error messages |
SPI_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No SPI messages |
Type definitions
To be documented
Public variables
SPI logging
SPI_DEFAULT_LOG_LEVEL:LongWord = SPI_LOG_LEVEL_DEBUG;
|
Minimum level for SPI messages. Only messages with level greater than or equal to this will be printed. |
SPI_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure SPIInit;
Description: Initialize the SPI unit and SPI device table
| Note | Called only during system startup |
|---|
SPI functions
function SPIDeviceStart(SPI:PSPIDevice; Mode,ClockRate,ClockPhase,ClockPolarity:LongWord):LongWord;
Description: Start the specified SPI device ready for writing and reading
| SPI | The SPI device to start |
|---|---|
| Mode | The device mode to set (eg SPI_MODE_4WIRE) |
| ClockRate | The clock rate to set for the device |
| ClockPhase | The clock phase to set (eg SPI_CLOCK_PHASE_LOW) |
| ClockPolarity | The clock polarity to set (eg SPI_CLOCK_POLARITY_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceStop(SPI:PSPIDevice):LongWord;
Description: Stop the specified SPI device and terminate writing and reading
| SPI | The SPI device to stop |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceRead(SPI:PSPIDevice; ChipSelect:Word; Dest:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Read data from the specified SPI device
| SPI | The SPI device to read from |
|---|---|
| ChipSelect | The chip select for the slave to read from (eg SPI_CS_0) |
| Dest | Pointer to a buffer to receive the data |
| Size | The size of the buffer |
| Flags | The flags for this transfer (eg SPI_TRANSFER_DMA) |
| Count | The number of bytes read on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, dummy data will be written for each byte to be read} |
function SPIDeviceWrite(SPI:PSPIDevice; ChipSelect:Word; Source:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Write data to the specified SPI device
| SPI | The SPI device to write to |
|---|---|
| ChipSelect | The chip select for the slave to write to (eg SPI_CS_0) |
| Source | Pointer to a buffer of data to transmit |
| Size | The size of the buffer |
| Flags | The flags for this transfer (eg SPI_TRANSFER_DMA) |
| Count | The number of bytes written on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, received data will be discarded for each by written |
function SPIDeviceWriteRead(SPI:PSPIDevice; ChipSelect:Word; Source,Dest:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Write data to and Read data from the specified SPI device in one operation
| SPI | The SPI device to write to and read from |
|---|---|
| ChipSelect | The chip select for the slave to write to and read from (eg SPI_CS_0) |
| Source | Pointer to a buffer of data to transmit |
| Dest | Pointer to a buffer to receive the data |
| Size | The size of the buffer |
| Flags | The flags for this transfer (eg SPI_TRANSFER_DMA) |
| Count | The number of bytes written and read on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, both the source and dest buffers must be the same size |
function SPIDeviceGetMode(SPI:PSPIDevice):LongWord;
Description: Get the device mode of the specified SPI device
| SPI | The SPI device to get device mode from |
|---|---|
| Return | The device mode or SPI_MODE_UNKNOWN on failure |
function SPIDeviceSetMode(SPI:PSPIDevice; Mode:LongWord):LongWord;
Description: Set the device mode for the specified SPI device
| SPI | The SPI device to set device mode for |
|---|---|
| Mode | The device mode to set (eg SPI_MODE_4WIRE) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceGetClockRate(SPI:PSPIDevice; ChipSelect:Word):LongWord;
Description: Get the clock rate of the specified SPI device
| SPI | The SPI device to get clock rate from |
|---|---|
| ChipSelect | The chip select number to get clock rate from (SPI_CS_NONE for default) |
| Return | The clock rate in Hz or 0 on failure |
function SPIDeviceSetClockRate(SPI:PSPIDevice; ChipSelect:Word; ClockRate:LongWord):LongWord;
Description: Set the clock rate for the specified SPI device
| SPI | The SPI device to set clock rate for |
|---|---|
| ChipSelect | The chip select number to set clock rate for (SPI_CS_NONE for default) |
| ClockRate | The clock rate to set in Hz |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceGetClockPhase(SPI:PSPIDevice):LongWord;
Description: Get the clock phase of the specified SPI device
| SPI | The SPI device to get clock phase from |
|---|---|
| Return | The clock phase or SPI_CLOCK_PHASE_UNKNOWN on failure |
function SPIDeviceSetClockPhase(SPI:PSPIDevice; ClockPhase:LongWord):LongWord;
Description: Set the clock phase for the specified SPI device
| SPI | The SPI device to set clock phase for |
|---|---|
| ClockPhase | The clock phase to set (eg SPI_CLOCK_PHASE_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceGetClockPolarity(SPI:PSPIDevice):LongWord;
Description: Get the clock polarity of the specified SPI device
| SPI | The SPI device to get clock polarity from |
|---|---|
| Return | The clock polarity or SPI_CLOCK_POLARITY_UNKNOWN on failure |
function SPIDeviceSetClockPolarity(SPI:PSPIDevice; ClockPolarity:LongWord):LongWord;
Description: Set the clock polarity for the specified SPI device
| SPI | The SPI device to set clock polarity for |
|---|---|
| ClockPolarity | The clock polarity to set (eg SPI_CLOCK_POLARITY_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceGetSelectPolarity(SPI:PSPIDevice; ChipSelect:Word):LongWord;
Description: Get the chip select polarity of the specified SPI device
| SPI | The SPI device to get chip select polarity from |
|---|---|
| ChipSelect | The chip select number to get polarity from (SPI_CS_NONE for default) |
| Return | The chip select polarity or SPI_CS_POLARITY_UNKNOWN on failure |
function SPIDeviceSetSelectPolarity(SPI:PSPIDevice; ChipSelect:Word; SelectPolarity:LongWord):LongWord;
Description: Set the chip select polarity for the specified SPI device
| SPI | The SPI device to set chip select polarity for |
|---|---|
| ChipSelect | The chip select number to set polarity for (SPI_CS_NONE for default) |
| SelectPolarity | The chip select polarity to set (eg SPI_CS_POLARITY_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceProperties(SPI:PSPIDevice; Properties:PSPIProperties):LongWord;
Description: Get the properties for the specified SPI device
| SPI | The SPI device to get properties from |
|---|---|
| Properties | Pointer to a TSPIProperties structure to fill in |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SPIDeviceCreate:PSPIDevice;
Description: Create a new SPI entry
| Return | Pointer to new SPI entry or nil if SPI could not be created |
|---|
function SPIDeviceCreateEx(Size:LongWord):PSPIDevice;
Description: Create a new SPI entry
| Size | Size in bytes to allocate for new SPI (Including the SPI entry) |
|---|---|
| Return | Pointer to new SPI entry or nil if SPI could not be created |
function SPIDeviceDestroy(SPI:PSPIDevice):LongWord;
Description: Destroy an existing SPI entry
| Note | None documented |
|---|
function SPIDeviceRegister(SPI:PSPIDevice):LongWord;
Description: Register a new SPI in the SPI table
| Note | None documented |
|---|
function SPIDeviceDeregister(SPI:PSPIDevice):LongWord;
Description: Deregister a SPI from the SPI table
| Note | None documented |
|---|
function SPIDeviceFind(SPIId:LongWord):PSPIDevice;
Description: To be documented
| Note | None documented |
|---|
function SPIDeviceFindByName(const Name:String):PSPIDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function SPIDeviceFindByDescription(const Description:String):PSPIDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function SPIDeviceEnumerate(Callback:TSPIEnumerate; Data:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function SPIDeviceNotification(SPI:PSPIDevice; Callback:TSPINotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
RTL SPI functions
function SysSPIAvailable:Boolean;
Description: Check if an SPI device is available
| Note | None documented |
|---|
function SysSPIStart(Mode,ClockRate,ClockPhase,ClockPolarity:LongWord):LongWord;
Description: Start the default SPI device ready for writing and reading
| Mode | The device mode to set (eg SPI_MODE_4WIRE") |
|---|---|
| ClockRate | The clock rate to set for the device |
| ClockPhase | The clock phase to set (eg SPI_CLOCK_PHASE_LOW) |
| ClockPolarity | The clock polarity to set (eg SPI_CLOCK_POLARITY_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SysSPIStop:LongWord;
Description: Stop the default SPI device and terminate writing and reading
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function SysSPIRead(ChipSelect:Word; Dest:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read data from the default SPI device
| ChipSet | The chip select for the slave to read from (eg SPI_CS_0) |
|---|---|
| Dest | Pointer to a buffer to receive the data |
| Size | The size of the buffer |
| Count | The number of bytes read on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, dummy data will be written for each byte to be read |
function SysSPIWrite(ChipSelect:Word; Source:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Write data to the default SPI device
| ChipSet | The chip select for the slave to write to (eg SPI_CS_0) |
|---|---|
| Source | Pointer to a buffer of data to transmit |
| Size | The size of the buffer |
| Count | The number of bytes written on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, received data will be discarded for each by written |
function SysSPIWriteRead(ChipSelect:Word; Source,Dest:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Write data to and Read data from the default SPI device in one operation
| ChipSet | The chip select for the slave to write to and read from (eg SPI_CS_0) |
|---|---|
| Source | Pointer to a buffer of data to transmit |
| Dest | Pointer to a buffer to receive the data |
| Size | The size of the buffer |
| Count | The number of bytes written and read on return |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Because SPI writes and then reads for each byte, both the source and dest buffers must be the same size |
function SysSPIGetMode:LongWord;
Description: Get the device mode of the default SPI device
| Return | The device mode or SPI_MODE_UNKNOWN on failure |
|---|
function SysSPISetMode(Mode:LongWord):LongWord;
Description: Set the device mode for the default SPI device
| Mode | The device mode to set (eg SPI_MODE_4WIRE) |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SysSPIGetClockRate(ChipSelect:Word):LongWord;
Description: Get the clock rate of the default SPI device
| ChipSelect | The chip select number to get clock rate from (SPI_CS_NONE for default) |
|---|---|
| Return | The clock rate in Hz or 0 on failure |
function SysSPISetClockRate(ChipSelect:Word; ClockRate:LongWord):LongWord;
Description: Set the clock rate for the default SPI device
| ChipSelect | The chip select number to set clock rate for (SPI_CS_NONE for default) |
|---|---|
| ClockRate | The clock rate to set in Hz |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SysSPIGetClockPhase:LongWord;
Description: Get the clock phase of the default SPI device
| Return | The clock phase or SPI_CLOCK_PHASE_UNKNOWN on failure |
|---|
function SysSPISetClockPhase(ClockPhase:LongWord):LongWord;
Description: Set the clock phase for the default SPI device
| ClockPhase | The clock phase to set (eg SPI_CLOCK_PHASE_LOW) |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SysSPIGetClockPolarity:LongWord;
Description: Get the clock polarity of the default SPI device
| Return | The clock polarity or SPI_CLOCK_POLARITY_UNKNOWN on failure |
|---|
function SysSPISetClockPolarity(ClockPolarity:LongWord):LongWord;
Description: Set the clock polarity for the default SPI device
| ClockPolarity | The clock polarity to set (eg SPI_CLOCK_POLARITY_LOW) |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SysSPIGetSelectPolarity(ChipSelect:Word):LongWord;
Description: Get the chip select polarity of the default SPI device
| ChipSet | The chip select number to get polarity from (SPI_CS_NONE for default) |
|---|---|
| Return | The chip select polarity or SPI_CS_POLARITY_UNKNOWN on failure |
</div></div>
function SysSPISetSelectPolarity(ChipSelect:Word; SelectPolarity:LongWord):LongWord;
Description: Set the chip select polarity for the default SPI device
| ChipSet | The chip select number to set polarity for (SPI_CS_NONE for default) |
|---|---|
| SelectPolarity | The chip select polarity to set (eg SPI_CS_POLARITY_LOW) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
SPI helper functions
function SPIGetCount:LongWord; inline;
Description: Get the current SPI count
| Note | None documented |
|---|
function SPIDeviceGetDefault:PSPIDevice; inline;
Description: Get the current default SPI device
| Note | None documented |
|---|
function SPIDeviceSetDefault(SPI:PSPIDevice):LongWord;
Description: Set the current default SPI device
| Note | None documented |
|---|
function SPIDeviceCheck(SPI:PSPIDevice):PSPIDevice;
Description: Check if the supplied SPI is in the SPI table
| Note | None documented |
|---|
procedure SPILog(Level:LongWord; SPI:PSPIDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure SPILogInfo(SPI:PSPIDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure SPILogError(SPI:PSPIDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure SPILogDebug(SPI:PSPIDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
function SPIChipSelectToString(ChipSelect:Word):String;
Description: To be documented
| Note | None documented |
|---|
function SPIModeToString(Mode:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function SPIClockPhaseToString(Phase:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function SPIClockPolarityToString(Polarity:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
function SPISelectPolarityToString(Polarity:LongWord):String;
Description: To be documented
| Note | None documented |
|---|
Return to Unit Reference
