S2PI: SPI incl. GPIO Hardware Layer Module. More...

Collaboration diagram for S2PI: Serial Peripheral Interface:

Typedefs
typedef status_t(*	s2pi_callback_t) (status_t status, void *param)
	S2PI layer callback function type for the SPI transfer completed event.

typedef void(*	s2pi_irq_callback_t) (void *param)
	S2PI layer callback function type for the GPIO interrupt event.

typedef int32_t	s2pi_slave_t

Enumerations
enum	s2pi_pin_t { S2PI_CLK , S2PI_CS , S2PI_MOSI , S2PI_MISO , S2PI_IRQ }

Functions
status_t	S2PI_GetStatus (s2pi_slave_t slave)
	Returns the status of the SPI module.

status_t	S2PI_TryGetMutex (s2pi_slave_t slave)
	Tries to grab the SPI interface mutex for the next transfer.

void	S2PI_ReleaseMutex (s2pi_slave_t slave)
	Releases the SPI interface mutex.

status_t	S2PI_TransferFrame (s2pi_slave_t slave, uint8_t const txData, uint8_t rxData, size_t frameSize, s2pi_callback_t callback, void *callbackData)
	Transfers a single SPI frame asynchronously.

status_t	S2PI_Abort (s2pi_slave_t slave)
	Terminates a currently ongoing asynchronous SPI transfer.

status_t	S2PI_SetIrqCallback (s2pi_slave_t slave, s2pi_irq_callback_t callback, void *callbackData)
	Set a callback for the GPIO IRQ for a specified S2PI slave.

uint32_t	S2PI_ReadIrqPin (s2pi_slave_t slave)
	Reads the current interrupt pending status of the IRQ pin.

status_t	S2PI_CycleCsPin (s2pi_slave_t slave)
	Cycles the chip select line.

status_t	S2PI_CaptureGpioControl (s2pi_slave_t slave)
	Captures the S2PI pins for GPIO usage.

status_t	S2PI_ReleaseGpioControl (s2pi_slave_t slave)
	Releases the S2PI pins from GPIO usage and switches back to SPI mode.

status_t	S2PI_WriteGpioPin (s2pi_slave_t slave, s2pi_pin_t pin, uint32_t value)
	Writes the output for a specified SPI pin in GPIO mode.

status_t	S2PI_ReadGpioPin (s2pi_slave_t slave, s2pi_pin_t pin, uint32_t *value)
	Reads the input from a specified SPI pin in GPIO mode.

Detailed Description

S2PI: SPI incl. GPIO Hardware Layer Module.

The S2PI module consists of a standard SPI interface plus a single GPIO interrupt line. Furthermore, the SPI pins are accessible via GPIO control to allow a software emulation of additional protocols using the same pins.

SPI interface:

The SPI interface is based around a single functionality:

S2PI_TransferFrame. This function transfers a specified number of bytes via the interfaces MOSI line and simultaneously reads the incoming data on the MOSI line. The read can also be skipped. The transfer happen asynchronously, e.g. via a DMA request. After finishing the transfer, the provided callback is invoked with the status of the transfer and the provided abstract parameter. Furthermore, the functions receives a slave parameter that can be used to connect multiple slaves, each with its individual chip select line.

The interface also provides functionality to change the SPI baud rate. An additional abort method is used to cancel the ongoing transfer.

GPIO interface:

The GPIO part of the S2PI interface has two distinct concerns:

First, the GPIO interface handles the measurement finished interrupt from the device. When the device invokes the interrupt, it pulls the interrupt line to low. Thus the interrupt must trigger when a transition from high to low occurs on the interrupt line.

The module simply invokes a callback when this interrupt occurs. The S2PI_SetIrqCallback method is used to install the callback for a specified slave. Each slave will have its own interrupt line. An additional callback parameter can be set that would be passed to the callback function.

In addition to the interrupt, all SPI pins need to be accessible as GPIO pins through this interface. This is required to read the EEPROM memory on the device hat is connected to the SPI pins but requires a different protocol that is not compatible to any standard SPI interface. Therefore, the interface provides the possibility to switch to GPIO control mode that allows to emulate the EEPROM protocol via software bit banging.

Two methods are provided to switch forth and back between SPI and GPIO control. In GPIO mode, several functions are used to read and write the individual GPIO pins.

Note that the GPIO mode is only required to readout the EEPROM upon initialization of the device, i.e. during execution of the Argus_Init or Argus_Reinit methods. The GPIO mode is not used during measurements.

Typedef Documentation

◆ s2pi_callback_t

typedef status_t(* s2pi_callback_t) (status_t status, void *param)

S2PI layer callback function type for the SPI transfer completed event.

Parameters

status	The status of the completed transfer (STATUS_OK on success).
param	The provided (optional, can be null) callback parameter.

Returns: Returns the status (STATUS_OK on success).

◆ s2pi_irq_callback_t

typedef void(* s2pi_irq_callback_t) (void *param)

S2PI layer callback function type for the GPIO interrupt event.

Parameters

param The provided (optional, can be null) callback parameter.

◆ s2pi_slave_t

typedef int32_t s2pi_slave_t

The S2PI slave identifier. Basically an user defined enumerable type that can be used to identify the slave within the SPI module.

Enumeration Type Documentation

◆ s2pi_pin_t

enum s2pi_pin_t

The enumeration of S2PI pins.

Enumerator
S2PI_CLK	The SPI clock pin.
S2PI_CS	The SPI chip select pin.
S2PI_MOSI	The SPI MOSI pin.
S2PI_MISO	The SPI MISO pin.
S2PI_IRQ	The IRQ pin.

Function Documentation

◆ S2PI_Abort()

status_t S2PI_Abort ( s2pi_slave_t slave )

Terminates a currently ongoing asynchronous SPI transfer.

When a callback is set for the current ongoing activity, it is invoked with the ERROR_ABORTED error byte.

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

Returns: Returns the status (STATUS_OK on success).

◆ S2PI_CaptureGpioControl()

status_t S2PI_CaptureGpioControl ( s2pi_slave_t slave )

Captures the S2PI pins for GPIO usage.

The SPI is disabled (module status: STATUS_S2PI_GPIO_MODE) and the pins are configured for GPIO operation. The GPIO control must be release with the S2PI_ReleaseGpioControl function in order to switch back to ordinary SPI functionality.

Note: This function is only called during device initialization!

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

Returns: Returns the status (STATUS_OK on success).

◆ S2PI_CycleCsPin()

status_t S2PI_CycleCsPin ( s2pi_slave_t slave )

Cycles the chip select line.

In order to cancel the integration on the ASIC, a fast toggling of the chip select pin of the corresponding SPI slave is required. Therefore, this function toggles the CS from high to low and back. The SPI instance for the specified S2PI slave must be idle, otherwise the status STATUS_BUSY is returned.

Parameters

slave The specified S2PI slave.

Returns: Returns the status (STATUS_OK on success).

◆ S2PI_GetStatus()

status_t S2PI_GetStatus ( s2pi_slave_t slave )

Returns the status of the SPI module.

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

Returns

Returns the status:

STATUS_IDLE: No SPI transfer or GPIO access is ongoing.
STATUS_BUSY: An SPI transfer is in progress.
STATUS_S2PI_GPIO_MODE: The module is in GPIO mode.

◆ S2PI_ReadGpioPin()

status_t S2PI_ReadGpioPin	(	s2pi_slave_t	slave,
		s2pi_pin_t	pin,
		uint32_t *	value
	)

Reads the input from a specified SPI pin in GPIO mode.

This function reads the value of an SPI pin if the SPI pins are captured for GPIO operation via the S2PI_CaptureGpioControl previously.

Note: This function is only called during device initialization!

Parameters

slave	The specified S2PI slave.
pin	The specified S2PI pin.
value	The GPIO pin state to read (0 = low, GND level, 1 = high, VCC level).

Returns: Returns the status (STATUS_OK on success).

◆ S2PI_ReadIrqPin()

uint32_t S2PI_ReadIrqPin ( s2pi_slave_t slave )

Reads the current interrupt pending status of the IRQ pin.

In order to keep a low priority for GPIO IRQs, the state of the IRQ pin must be read in order to reliable check for chip timeouts.

The execution of the interrupt service routine for the data-ready interrupt from the corresponding GPIO pin might be delayed due to priority issues. The delayed execution might disable the timeout for the eye-safety checker too late causing false error messages. In order to overcome the issue, the interrupt state of the IRQ GPIO input pin is read before raising a timeout error in order to check if the device has already finished and the IRQ is still pending to be executed!

Note: an easy implementation is to simply return the state of the IRQ line, i.e. 0 if there is a low input state and 1 if there is a high input state on the IRQ input pin. However, this implementation is not fully reliable since the GPIO interrupt (triggered on the falling edge) might be missed and the callback is never invoked while the IRQ line is correctly asserted to low state by the device. In that case, the API is waiting forever until the callback is invoked which might never happen. Therefore, it is better if the implementation checks the state of the IRQ pending status register or even combines both variations.

Parameters

slave The specified S2PI slave.

Returns: Returns 1U if the IRQ is NOT pending (pin is in high state) and 0U if the IRQ is pending (pin is pulled to low state by the device).

◆ S2PI_ReleaseGpioControl()

status_t S2PI_ReleaseGpioControl ( s2pi_slave_t slave )

Releases the S2PI pins from GPIO usage and switches back to SPI mode.

The GPIO pins are configured for SPI operation and the GPIO mode is left. Must be called if the pins are captured for GPIO operation via the S2PI_CaptureGpioControl function.

Note: This function is only called during device initialization!

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

Returns: Returns the status (STATUS_OK on success).

◆ S2PI_ReleaseMutex()

void S2PI_ReleaseMutex ( s2pi_slave_t slave )

Releases the SPI interface mutex.

Once the mutex is captured, only a single thread (the one that captured it) will call this release function, so there is no need for any test or thread safe barriers. Also there is no side effect of calling this function when the Mutex is not taken so this function can be really simple and doesn't need to return anything.

See S2PI_TryGetMutex on more information and an example implementation for the single SPI interface case.

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

◆ S2PI_SetIrqCallback()

status_t S2PI_SetIrqCallback	(	s2pi_slave_t	slave,
		s2pi_irq_callback_t	callback,
		void *	callbackData
	)

Set a callback for the GPIO IRQ for a specified S2PI slave.

Parameters

slave	The specified S2PI slave.
callback	A callback function to be invoked when the specified S2PI slave IRQ occurs. Pass a null pointer to disable the callback.
callbackData	A pointer to a state that will be passed to the callback. Pass a null pointer if not used.

Returns

Returns the status:

STATUS_OK: Successfully installation of the callback.
ERROR_S2PI_INVALID_SLAVE: A wrong slave identifier is provided.

◆ S2PI_TransferFrame()

status_t S2PI_TransferFrame	(	s2pi_slave_t	slave,
		uint8_t const *	txData,
		uint8_t *	rxData,
		size_t	frameSize,
		s2pi_callback_t	callback,
		void *	callbackData
	)

Transfers a single SPI frame asynchronously.

Transfers a single SPI frame in asynchronous manner. The Tx data buffer is written to the device via the MOSI line. Optionally, the data on the MISO line is written to the provided Rx data buffer. If null, the read data is dismissed. Note that Rx and Tx buffer can be identical. I.e. the same buffer is used for writing and reading data. First, a byte is transmitted and the received byte overwrites the previously send value.

The transfer of a single frame requires to not toggle the chip select line to high in between the data frame. The maximum number of bytes transferred in a single SPI transfer is given by the data value register of the device, which is 396 data bytes plus a single address byte: 397 bytes.

An optional callback is invoked when the asynchronous transfer is finished. If the callback parameter is a null pointer, no callback is provided. Note that the provided buffer must not change while the transfer is ongoing.

Use the slave parameter to determine the corresponding slave via the given chip select line.

Usually, two distinct interrupts are required to handle the RX and TX ready events. The callback must be invoked from whichever interrupt comes after the SPI transfer has been finished. Note that new SPI transfers are invoked from within the callback function (i.e. from within the interrupt service routine of same priority).

Parameters

slave	The specified S2PI slave.
txData	The 8-bit values to write to the SPI bus MOSI line.
rxData	The 8-bit values received from the SPI bus MISO line (pass a null pointer if the data don't need to be read).
frameSize	The number of 8-bit values to be sent/received.
callback	A callback function to be invoked when the transfer is finished. Pass a null pointer if no callback is required.
callbackData	A pointer to a state that will be passed to the callback. Pass a null pointer if not used.

Returns

Returns the status:

STATUS_OK: Successfully invoked the transfer.
ERROR_INVALID_ARGUMENT: An invalid parameter has been passed.
ERROR_S2PI_INVALID_SLAVE: A wrong slave identifier is provided.
STATUS_BUSY: An SPI transfer is already in progress. The transfer was not started.
STATUS_S2PI_GPIO_MODE: The module is in GPIO mode. The transfer was not started.

◆ S2PI_TryGetMutex()

status_t S2PI_TryGetMutex ( s2pi_slave_t slave )

Tries to grab the SPI interface mutex for the next transfer.

This mutex prevents new asynchronous SPI requests to interfere with transfers already in progress for this interface.

Note that this is only required if multiple device are connected to a single SPI interface. If only operating a single device per SPI, the function can simply always return STATUS_OK.

There must be a dedicated mutex object per SPI interface if multiple SPI interfaces are used.

The mutex will be released in the S2PI_ReleaseMutex function. See S2PI_ReleaseMutex for additional information.

Here is a simple example implementation for the multiple devices on a single SPI interface case. Note that the SpiMutexBlocked must be defined per SPI interface if multiple SPI interfaces are used.

static volatile bool SpiMutexBlocked = false;
status_t S2PI_TryGetMutex(s2pi_slave_t slave)
{
    (void) slave; // not used in this implementation as all
                  // SPI slaves are on the same SPI interface
 
    status_t status = STATUS_BUSY;
    IRQ_LOCK();
    if (!SpiMutexBlocked)
    {
        SpiMutexBlocked = true;
        status = STATUS_OK;
    }
    IRQ_UNLOCK();
    return status;
}
void S2PI_ReleaseMutex(s2pi_slave_t slave)
{
    (void) slave; // not used in this implementation
    SpiMutexBlocked = false;
}

Parameters

slave The specified S2PI slave. Note that the slave information is only required if multiple SPI instances are used in order to map to the correct SPI instance.

Returns

Returns the status:

STATUS_OK: the SPI interface was successfully reserved for the caller
STATUS_BUSY: another transfer is ongoing, the caller must not access the bus

◆ S2PI_WriteGpioPin()

status_t S2PI_WriteGpioPin	(	s2pi_slave_t	slave,
		s2pi_pin_t	pin,
		uint32_t	value
	)

Writes the output for a specified SPI pin in GPIO mode.

This function writes the value of an SPI pin if the SPI pins are captured for GPIO operation via the S2PI_CaptureGpioControl previously.

Note: Since some GPIO peripherals switch the GPIO pins very fast a delay must be added after each GBIO access (i.e. right before returning from the S2PI_WriteGpioPin method) in order to decrease the baud rate of the software EEPROM protocol. Increase the delay if timing issues occur while reading the EERPOM. For example: Delay = 10 µsec => Baud Rate < 100 kHz; This function is only called during device initialization!

Parameters

slave	The specified S2PI slave.
pin	The specified S2PI pin.
value	The GPIO pin state to write (0 = low, 1 = high).

Returns: Returns the status (STATUS_OK on success).

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ s2pi_callback_t

◆ s2pi_irq_callback_t

◆ s2pi_slave_t

Enumeration Type Documentation

◆ s2pi_pin_t

Function Documentation

◆ S2PI_Abort()

◆ S2PI_CaptureGpioControl()

◆ S2PI_CycleCsPin()

◆ S2PI_GetStatus()

◆ S2PI_ReadGpioPin()

◆ S2PI_ReadIrqPin()

◆ S2PI_ReleaseGpioControl()

◆ S2PI_ReleaseMutex()

◆ S2PI_SetIrqCallback()

◆ S2PI_TransferFrame()

◆ S2PI_TryGetMutex()

◆ S2PI_WriteGpioPin()