A synchronous serial implementation using the SPI userspace interface provided by the Linux kernel. More...

#include <SpiMasterSyncSerial.hpp>

Inheritance diagram for duds::hardware::interface::linux::SpiMasterSyncSerial:

Collaboration diagram for duds::hardware::interface::linux::SpiMasterSyncSerial:

Public Member Functions
	SpiMasterSyncSerial ()
	Creates the object without a SPI device to use. More...

	SpiMasterSyncSerial (const std::string &path, Flags flags=MssSpiMode0, int freq=100000)
	Creates the object and attempts to open the SPI device. More...

	SpiMasterSyncSerial (Flags flags)
	Creates the object with SPI mode flags but no SPI device. More...

	~SpiMasterSyncSerial ()

void	open (const std::string &path, Flags flags=MssSpiMode0, int freq=100000)
	Opens the SPI device file and configures it. More...

void	setClockFrequency (unsigned int freq)
	Changes the maximum clock frequency. More...

void	setClockPeriod (unsigned int nanos)
	Changes the minimum clock period. More...

Public Member Functions inherited from duds::hardware::interface::MasterSyncSerial
	MasterSyncSerial ()
	Builds a MasterSyncSerial with an invalid clock period and all configuration flags clear. More...

	MasterSyncSerial (Flags flags, int period)
	Builds a MasterSyncSerial object. More...

virtual	~MasterSyncSerial ()=0
	Derived class destructors should assure that communication has stopped by calling forceClose(). More...

std::unique_ptr< MasterSyncSerialAccess >	access ()
	Obtain access for communication; transitions the object from the ready (MssReady) to the open (MssOpen) state. More...

void	access (MasterSyncSerialAccess &acc)
	Obtain access for communication; transitions the object from the ready (MssReady) to the open (MssOpen) state. More...

std::unique_ptr< MasterSyncSerialAccess >	accessStart ()
	Obtain access for communication; transitions the object from the ready (MssReady) to the communicating (MssCommunicating) state. More...

void	accessStart (MasterSyncSerialAccess &acc)
	Obtain access for communication; transitions the object from the ready (MssReady) to the communicating (MssCommunicating) state. More...

unsigned int	clockFrequency () const noexcept
	Computes and returns the maximum clock frequency in Hertz. More...

unsigned int	clockPeriod () const noexcept
	Returns the minimum clock period in nanoseconds. More...

Flags	configFlags () const noexcept
	Returns the current set of configuration flags. More...

virtual void	converse (Conversation &conv)
	Has a half-duplex Conversation with the connected device. More...

bool	inUse () const noexcept
	Returns true when this serial interface is in use by checking for the existence of an access object. More...

Public Member Functions inherited from duds::hardware::interface::Conversationalist
virtual	~Conversationalist ()=0
	Allow proper destruction using a Conversationalist pointer. More...

Protected Member Functions
virtual void	close ()
	Transitions the object from the open (MssOpen) to the ready (MssReady) state. More...

virtual void	open ()
	Transitions the object from the ready (MssReady) to the open (MssOpen) state. More...

virtual void	start ()
	Denotes the start of a conversation; transitions from the open state to the communicating state. More...

virtual void	stop ()
	Denotes the end of a conversation; transitions from the communicating state to the open state. More...

virtual void	transfer (const std::uint8_t __restrict__ out, std::uint8_t __restrict__ in, duds::general::Bits bits)
	Moves data about. More...

Protected Member Functions inherited from duds::hardware::interface::MasterSyncSerial
void	clockFrequency (unsigned int freq)
	Changes the maximum clock frequency. More...

void	clockPeriod (unsigned int nanos)
	Changes the minimum clock period. More...

void	condStart ()
	Calls start() if not currently communicating (clear MssCommunicating flag). More...

void	condStop ()
	Calls stop() if currently communicating (set MssCommunicating flag). More...

void	converseAlreadyOpen (Conversation &conv)
	Has a half-duplex Conversation with the connected device. More...

void	forceClose ()
	Attempts to forcibly cease communications by calling condStop() and close(). More...

virtual void	receive (std::uint8_t *buff, duds::general::Bits bits)
	Receives bits of data. More...

virtual void	transmit (const std::uint8_t *buff, duds::general::Bits bits)
	Sends bits of data. More...

Private Attributes
int	spifd
	The file descriptor for SPI access. More...

spi_ioc_transfer	xfer
	Data for telling the kernel what to send and receive. More...

Additional Inherited Members
Public Types inherited from duds::hardware::interface::MasterSyncSerial
typedef duds::general::BitFlags< struct MssFlags >	Flags
	Configuration flags for various synchronous serial options. More...

Static Public Attributes inherited from duds::hardware::interface::MasterSyncSerial
static constexpr Flags	MssClockIdleHigh = Flags(2)
	Before communication begins, and after it ends, the clock line should have a high logic level. More...

static constexpr Flags	MssCommunicating = Flags(128)
	Indicates that communication is underway. More...

static constexpr Flags	MssConfigMask = Flags(31)
	All the flags that are used for configuration rather than the current state. More...

static constexpr Flags	MssFirstDerivedClassFlag = Flags(256)
	The first flag that may be defined by a derived class. More...

static constexpr Flags	MssFullDuplex = Flags(16)
	Communication is full duplex. More...

static constexpr Flags	MssMSbFirst = Flags(8)
	Send data MSb first, little endian. More...

static constexpr Flags	MssOpen = Flags(64)
	Indicates that all required resources for communication have been acquired. More...

static constexpr Flags	MssOutFallInRise = Flags(4)
	Output on the falling edge of the clock and read on the rising edge. More...

static constexpr Flags	MssReady = Flags(32)
	Indictates that all required resources for communication have been identified and passed a validity check. More...

static constexpr Flags	MssSpiMode0
	Flags for SPI mode 0. More...

static constexpr Flags	MssSpiMode0LSb = MssOutFallInRise \| MssFullDuplex
	Flags for SPI mode 0 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode1 = MssMSbFirst \| MssFullDuplex
	Flags for SPI mode 1. More...

static constexpr Flags	MssSpiMode1LSb = MssFullDuplex
	Flags for SPI mode 1 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode2
	Flags for SPI mode 2. More...

static constexpr Flags	MssSpiMode2LSb = MssClockIdleHigh \| MssFullDuplex
	Flags for SPI mode 2 with the LSb transfered first. More...

static constexpr Flags	MssSpiMode3
	Flags for SPI mode 3. More...

static constexpr Flags	MssSpiMode3LSb
	Flags for SPI mode 3 with the LSb transfered first. More...

static constexpr Flags	MssUseSelect = Flags(1)
	Use a select line to tell a device to pay attention to the master. More...

Protected Attributes inherited from duds::hardware::interface::MasterSyncSerial
Flags	flags
	Configuration flags. More...

unsigned int	minHalfPeriod
	The minimum time between changing the clock edge in nanoseconds. More...

Detailed Description

A synchronous serial implementation using the SPI userspace interface provided by the Linux kernel.

This requires proper kernel support for the hardware. In addition to a number of SPI master controllers, Linux also has support for SPI using GPIOs. The SPI using GPIO support should have less overhead and better performance than DigitalPinMasterSyncSerial. This class supports only 8-bit words, but otherwise supports all SPI modes. Specific master controllers may not support all modes.

Todo:: Many errors are reported with SyncSerialIoError exceptions; change this to provide better information on what failed.

Warning: The device will be selected by the SPI hardware only while data is being transfered; selection will not follow conversations (bewteen calls to MasterSyncSerialAccess::start() and MasterSyncSerialAccess::stop()) like it will with DigitalPinMasterSyncSerial.

This could be expanded upon by a class that uses a ChipSelect object to allow multiple devices on the same device file so that more devices can be used on the same bus. However, any process using another device file for the same bus can interrupt communications between transfers. This will need to be handled properly by the circuit to deselect the device selected by the ChipSelect object, and by the devices at the other end of the bus.

Author: Jeff Jackowski.

Definition at line 47 of file SpiMasterSyncSerial.hpp.

Constructor & Destructor Documentation

◆ SpiMasterSyncSerial() [1/3]

duds::hardware::interface::linux::SpiMasterSyncSerial::SpiMasterSyncSerial ( )

Creates the object without a SPI device to use.

Definition at line 20 of file SpiMasterSyncSerial.cpp.

◆ SpiMasterSyncSerial() [2/3]

duds::hardware::interface::linux::SpiMasterSyncSerial::SpiMasterSyncSerial	(	const std::string &	path,
		Flags	flags = `MssSpiMode0`,
		int	freq = `100000`
	)

Creates the object and attempts to open the SPI device.

Parameters

path	The path to the SPI device file.
flags	The flags specifying the SPI mode to use. Not all modes may be supported.
freq	The maximum clock frequency in hertz.

Definition at line 22 of file SpiMasterSyncSerial.cpp.

◆ SpiMasterSyncSerial() [3/3]

duds::hardware::interface::linux::SpiMasterSyncSerial::SpiMasterSyncSerial ( Flags flags )

Creates the object with SPI mode flags but no SPI device.

Parameters

flags The flags specifying the SPI mode to use. Not all modes may be supported.

Definition at line 31 of file SpiMasterSyncSerial.cpp.

◆ ~SpiMasterSyncSerial()

duds::hardware::interface::linux::SpiMasterSyncSerial::~SpiMasterSyncSerial ( )

Definition at line 34 of file SpiMasterSyncSerial.cpp.

Member Function Documentation

◆ close()

void duds::hardware::interface::linux::SpiMasterSyncSerial::close ( )

protectedvirtual

Transitions the object from the open (MssOpen) to the ready (MssReady) state.

This should relinquish access to any required shared resources.

Precondition: This function will only be called when in the open state.

Postcondition: The object will be ready, but the flag MssOpen is still set. The caller of this function will clear the flag.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 131 of file SpiMasterSyncSerial.cpp.

Referenced by open(), and ~SpiMasterSyncSerial().

◆ open() [1/2]

void duds::hardware::interface::linux::SpiMasterSyncSerial::open ( )

protectedvirtual

Transitions the object from the ready (MssReady) to the open (MssOpen) state.

This should acquire access to any required shared resources.

Precondition: This function will only be called when in the ready state.

Postcondition: The object will be open, but the flag MssOpen is not set. The caller of this function will set the flag.

Exceptions

boost::exception Badness; state transision did not occur.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 129 of file SpiMasterSyncSerial.cpp.

Referenced by open(), and SpiMasterSyncSerial().

◆ open() [2/2]

void duds::hardware::interface::linux::SpiMasterSyncSerial::open	(	const std::string &	path,
		Flags	flags = `MssSpiMode0`,
		int	freq = `100000`
	)

Opens the SPI device file and configures it.

Parameters

path	The path to the SPI device file.
flags	The flags specifying the SPI mode to use. Not all modes may be supported. If all bits are cleared, the already set flags will be used.
freq	The maximum clock frequency in hertz.

Precondition: The object is not in the open (MssOpen) state; no access object exists to use this object.

Postcondition: The object is in the ready (MssReady) state.

Exceptions

SyncSerialIoError	A failure ocurred when opening the file, or when setting the SPI communication parameters. The hardware may not support all SPI modes of operation, but the kernel's SPI over GPIO support should.
SyncSerialInUse	The object is in the open (MssOpen) or communicating (MssCommunicating) state.

Todo:: Report errors better to know what exactly failed.

Definition at line 39 of file SpiMasterSyncSerial.cpp.

◆ setClockFrequency()

void duds::hardware::interface::linux::SpiMasterSyncSerial::setClockFrequency ( unsigned int freq )

Changes the maximum clock frequency.

Precondition: No communication must be taking place; the object must not be in the MssCommunicating state.

Postcondition: minHalfPeriod has half the period of the clock in nanoseconds.

Parameters

freq	The requested maximum clock frequence in hertz.

Exceptions

SyncSerialInUse Called while communication is in progress.

Definition at line 100 of file SpiMasterSyncSerial.cpp.

Referenced by open(), and SpiMasterSyncSerial().

◆ setClockPeriod()

void duds::hardware::interface::linux::SpiMasterSyncSerial::setClockPeriod ( unsigned int nanos )

Changes the minimum clock period.

Precondition: No communication must be taking place; the object must not be in the MssCommunicating state.

Postcondition: minHalfPeriod has half the period of the clock in nanoseconds.

Parameters

nanos The requested minimum clock period in nanoseconds.

Exceptions

SyncSerialInUse Called while communication is in progress.

Definition at line 110 of file SpiMasterSyncSerial.cpp.

◆ start()

void duds::hardware::interface::linux::SpiMasterSyncSerial::start ( )

protectedvirtual

Denotes the start of a conversation; transitions from the open state to the communicating state.

Precondition: This object is in the ready state (MssReady) and not in the communicating state (MssCommunicating). These conditions are checked by condStart().

Postcondition: Communication may commence. If the other end needs to be selected, the selection has occured. The MssCommunicating flag does not need to be set; that is handled by condStart().

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 133 of file SpiMasterSyncSerial.cpp.

◆ stop()

void duds::hardware::interface::linux::SpiMasterSyncSerial::stop ( )

protectedvirtual

Denotes the end of a conversation; transitions from the communicating state to the open state.

Precondition: This object is in the communicating state (MssCommunicating) and not in the open state (MssOpen). These conditions are checked by condStop().

Postcondition: The chip is deselected if the MssUseSelect flag is set. The clock is in the idle state.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 135 of file SpiMasterSyncSerial.cpp.

◆ transfer()

void duds::hardware::interface::linux::SpiMasterSyncSerial::transfer	(	const std::uint8_t *__restrict__	out,
		std::uint8_t *__restrict__	in,
		duds::general::Bits	bits
	)

protectedvirtual

Moves data about.

Warning: Only multiples of 8 are currently supported for bits.

Implements duds::hardware::interface::MasterSyncSerial.

Definition at line 137 of file SpiMasterSyncSerial.cpp.

Member Data Documentation

◆ spifd

int duds::hardware::interface::linux::SpiMasterSyncSerial::spifd

private

The file descriptor for SPI access.

Definition at line 56 of file SpiMasterSyncSerial.hpp.

Referenced by open(), setClockFrequency(), setClockPeriod(), transfer(), and ~SpiMasterSyncSerial().

◆ xfer

spi_ioc_transfer duds::hardware::interface::linux::SpiMasterSyncSerial::xfer

private

Data for telling the kernel what to send and receive.

Placed here to avoid initializing the whole struct before every transfer.

Definition at line 52 of file SpiMasterSyncSerial.hpp.

Referenced by open(), and transfer().

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

Public Member Functions

Protected Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SpiMasterSyncSerial() [1/3]

◆ SpiMasterSyncSerial() [2/3]

◆ SpiMasterSyncSerial() [3/3]

◆ ~SpiMasterSyncSerial()

Member Function Documentation

◆ close()

◆ open() [1/2]

◆ open() [2/2]

◆ setClockFrequency()

◆ setClockPeriod()

◆ start()

◆ stop()

◆ transfer()

Member Data Documentation

◆ spifd

◆ xfer