SPI Configuration Functions

Modules
	SPI hal tests
	The SPI HAL tests ensure driver conformance to defined behaviour.

Functions
void	spi_get_capabilities (PinName ssel, bool slave, spi_capabilities_t *cap)
	Fills the given spi_capabilities_t structure with the capabilities of the given peripheral. More...
void	spi_init_direct (spi_t *obj, const spi_pinmap_t *pinmap)
	Initialize the SPI peripheral. More...
void	spi_init (spi_t *obj, PinName mosi, PinName miso, PinName sclk, PinName ssel)
	Initialize the SPI peripheral. More...
void	spi_free (spi_t *obj)
	Release a SPI object. More...
void	spi_format (spi_t *obj, int bits, int mode, int slave)
	Configure the SPI format. More...
void	spi_frequency (spi_t *obj, int hz)
	Set the SPI baud rate. More...

Detailed Description

Defined behavior

• spi_init initializes the spi_t control structure
• spi_init configures the pins used by SPI
• spi_get_capabilities() fills the given spi_capabilities_t instance
• spi_get_capabilities() should consider the ssel pin when evaluation the support_slave_mode and hw_cs_handle capability - TBD (basic test)
• spi_get_capabilities(): if the given ssel pin cannot be managed by hardware, support_slave_mode and hw_cs_handle should be false - TBD (basic test)
• At least a symbol width of 8bit must be supported
• The supported frequency range must include the range [0.2..2] MHz
• spi_free returns the pins owned by the SPI object to their reset state
• spi_format sets the number of bits per frame
• spi_format configures clock polarity and phase
• spi_format configures master/slave mode
• spi_frequency sets the SPI baud rate
• spi_master_write writes a symbol out in master mode and receives a symbol
• spi_master_block_write writes tx_length words to the bus
• spi_master_block_write reads rx_length words from the bus
• spi_master_block_write returns the maximum of tx_length and rx_length
• spi_master_block_write specifies the write_fill which is default data transmitted while performing a read
• spi_get_module returns the SPI module number - TBD (basic test)
• spi_slave_read returns a received value out of the SPI receive buffer in slave mode - TBD (SPI slave test)
• spi_slave_read blocks until a value is available - TBD (SPI slave test)
• spi_slave_write writes a value to the SPI peripheral in slave mode - TBD (SPI slave test)
• spi_slave_write blocks until the SPI peripheral can be written to - TBD (SPI slave test)
• spi_busy returns non-zero if the peripheral is currently transmitting, 0 otherwise - TBD (basic test)
• spi_master_transfer starts the SPI asynchronous transfer
• spi_master_transfer writes tx_len words to the bus
• spi_master_transfer reads rx_len words from the bus
• spi_master_transfer specifies the bit width of buffer words
• The callback given to spi_master_transfer is invoked when the transfer completes (with a success or an error)
• spi_master_transfer specifies the logical OR of events to be registered
• The spi_master_transfer function may use the DMAUsage hint to select the appropriate async algorithm - Not testable
• spi_irq_handler_asynch reads the received values out of the RX FIFO
• spi_irq_handler_asynch writes values into the TX FIFO
• spi_irq_handler_asynch checks for transfer termination conditions, such as buffer overflows or transfer complete
• spi_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise 0
• spi_abort_asynch aborts an on-going async transfer
• spi_active returns non-zero if the SPI port is active or zero if it is not

Undefined behavior

• Calling spi_init multiple times on the same spi_t without spi_free
• Calling any function other than spi_init on a non-initialized or freed spi_t
• Passing pins that cannot be on the same peripheral
• Passing an invalid pointer as obj to any function
• Passing an invalid pointer as handler to spi_master_transfer
• Calling spi_abort_asynch while no async transfer is being processed (no transfer or a synchronous transfer)

Function Documentation

spi_get_capabilities()

void spi_get_capabilities	(	PinName	ssel,
		bool	slave,
		spi_capabilities_t *	cap
	)

Fills the given spi_capabilities_t structure with the capabilities of the given peripheral.

spi_init_direct()

void spi_init_direct	(	spi_t *	obj,
		const spi_pinmap_t *	pinmap
	)

Initialize the SPI peripheral.

Configures the pins used by SPI and enables the peripheral.

After this function is called by the driver layer, spi_format() and spi_frequency() will be called before the SPI bus is used.

Parameters

[out]	obj	The SPI object to initialize
[in]	pinmap	pointer to structure which holds static pinmap

spi_init()

void spi_init	(	spi_t *	obj,
		PinName	mosi,
		PinName	miso,
		PinName	sclk,
		PinName	ssel
	)

Initialize the SPI peripheral.

Configures the pins used by SPI and enables the peripheral

After this function is called by the driver layer, spi_format() and spi_frequency() will be called before the SPI bus is used.

Parameters

[out]	obj	The SPI object to initialize
[in]	mosi	The pin to use for MOSI
[in]	miso	The pin to use for MISO
[in]	sclk	The pin to use for SCLK
[in]	ssel	The pin to use for SSEL

spi_free()

void spi_free

(

spi_t *

obj

)

Release a SPI object.

Return the pins owned by the SPI object to their reset state Disable the SPI peripheral Disable the SPI clock

Parameters

[in]

obj

The SPI object to deinitialize

spi_format()

void spi_format	(	spi_t *	obj,
		int	bits,
		int	mode,
		int	slave
	)

Configure the SPI format.

Set the number of bits per frame, configure clock polarity and phase, shift order and master/slave mode. The default bit order is MSB.

This function shall NOT modify the SPI frequency if the SPI frequency has previously been set.

Parameters

[in,out]	obj	The SPI object to configure
[in]	bits	The number of bits per frame
[in]	mode	The SPI mode (clock polarity, phase, and shift direction)
[in]	slave	Zero for master mode or non-zero for slave mode

spi_frequency()

void spi_frequency	(	spi_t *	obj,
		int	hz
	)

Set the SPI baud rate.

Actual frequency may differ from the desired frequency due to available dividers and bus clock Configures the SPI peripheral's baud rate

Parameters

[in,out]	obj	The SPI object to configure
[in]	hz	The baud rate in Hz