Defined behavior

More...

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 - Verified by fpga_spi_test_init_free, fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_get_capabilities() fills the given spi_capabilities_t instance - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
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 - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
The supported frequency range must include the range [0.2..2] MHz - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_free returns the pins owned by the SPI object to their reset state - Verified by fpga_spi_test_init_free
spi_format sets the number of bits per frame - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_format configures clock polarity and phase - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_format configures master/slave mode - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common; slave mode - TBD
spi_frequency sets the SPI baud rate - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_write writes a symbol out in master mode and receives a symbol - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_block_write writes tx_length words to the bus - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_block_write reads rx_length words from the bus - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_block_write returns the maximum of tx_length and rx_length - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_block_write specifies the write_fill which is default data transmitted while performing a read - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
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 - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_transfer writes tx_len words to the bus - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_transfer reads rx_len words from the bus - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_transfer specifies the bit width of buffer words - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
The callback given to spi_master_transfer is invoked when the transfer completes (with a success or an error) - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_master_transfer specifies the logical OR of events to be registered - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
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 - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_irq_handler_asynch writes values into the TX FIFO - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_irq_handler_asynch checks for transfer termination conditions, such as buffer overflows or transfer complete - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise 0 - Verified by fpga_spi_test_common_no_ss and fpga_spi_test_common
spi_abort_asynch aborts an on-going async transfer - TBD (basic test)
spi_active returns non-zero if the SPI port is active or zero if it is not - TBD (basic test)

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 while no async transfer is being processed (no transfer or a synchronous transfer)

Function Documentation

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.

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

void spi_free ( spi_t * obj )

Release a SPI object.

TODO: spi_free is currently unimplemented This will require reference counting at the C++ level to be safe

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

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

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.

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

Initialize the SPI peripheral.

Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral

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

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

Initialize the SPI peripheral.

Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral

Parameters

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

Defined behavior

Modules

Functions

Detailed Description

Defined behavior

Undefined behavior

Function Documentation

Important Information for this Arm website