SPI Master HAL

SPI Master Hardware Abstraction Layer API Reference. More...

Functions list
void	hal_spi_master_configure_default (hal_spi_master_config_t *config)
	Configure SPI Master configuration structure with default values. More...
err_t	hal_spi_master_open (handle_t *handle, bool hal_obj_open_state)
	Open the SPI Master HAL object on selected pins. More...
void	hal_spi_master_select_device (hal_pin_name_t chip_select)
	Select SPI Slave device. More...
void	hal_spi_master_deselect_device (hal_pin_name_t chip_select)
	Deselect SPI Slave device. More...
void	hal_spi_master_set_chip_select_polarity (hal_spi_master_chip_select_polarity_t polarity)
	Set desired chip select polarity. More...
void	hal_spi_master_set_default_write_data (handle_t *handle, hal_spi_master_config_t *config)
	Set SPI Master default ( dummy ) write data. More...
err_t	hal_spi_master_set_speed (handle_t *handle, hal_spi_master_config_t *config)
	Set desired SPI communication speed. More...
err_t	hal_spi_master_set_mode (handle_t *handle, hal_spi_master_config_t *config)
	Set desired SPI communication mode. More...
err_t	hal_spi_master_write (handle_t handle, uint8_t *__generic_ptr write_data_buffer, size_t write_data_length)
	Write byte to SPI bus. More...
err_t	hal_spi_master_read (handle_t handle, uint8_t *read_data_buffer, size_t read_data_length)
	Read byte from SPI bus. More...
err_t	hal_spi_master_write_then_read (handle_t handle, uint8_t *write_data_buffer, size_t length_write_data, uint8_t *read_data_buffer, size_t length_read_data)
	Perform a sequence of SPI Master writes immediately followed by a SPI Master read. More...
err_t	hal_spi_master_close (handle_t *handle)
	Close SPI Master HAL context object. More...

Detailed Description

API for configuring and manipulating SPI Master HAL module.

Function Documentation

hal_spi_master_configure_default()

void hal_spi_master_configure_default

(

hal_spi_master_config_t *

config

)

Configures structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

SPI Master HAL layer configuration settings. See hal_spi_master_config_t structure definition for detailed explanation.

Default values:

Function	Default value
SPI SCK pin	HAL_PIN_NC (invalid pin)
SPI MISO pin	HAL_PIN_NC (invalid pin)
SPI MOSI pin	HAL_PIN_NC (invalid pin)
SPI Speed	100KHz
SPI mode	0
SPI default write data	0

Returns

Nothing.

Example

// HAL SPI configuration structure.
hal_spi_master_config_t hal_spi_master_config;
 
// Populate structure to default init values.
hal_spi_master_configure_default( &hal_spi_master_config );

hal_spi_master_open()

err_t hal_spi_master_open	(	handle_t *	handle,
		bool	hal_obj_open_state
	)

Opens the SPI Master HAL object on selected pins. Allocates memory and pin for specified object.

Parameters

[in]	handle	SPI Master HAL object. See hal_spi_master_t structure definition for detailed explanation.
[in]	hal_obj_open_state	SPI Master configuration structure. See hal_spi_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Note

This function needs to be called before other HAL functions.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

hal_spi_master_t hal_spi_master;
 
// HAL SPI configuration structure.
hal_spi_master_config_t hal_spi_master_config;
 
// Populate structure to default init values.
hal_spi_master_configure_default( &hal_spi_master_config );
 
// Specify desired SPI Serial Clock pin.
hal_spi_master_config.sck = PC3;
 
// Specify desired SPI Master-In Slave-Out pin.
hal_spi_master_config.miso = PC4;
 
// Specify desired SPI Master-Out Slave-In pin.
hal_spi_master_config.mosi = PC5;
 
// Specify desired SPI transfer rate.
hal_spi_master_config.speed = 100000;
 
// Specify desired SPI Mode.
hal_spi_master_config.mode = SPI_MASTER_MODE_0;
 
// Specify SPI default write (dummy) data.
hal_spi_master_config.default_write_data = 0x00;
 
// Allocate resources for SPI module.
hal_spi_master_open( &hal_spi_master, &hal_spi_master_config );

hal_spi_master_select_device()

void hal_spi_master_select_device

(

hal_pin_name_t

chip_select

)

Sets digital output individual slave pin to logic 0.

Parameters

[in]

chip_select

Device-specific chip select pin.

Returns

Nothing.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Select desired device.
hal_spi_master_select_device( PA1 );

hal_spi_master_deselect_device()

void hal_spi_master_deselect_device

(

hal_pin_name_t

chip_select

)

Sets digital output individual slave pin to logic 1.

Parameters

[in]

chip_select

Device-specific chip select pin.

Returns

Nothing.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Deselect desired device.
hal_spi_master_deselect_device( PA1 );

hal_spi_master_set_chip_select_polarity()

void hal_spi_master_set_chip_select_polarity

(

hal_spi_master_chip_select_polarity_t

polarity

)

Sets SPI Master chip select polarity either to active low or active high. Chip select polarity shall be active low by default.

Parameters

[in]

polarity

Desired chip select polarity mode. See hal_spi_master_chip_select_polarity_t for valid values.

Returns

Nothing.

Example

// Specify desired chip-select polarity.
hal_spi_master_set_chip_select_polarity( HAL_SPI_MASTER_CHIP_SELECT_POLARITY_ACTIVE_LOW );

hal_spi_master_set_default_write_data()

void hal_spi_master_set_default_write_data	(	handle_t *	handle,
		hal_spi_master_config_t *	config
	)

Default write data is sent by driver when the data transmit buffer is shorter than data receive buffer.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[in]	config	HAL SPI Master config structure. See hal_spi_master_config_t structure definition for detailed explanation.

Returns

Nothing.

Precondition

Before calling this function, the user is expected to call hal_spi_master_open function.

Example

// Specify desired default write (dummy) data.
hal_spi_master_set_default_write_data( &handle, 0x00 );

hal_spi_master_set_speed()

err_t hal_spi_master_set_speed	(	handle_t *	handle,
		hal_spi_master_config_t *	config
	)

Sets SPI Master module speed to passed value if possible. If not possible, returns error. Make sure to check for return value. Initializes SPI module on hardware level.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[in]	config	HAL SPI Master config structure. See hal_spi_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_spi_master_open function.

Example

// Specify desired SPI transfer rate.
hal_spi_master_set_speed( &handle, 100000 );

hal_spi_master_set_mode()

err_t hal_spi_master_set_mode	(	handle_t *	handle,
		hal_spi_master_config_t *	config
	)

Sets SPI Master module mode to passed value if possible. If not possible, returns error. Make sure to check for return value. Initializes SPI module on hardware level.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[in]	config	HAL SPI Master config structure. See hal_spi_master_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_spi_master_open function.

Example

// Specify desired SPI mode.
hal_spi_master_set_mode( &handle, HAL_SPI_MASTER_MODE_0 );

hal_spi_master_write()

err_t hal_spi_master_write	(	handle_t	handle,
		uint8_t *__generic_ptr	write_data_buffer,
		size_t	write_data_length
	)

Writes byte to SPI bus in blocking mode. Received byte is discarded.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[in]	write_data_buffer	Value to send.
[in]	write_data_length	Number of bytes to write from data buffer.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_spi_master_open function.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be written.
#define DATA_LENGTH 150
 
// Specify data structure for data to be sent.
uint8_t write_sequence[ DATA_LENGTH ];
 
// Specify i.e. 0th element to be sent.
write_sequence[0] = 0x02;
 
// Specify i.e. 1st element to be sent.
write_sequence[1] = 0x05;
 
// Write specified data on SPI bus.
hal_spi_master_write( handle, &write_sequence, DATA_LENGTH );

hal_spi_master_read()

err_t hal_spi_master_read	(	handle_t	handle,
		uint8_t *	read_data_buffer,
		size_t	read_data_length
	)

Reads byte from SPI bus in blocking mode. Transmitted byte is user-defined default (dummy) write data.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[out]	read_data_buffer	Read buffer.
[in]	read_data_length	Number of bytes to be read.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_spi_master_open function.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be read.
#define DATA_LENGTH 150
 
// Specify data structure for data to be read.
uint8_t read_sequence[ DATA_LENGTH ];
 
// Read specified data on SPI bus.
hal_spi_master_read( handle, &read_sequence, DATA_LENGTH );

hal_spi_master_write_then_read()

err_t hal_spi_master_write_then_read	(	handle_t	handle,
		uint8_t *	write_data_buffer,
		size_t	length_write_data,
		uint8_t *	read_data_buffer,
		size_t	length_read_data
	)

Writes a sequence of bytes to SPI bus, followed by a corresponding read.

Parameters

[in]	handle	SPI master handle. See hal_spi_master_t structure definition for detailed explanation.
[in]	write_data_buffer	Value to send.
[in]	length_write_data	Number of bytes to write from data buffer.
[out]	read_data_buffer	Read buffer.
[in]	length_read_data	Number of bytes to be read.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call spi_master_open function. Before calling this function.

Note

If the transmitted data sequence is shorter than the received data sequence, the remaining places in the data transmit buffer will be populated with user-defined data. See hal_spi_master_set_default_write_data function for more details.

Warning

The following example describes only how the function is used. This is not a working example.

Example

// Specify length of data to be written and read.
#define DATA_LENGTH 150
 
// Specify data structure for data to be sent.
uint8_t write_sequence[ DATA_LENGTH ];
 
// Specify data structure for data to be read.
uint8_t read_sequence[ DATA_LENGTH ];
 
// Specify i.e. 0th element to be sent.
write_sequence[0] = 0x02;
 
// Specify i.e. 1st element to be sent.
write_sequence[1] = 0x05;
 
// Write then read specified data on SPI bus.
hal_spi_master_write_then_read( handle, &write_sequence,
 DATA_LENGTH,
 &read_sequence,
 DATA_LENGTH );

hal_spi_master_close()

err_t hal_spi_master_close

(

handle_t *

handle

)

Closes SPI Master HAL context object, resets pin AF to default values and clears all buffers used by object.

Parameters

[in,out]

handle

SPI master handle. See hal_spi_master_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_spi_master_err_t, which is size dependant on the architecture.

Example

// Close the SPI module object handler.
hal_spi_master_close( &handle );