Difference between revisions of "Unit SPI"

Revision as of 04:26, 30 November 2016

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

To be documented

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

@@ Line 201: / Line 201: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 <pre style="border: 0; padding-bottom:0px;">function SPIDeviceRead(SPI:PSPIDevice; ChipSelect:Word; Dest:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</pre>
-<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Read data ?rom the specified SPI device</div>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Read data from the specified SPI device</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
 ! '''SPI'''
-| The SPI device to read ?rom
+| The SPI device to read from
 |-
 ! '''ChipSelect'''
-| The chip select for the slave to read ?rom (eg SPI_CS_0)
+| The chip select for the slave to read from (eg SPI_CS_0)
 |-
 ! '''Dest'''
@@ Line 267: / Line 267: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 <pre style="border: 0; padding-bottom:0px;">function SPIDeviceWriteRead(SPI:PSPIDevice; ChipSelect:Word; Source,Dest:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</pre>
-<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Write data to and Read data ?rom the specified SPI device in one operation</div>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Write data to and Read data from the specified SPI device in one operation</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
 ! '''SPI'''
-| The SPI device to write to and read ?rom
+| The SPI device to write to and read from
 |-
 ! '''ChipSelect'''
-| The chip select for the slave to write to and read ?rom (eg SPI_CS_0)
+| The chip select for the slave to write to and read from (eg SPI_CS_0)
 |-
 ! '''Source'''
@@ Line 308: / Line 308: @@
 |-
 ! '''SPI'''
-| The SPI device to get device mode ?rom
+| The SPI device to get device mode from
 |-
 ! '''Return'''
@@ Line 341: / Line 341: @@
 |-
 ! '''SPI'''
-| The SPI device to get clock rate ?rom
+| The SPI device to get clock rate from
 |-
 ! '''ChipSelect'''
-| The chip select number to get clock rate ?rom (SPI_CS_NONE for default)
+| The chip select number to get clock rate from (SPI_CS_NONE for default)
 |-
 ! '''Return'''
@@ Line 380: / Line 380: @@
 |-
 ! '''SPI'''
-| The SPI device to get clock phase ?rom
+| The SPI device to get clock phase from
 |-
 ! '''Return'''
@@ Line 413: / Line 413: @@
 |-
 ! '''SPI'''
-| The SPI device to get clock polarity ?rom
+| The SPI device to get clock polarity from
 |-
 ! '''Return'''
@@ Line 446: / Line 446: @@
 |-
 ! '''SPI'''
-| The SPI device to get chip select polarity ?rom
+| The SPI device to get chip select polarity from
 |-
 ! '''ChipSelect'''
-| The chip select number to get polarity ?rom (SPI_CS_NONE for default)
+| The chip select number to get polarity from (SPI_CS_NONE for default)
 |-
 ! '''Return'''
@@ Line 485: / Line 485: @@
 |-
 ! '''SPI'''
-| The SPI device to get properties ?rom
+| The SPI device to get properties from
 |-
 ! '''Properties'''
@@ Line 549: / Line 549: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 <pre style="border: 0; padding-bottom:0px;">function SPIDeviceDeregister(SPI:PSPIDevice):LongWord;</pre>
-<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Deregister a SPI ?rom the SPI table</div>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Deregister a SPI from the SPI table</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"
@@ Line 672: / Line 672: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 <pre style="border: 0; padding-bottom:0px;">function SysSPIRead(ChipSelect:Word; Dest:Pointer; Size:LongWord; var Count:LongWord):LongWord;</pre>
-<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Read data ?rom the default SPI device</div>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Read data from the default SPI device</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
 ! '''ChipSet'''
-| The chip select for the slave to read ?rom (eg SPI_CS_0)
+| The chip select for the slave to read from (eg SPI_CS_0)
 |-
 ! '''Dest'''
@@ Line 726: / Line 726: @@
 <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 <pre style="border: 0; padding-bottom:0px;">function SysSPIWriteRead(ChipSelect:Word; Source,Dest:Pointer; Size:LongWord; var Count:LongWord):LongWord;</pre>
-<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Write data to and Read data ?rom the default SPI device in one operation</div>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Write data to and Read data from the default SPI device in one operation</div>
 <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 {| class="wikitable" style="font-size: 14px; background: white;"
 |-
 ! '''ChipSet'''
-| The chip select for the slave to write to and read ?rom (eg SPI_CS_0)
+| The chip select for the slave to write to and read from (eg SPI_CS_0)
 |-
 ! '''Source'''
@@ Line 788: / Line 788: @@
 |-
 ! '''ChipSelect'''
-| The chip select number to get clock rate ?rom (SPI_CS_NONE for default)
+| The chip select number to get clock rate from (SPI_CS_NONE for default)
 |-
 ! '''Return'''
@@ Line 875: / Line 875: @@
 |-
 ! '''ChipSet'''
-| The chip select number to get polarity ?rom (SPI_CS_NONE for default)
+| The chip select number to get polarity from (SPI_CS_NONE for default)
 |-
 ! '''Return'''

Difference between revisions of "Unit SPI"

Revision as of 04:26, 30 November 2016

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools