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 SPI &	get_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

enum PropWare::SPI::BitMode

strong

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

enum PropWare::SPI::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 Mode	CPOL	CPHA
0	0	0
1	0	1
2	1	0
3	1	1

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]	mosi	Pin mask for MOSI
[in]	miso	Pin mask for MISO
[in]	sclk	Pin mask for SCLK
[in]	frequency	Frequency to run the bus, in hertz
[in]	mode	Determines clock phase and polarity
[in]	bitmode	Determine 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]	printer	Object used for printing error string
[in]	err	Error 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] c Individual 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] bitmode Select 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] frequency Frequency, 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] mode Sets 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] bits Number 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]	buffer	Address to store data
[in]	numberOfBytes	Number 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]	bits	Number of bits to be shifted out
[in]	value	The 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]	numberOfBytes	Number of words to send

Definition at line 270 of file spi.h.

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

PropWare/serial/spi/spi.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ BitMode

◆ ErrorCode

◆ Mode

Constructor & Destructor Documentation

◆ SPI()

Member Function Documentation

◆ get_clock()

◆ get_instance()

◆ print_error_str()

◆ put_char()

◆ puts()

◆ set_bit_mode()

◆ set_clock()

◆ set_mode()

◆ shift_in()

◆ shift_in_block_mode0_msb_first_fast()

◆ shift_out()

◆ shift_out_block_msb_first_fast()