Unit SPI

From Ultibo.org
Revision as of 01:37, 7 October 2016 by Ultibo (Talk | contribs)

Jump to: navigation, search

Return to Unit Reference


Description


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


To be documented

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 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 SPIDeviceGetMode(SPI:PSPIDevice):LongWord;
Description: Get the device mode of the specified SPI device
SPI The SPI device to get device mode ?rom
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 ?rom
ChipSelect The chip select number to get clock rate ?rom (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 ?rom
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 ?rom
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 ?rom
ChipSelect The chip select number to get polarity ?rom (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 ?rom
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 ?rom 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 ?rom the default SPI device
ChipSet The chip select for the slave to read ?rom (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 ?rom the default SPI device in one operation
ChipSet The chip select for the slave to write to and read ?rom (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 ?rom (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 ?rom (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