This class provides the SPI master interface definition. More...

#include <spi.hpp>

Inheritance diagram for embvm::spi::master:

Public Member Functions
virtual void	configure (spi::baud_t baud) noexcept
	Configure the SPI bus. More...

spi::mode	mode () const noexcept
	Get the current SPI bus mode. More...

spi::mode	mode (spi::mode mode) noexcept
	Set the SPI bus mode. More...

spi::order	order () const noexcept
	Get the current SPI bus byte order. More...

spi::order	order (spi::order order) noexcept
	Set the SPI bus byte order. More...

void	start () noexcept
	Start the driver. More...

void	stop () noexcept
	Stop the driver. More...

void	restart () noexcept
	Restart the driver. More...

type_safe::boolean	started () const noexcept
	Check if the driver has been started. More...

constexpr embvm::DriverType_t	DriverType () const noexcept
	Returns the registered type ID of the driver. More...

constexpr const std::string_view &	name () const noexcept
	Provides a string_view reference of the driver name. More...

constexpr const char *	name_cstr () const noexcept
	Provides a c-string version of the driver name. More...

virtual DriverBase &	operator++ () noexcept
	Increment operator is a no-op, but is used for iterator compatibility. More...

Static Public Member Functions
static constexpr embvm::DriverType	type () noexcept
	SPI Driver Type ID. More...

Protected Member Functions
	master (const spi::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Default constructor. More...

	master (const char *name, const spi::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct a SPI master with a C-string name. More...

	master (const std::string &name, const spi::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct a SPI master with a std::string name. More...

	master (const std::string_view &name, const spi::commBus::DispatcherFunc &dispatcher=nullptr) noexcept
	Construct a SPI master with a std::string_view name. More...

	~master () noexcept override
	Default destructor. More...

virtual void	setMode_ (spi::mode mode) noexcept=0
	Set the SPI bus mode. More...

virtual void	setOrder_ (spi::order order) noexcept=0
	Set the SPI bus byte order. More...

virtual void	configure_ () noexcept=0
	Configure the SPI bus for operation. More...

void	start_ () noexcept override=0
	Derived classes override the start_ method to control driver-specific startup behavior. More...

void	stop_ () noexcept override=0
	Derived classes override the start_ method to control driver-specific startup behavior. More...

spi::baud_t	baudrate_ (spi::baud_t baud) noexcept override=0

embvm::comm::status	transfer_ (const spi::op_t &op, const cb_t &cb) noexcept override=0

Protected Attributes
spi::mode	mode_ = spi::mode::mode0
	Stores the active SPI mode configuration. More...

spi::order	order_ = spi::order::msbFirst
	Stores the active SPI byte ordering. More...

type_safe::boolean	started_ = false
	Tracks the driver state. More...

const std::string_view	name_
	Name of the driver instance. More...

const embvm::DriverType_t	type_
	Type ID of the driver instance. More...

Detailed Description

This class provides the SPI master interface definition.

This class defines common interfaces and types for SPI master devices.

Implementing a spi::master Driver

To implement your own SPI master device, simply inherit from this class type:

class aardvarkSPIMaster final : public spi::master

{...}

Derived classes must imlement the following pure virtual functions to complete SPI master behavior:

setOrder_(), to set byte ordering
setMode_(), to set bus mode
configure_(), to configure the target hardware for operation

Derived classes must also implement pure virtual functions required by the comm bus, such as:

transfer_(), which initiates a bus transfer
baudrate_(), which configures the baudrate

Using a spi::master Driver

spi::master usage follows this general pattern:

Declare a spi::master device
Configure the device
Initialize a transfer

Declare a spi::master device

Derived classes will have their own specific constructor schemes. In all cases you will use a derived class for the declaration.

aardvarkAdapter aardvark{aardvarkMode::SPI};

aardvarkSPIMaster d{aardvark, "spi0"};

Configure a spi::master device

After the device has been declared, the object can be used to configure the SPI bus. Initial configuration will happen with the configure() function, which sets up the SPI device with the target baudrate.

The mode() function is used to change the SPI bus mode (spi::mode). The order() function can be used to change the order bytes are sent over the bus (spi::order).

Initialize a Transfer

All transfers require an op structure instance with the proper settings:

uint8_t input[2] = {0xAA, 0xBB};
uint8_t output[2];
spi::op_t op = {input, output, 2};

You should also prepare a callback function to handle the transfer completion:

void spi_callback(spi::op_t input, embvm::comm::status status)
{
...
}

To initiate a transfer, call transfer() with the op and callback:

auto err = d.transfer(op, spi_callback);

When the transfer completes, the callback function will be called with a copy of the op struct and the result of the transfer.

Using with a Dispatch Queue

commBus devices support dispatching callbacks. You can construct a spi::master instance with a dispatcher function:

embutil::DynamicDispatchQueue<> dispatch;

spi0(dispatch.getBoundDispatch());

If a dispatcher has been configured, callbacks will be invoked on the dispatch thread instead of the spi::master's local thread. We recommend using dispatchers when possible for improved responsiveness.

Constructor & Destructor Documentation

◆ master() [1/4]

embvm::spi::master::master ( const spi::commBus::DispatcherFunc & dispatcher = nullptr )

inlineexplicitprotectednoexcept

Default constructor.

Initializes the spi::master device with a generic name and optional dispatcher.

Parameters

dispatcher The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

spi0(dispatch.getBoundDispatch());

◆ master() [2/4]

embvm::spi::master::master	(	const char *	name,
		const spi::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct a SPI master with a C-string name.

Initializes the spi::master instance with a name and optional dispatcher.

Parameters

name	C-string name for the SPI master instance.
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

spi0("spi0", dispatch.getBoundDispatch());

◆ master() [3/4]

embvm::spi::master::master	(	const std::string &	name,
		const spi::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct a SPI master with a std::string name.

Initializes the spi::master instance with a name and optional dispatcher.

Parameters

name	std::string name for the SPI master instance. Note: spi::master() uses a std::string_view, so the std::string must remain valid
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

spi0("spi0", dispatch.getBoundDispatch());

◆ master() [4/4]

embvm::spi::master::master	(	const std::string_view &	name,
		const spi::commBus::DispatcherFunc &	dispatcher = `nullptr`
	)

inlineexplicitprotectednoexcept

Construct a SPI master with a std::string_view name.

Initializes the spi::master instance with a name and optional dispatcher.

Parameters

name	std::string_view name for the SPI master instance. Note: spi::master() uses a std::string_view, so the original string must remain valid
dispatcher	The functor which callbacks will be dispatched to. This will often be paired with a dispatch queue. Example:

embutil::DynamicDispatchQueue<> dispatch;

spi0("spi0", dispatch.getBoundDispatch());

◆ ~master()

embvm::spi::master::~master ( )

overrideprotecteddefaultnoexcept

Default destructor.

Member Function Documentation

◆ baudrate_()

spi::baud_t embvm::spi::master::baudrate_ ( spi::baud_t baud )

overrideprotectedpure virtualnoexcept

Implemented in test::spiTestDriver, embvm::spi::activeMaster< TQueueSize, TLock, TCond >, and embdrv::aardvarkSPIMaster.

◆ configure()

virtual void embvm::spi::master::configure ( spi::baud_t baud )

inlinevirtualnoexcept

Configure the SPI bus.

Configures the SPI bus for operation and sets the target baud rate.

Derived classes must implement the configure_() function to set up the target hardware.

Parameters

baud	The target baudrate, in Hz. TODO: Tolerance - allowed relative tolerance for the resulting baudrate

References configure_().

◆ configure_()

virtual void embvm::spi::master::configure_ ( )

protectedpure virtualnoexcept

Configure the SPI bus for operation.

This function is implemented by the derived class. It is responsible for configuring the target hardware for operation.

Implemented in test::spiTestDriver, embdrv::aardvarkSPIMaster, and embvm::spi::activeMaster< TQueueSize, TLock, TCond >.

Referenced by configure().

◆ DriverType()

constexpr embvm::DriverType_t embvm::DriverBase::DriverType ( ) const

inlinenoexceptinherited

Returns the registered type ID of the driver.

When using DriverBase interfaces, clients can retrieve the registered driver type in order to up-cast to the correct interface.

The type is returned as a embvm::DriverType_t rather than a embvm::DriverType enum to work with custom user-defined types. Enforcing a embvm::DriverType return value would prevent clients from defining and using their own custom types.

Returns: the registered driver type as a embvm::DriverType_t value

References embvm::DriverBase::type_.

◆ mode() [1/2]

spi::mode embvm::spi::master::mode ( ) const

inlinenoexcept

Get the current SPI bus mode.

Returns: The currently configured mode.

References mode_.

Referenced by mode(), and embvm::spi::activeMaster< TQueueSize, TLock, TCond >::setMode_().

◆ mode() [2/2]

spi::mode embvm::spi::master::mode ( spi::mode mode )

inlinenoexcept

Set the SPI bus mode.

Derived classes must implement the setMode_() function, which is reponsible for configuring the target hardware.

Parameters

mode	The desired SPI bus mode.

Returns: The new SPI bus mode.

References mode(), mode_, and setMode_().

◆ name()

constexpr const std::string_view& embvm::DriverBase::name ( ) const

inlinenoexceptinherited

Provides a string_view reference of the driver name.

Returns: std::string_view ref containing the driver name.

References embvm::DriverBase::name_.

◆ name_cstr()

constexpr const char* embvm::DriverBase::name_cstr ( ) const

inlinenoexceptinherited

Provides a c-string version of the driver name.

Returns: c-string containing the driver name

References embvm::DriverBase::name_.

◆ operator++()

virtual DriverBase& embvm::DriverBase::operator++ ( )

inlinevirtualnoexceptinherited

Increment operator is a no-op, but is used for iterator compatibility.

◆ order() [1/2]

spi::order embvm::spi::master::order ( ) const

inlinenoexcept

Get the current SPI bus byte order.

Returns: The currently configured byte order.

References order_.

Referenced by order(), and embvm::spi::activeMaster< TQueueSize, TLock, TCond >::setOrder_().

◆ order() [2/2]

spi::order embvm::spi::master::order ( spi::order order )

inlinenoexcept

Set the SPI bus byte order.

Derived classes must implement the setOrder_() function, which is reponsible for configuring the target hardware.

Parameters

order The desired byte ordering.

Returns: The new byte ordering.

References order(), order_, and setOrder_().

◆ restart()

void embvm::DriverBase::restart ( )

inlinenoexceptinherited

Restart the driver.

Calls stop() and then start() on the driver. If the driver is not started, then it will be started after the start() function is invoked.

References embvm::DriverBase::start(), and embvm::DriverBase::stop().

◆ setMode_()

virtual void embvm::spi::master::setMode_ ( spi::mode mode )

protectedpure virtualnoexcept

Set the SPI bus mode.

This function is implemented by the derived class. It is responsible for configuring the target hardware to use the new mode.

Parameters

mode	The desired byte ordering.

Implemented in test::spiTestDriver, embdrv::aardvarkSPIMaster, and embvm::spi::activeMaster< TQueueSize, TLock, TCond >.

Referenced by mode().

◆ setOrder_()

virtual void embvm::spi::master::setOrder_ ( spi::order order )

protectedpure virtualnoexcept

Set the SPI bus byte order.

This function is implemented by the derived class. It is responsible for configuring the target hardware to use the new byte ordering.

Parameters

order The desired byte ordering.

Implemented in test::spiTestDriver, embdrv::aardvarkSPIMaster, and embvm::spi::activeMaster< TQueueSize, TLock, TCond >.

Referenced by order().

◆ start()

void embvm::DriverBase::start ( )

inlinenoexceptinherited

Start the driver.

If the driver is not started, call the start_() function defined by the derived class. (Template Method Pattern)

References embvm::DriverBase::start_(), and embvm::DriverBase::started_.

Referenced by NRF52DongleHWPlatform::init_(), NRF52DKHWPlatform::init_(), BlinkySimulatorHWPlatform::init_(), FWDemoSimulatorHWPlatform::init_(), FrameworkDemoSimPlatform::initHWPlatform_(), embvm::DriverBase::restart(), embvm::timer::Timer::restart(), embvm::spi::activeMaster< TQueueSize, TLock, TCond >::start_(), embvm::i2c::activeMaster< 128 >::start_(), embdrv::aardvarkSPIMaster::start_(), embdrv::aardvarkI2CMaster::start_(), embdrv::aardvarkGPIOInput< 4 >::start_(), embdrv::vl53l1x::start_(), embdrv::aardvarkGPIOOutput< 5 >::start_(), BlinkySimulatorHWPlatform::startBlink(), and FWDemoSimulatorHWPlatform::startLEDTimer().

◆ start_()

void embvm::spi::master::start_ ( )

overrideprotectedpure virtualnoexcept

Derived classes override the start_ method to control driver-specific startup behavior.

(Template Method Pattern)

Implements embvm::DriverBase.

Implemented in test::spiTestDriver, embdrv::aardvarkSPIMaster, and embvm::spi::activeMaster< TQueueSize, TLock, TCond >.

◆ started()

type_safe::boolean embvm::DriverBase::started ( ) const

inlinenoexceptinherited

Check if the driver has been started.

Returns: true if the driver is running (started), false if not running (stopped).

References embvm::DriverBase::started_.

Referenced by embdrv::aardvarkSPIMaster::configure_(), embdrv::aardvarkGPIOInput< 4 >::get(), embdrv::aardvarkGPIOOutput< 5 >::set(), embdrv::vl53l1x::start_(), embdrv::aardvarkAdapter::start_(), and embdrv::aardvarkAdapter::stop_().

◆ stop()

void embvm::DriverBase::stop ( )

inlinenoexceptinherited

Stop the driver.

If the driver has been started, call the stop_() function defined by the derived class. (Template Method Pattern)

References embvm::DriverBase::started_, and embvm::DriverBase::stop_().

Referenced by embvm::DriverBase::restart(), embvm::timer::Timer::restart(), embvm::spi::activeMaster< TQueueSize, TLock, TCond >::stop_(), embvm::i2c::activeMaster< 128 >::stop_(), embdrv::aardvarkSPIMaster::stop_(), embdrv::aardvarkI2CMaster::stop_(), embdrv::aardvarkGPIOInput< 4 >::stop_(), embdrv::aardvarkGPIOOutput< 5 >::stop_(), FWDemoSimulatorHWPlatform::~FWDemoSimulatorHWPlatform(), and embdrv::SimulatorTimer::~SimulatorTimer().

◆ stop_()

void embvm::spi::master::stop_ ( )

overrideprotectedpure virtualnoexcept

Derived classes override the start_ method to control driver-specific startup behavior.

(Template Method Pattern)

Implements embvm::DriverBase.

Implemented in test::spiTestDriver, embdrv::aardvarkSPIMaster, and embvm::spi::activeMaster< TQueueSize, TLock, TCond >.

◆ transfer_()

embvm::comm::status embvm::spi::master::transfer_	(	const spi::op_t &	op,
		const cb_t &	cb
	)

overrideprotectedpure virtualnoexcept

◆ type()

static constexpr embvm::DriverType embvm::spi::master::type ( )

inlinestaticnoexcept

SPI Driver Type ID.

Returns: SPI type ID.

References embvm::SPI.

Member Data Documentation

◆ mode_

spi::mode embvm::spi::master::mode_ = spi::mode::mode0

protected

Stores the active SPI mode configuration.

Referenced by embdrv::aardvarkSPIMaster::configure_(), and mode().

◆ name_

const std::string_view embvm::DriverBase::name_

protectedinherited

Name of the driver instance.

Referenced by embvm::DriverBase::name(), and embvm::DriverBase::name_cstr().

◆ order_

spi::order embvm::spi::master::order_ = spi::order::msbFirst

protected

Stores the active SPI byte ordering.

Referenced by embdrv::aardvarkSPIMaster::configure_(), and order().

◆ started_

type_safe::boolean embvm::DriverBase::started_ = false

protectedinherited

Tracks the driver state.

True if the driver has been started, false if it has been stopped or not yet started.

Referenced by embvm::DriverBase::start(), embvm::DriverBase::started(), and embvm::DriverBase::stop().

◆ type_

const embvm::DriverType_t embvm::DriverBase::type_

protectedinherited

Type ID of the driver instance.

Referenced by embvm::DriverBase::DriverType().

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

src/core/driver/spi.hpp
src/core/driver/internal/spi.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Implementing a spi::master Driver

Using a spi::master Driver

Declare a spi::master device

Configure a spi::master device

Initialize a Transfer

Using with a Dispatch Queue

Constructor & Destructor Documentation

◆ master() [1/4]

◆ master() [2/4]

◆ master() [3/4]

◆ master() [4/4]

◆ ~master()

Member Function Documentation

◆ baudrate_()

◆ configure()

◆ configure_()

◆ DriverType()

◆ mode() [1/2]

◆ mode() [2/2]

◆ name()

◆ name_cstr()

◆ operator++()

◆ order() [1/2]

◆ order() [2/2]

◆ restart()

◆ setMode_()

◆ setOrder_()

◆ start()

◆ start_()

◆ started()

◆ stop()

◆ stop_()

◆ transfer_()

◆ type()

Member Data Documentation

◆ mode_

◆ name_

◆ order_

◆ started_

◆ type_