Generic SPI Driver. More...

Detailed Description

Generic SPI Driver.

This module implements a generic SPI (Serial Peripheral Interface) driver allowing bidirectional and monodirectional transfers, complex atomic transactions are supported as well.

Precondition: In order to use the SPI driver the HAL_USE_SPI option must be enabled in halconf.h.

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

The driver is not thread safe for performance reasons, if you need to access the SPI bus from multiple threads then use the spiAcquireBus() and spiReleaseBus() APIs in order to gain exclusive access.

Collaboration diagram for SPIv2 Driver:

Chip Select modes
#define	SPI_SELECT_MODE_NONE
#define	SPI_SELECT_MODE_PAD 1 /** @brief Legacy mode. */
#define	SPI_SELECT_MODE_PORT 2 /** @brief Fastest mode. */
#define	SPI_SELECT_MODE_LINE 3 /** @brief Packed mode. */
#define	SPI_SELECT_MODE_LLD 4 /** @brief LLD-defined mode.*/

SPI configuration options
#define	SPI_USE_SYNCHRONIZATION FALSE
	Support for thread synchronization API.
#define	SPI_USE_ASSERT_ON_ERROR TRUE
	Inserts an assertion on function errors before returning.
#define	SPI_USE_MUTUAL_EXCLUSION TRUE
	Enables the `spiAcquireBus()` and `spiReleaseBus()` APIs.
#define	SPI_SELECT_MODE SPI_SELECT_MODE_PAD
	Handling method for SPI CS line.

Macro Functions
#define	spiIsBufferComplete(spip)
	Buffer state.
#define	spiSelectI(spip)
	Asserts the slave select signal and prepares for transfers.
#define	spiUnselectI(spip)
	Deasserts the slave select signal.
#define	spiPolledExchange(spip, frame)
	Exchanges one frame using a polled wait.
#define	spiAbortI(spip)
	Compatibility API with SPI driver v1.
#define	spiAbort(spip)
	Compatibility API with SPI driver v1.

Low level driver helper macros
#define	__spi_wakeup_isr(spip, msg)
	Wakes up the waiting thread.
#define	__spi_isr_complete_code(spip)
	Common ISR code in linear mode.
#define	__spi_isr_half_code(spip)
	Half buffer filled ISR code in circular mode.
#define	__spi_isr_full_code(spip)
	Full buffer filled ISR code in circular mode.
#define	__spi_isr_error_code(spip, msg)
	ISR error reporting code..

PLATFORM configuration options
#define	PLATFORM_SPI_USE_SPI1 FALSE
	SPI1 driver enable switch.

Data Structures
struct	hal_spi_config
	Driver configuration structure. More...
struct	hal_spi_driver
	Structure representing an SPI driver. More...

Macros
#define	SPI_SUPPORTS_CIRCULAR TRUE
	Circular mode support flag.
#define	SPI_SUPPORTS_SLAVE_MODE TRUE
	Slave mode support flag.
#define	spi_lld_driver_fields
	Low level fields of the SPI driver structure.
#define	spi_lld_config_fields
	Low level fields of the SPI configuration structure.

Typedefs
typedef struct hal_spi_driver	SPIDriver
	Type of a structure representing an SPI driver.
typedef struct hal_spi_config	SPIConfig
	Type of a SPI driver configuration structure.
typedef void(*	spicb_t) (SPIDriver *spip)
	SPI notification callback type.

Enumerations
enum	spistate_t { SPI_UNINIT = 0 , SPI_STOP = 1 , SPI_READY = 2 , SPI_ACTIVE = 3 , SPI_COMPLETE = 4 }
	Driver state machine possible states. More...

Functions
void	spiInit (void)
	SPI Driver initialization.
void	spiObjectInit (SPIDriver *spip)
	Initializes the standard part of a `SPIDriver` structure.
msg_t	spiStart (SPIDriver spip, const SPIConfig config)
	Configures and activates the SPI peripheral.
void	spiStop (SPIDriver *spip)
	Deactivates the SPI peripheral.
void	spiSelect (SPIDriver *spip)
	Asserts the slave select signal and prepares for transfers.
void	spiUnselect (SPIDriver *spip)
	Deasserts the slave select signal.
msg_t	spiStartIgnoreI (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
msg_t	spiStartIgnore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
msg_t	spiStartExchangeI (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
msg_t	spiStartExchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
msg_t	spiStartSendI (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
msg_t	spiStartSend (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
msg_t	spiStartReceiveI (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
msg_t	spiStartReceive (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
msg_t	spiStopTransferI (SPIDriver spip, size_t sizep)
	Stops the ongoing SPI operation.
msg_t	spiStopTransfer (SPIDriver spip, size_t sizep)
	Stops the ongoing SPI operation, if any.
msg_t	spiSynchronizeS (SPIDriver *spip, sysinterval_t timeout)
	Synchronizes with current transfer completion.
msg_t	spiSynchronize (SPIDriver *spip, sysinterval_t timeout)
	Synchronizes with current transfer completion.
msg_t	spiIgnore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
msg_t	spiExchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
msg_t	spiSend (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
msg_t	spiReceive (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
void	spiAcquireBus (SPIDriver *spip)
	Gains exclusive access to the SPI bus.
void	spiReleaseBus (SPIDriver *spip)
	Releases exclusive access to the SPI bus.
void	spi_lld_init (void)
	Low level SPI driver initialization.
msg_t	spi_lld_start (SPIDriver *spip)
	Configures and activates the SPI peripheral.
void	spi_lld_stop (SPIDriver *spip)
	Deactivates the SPI peripheral.
void	spi_lld_select (SPIDriver *spip)
	Asserts the slave select signal and prepares for transfers.
void	spi_lld_unselect (SPIDriver *spip)
	Deasserts the slave select signal.
msg_t	spi_lld_ignore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
msg_t	spi_lld_exchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
msg_t	spi_lld_send (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
msg_t	spi_lld_receive (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
msg_t	spi_lld_stop_transfer (SPIDriver spip, size_t sizep)
	Aborts the ongoing SPI operation, if any.
uint16_t	spi_lld_polled_exchange (SPIDriver *spip, uint16_t frame)
	Exchanges one frame using a polled wait.

Variables
SPIDriver	SPID1
	SPI1 driver identifier.

Macro Definition Documentation

◆ SPI_SELECT_MODE_NONE

#define SPI_SELECT_MODE_NONE

Value:

                                                    0   /** @brief @p spiSelect() and
                                                    @p spiUnselect() do
                                                    nothing.                */

Definition at line 38 of file hal_spi_v2.h.

◆ SPI_SELECT_MODE_PAD

#define SPI_SELECT_MODE_PAD 1 /** @brief Legacy mode. */

Definition at line 39 of file hal_spi_v2.h.

◆ SPI_SELECT_MODE_PORT

#define SPI_SELECT_MODE_PORT 2 /** @brief Fastest mode. */

Definition at line 40 of file hal_spi_v2.h.

◆ SPI_SELECT_MODE_LINE

#define SPI_SELECT_MODE_LINE 3 /** @brief Packed mode. */

Definition at line 41 of file hal_spi_v2.h.

◆ SPI_SELECT_MODE_LLD

#define SPI_SELECT_MODE_LLD 4 /** @brief LLD-defined mode.*/

Definition at line 42 of file hal_spi_v2.h.

◆ SPI_USE_SYNCHRONIZATION

#define SPI_USE_SYNCHRONIZATION FALSE

Support for thread synchronization API.

Definition at line 58 of file hal_spi_v2.h.

◆ SPI_USE_ASSERT_ON_ERROR

#define SPI_USE_ASSERT_ON_ERROR TRUE

Inserts an assertion on function errors before returning.

Definition at line 68 of file hal_spi_v2.h.

◆ SPI_USE_MUTUAL_EXCLUSION

#define SPI_USE_MUTUAL_EXCLUSION TRUE

Enables the spiAcquireBus() and spiReleaseBus() APIs.

Note: Disabling this option saves both code and data space.

Definition at line 76 of file hal_spi_v2.h.

◆ SPI_SELECT_MODE

#define SPI_SELECT_MODE SPI_SELECT_MODE_PAD

Handling method for SPI CS line.

Note: Disabling this option saves both code and data space.

Definition at line 84 of file hal_spi_v2.h.

◆ spiIsBufferComplete

#define spiIsBufferComplete ( spip )

Value:

((bool)((spip)->state == SPI_COMPLETE))

SPI_COMPLETE

@ SPI_COMPLETE

Definition hal_spi_v1.h:111

Buffer state.

Note: This function is meant to be called from the SPI callback only.

Parameters

[in] spip pointer to the SPIDriver object

Returns: The buffer state.

Return values

false	if the driver filled/sent the first half of the buffer.
true	if the driver filled/sent the second half of the buffer.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 263 of file hal_spi_v2.h.

◆ spiSelectI

#define spiSelectI ( spip )

Value:

do {                                                                        \
  spi_lld_select(spip);                                                     \
} while (false)

Asserts the slave select signal and prepares for transfers.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 273 of file hal_spi_v2.h.

◆ spiUnselectI

#define spiUnselectI ( spip )

Value:

do {                                                                        \
  spi_lld_unselect(spip);                                                   \
} while (false)

Deasserts the slave select signal.

The previously selected peripheral is unselected.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 286 of file hal_spi_v2.h.

◆ spiPolledExchange

#define spiPolledExchange	(		spip,
			frame )

Value:

spi_lld_polled_exchange(spip, frame)

spi_lld_polled_exchange

uint16_t spi_lld_polled_exchange(SPIDriver *spip, uint16_t frame)

Exchanges one frame using a polled wait.

Definition hal_spi_lld.c:272

Exchanges one frame using a polled wait.

This synchronous function exchanges one frame using a polled synchronization method. This function is useful when exchanging small amount of data on high speed channels, usually in this situation is much more efficient just wait for completion using polling than suspending the thread waiting for an interrupt.

Note: This API is implemented as a macro in order to minimize latency.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	frame	the data frame to send over the SPI bus

Returns: The received data frame from the SPI bus.

Definition at line 343 of file hal_spi_v2.h.

◆ spiAbortI

#define spiAbortI ( spip )

Value:

spiStopTransferI(spip, NULL)

spiStopTransferI

msg_t spiStopTransferI(SPIDriver *spip, size_t *sizep)

Stops the ongoing SPI operation.

Definition hal_spi_v2.inc:445

Compatibility API with SPI driver v1.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 352 of file hal_spi_v2.h.

Referenced by spiAbort().

◆ spiAbort

#define spiAbort ( spip )

Value:

spiStopTransfer(spip, NULL)

spiStopTransfer

msg_t spiStopTransfer(SPIDriver *spip, size_t *sizep)

Stops the ongoing SPI operation, if any.

Definition hal_spi_v2.inc:484

Compatibility API with SPI driver v1.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 361 of file hal_spi_v2.h.

◆ __spi_wakeup_isr

#define __spi_wakeup_isr	(		spip,
			msg )

Value:

  {                                       \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(spip)->sync_transfer, msg);                           \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	msg	wakeup message

Function Class:: Not an API, this function is for internal use only.

Definition at line 377 of file hal_spi_v2.h.

◆ __spi_isr_complete_code

#define __spi_isr_complete_code ( spip )

Value:

  {                                     \
  if ((spip)->config->data_cb) {                                            \
    (spip)->state = SPI_COMPLETE;                                           \
    (spip)->config->data_cb(spip);                                          \
    if ((spip)->state == SPI_COMPLETE)                                      \
      (spip)->state = SPI_READY;                                            \
  }                                                                         \
  else {                                                                    \
    (spip)->state = SPI_READY;                                              \
  }                                                                         \
  __spi_wakeup_isr(spip, MSG_OK);                                           \
}

Common ISR code in linear mode.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 400 of file hal_spi_v2.h.

◆ __spi_isr_half_code

#define __spi_isr_half_code ( spip )

Value:

  {                                         \
  if ((spip)->config->data_cb) {                                            \
    (spip)->config->data_cb(spip);                                          \
  }                                                                         \
}

Half buffer filled ISR code in circular mode.

This code handles the portable part of the ISR code:

Callback invocation.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 425 of file hal_spi_v2.h.

◆ __spi_isr_full_code

#define __spi_isr_full_code ( spip )

Value:

  {                                         \
  if ((spip)->config->data_cb) {                                            \
    (spip)->state = SPI_COMPLETE;                                           \
    (spip)->config->data_cb(spip);                                          \
    if ((spip)->state == SPI_COMPLETE) {                                    \
      (spip)->state = SPI_ACTIVE;                                           \
    }                                                                       \
  }                                                                         \
}

Full buffer filled ISR code in circular mode.

This code handles the portable part of the ISR code:

Callback invocation.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 444 of file hal_spi_v2.h.

◆ __spi_isr_error_code

#define __spi_isr_error_code	(		spip,
			msg )

Value:

  {                                   \
  if ((spip)->config->error_cb) {                                           \
    (spip)->config->error_cb(spip);                                         \
  }                                                                         \
  __spi_wakeup_isr(spip, msg);                                              \
}

ISR error reporting code..

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	msg	error code

Function Class:: Not an API, this function is for internal use only.

Definition at line 464 of file hal_spi_v2.h.

◆ SPI_SUPPORTS_CIRCULAR

#define SPI_SUPPORTS_CIRCULAR TRUE

Circular mode support flag.

Definition at line 37 of file hal_spi_v2_lld.h.

◆ SPI_SUPPORTS_SLAVE_MODE

#define SPI_SUPPORTS_SLAVE_MODE TRUE

Slave mode support flag.

Definition at line 42 of file hal_spi_v2_lld.h.

◆ PLATFORM_SPI_USE_SPI1

#define PLATFORM_SPI_USE_SPI1 FALSE

SPI1 driver enable switch.

If set to TRUE the support for SPI1 is included.

Note: The default is FALSE.

Definition at line 58 of file hal_spi_v2_lld.h.

◆ spi_lld_driver_fields

#define spi_lld_driver_fields

Value:

/* Dummy field, it is not needed.*/ \

uint32_t dummy;

Low level fields of the SPI driver structure.

Definition at line 77 of file hal_spi_v2_lld.h.

◆ spi_lld_config_fields

#define spi_lld_config_fields

Value:

/* Dummy configuration, it is not needed.*/ \

uint32_t dummy;

Low level fields of the SPI configuration structure.

Definition at line 84 of file hal_spi_v2_lld.h.

Typedef Documentation

◆ SPIDriver

typedef struct hal_spi_driver SPIDriver

Type of a structure representing an SPI driver.

Definition at line 127 of file hal_spi_v2.h.

◆ SPIConfig

typedef struct hal_spi_config SPIConfig

Type of a SPI driver configuration structure.

Definition at line 132 of file hal_spi_v2.h.

◆ spicb_t

typedef void(* spicb_t) (SPIDriver *spip)

SPI notification callback type.

Parameters

[in] spip pointer to the SPIDriver object triggering the callback

Definition at line 140 of file hal_spi_v2.h.

Enumeration Type Documentation

◆ spistate_t

enum spistate_t

Driver state machine possible states.

Enumerator
SPI_UNINIT	Not initialized.
SPI_STOP	Stopped.
SPI_READY	Ready.
SPI_ACTIVE	Exchanging data.
SPI_COMPLETE	Asynchronous operation complete.

Definition at line 116 of file hal_spi_v2.h.

Function Documentation

◆ spiInit()

void spiInit ( void )

SPI Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:: Object or module nitializer function.

Definition at line 54 of file hal_spi_v2.inc.

References spi_lld_init().

Here is the call graph for this function:

◆ spiObjectInit()

void spiObjectInit ( SPIDriver * spip )

Initializes the standard part of a SPIDriver structure.

Parameters

[out] spip pointer to the SPIDriver object

Function Class:: Object or module nitializer function.

Definition at line 66 of file hal_spi_v2.inc.

References hal_spi_driver::config, hal_spi_driver::mutex, osalMutexObjectInit(), SPI_STOP, hal_spi_driver::state, and hal_spi_driver::sync_transfer.

Here is the call graph for this function:

◆ spiStart()

msg_t spiStart	(	SPIDriver *	spip,
		const SPIConfig *	config )

Configures and activates the SPI peripheral.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	config	pointer to the `SPIConfig` object

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 90 of file hal_spi_v2.inc.

References hal_spi_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), spi_lld_start(), SPI_READY, SPI_STOP, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStop()

void spiStop ( SPIDriver * spip )

Deactivates the SPI peripheral.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 125 of file hal_spi_v2.inc.

References hal_spi_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), spi_lld_stop(), SPI_READY, SPI_STOP, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiSelect()

void spiSelect ( SPIDriver * spip )

Asserts the slave select signal and prepares for transfers.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 148 of file hal_spi_v2.inc.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), SPI_READY, spiSelectI, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiUnselect()

void spiUnselect ( SPIDriver * spip )

Deasserts the slave select signal.

The previously selected peripheral is unselected.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 166 of file hal_spi_v2.inc.

References osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), SPI_READY, spiUnselectI, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStartIgnoreI()

msg_t spiStartIgnoreI	(	SPIDriver *	spip,
		size_t	n )

Ignores data on the SPI bus.

This asynchronous function starts the transmission of a series of idle words on the SPI bus and ignores the received data.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be ignored

Returns: The operation status.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 190 of file hal_spi_v2.inc.

References hal_spi_config::circular, hal_spi_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, SPI_ACTIVE, spi_lld_ignore(), SPI_READY, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStartIgnore()

msg_t spiStartIgnore	(	SPIDriver *	spip,
		size_t	n )

Ignores data on the SPI bus.

This asynchronous function starts the transmission of a series of idle words on the SPI bus and ignores the received data.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be ignored

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 226 of file hal_spi_v2.inc.

References osalSysLock(), osalSysUnlock(), and spiStartIgnoreI.

Here is the call graph for this function:

◆ spiStartExchangeI()

msg_t spiStartExchangeI	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf,
		void *	rxbuf )

Exchanges data on the SPI bus.

This asynchronous function starts a simultaneous transmit/receive operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be exchanged
[in]	txbuf	the pointer to the transmit buffer
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 254 of file hal_spi_v2.inc.

References hal_spi_config::circular, hal_spi_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, SPI_ACTIVE, spi_lld_exchange(), SPI_READY, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStartExchange()

msg_t spiStartExchange	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf,
		void *	rxbuf )

Exchanges data on the SPI bus.

This asynchronous function starts a simultaneous transmit/receive operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be exchanged
[in]	txbuf	the pointer to the transmit buffer
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 296 of file hal_spi_v2.inc.

References osalSysLock(), osalSysUnlock(), and spiStartExchangeI.

Here is the call graph for this function:

◆ spiStartSendI()

msg_t spiStartSendI	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf )

Sends data over the SPI bus.

This asynchronous function starts a transmit operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to send
[in]	txbuf	the pointer to the transmit buffer

Returns: The operation status.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 323 of file hal_spi_v2.inc.

References hal_spi_config::circular, hal_spi_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, SPI_ACTIVE, spi_lld_send(), SPI_READY, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStartSend()

msg_t spiStartSend	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf )

Sends data over the SPI bus.

This asynchronous function starts a transmit operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to send
[in]	txbuf	the pointer to the transmit buffer

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 361 of file hal_spi_v2.inc.

References osalSysLock(), osalSysUnlock(), and spiStartSendI.

Here is the call graph for this function:

◆ spiStartReceiveI()

msg_t spiStartReceiveI	(	SPIDriver *	spip,
		size_t	n,
		void *	rxbuf )

Receives data from the SPI bus.

This asynchronous function starts a receive operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to receive
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 387 of file hal_spi_v2.inc.

References hal_spi_config::circular, hal_spi_driver::config, HAL_RET_SUCCESS, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, SPI_ACTIVE, spi_lld_receive(), SPI_READY, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiStartReceive()

msg_t spiStartReceive	(	SPIDriver *	spip,
		size_t	n,
		void *	rxbuf )

Receives data from the SPI bus.

This asynchronous function starts a receive operation.

Precondition: A slave must have been selected using spiSelect() or spiSelectI().

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to receive
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 425 of file hal_spi_v2.inc.

References osalSysLock(), osalSysUnlock(), and spiStartReceiveI.

Here is the call graph for this function:

◆ spiStopTransferI()

msg_t spiStopTransferI	(	SPIDriver *	spip,
		size_t *	sizep )

Stops the ongoing SPI operation.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[out]	sizep	pointer to the counter of frames not yet transferred or `NULL`

Returns: The operation status.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 445 of file hal_spi_v2.inc.

References HAL_RET_SUCCESS, MSG_RESET, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, osalThreadResumeI(), SPI_ACTIVE, SPI_COMPLETE, spi_lld_stop_transfer(), SPI_READY, hal_spi_driver::state, and hal_spi_driver::sync_transfer.

Referenced by spiStopTransfer().

Here is the call graph for this function:

◆ spiStopTransfer()

msg_t spiStopTransfer	(	SPIDriver *	spip,
		size_t *	sizep )

Stops the ongoing SPI operation, if any.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[out]	sizep	pointer to the counter of frames not yet transferred or `NULL`

Returns: The operation status.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 484 of file hal_spi_v2.inc.

References osalOsRescheduleS(), osalSysLock(), osalSysUnlock(), and spiStopTransferI().

Here is the call graph for this function:

◆ spiSynchronizeS()

msg_t spiSynchronizeS	(	SPIDriver *	spip,
		sysinterval_t	timeout )

Synchronizes with current transfer completion.

Note: This function can only be called by a single thread at time.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	timeout	synchronization timeout

Returns: The synchronization result.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 511 of file hal_spi_v2.inc.

References MSG_OK, osalDbgAssert, osalDbgCheck, osalThreadSuspendTimeoutS(), SPI_ACTIVE, SPI_READY, hal_spi_driver::state, and hal_spi_driver::sync_transfer.

Referenced by spiExchange(), spiIgnore(), spiReceive(), spiSend(), and spiSynchronize().

Here is the call graph for this function:

◆ spiSynchronize()

msg_t spiSynchronize	(	SPIDriver *	spip,
		sysinterval_t	timeout )

Synchronizes with current transfer completion.

Note: This function can only be called by a single thread at time.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	timeout	synchronization timeout

Returns: The synchronization result.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 541 of file hal_spi_v2.inc.

References osalSysLock(), osalSysUnlock(), and spiSynchronizeS().

Here is the call graph for this function:

◆ spiIgnore()

msg_t spiIgnore	(	SPIDriver *	spip,
		size_t	n )

Ignores data on the SPI bus.

This synchronous function performs the transmission of a series of idle words on the SPI bus and ignores the received data.

Precondition: In order to use this function the option SPI_USE_SYNCHRONIZATION must be enabled.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be ignored

Returns: The operation status.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 567 of file hal_spi_v2.inc.

References MSG_OK, osalSysLock(), osalSysUnlock(), spiStartIgnoreI, spiSynchronizeS(), and TIME_INFINITE.

Here is the call graph for this function:

◆ spiExchange()

msg_t spiExchange	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf,
		void *	rxbuf )

Exchanges data on the SPI bus.

This synchronous function performs a simultaneous transmit/receive operation.

Precondition: In order to use this function the option SPI_USE_SYNCHRONIZATION must be enabled.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be exchanged
[in]	txbuf	the pointer to the transmit buffer
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 602 of file hal_spi_v2.inc.

References MSG_OK, osalSysLock(), osalSysUnlock(), spiStartExchangeI, spiSynchronizeS(), and TIME_INFINITE.

Here is the call graph for this function:

◆ spiSend()

msg_t spiSend	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf )

Sends data over the SPI bus.

This synchronous function performs a transmit operation.

Precondition: In order to use this function the option SPI_USE_SYNCHRONIZATION must be enabled.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to send
[in]	txbuf	the pointer to the transmit buffer

Returns: The operation status.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 636 of file hal_spi_v2.inc.

References MSG_OK, osalSysLock(), osalSysUnlock(), spiStartSendI, spiSynchronizeS(), and TIME_INFINITE.

Here is the call graph for this function:

◆ spiReceive()

msg_t spiReceive	(	SPIDriver *	spip,
		size_t	n,
		void *	rxbuf )

Receives data from the SPI bus.

This synchronous function performs a receive operation.

Precondition: In order to use this function the option SPI_USE_SYNCHRONIZATION must be enabled.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to receive
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Return values

MSG_OK	if operation completed without errors.
MSG_TIMEOUT	if synchronization timed out.
MSG_RESET	if the transfer has been stopped.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 669 of file hal_spi_v2.inc.

References MSG_OK, osalSysLock(), osalSysUnlock(), spiStartReceiveI, spiSynchronizeS(), and TIME_INFINITE.

Here is the call graph for this function:

◆ spiAcquireBus()

void spiAcquireBus ( SPIDriver * spip )

Gains exclusive access to the SPI bus.

This function tries to gain ownership to the SPI bus, if the bus is already being used then the invoking thread is queued.

Precondition: In order to use this function the option SPI_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 697 of file hal_spi_v2.inc.

References hal_spi_driver::mutex, osalDbgCheck, and osalMutexLock().

Here is the call graph for this function:

◆ spiReleaseBus()

void spiReleaseBus ( SPIDriver * spip )

Releases exclusive access to the SPI bus.

Precondition: In order to use this function the option SPI_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 713 of file hal_spi_v2.inc.

References hal_spi_driver::mutex, osalDbgCheck, and osalMutexUnlock().

Here is the call graph for this function:

◆ spi_lld_init()

void spi_lld_init ( void )

Low level SPI driver initialization.

Function Class:: Not an API, this function is for internal use only.

Definition at line 65 of file hal_spi_v2_lld.c.

References SPID1, and spiObjectInit().

Here is the call graph for this function:

◆ spi_lld_start()

msg_t spi_lld_start ( SPIDriver * spip )

Configures and activates the SPI peripheral.

Parameters

[in] spip pointer to the SPIDriver object

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 81 of file hal_spi_v2_lld.c.

References HAL_RET_IS_INVALID, HAL_RET_SUCCESS, osalDbgAssert, SPI_STOP, SPID1, and hal_spi_driver::state.

◆ spi_lld_stop()

void spi_lld_stop ( SPIDriver * spip )

Deactivates the SPI peripheral.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 111 of file hal_spi_v2_lld.c.

References osalDbgAssert, SPI_READY, SPID1, and hal_spi_driver::state.

◆ spi_lld_select()

void spi_lld_select ( SPIDriver * spip )

Asserts the slave select signal and prepares for transfers.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 139 of file hal_spi_v2_lld.c.

◆ spi_lld_unselect()

void spi_lld_unselect ( SPIDriver * spip )

Deasserts the slave select signal.

The previously selected peripheral is unselected.

Parameters

[in] spip pointer to the SPIDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 152 of file hal_spi_v2_lld.c.

◆ spi_lld_ignore()

msg_t spi_lld_ignore	(	SPIDriver *	spip,
		size_t	n )

Ignores data on the SPI bus.

This synchronous function performs the transmission of a series of idle words on the SPI bus and ignores the received data.

Precondition: In order to use this function the option SPI_USE_SYNCHRONIZATION must be enabled.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be ignored

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 171 of file hal_spi_v2_lld.c.

References HAL_RET_SUCCESS.

◆ spi_lld_exchange()

msg_t spi_lld_exchange	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf,
		void *	rxbuf )

Exchanges data on the SPI bus.

This asynchronous function starts a simultaneous transmit/receive operation.

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to be exchanged
[in]	txbuf	the pointer to the transmit buffer
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 195 of file hal_spi_v2_lld.c.

References HAL_RET_SUCCESS.

◆ spi_lld_send()

msg_t spi_lld_send	(	SPIDriver *	spip,
		size_t	n,
		const void *	txbuf )

Sends data over the SPI bus.

This asynchronous function starts a transmit operation.

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to send
[in]	txbuf	the pointer to the transmit buffer

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 220 of file hal_spi_v2_lld.c.

References HAL_RET_SUCCESS.

◆ spi_lld_receive()

msg_t spi_lld_receive	(	SPIDriver *	spip,
		size_t	n,
		void *	rxbuf )

Receives data from the SPI bus.

This asynchronous function starts a receive operation.

Postcondition: At the end of the operation the configured callback is invoked.

Note: The buffers are organized as uint8_t arrays for data sizes below or equal to 8 bits else it is organized as uint16_t arrays.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	n	number of words to receive
[out]	rxbuf	the pointer to the receive buffer

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 243 of file hal_spi_v2_lld.c.

References HAL_RET_SUCCESS.

◆ spi_lld_stop_transfer()

msg_t spi_lld_stop_transfer	(	SPIDriver *	spip,
		size_t *	sizep )

Aborts the ongoing SPI operation, if any.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[out]	sizep	pointer to the counter of frames not yet transferred or `NULL`

Returns: The operation status.

Function Class:: Not an API, this function is for internal use only.

Definition at line 262 of file hal_spi_v2_lld.c.

References HAL_RET_SUCCESS.

Referenced by spiStopTransferI().

◆ spi_lld_polled_exchange()

uint16_t spi_lld_polled_exchange	(	SPIDriver *	spip,
		uint16_t	frame )

Exchanges one frame using a polled wait.

This synchronous function exchanges one frame using a polled synchronization method. This function is useful when exchanging small amount of data on high speed channels, usually in this situation is much more efficient just wait for completion using polling than suspending the thread waiting for an interrupt.

Parameters

[in]	spip	pointer to the `SPIDriver` object
[in]	frame	the data frame to send over the SPI bus

Returns: The received data frame from the SPI bus.

Definition at line 282 of file hal_spi_v2_lld.c.

Variable Documentation

◆ SPID1

SPIDriver SPID1

SPI1 driver identifier.

Definition at line 41 of file hal_spi_v2_lld.c.

Detailed Description

Driver State Machine

Chip Select modes

SPI configuration options

Macro Functions

Low level driver helper macros

PLATFORM configuration options

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ SPI_SELECT_MODE_NONE

◆ SPI_SELECT_MODE_PAD

◆ SPI_SELECT_MODE_PORT

◆ SPI_SELECT_MODE_LINE

◆ SPI_SELECT_MODE_LLD

◆ SPI_USE_SYNCHRONIZATION

◆ SPI_USE_ASSERT_ON_ERROR

◆ SPI_USE_MUTUAL_EXCLUSION

◆ SPI_SELECT_MODE

◆ spiIsBufferComplete

◆ spiSelectI

◆ spiUnselectI

◆ spiPolledExchange

◆ spiAbortI

◆ spiAbort

◆ __spi_wakeup_isr

◆ __spi_isr_complete_code

◆ __spi_isr_half_code

◆ __spi_isr_full_code

◆ __spi_isr_error_code

◆ SPI_SUPPORTS_CIRCULAR

◆ SPI_SUPPORTS_SLAVE_MODE

◆ PLATFORM_SPI_USE_SPI1

◆ spi_lld_driver_fields

◆ spi_lld_config_fields

Typedef Documentation

◆ SPIDriver

◆ SPIConfig

◆ spicb_t

Enumeration Type Documentation

◆ spistate_t

Function Documentation

◆ spiInit()

◆ spiObjectInit()

◆ spiStart()

◆ spiStop()

◆ spiSelect()

◆ spiUnselect()

◆ spiStartIgnoreI()

◆ spiStartIgnore()

◆ spiStartExchangeI()

◆ spiStartExchange()

◆ spiStartSendI()

◆ spiStartSend()

◆ spiStartReceiveI()

◆ spiStartReceive()

◆ spiStopTransferI()

◆ spiStopTransfer()

◆ spiSynchronizeS()

◆ spiSynchronize()

◆ spiIgnore()

◆ spiExchange()

◆ spiSend()

◆ spiReceive()

◆ spiAcquireBus()

◆ spiReleaseBus()

◆ spi_lld_init()

◆ spi_lld_start()

◆ spi_lld_stop()

◆ spi_lld_select()

◆ spi_lld_unselect()

◆ spi_lld_ignore()

◆ spi_lld_exchange()

◆ spi_lld_send()

◆ spi_lld_receive()

◆ spi_lld_stop_transfer()