PropWare  3.0.0.224
C++ objects and CMake build system for Parallax Propeller
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
PropWare::SPI Class Reference

SPI serial communications library; Core functionality comes from a dedicated assembly cog. More...

#include <PropWare/serial/spi/spi.h>

+ Inheritance diagram for PropWare::SPI:
+ Collaboration diagram for PropWare::SPI:

Public Types

enum  Mode {
  Mode::MODE_0,
  Mode::MODE_1,
  Mode::MODE_2,
  Mode::MODE_3
}
 Descriptor for SPI signal as defined by Motorola modes. More...
 
enum  BitMode {
  LSB_FIRST,
  MSB_FIRST
}
 Determine if data is communicated with the LSB or MSB sent/received first. More...
 
enum  ErrorCode {
  NO_ERROR = 0,
  BEG_ERROR = 1,
  INVALID_FREQ = BEG_ERROR,
  END_ERROR = INVALID_FREQ
}
 

Public Member Functions

 SPI (const Pin::Mask mosi=Pin::Mask::NULL_PIN, const Pin::Mask miso=Pin::Mask::NULL_PIN, const Pin::Mask sclk=Pin::Mask::NULL_PIN, const uint32_t frequency=DEFAULT_FREQUENCY, const Mode mode=Mode::MODE_0, const BitMode bitmode=BitMode::MSB_FIRST)
 Construct an SPI bus on the given pins with the given settings. More...
 
 ~SPI ()
 Release the pins to floating inputs.
 
void set_mosi (const Port::Mask mask)
 Release the current MOSI pin as a floating input and set the new one as output.
 
void set_miso (const Port::Mask mask)
 Set the new pin as input.
 
void set_sclk (const Port::Mask mask)
 Release the current SCLK pin as a floating input and set the new one as output.
 
void set_mode (const Mode mode)
 Set the mode of SPI communication. More...
 
void set_bit_mode (const BitMode bitmode)
 Set the bitmode of SPI communication. More...
 
PropWare::ErrorCode set_clock (const uint32_t frequency)
 Change the SPI module's clock frequency. More...
 
int32_t get_clock () const
 Retrieve the SPI module's clock frequency. More...
 
void shift_out (uint8_t bits, uint32_t value) const
 Send a value out to a peripheral device. More...
 
uint32_t shift_in (const unsigned int bits) const
 Read a value from the MISO line. More...
 
void shift_out_block_msb_first_fast (const uint8_t buffer[], size_t numberOfBytes) const
 Send an array of data at max transmit speed. Mode is always MODE_0 and data is always MSB first. More...
 
void shift_in_block_mode0_msb_first_fast (const uint8_t *buffer, size_t numberOfBytes) const
 Receive an array of data at max transmit speed. Mode is always MODE_0 and data is always MSB first. More...
 
virtual void put_char (const char c)
 Print a single character. More...
 
virtual void puts (const char string[])
 Send a null-terminated character array. Though this method could be created using put_char, some objects (such as PropWare::UART), have optimized methods for sending a string and PrintCapable::puts can utilize them. More...
 
virtual char get_char ()
 Read and return a single character. Whether the method is blocking or not depends entirely on the implementation.
 
void print_error_str (const Printer &printer, const ErrorCode err) const
 Print an error string through the provided PropWare::Printer interface. More...
 

Static Public Member Functions

static SPIget_instance ()
 Best way to access an SPI instance is through here, where you can get a shared instance of the SPI module (not thread safe) More...
 

Static Public Attributes

static const int32_t DEFAULT_FREQUENCY = 100000
 

Detailed Description

SPI serial communications library; Core functionality comes from a dedicated assembly cog.

Generally, multiple instances of the SPI class are not desired. To avoid the programmer from accidentally creating multiple instances, this class is set up as a singleton. A static instance can be retrieved with get_instance(). If multiple instances of PropWare::SPI are desired, the PropWare library (and your project) should be built from source with PROPWARE_NO_SAFE_SPI defined

Examples
ADXL345_Demo.cpp, L3G_Demo.cpp, MAX6675_Demo.cpp, MAX72xx_Demo.cpp, MCP2515_Demo.cpp, MCP3xxx_Demo.cpp, and SPI_Demo.cpp.

Definition at line 43 of file spi.h.

Member Enumeration Documentation

◆ BitMode

Determine if data is communicated with the LSB or MSB sent/received first.

Note
Initial value is SPI_MODES + 1 making them easily distinguishable

Definition at line 78 of file spi.h.

◆ ErrorCode

Error codes - Proceeded by nothing

Enumerator
NO_ERROR 

No error

BEG_ERROR 

First SPI error

INVALID_FREQ 

SPI Error 1

END_ERROR 

Last SPI error code

Definition at line 86 of file spi.h.

◆ Mode

enum PropWare::SPI::Mode
strong

Descriptor for SPI signal as defined by Motorola modes.

These modes control whether data is shifted in and out on the rising or falling edge of the data clock signal (called the clock phase), and whether the clock is idle when high or low (called the clock polarity). CPOL 0 refers to a low polarity (where the clock idles in the low state) and CPOL 1 is for high polarity. CPHA 0 refers to falling edge clock phase and CPHA 1 refers to rising edge.

SPI ModeCPOLCPHA
000
101
210
311
Enumerator
MODE_0 

Mode 0

MODE_1 

Mode 1

MODE_2 

Mode 2

MODE_3 

Mode 3

Definition at line 66 of file spi.h.

Constructor & Destructor Documentation

◆ SPI()

PropWare::SPI::SPI ( const Pin::Mask  mosi = Pin::Mask::NULL_PIN,
const Pin::Mask  miso = Pin::Mask::NULL_PIN,
const Pin::Mask  sclk = Pin::Mask::NULL_PIN,
const uint32_t  frequency = DEFAULT_FREQUENCY,
const Mode  mode = Mode::MODE_0,
const BitMode  bitmode = BitMode::MSB_FIRST 
)

Construct an SPI bus on the given pins with the given settings.

Parameters
[in]mosiPin mask for MOSI
[in]misoPin mask for MISO
[in]sclkPin mask for SCLK
[in]frequencyFrequency to run the bus, in hertz
[in]modeDetermines clock phase and polarity
[in]bitmodeDetermine if the MSB or LSB should be clocked out first

Definition at line 119 of file spi.h.

+ Here is the call graph for this function:

Member Function Documentation

◆ get_clock()

int32_t PropWare::SPI::get_clock ( ) const

Retrieve the SPI module's clock frequency.

Returns
Returns 0 upon success, otherwise error code

Definition at line 208 of file spi.h.

◆ get_instance()

static SPI& PropWare::SPI::get_instance ( )
static

Best way to access an SPI instance is through here, where you can get a shared instance of the SPI module (not thread safe)

Returns
Address of the shared SPI instance

Definition at line 103 of file spi.h.

◆ print_error_str()

void PropWare::SPI::print_error_str ( const Printer printer,
const ErrorCode  err 
) const

Print an error string through the provided PropWare::Printer interface.

Parameters
[in]printerObject used for printing error string
[in]errError number used to determine error string

Definition at line 376 of file spi.h.

◆ put_char()

virtual void PropWare::SPI::put_char ( const char  c)
virtual

Print a single character.

Parameters
[in]cIndividual char to be printed

Implements PropWare::PrintCapable.

Definition at line 355 of file spi.h.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ puts()

virtual void PropWare::SPI::puts ( const char  string[])
virtual

Send a null-terminated character array. Though this method could be created using put_char, some objects (such as PropWare::UART), have optimized methods for sending a string and PrintCapable::puts can utilize them.

Precondition
string[] must be terminated with a null terminator
Parameters
[in]string[]Array of data words with the final word being 0 - the null terminator

Implements PropWare::PrintCapable.

Definition at line 359 of file spi.h.

+ Here is the call graph for this function:

◆ set_bit_mode()

void PropWare::SPI::set_bit_mode ( const BitMode  bitmode)

Set the bitmode of SPI communication.

Parameters
[in]bitmodeSelect one of LSB_FIRST or MSB_FIRST to choose which bit will be shifted out first

Definition at line 181 of file spi.h.

+ Here is the caller graph for this function:

◆ set_clock()

PropWare::ErrorCode PropWare::SPI::set_clock ( const uint32_t  frequency)

Change the SPI module's clock frequency.

Parameters
[in]frequencyFrequency, in Hz, to run the SPI clock; Must be less than CLKFREQ/20 (for 80 MHz, 900 kHz is the fastest I've tested successfully)
Returns
Returns 0 upon success, otherwise error code

Definition at line 193 of file spi.h.

+ Here is the caller graph for this function:

◆ set_mode()

void PropWare::SPI::set_mode ( const Mode  mode)

Set the mode of SPI communication.

Parameters
[in]modeSets the SPI mode to one MODE_0, MODE_1, MODE_2, or MODE_3

Definition at line 166 of file spi.h.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ shift_in()

uint32_t PropWare::SPI::shift_in ( const unsigned int  bits) const

Read a value from the MISO line.

Parameters
[in]bitsNumber of bits to read
Returns
Value from the data bus

Definition at line 242 of file spi.h.

+ Here is the caller graph for this function:

◆ shift_in_block_mode0_msb_first_fast()

void PropWare::SPI::shift_in_block_mode0_msb_first_fast ( const uint8_t *  buffer,
size_t  numberOfBytes 
) const

Receive an array of data at max transmit speed. Mode is always MODE_0 and data is always MSB first.

Parameters
[out]bufferAddress to store data
[in]numberOfBytesNumber of bytes to receive

Definition at line 317 of file spi.h.

◆ shift_out()

void PropWare::SPI::shift_out ( uint8_t  bits,
uint32_t  value 
) const

Send a value out to a peripheral device.

Pass a value and mode into the assembly cog to be sent to the peripheral; NOTE: this function is non-blocking and chip-select should not be set inactive immediately after the return (you should call spi_wait() before setting chip-select inactive)

Parameters
[in]bitsNumber of bits to be shifted out
[in]valueThe value to be shifted out
Returns
Returns 0 upon success, otherwise error code

Definition at line 224 of file spi.h.

+ Here is the caller graph for this function:

◆ shift_out_block_msb_first_fast()

void PropWare::SPI::shift_out_block_msb_first_fast ( const uint8_t  buffer[],
size_t  numberOfBytes 
) const

Send an array of data at max transmit speed. Mode is always MODE_0 and data is always MSB first.

Clock will run at 4 MHz with a sustained 3.33 Mbps average bitrate over multiple bytes.

Parameters
[in]buffer[]Address where data is stored
[in]numberOfBytesNumber of words to send

Definition at line 270 of file spi.h.


The documentation for this class was generated from the following file: