Generic SPI Driver (legacy). More...

Detailed Description

Generic SPI Driver (legacy).

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 SPIv1 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_WAIT TRUE
	Enables synchronous APIs.
#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	spiStartIgnoreI(spip, n)
	Ignores data on the SPI bus.
#define	spiStartExchangeI(spip, n, txbuf, rxbuf)
	Exchanges data on the SPI bus.
#define	spiStartSendI(spip, n, txbuf)
	Sends data over the SPI bus.
#define	spiStartReceiveI(spip, n, rxbuf)
	Receives data from the SPI bus.
#define	spiPolledExchange(spip, frame)
	Exchanges one frame using a polled wait.

Low level driver helper macros
#define	_spi_wakeup_isr(spip)
	Wakes up the waiting thread.
#define	_spi_isr_code(spip)
	Common ISR code when circular mode is not supported.
#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.

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_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(*	spicallback_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.
void	spiStartIgnore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
void	spiStartExchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
void	spiStartSend (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
void	spiStartReceive (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
void	spiAbortI (SPIDriver *spip)
	Aborts the ongoing SPI operation.
void	spiAbort (SPIDriver *spip)
	Aborts the ongoing SPI operation, if any.
void	spiIgnore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
void	spiExchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
void	spiSend (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
void	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.
void	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.
void	spi_lld_ignore (SPIDriver *spip, size_t n)
	Ignores data on the SPI bus.
void	spi_lld_exchange (SPIDriver spip, size_t n, const void txbuf, void *rxbuf)
	Exchanges data on the SPI bus.
void	spi_lld_send (SPIDriver spip, size_t n, const void txbuf)
	Sends data over the SPI bus.
void	spi_lld_receive (SPIDriver spip, size_t n, void rxbuf)
	Receives data from the SPI bus.
void	spi_lld_abort (SPIDriver *spip)
	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_v1.h.

◆ SPI_SELECT_MODE_PAD

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

Definition at line 39 of file hal_spi_v1.h.

◆ SPI_SELECT_MODE_PORT

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

Definition at line 40 of file hal_spi_v1.h.

◆ SPI_SELECT_MODE_LINE

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

Definition at line 41 of file hal_spi_v1.h.

◆ SPI_SELECT_MODE_LLD

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

Definition at line 42 of file hal_spi_v1.h.

◆ SPI_USE_WAIT

#define SPI_USE_WAIT TRUE

Enables synchronous APIs.

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

Definition at line 58 of file hal_spi_v1.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 66 of file hal_spi_v1.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 74 of file hal_spi_v1.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 231 of file hal_spi_v1.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 241 of file hal_spi_v1.h.

Referenced by spiSelect().

◆ 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 254 of file hal_spi_v1.h.

Referenced by spiUnselect().

◆ spiStartIgnoreI

#define spiStartIgnoreI	(		spip,
			n )

Value:

  {                                          \
  (spip)->state = SPI_ACTIVE;                                               \
  spi_lld_ignore(spip, 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

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 311 of file hal_spi_v1.h.

Referenced by spiIgnore(), and spiStartIgnore().

◆ spiStartExchangeI

#define spiStartExchangeI	(	spip,
		n,
		txbuf,
		rxbuf )

Value:

  {                          \
  (spip)->state = SPI_ACTIVE;                                               \
  spi_lld_exchange(spip, n, txbuf, 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

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 333 of file hal_spi_v1.h.

Referenced by spiExchange(), and spiStartExchange().

◆ spiStartSendI

#define spiStartSendI	(	spip,
		n,
		txbuf )

Value:

  {                                     \
  (spip)->state = SPI_ACTIVE;                                               \
  spi_lld_send(spip, n, 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

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 353 of file hal_spi_v1.h.

Referenced by spiSend(), and spiStartSend().

◆ spiStartReceiveI

#define spiStartReceiveI	(	spip,
		n,
		rxbuf )

Value:

  {                                  \
  (spip)->state = SPI_ACTIVE;                                               \
  spi_lld_receive(spip, n, 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

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 373 of file hal_spi_v1.h.

Referenced by spiReceive(), and spiStartReceive().

◆ 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 391 of file hal_spi_v1.h.

◆ _spi_wakeup_isr

#define _spi_wakeup_isr ( spip )

Value:

  {                                             \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(spip)->thread, MSG_OK);                               \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread.

Parameters

[in] spip pointer to the SPIDriver object

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

Definition at line 406 of file hal_spi_v1.h.

◆ _spi_isr_code

#define _spi_isr_code ( spip )

Value:

  {                                               \
  if ((spip)->config->end_cb) {                                             \
    (spip)->state = SPI_COMPLETE;                                           \
    (spip)->config->end_cb(spip);                                           \
    if ((spip)->state == SPI_COMPLETE)                                      \
      (spip)->state = SPI_READY;                                            \
  }                                                                         \
  else                                                                      \
    (spip)->state = SPI_READY;                                              \
  _spi_wakeup_isr(spip);                                                    \
}

Common ISR code when circular mode is not supported.

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 429 of file hal_spi_v1.h.

◆ _spi_isr_half_code

#define _spi_isr_half_code ( spip )

Value:

  {                                          \
  if ((spip)->config->end_cb) {                                             \
    (spip)->config->end_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 453 of file hal_spi_v1.h.

◆ _spi_isr_full_code

#define _spi_isr_full_code ( spip )

Value:

  {                                          \
  if ((spip)->config->end_cb) {                                             \
    (spip)->state = SPI_COMPLETE;                                           \
    (spip)->config->end_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 472 of file hal_spi_v1.h.

◆ SPI_SUPPORTS_CIRCULAR

#define SPI_SUPPORTS_CIRCULAR TRUE

Circular mode support flag.

Definition at line 37 of file hal_spi_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 53 of file hal_spi_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 72 of file hal_spi_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 79 of file hal_spi_lld.h.

Typedef Documentation

◆ SPIDriver

typedef struct hal_spi_driver SPIDriver

Type of a structure representing an SPI driver.

Definition at line 117 of file hal_spi_v1.h.

◆ SPIConfig

typedef struct hal_spi_config SPIConfig

Type of a SPI driver configuration structure.

Definition at line 121 of file hal_spi_v1.h.

◆ spicallback_t

typedef void(* spicallback_t) (SPIDriver *spip)

SPI notification callback type.

Parameters

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

Definition at line 129 of file hal_spi_v1.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 106 of file hal_spi_v1.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_v1.inc.

References spi_lld_init().

Referenced by halInit().

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_v1.inc.

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

Referenced by spi_lld_init().

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_v1.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.

Referenced by __xsnor_bus_acquire(), mmcConnect(), mmcDisconnect(), mmcStartSequentialRead(), mmcStartSequentialWrite(), mmcSync(), snorStart(), and xsnorStart().

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 126 of file hal_spi_v1.inc.

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

Referenced by bus_stop(), mmcConnect(), mmcDisconnect(), mmcStop(), and xsnorStop().

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 149 of file hal_spi_v1.inc.

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

Referenced by __xsnor_bus_cmd(), __xsnor_bus_cmd_addr(), __xsnor_bus_cmd_addr_dummy_receive(), __xsnor_bus_cmd_addr_receive(), __xsnor_bus_cmd_addr_send(), __xsnor_bus_cmd_dummy_receive(), __xsnor_bus_cmd_receive(), __xsnor_bus_cmd_send(), bus_cmd(), bus_cmd_addr(), bus_cmd_addr_dummy_receive(), bus_cmd_addr_receive(), bus_cmd_addr_send(), bus_cmd_dummy_receive(), bus_cmd_receive(), bus_cmd_send(), mmc_read_CxD(), mmc_send_command_R1(), mmc_send_command_R3(), mmcDisconnect(), mmcStartSequentialRead(), mmcStartSequentialWrite(), and mmcSync().

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 167 of file hal_spi_v1.inc.

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

Referenced by __xsnor_bus_cmd(), __xsnor_bus_cmd_addr(), __xsnor_bus_cmd_addr_dummy_receive(), __xsnor_bus_cmd_addr_receive(), __xsnor_bus_cmd_addr_send(), __xsnor_bus_cmd_dummy_receive(), __xsnor_bus_cmd_receive(), __xsnor_bus_cmd_send(), bus_cmd(), bus_cmd_addr(), bus_cmd_addr_dummy_receive(), bus_cmd_addr_receive(), bus_cmd_addr_send(), bus_cmd_dummy_receive(), bus_cmd_receive(), bus_cmd_send(), mmc_read_CxD(), mmc_send_command_R1(), mmc_send_command_R3(), mmcDisconnect(), mmcSequentialRead(), mmcSequentialWrite(), mmcStartSequentialRead(), mmcStartSequentialWrite(), mmcStopSequentialRead(), mmcStopSequentialWrite(), and mmcSync().

Here is the call graph for this function:

◆ spiStartIgnore()

void 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

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

Definition at line 190 of file hal_spi_v1.inc.

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

Here is the call graph for this function:

◆ spiStartExchange()

void 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

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

Definition at line 217 of file hal_spi_v1.inc.

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

Here is the call graph for this function:

◆ spiStartSend()

void 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

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

Definition at line 244 of file hal_spi_v1.inc.

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

Here is the call graph for this function:

◆ spiStartReceive()

void 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

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

Definition at line 269 of file hal_spi_v1.inc.

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

Here is the call graph for this function:

◆ spiAbortI()

void spiAbortI ( SPIDriver * spip )

Aborts the ongoing SPI operation.

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 287 of file hal_spi_v1.inc.

References MSG_OK, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, osalThreadResumeI(), SPI_ACTIVE, SPI_COMPLETE, spi_lld_abort(), SPI_READY, hal_spi_driver::state, and hal_spi_driver::thread.

Here is the call graph for this function:

◆ spiAbort()

void spiAbort ( SPIDriver * spip )

Aborts the ongoing SPI operation, if any.

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 309 of file hal_spi_v1.inc.

References osalDbgAssert, osalOsRescheduleS(), osalSysLock(), osalSysUnlock(), SPI_ACTIVE, SPI_READY, spiAbortI, and hal_spi_driver::state.

Here is the call graph for this function:

◆ spiIgnore()

void 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_WAIT must be enabled.

Parameters

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

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

Definition at line 335 of file hal_spi_v1.inc.

References hal_spi_config::circular, hal_spi_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), SPI_READY, spiStartIgnoreI, hal_spi_driver::state, and hal_spi_driver::thread.

Referenced by __xsnor_bus_cmd_addr_dummy_receive(), __xsnor_bus_cmd_dummy_receive(), bus_cmd_addr_dummy_receive(), bus_cmd_dummy_receive(), mmc_read_CxD(), mmcConnect(), mmcSequentialRead(), and mmcSequentialWrite().

Here is the call graph for this function:

◆ spiExchange()

void 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_WAIT 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

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

Definition at line 365 of file hal_spi_v1.inc.

References hal_spi_config::circular, hal_spi_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), SPI_READY, spiStartExchangeI, hal_spi_driver::state, and hal_spi_driver::thread.

Here is the call graph for this function:

◆ spiSend()

void 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_WAIT 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

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

Definition at line 395 of file hal_spi_v1.inc.

References hal_spi_config::circular, hal_spi_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), SPI_READY, spiStartSendI, hal_spi_driver::state, and hal_spi_driver::thread.

Referenced by __xsnor_bus_cmd(), __xsnor_bus_cmd_addr_send(), __xsnor_bus_cmd_dummy_receive(), __xsnor_bus_cmd_receive(), __xsnor_bus_cmd_send(), __xsnor_spi_cmd_addr(), bus_cmd(), bus_cmd_addr_send(), bus_cmd_dummy_receive(), bus_cmd_receive(), bus_cmd_send(), mmc_send_hdr(), mmcSequentialWrite(), mmcStopSequentialRead(), mmcStopSequentialWrite(), and snor_spi_cmd_addr().

Here is the call graph for this function:

◆ spiReceive()

void 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_WAIT 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

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

Definition at line 423 of file hal_spi_v1.inc.

References hal_spi_config::circular, hal_spi_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), SPI_READY, spiStartReceiveI, hal_spi_driver::state, and hal_spi_driver::thread.

Referenced by __xsnor_bus_cmd_addr_dummy_receive(), __xsnor_bus_cmd_addr_receive(), __xsnor_bus_cmd_dummy_receive(), __xsnor_bus_cmd_receive(), bus_cmd_addr_dummy_receive(), bus_cmd_addr_receive(), bus_cmd_dummy_receive(), bus_cmd_receive(), mmc_read_CxD(), mmc_recvr1(), mmc_recvr3(), mmc_wait_idle(), mmcSequentialRead(), and mmcSequentialWrite().

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 450 of file hal_spi_v1.inc.

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

Referenced by __xsnor_bus_acquire(), mmc_connect(), mmc_disconnect(), mmc_read(), mmc_sync(), and mmc_write().

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 466 of file hal_spi_v1.inc.

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

Referenced by __xsnor_bus_release(), mmc_connect(), mmc_disconnect(), mmc_read(), mmc_sync(), and mmc_write().

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_lld.c.

References SPID1, and spiObjectInit().

Referenced by spiInit().

Here is the call graph for this function:

◆ spi_lld_start()

void spi_lld_start ( SPIDriver * spip )

Configures and activates 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 80 of file hal_spi_lld.c.

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

Referenced by spiStart().

◆ 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 110 of file hal_spi_lld.c.

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

Referenced by spiStop().

◆ 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 138 of file hal_spi_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_lld.c.

◆ spi_lld_ignore()

void spi_lld_ignore	(	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.

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

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

Definition at line 170 of file hal_spi_lld.c.

Referenced by spiStartIgnoreI().

◆ spi_lld_exchange()

void 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

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

Definition at line 192 of file hal_spi_lld.c.

Referenced by spiStartExchangeI().

◆ spi_lld_send()

void 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

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

Definition at line 215 of file hal_spi_lld.c.

Referenced by spiStartSendI().

◆ spi_lld_receive()

void 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

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

Definition at line 236 of file hal_spi_lld.c.

Referenced by spiStartReceiveI().

◆ spi_lld_abort()

void spi_lld_abort ( SPIDriver * spip )

Aborts the ongoing SPI operation, if any.

Parameters

[in] spip pointer to the SPIDriver object

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

Definition at line 252 of file hal_spi_lld.c.

Referenced by spiAbortI().

◆ 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.

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

Definition at line 272 of file hal_spi_lld.c.

Variable Documentation

◆ SPID1

SPIDriver SPID1

SPI1 driver identifier.

Definition at line 41 of file hal_spi_lld.c.

Referenced by spi_lld_init(), spi_lld_start(), and spi_lld_stop().

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_WAIT

◆ SPI_USE_MUTUAL_EXCLUSION

◆ SPI_SELECT_MODE

◆ spiIsBufferComplete

◆ spiSelectI

◆ spiUnselectI

◆ spiStartIgnoreI

◆ spiStartExchangeI

◆ spiStartSendI

◆ spiStartReceiveI

◆ spiPolledExchange

◆ _spi_wakeup_isr

◆ _spi_isr_code

◆ _spi_isr_half_code

◆ _spi_isr_full_code

◆ SPI_SUPPORTS_CIRCULAR

◆ PLATFORM_SPI_USE_SPI1

◆ spi_lld_driver_fields

◆ spi_lld_config_fields

Typedef Documentation

◆ SPIDriver

◆ SPIConfig

◆ spicallback_t

Enumeration Type Documentation

◆ spistate_t

Function Documentation

◆ spiInit()

◆ spiObjectInit()

◆ spiStart()

◆ spiStop()

◆ spiSelect()

◆ spiUnselect()

◆ spiStartIgnore()

◆ spiStartExchange()

◆ spiStartSend()

◆ spiStartReceive()

◆ spiAbortI()

◆ spiAbort()

◆ 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_abort()

◆ spi_lld_polled_exchange()

Variable Documentation

◆ SPID1