Abstract base class for SPI device implementations. More...

#include <BaseSpi.h>

Inheritance diagram for BaseSpi:

Collaboration diagram for BaseSpi:

Public Member Functions
virtual	~BaseSpi () noexcept=default
	Virtual destructor ensures proper cleanup in derived classes.

	BaseSpi (const BaseSpi &)=delete

BaseSpi &	operator= (const BaseSpi &)=delete

	BaseSpi (BaseSpi &&)=delete

BaseSpi &	operator= (BaseSpi &&)=delete

bool	EnsureInitialized () noexcept
	Ensures that the SPI bus is initialized (lazy initialization).

bool	EnsureDeinitialized () noexcept
	Ensures that the SPI bus is deinitialized (lazy deinitialization).

bool	IsInitialized () const noexcept
	Checks if the bus is initialized.

virtual bool	Initialize () noexcept=0
	Initialize the SPI bus.

virtual bool	Deinitialize () noexcept=0
	Deinitialize the SPI bus.

virtual hf_spi_err_t	Transfer (const hf_u8_t tx_data, hf_u8_t rx_data, hf_u16_t length, hf_u32_t timeout_ms=0) noexcept=0
	Perform a full-duplex SPI transfer.

virtual void	IdleChipSelect () noexcept
	Force soft-CS to the idle (deasserted) level without a transfer.

virtual void	HoldChipSelectMs (hf_u32_t) noexcept
	Assert soft-CS for `ms` milliseconds (logic-analyzer / pad proof).

virtual bool	SetTransferMode (hf_u8_t) noexcept
	Select CPOL/CPHA mode for the next soft-CS transfer (0..3).

virtual bool	SetIoSwap (bool) noexcept
	Swap MOSI↔MISO AF on the next transfer (STM32 SPI CFG2 IOSWP).

virtual hf_spi_err_t	TransferChain (const hf_u8_t const tx_frames, hf_u8_t const rx_frames, hf_u16_t frame_length, hf_u16_t frame_count, hf_u32_t inter_frame_gap_us, hf_u32_t timeout_ms=0) noexcept
	Run `frame_count` soft-CS frames in one ownership window.

virtual const void *	GetDeviceConfig () const noexcept=0
	Get the device configuration for this SPI device.

virtual bool	Open () noexcept
	Legacy compatibility: Open and initialize the SPI bus.

virtual bool	Close () noexcept
	Legacy compatibility: Close and de-initialize the SPI bus.

virtual bool	Transfer (const hf_u8_t tx_data, hf_u8_t rx_data, hf_u16_t length) noexcept
	Legacy compatibility: Transfer with boolean return.

virtual hf_spi_err_t	Write (const hf_u8_t *data, hf_u16_t length, hf_u32_t timeout_ms=0) noexcept
	Write data to SPI bus.

virtual hf_spi_err_t	Read (hf_u8_t *data, hf_u16_t length, hf_u32_t timeout_ms=0) noexcept
	Read data from SPI bus.

virtual bool	Write (const hf_u8_t *data, hf_u16_t length) noexcept
	Legacy compatibility: Write with boolean return.

virtual bool	Read (hf_u8_t *data, hf_u16_t length) noexcept
	Legacy compatibility: Read with boolean return.

virtual bool	WriteByte (hf_u8_t data) noexcept
	Write single byte to SPI bus.

virtual bool	ReadByte (hf_u8_t &data) noexcept
	Read single byte from SPI bus.

virtual bool	TransferByte (hf_u8_t tx_data, hf_u8_t &rx_data) noexcept
	Write single byte and read response.

virtual hf_spi_err_t	ResetStatistics () noexcept
	Reset SPI operation statistics.

virtual hf_spi_err_t	ResetDiagnostics () noexcept
	Reset SPI diagnostic information.

virtual hf_spi_err_t	GetStatistics (hf_spi_statistics_t &statistics) const noexcept
	Get SPI operation statistics.

virtual hf_spi_err_t	GetDiagnostics (hf_spi_diagnostics_t &diagnostics) const noexcept
	Get SPI diagnostic information.

Protected Member Functions
	BaseSpi () noexcept
	Protected default constructor.

Protected Attributes
bool	initialized_
	Initialization state.

hf_spi_statistics_t	statistics_
	SPI operation statistics.

hf_spi_diagnostics_t	diagnostics_
	SPI diagnostic information.

Detailed Description

Abstract base class for SPI device implementations.

This class provides a comprehensive SPI device abstraction that serves as the base for all SPI device implementations in the HardFOC system. Each instance represents a single SPI device with pre-configured settings. It supports:

Master mode SPI communication
Configurable SPI modes (0-3)
Full-duplex, write-only, and read-only transfers
Configurable clock speeds and timing
Automatic chip select management
Configurable word sizes
Comprehensive error handling
Lazy initialization pattern

Device configuration (mode, speed, CS pin) is set during device creation and managed automatically, ensuring each device operates with its correct settings without manual configuration per transaction.

Derived classes implement platform-specific details such as:

On-chip SPI controllers with device handles
SPI bridge or adapter hardware
Device-specific configurations

Note: This is a header-only abstract base class - instantiate concrete implementations instead.; This class is not inherently thread-safe. Use appropriate synchronization if accessed from multiple contexts.; Each BaseSpi instance represents a specific SPI device, not the SPI bus itself.

Constructor & Destructor Documentation

◆ ~BaseSpi()

virtual BaseSpi::~BaseSpi ( )

virtualdefaultnoexcept

Virtual destructor ensures proper cleanup in derived classes.

◆ BaseSpi() [1/3]

BaseSpi::BaseSpi ( const BaseSpi & )

delete

◆ BaseSpi() [2/3]

BaseSpi::BaseSpi ( BaseSpi && )

delete

◆ BaseSpi() [3/3]

BaseSpi::BaseSpi ( )

inlineprotectednoexcept

Protected default constructor.

Note: Configurations are handled by derived classes

Member Function Documentation

◆ Close()

virtual bool BaseSpi::Close ( )

inlinevirtualnoexcept

Legacy compatibility: Close and de-initialize the SPI bus.

Returns: true if closed, false otherwise.

◆ Deinitialize()

virtual bool BaseSpi::Deinitialize ( )

pure virtualnoexcept

Deinitialize the SPI bus.

Returns: true if successful, false otherwise

Note: Must be implemented by concrete classes.

Implemented in EspSpiDevice, and StmSpiDevice.

◆ EnsureDeinitialized()

bool BaseSpi::EnsureDeinitialized ( )

inlinenoexcept

Ensures that the SPI bus is deinitialized (lazy deinitialization).

Returns: true if the SPI bus is deinitialized, false otherwise.

◆ EnsureInitialized()

bool BaseSpi::EnsureInitialized ( )

inlinenoexcept

Ensures that the SPI bus is initialized (lazy initialization).

Returns: true if the SPI bus is initialized, false otherwise.

◆ GetDeviceConfig()

virtual const void * BaseSpi::GetDeviceConfig ( ) const

pure virtualnoexcept

Get the device configuration for this SPI device.

Returns: Device-specific configuration information

Implemented in EspSpiDevice, and StmSpiDevice.

◆ GetDiagnostics()

virtual hf_spi_err_t BaseSpi::GetDiagnostics ( hf_spi_diagnostics_t & diagnostics ) const

inlinevirtualnoexcept

Get SPI diagnostic information.

Parameters

diagnostics Reference to store diagnostics data

Returns: hf_spi_err_t::SPI_SUCCESS if successful, SPI_ERR_NOT_SUPPORTED if not implemented

◆ GetStatistics()

virtual hf_spi_err_t BaseSpi::GetStatistics ( hf_spi_statistics_t & statistics ) const

inlinevirtualnoexcept

Get SPI operation statistics.

Parameters

statistics Reference to store statistics data

Returns: hf_spi_err_t::SPI_SUCCESS if successful, SPI_ERR_NOT_SUPPORTED if not implemented

◆ HoldChipSelectMs()

virtual void BaseSpi::HoldChipSelectMs ( hf_u32_t )

inlinevirtualnoexcept

Assert soft-CS for ms milliseconds (logic-analyzer / pad proof).

Shared-bus implementations should take the bus lock, idle peer CS lines, hold this CS active, then release. Default: no-op.

Reimplemented in StmSpiDevice.

◆ IdleChipSelect()

virtual void BaseSpi::IdleChipSelect ( )

inlinevirtualnoexcept

Force soft-CS to the idle (deasserted) level without a transfer.

Shared multi-slave buses call this on peer devices before a mode-sensitive identity burst so a stuck-low CS cannot contend on MISO. Default: no-op (hardware-NSS / single-slave backends).

Reimplemented in StmSpiDevice.

◆ Initialize()

virtual bool BaseSpi::Initialize ( )

pure virtualnoexcept

Initialize the SPI bus.

Returns: true if successful, false otherwise

Note: Must be implemented by concrete classes.

Implemented in EspSpiDevice, and StmSpiDevice.

◆ IsInitialized()

bool BaseSpi::IsInitialized ( ) const

inlinenoexcept

Checks if the bus is initialized.

Returns: true if initialized, false otherwise

◆ Open()

virtual bool BaseSpi::Open ( )

inlinevirtualnoexcept

Legacy compatibility: Open and initialize the SPI bus.

Returns: true if open, false otherwise.

◆ operator=() [1/2]

BaseSpi & BaseSpi::operator= ( BaseSpi && )

delete

◆ operator=() [2/2]

BaseSpi & BaseSpi::operator= ( const BaseSpi & )

delete

◆ Read() [1/2]

virtual bool BaseSpi::Read	(	hf_u8_t *	data,
		hf_u16_t	length
	)

inlinevirtualnoexcept

Legacy compatibility: Read with boolean return.

Parameters

data	Buffer to store received data
length	Number of bytes to read

Returns: true if read succeeded

◆ Read() [2/2]

virtual hf_spi_err_t BaseSpi::Read	(	hf_u8_t *	data,
		hf_u16_t	length,
		hf_u32_t	timeout_ms = `0`
	)

inlinevirtualnoexcept

Read data from SPI bus.

Parameters

data	Buffer to store received data
length	Number of bytes to read
timeout_ms	Timeout in milliseconds (0 = use default)

Returns: hf_spi_err_t result code

◆ ReadByte()

virtual bool BaseSpi::ReadByte ( hf_u8_t & data )

inlinevirtualnoexcept

Read single byte from SPI bus.

Parameters

data	Output: byte read

Returns: true if successful, false otherwise

◆ ResetDiagnostics()

virtual hf_spi_err_t BaseSpi::ResetDiagnostics ( )

inlinevirtualnoexcept

Reset SPI diagnostic information.

Returns: hf_spi_err_t::SPI_SUCCESS if successful, error code otherwise

Note: Override this method to provide platform-specific diagnostics reset

◆ ResetStatistics()

virtual hf_spi_err_t BaseSpi::ResetStatistics ( )

inlinevirtualnoexcept

Reset SPI operation statistics.

Returns: hf_spi_err_t::SPI_SUCCESS if successful, error code otherwise

Note: Override this method to provide platform-specific statistics reset

◆ SetIoSwap()

virtual bool BaseSpi::SetIoSwap ( bool )

inlinevirtualnoexcept

Swap MOSI↔MISO AF on the next transfer (STM32 SPI CFG2 IOSWP).

Useful when SDI/SDO leads may be crossed on long wiring. Default: unsupported. Callers must restore false after a failed identity sweep so Mode0 peers keep the normal pin map.

Reimplemented in StmSpiDevice.

◆ SetTransferMode()

virtual bool BaseSpi::SetTransferMode ( hf_u8_t )

inlinevirtualnoexcept

Select CPOL/CPHA mode for the next soft-CS transfer (0..3).

Shared multi-slave buses apply this on the next Transfer via SPE rewrite. Default: unsupported.

Reimplemented in StmSpiDevice.

◆ Transfer() [1/2]

virtual bool BaseSpi::Transfer	(	const hf_u8_t *	tx_data,
		hf_u8_t *	rx_data,
		hf_u16_t	length
	)

inlinevirtualnoexcept

Legacy compatibility: Transfer with boolean return.

Parameters

tx_data	Transmit data buffer
rx_data	Receive data buffer
length	Number of bytes to transfer

Returns: true if transfer succeeded

◆ Transfer() [2/2]

virtual hf_spi_err_t BaseSpi::Transfer	(	const hf_u8_t *	tx_data,
		hf_u8_t *	rx_data,
		hf_u16_t	length,
		hf_u32_t	timeout_ms = `0`
	)

pure virtualnoexcept

Perform a full-duplex SPI transfer.

Parameters

tx_data	Transmit data buffer (can be nullptr for read-only)
rx_data	Receive data buffer (can be nullptr for write-only)
length	Number of bytes to transfer
timeout_ms	Timeout in milliseconds (0 = use default)

Returns: hf_spi_err_t result code

Note: Must be implemented by concrete classes.; Chip select is managed automatically by the device implementation.

Implemented in EspSpiDevice, and StmSpiDevice.

◆ TransferByte()

virtual bool BaseSpi::TransferByte	(	hf_u8_t	tx_data,
		hf_u8_t &	rx_data
	)

inlinevirtualnoexcept

Write single byte and read response.

Parameters

tx_data	Byte to write
rx_data	Output: byte read

Returns: true if successful, false otherwise

◆ TransferChain()

virtual hf_spi_err_t BaseSpi::TransferChain	(	const hf_u8_t const	tx_frames,
		hf_u8_t const	rx_frames,
		hf_u16_t	frame_length,
		hf_u16_t	frame_count,
		hf_u32_t	inter_frame_gap_us,
		hf_u32_t	timeout_ms = `0`
	)

inlinevirtualnoexcept

Run frame_count soft-CS frames in one ownership window.

Each frame asserts CS, transfers frame_length bytes, then deasserts CS. Optional inter_frame_gap_us is applied between frames (after CS release).

Default implementation calls Transfer sequentially (each call may take/release the bus lock). Shared multi-slave buses should override so a pipelined protocol (e.g. TLE92466ED command + dummy read) cannot be interleaved with another device's mode/CS cycle.

Reimplemented in StmSpiDevice.

◆ Write() [1/2]

virtual bool BaseSpi::Write	(	const hf_u8_t *	data,
		hf_u16_t	length
	)

inlinevirtualnoexcept

Legacy compatibility: Write with boolean return.

Parameters

data	Data buffer to transmit
length	Number of bytes to write

Returns: true if write succeeded

◆ Write() [2/2]

virtual hf_spi_err_t BaseSpi::Write	(	const hf_u8_t *	data,
		hf_u16_t	length,
		hf_u32_t	timeout_ms = `0`
	)

inlinevirtualnoexcept

Write data to SPI bus.

Parameters

data	Data buffer to transmit
length	Number of bytes to write
timeout_ms	Timeout in milliseconds (0 = use default)

Returns: hf_spi_err_t result code

◆ WriteByte()

virtual bool BaseSpi::WriteByte ( hf_u8_t data )

inlinevirtualnoexcept

Write single byte to SPI bus.

Parameters

data	Byte to write

Returns: true if successful, false otherwise

Member Data Documentation

◆ diagnostics_

hf_spi_diagnostics_t BaseSpi::diagnostics_

protected

SPI diagnostic information.

◆ initialized_

bool BaseSpi::initialized_

protected

Initialization state.

◆ statistics_

hf_spi_statistics_t BaseSpi::statistics_

protected

SPI operation statistics.

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

inc/base/BaseSpi.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~BaseSpi()

◆ BaseSpi() [1/3]

◆ BaseSpi() [2/3]

◆ BaseSpi() [3/3]

Member Function Documentation

◆ Close()

◆ Deinitialize()

◆ EnsureDeinitialized()

◆ EnsureInitialized()

◆ GetDeviceConfig()

◆ GetDiagnostics()

◆ GetStatistics()

◆ HoldChipSelectMs()

◆ IdleChipSelect()

◆ Initialize()

◆ IsInitialized()

◆ Open()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadByte()

◆ ResetDiagnostics()

◆ ResetStatistics()

◆ SetIoSwap()

◆ SetTransferMode()

◆ Transfer() [1/2]

◆ Transfer() [2/2]

◆ TransferByte()

◆ TransferChain()

◆ Write() [1/2]

◆ Write() [2/2]

◆ WriteByte()

Member Data Documentation

◆ diagnostics_

◆ initialized_

◆ statistics_