MT2523 API Reference  LinkIt SDK v4
SPI_MASTER

This section introduces the Serial Peripheral Interface Master (SPI_Master) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions. More...

Overview

This section introduces the Serial Peripheral Interface Master (SPI_Master) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, enums, structures and functions.

Terms and acronyms

Terms Details
DMA Direct Memory Access. DMA is a feature of computer systems that allows certain hardware subsystems to access main system memory independent from the central processing unit (CPU).
FIFO First In, First Out. FIFO is a method for organizing and manipulating a data buffer, where the first entry, or 'head' of the queue, is processed first.
GPIO General Purpose Inputs-Outputs. For more details, please refer to GPIO.
NVIC Nested Vectored Interrupt Controller. NVIC is the interrupt controller of ARM Cortex-M series processors. For more details, please refer to ARM Cortex-M4 technical reference manual.
SPI Serial Peripheral Interface. The Serial Peripheral Interface bus is a synchronous serial communication interface specification used for short distance communication. For more information, please check Serial Peripheral Interface Bus in Wikipedia.

Supported features

This controller supports a wide range of SPI interface devices, including full-duplex transaction ability to communicate with both half-duplex and full-duplex devices. For half-duplex devices, the data flow direction is not relevant for the software. Hardware provides access for various timing adjustments.

Software architecture of the SPI

How to use this driver

Functions

hal_spi_master_status_t hal_spi_master_init (hal_spi_master_port_t master_port, hal_spi_master_config_t *spi_config)
 This function is mainly used to initialize the SPI master and set user defined common parameters like clock frequency, bit order, clock polarity, clock phase and default settings. More...
 
hal_spi_master_status_t hal_spi_master_deinit (hal_spi_master_port_t master_port)
 This function resets the SPI master, gates its clock, disables interrupts. More...
 
hal_spi_master_status_t hal_spi_master_set_advanced_config (hal_spi_master_port_t master_port, hal_spi_master_advanced_config_t *advanced_config)
 SPI master advanced configuration function. More...
 
hal_spi_master_status_t hal_spi_master_send_polling (hal_spi_master_port_t master_port, uint8_t *data, uint32_t size)
 This function is used to send data synchronously with FIFO mode. More...
 
hal_spi_master_status_t hal_spi_master_send_dma (hal_spi_master_port_t master_port, uint8_t *data, uint32_t size)
 This function is used to send data asynchronously with DMA mode. More...
 
hal_spi_master_status_t hal_spi_master_send_dma_blocking (hal_spi_master_port_t master_port, uint8_t *data, uint32_t size)
 This function is used to send data synchronously with DMA mode. More...
 
hal_spi_master_status_t hal_spi_master_send_and_receive_polling (hal_spi_master_port_t master_port, hal_spi_master_send_and_receive_config_t *spi_send_and_receive_config)
 This function simultaneously sends and receives data in the FIFO mode. More...
 
hal_spi_master_status_t hal_spi_master_send_and_receive_dma (hal_spi_master_port_t master_port, hal_spi_master_send_and_receive_config_t *spi_send_and_receive_config)
 This function is used to send and receive data asynchronously with DMA mode. More...
 
hal_spi_master_status_t hal_spi_master_send_and_receive_dma_blocking (hal_spi_master_port_t master_port, hal_spi_master_send_and_receive_config_t *spi_send_and_receive_config)
 This function simultaneously sends and receives data in the DMA mode. More...
 
hal_spi_master_status_t hal_spi_master_get_running_status (hal_spi_master_port_t master_port, hal_spi_master_running_status_t *running_status)
 This function gets current running status of the SPI master. More...
 
hal_spi_master_status_t hal_spi_master_set_chip_select_timing (hal_spi_master_port_t master_port, hal_spi_master_chip_select_timing_t chip_select_timing)
 This function is used to configure SPI master chip select timing parameter. More...
 
hal_spi_master_status_t hal_spi_master_set_deassert (hal_spi_master_port_t master_port, hal_spi_master_deassert_t deassert)
 SPI master chip select de-assertion mode configuration. More...
 
hal_spi_master_status_t hal_spi_master_set_macro_selection (hal_spi_master_port_t master_port, hal_spi_master_macro_select_t macro_select)
 SPI master macro group configuration. More...
 
hal_spi_master_status_t hal_spi_master_register_callback (hal_spi_master_port_t master_port, hal_spi_master_callback_t callback, void *user_data)
 This function is used to register user's callback to SPI master driver. More...
 

Modules

 Define
 
 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_spi_master_status_t hal_spi_master_deinit ( hal_spi_master_port_t  master_port)

This function resets the SPI master, gates its clock, disables interrupts.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT means master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_OK means this function return successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_init()
hal_spi_master_status_t hal_spi_master_get_running_status ( hal_spi_master_port_t  master_port,
hal_spi_master_running_status_t running_status 
)

This function gets current running status of the SPI master.

Note this API can only be called after hal_spi_master_init().

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[out]running_statusis the current running status. HAL_SPI_MASTER_BUSY, the SPI master is in busy status;
HAL_SPI_MASTER_IDLE, the SPI master is in idle status, user can use it to transfer data now.
Returns
HAL_SPI_MASTER_STATUS_ERROR, this API is called before hal_spi_master_init() is called;
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, running_status parameter is NULL;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
hal_spi_master_status_t hal_spi_master_init ( hal_spi_master_port_t  master_port,
hal_spi_master_config_t spi_config 
)

This function is mainly used to initialize the SPI master and set user defined common parameters like clock frequency, bit order, clock polarity, clock phase and default settings.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]spi_configis the SPI master configure parameters. Details are described at hal_spi_master_config_t.
Returns
HAL_SPI_MASTER_STATUS_ERROR means function error;
HAL_SPI_MASTER_STATUS_ERROR_BUSY means this port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_ERROR_PORT means master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER means an invalid parameter is given by user;
HAL_SPI_MASTER_STATUS_OK means this function return successfully.
Note
hal_spi_master_deinit() must be called when the SPI master is no longer in use, release the SPI master resource for the other users to use this SPI master. Please DO NOT call hal_spi_master_init() in interrupt handler, it may cause deadlock. In a multi-task applications, if hal_spi_master_init() returns error HAL_SPI_MASTER_STATUS_ERROR_BUSY, it is suggested to call functions that release the CPU and try again later.
Example
1 hal_spi_master_status_t user_spi_master_init(void)
2 {
3  hal_spi_master_port_t spi_port;
4  hal_spi_master_config_t spi_configure;
5  hal_spi_master_status_t error_status;
6  uint32_t try_times = 0;
7 
8  spi_port = HAL_SPI_SLAVE_0;
9  spi_config.bit_order = HAL_SPI_MASTER_LSB_FIRST;
10  spi_config.clock_frequency = 1000000;
11  spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE0;
12  spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY0;
13 
14  while (try_times < 10) {
15  error_status = hal_spi_master_init(spi_port, &spi_configure);
16  if (error_status == HAL_SPI_MASTER_STATUS_ERROR_BUSY) {
17  vTaskDelay((portTickType)100 / portTICK_RATE_MS);
18  try_times ++;
19  } else {
20  break;
21  }
22  }
23  return error_status;
24 }
See also
hal_spi_master_deinit()
hal_spi_master_status_t hal_spi_master_register_callback ( hal_spi_master_port_t  master_port,
hal_spi_master_callback_t  callback,
void *  user_data 
)

This function is used to register user's callback to SPI master driver.

This function should be called when user wants to use the DMA mode, the callback will be called in SPI interrupt service routine.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]callbackis the callback function given by user, which will be called at SPI master interrupt service routine.
[in]user_datais a parameter given by user and will pass to user while the callback function is called. See the last parameter of hal_spi_master_callback_t.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_send_dma(), hal_spi_master_send_and_receive_dma()
hal_spi_master_status_t hal_spi_master_send_and_receive_dma ( hal_spi_master_port_t  master_port,
hal_spi_master_send_and_receive_config_t spi_send_and_receive_config 
)

This function is used to send and receive data asynchronously with DMA mode.

This function returns immediately, before calling this function, call hal_spi_master_register_callback() to register a callback, once the transaction is complete, the callback will be called in the SPI ISR.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]spi_send_and_receive_configis the structure that contains data buffer and data size, please refer to hal_spi_master_send_and_receive_config_t , for more details. Check the SPI device's datasheet to determine if the data is sent or received. For example, if ADIS16375 is used in full duplex communication mode, the data is received, while send command is valid. If PAH8001EI-2G sensor is used, the data is received, while send command is invalid. The address parameters must be non-cacheable and cannot be NULL.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter in spi_send_and_receive_config is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_send_dma()
hal_spi_master_status_t hal_spi_master_send_and_receive_dma_blocking ( hal_spi_master_port_t  master_port,
hal_spi_master_send_and_receive_config_t spi_send_and_receive_config 
)

This function simultaneously sends and receives data in the DMA mode.

This function doesn't return until the transfer is complete. Normally this function is used in the scenario where the IRQ must be disabled.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]spi_send_and_receive_configis the structure that contains data buffer and data size, please refer to hal_spi_master_send_and_receive_config_t , for more details. Check the SPI device's datasheet to determine if the data is sent or received. For example, if ADIS16375 is used in full duplex communication mode, the data is received, while send command is valid. If PAH8001EI-2G sensor is used, the data is received, while send command is invalid. The address parameters must be non-cacheable and cannot be NULL.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter in spi_send_and_receive_config is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_send_dma_blocking()
hal_spi_master_status_t hal_spi_master_send_and_receive_polling ( hal_spi_master_port_t  master_port,
hal_spi_master_send_and_receive_config_t spi_send_and_receive_config 
)

This function simultaneously sends and receives data in the FIFO mode.

This function doesn't return until the transfer is complete.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]spi_send_and_receive_configis the structure that contains data buffer and data size, please refer to hal_spi_master_send_and_receive_config_t , for more details. Check the SPI device's datasheet to determine if the data is sent or received. For example, if ADIS16375 is used in full duplex communication mode, the data is received, while send command is valid. If PAH8001EI-2G sensor is used, the data is received, while send command is invalid.
Returns
HAL_SPI_MASTER_STATUS_ERROR, the byte_order parameter is not properly configured for the FIFO mode;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter in spi_send_and_receive_config is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
1 hal_spi_master_send_and_receive_config_t spi_send_and_receive_config;
2 spi_send_and_receive_config.receive_buffer = receive_buffer;
3 spi_send_and_receive_config.send_data = send_data;
4 spi_send_and_receive_config.send_length = send_length;
5 spi_send_and_receive_config.receive_length = receive_length;
6 ret = hal_spi_master_send_and_receive_polling(HAL_SPI_MASTER_1, &spi_send_and_receive_config);
See also
hal_spi_master_send_polling()
hal_spi_master_status_t hal_spi_master_send_dma ( hal_spi_master_port_t  master_port,
uint8_t *  data,
uint32_t  size 
)

This function is used to send data asynchronously with DMA mode.

This function returns immediately, before calling this function, user should call hal_spi_master_register_callback() to register a callback, then the callback will be called in the SPI ISR.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]datais the data buffer to send, this parameter cannot be NULL, also the address must be a non-cacheable address.
[in]sizeis the number of bytes to send.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_send_and_receive_dma()
hal_spi_master_status_t hal_spi_master_send_dma_blocking ( hal_spi_master_port_t  master_port,
uint8_t *  data,
uint32_t  size 
)

This function is used to send data synchronously with DMA mode.

This function doesn't return until the transfer is complete. Normally this function is used in the scenario where the IRQ must be disabled.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]datais the data buffer to send, this parameter cannot be NULL, also the address must be a non-cacheable address.
[in]sizeis the number of bytes to send.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_master_send_and_receive_dma_blocking()
hal_spi_master_status_t hal_spi_master_send_polling ( hal_spi_master_port_t  master_port,
uint8_t *  data,
uint32_t  size 
)

This function is used to send data synchronously with FIFO mode.

This function doesn't return until the transfer is complete.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]datais the data buffer to send, this parameter cannot be NULL.
[in]sizeis the number of bytes to send. Note the user cannot send data size larger than HAL_SPI_MAXIMUM_POLLING_TRANSACTION_SIZE bytes.
Returns
HAL_SPI_MASTER_STATUS_ERROR, the byte_order parameter is not properly configured for the FIFO mode;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Example
1 ret = hal_spi_master_send_polling(HAL_SPI_MASTER_1,data,size);
See also
hal_spi_master_send_and_receive_polling()
hal_spi_master_status_t hal_spi_master_set_advanced_config ( hal_spi_master_port_t  master_port,
hal_spi_master_advanced_config_t advanced_config 
)

SPI master advanced configuration function.

User can call this function to customize more settings for the SPI device operation. For more information about the settings, please refer to hal_spi_master_advanced_config_t.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]advanced_configprovides advanced configuration parameters for the SPI master. Details are described at hal_spi_master_advanced_config_t.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, this port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Note
This function must be called after hal_spi_master_init().
Example
1 hal_spi_master_advanced_config_t advanced_config;
2 advanced_config.byte_order = HAL_SPI_MASTER_BIG_ENDIAN;
3 advanced_config.chip_polarity = HAL_SPI_MASTER_CHIP_SELECT_LOW;
4 advanced_config.get_tick = HAL_SPI_MASTER_GET_TICK_DELAY1;
5 advanced_config.sample_select = HAL_SPI_MASTER_SAMPLE_NEGATIVE;
6 ret = hal_spi_master_set_advanced_config(HAL_SPI_MASTER_1, &advanced_config);
hal_spi_master_status_t hal_spi_master_set_chip_select_timing ( hal_spi_master_port_t  master_port,
hal_spi_master_chip_select_timing_t  chip_select_timing 
)

This function is used to configure SPI master chip select timing parameter.

User can call this function to customize chip select signal timing if the default SPI master chip select signal timing doesn't match SPI device's requirement.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]chip_select_timingis the parameter settings for chip select timing.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid chip select timing parameter is givenby the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Note
This function must be called after hal_spi_master_init().
Example
Sample code please refers to How to use this driver.
hal_spi_master_status_t hal_spi_master_set_deassert ( hal_spi_master_port_t  master_port,
hal_spi_master_deassert_t  deassert 
)

SPI master chip select de-assertion mode configuration.

User can call this function to enable the deassert feature if the SPI device requires switching the chip select signal from invalid to valid after each byte transfer.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]deassertis the parameter to set SPI master chip select signal behavior after sending one byte.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid deassert parameter is given;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Note
This function must be called after hal_spi_master_init().
Example
Sample code please refers to How to use this driver.
hal_spi_master_status_t hal_spi_master_set_macro_selection ( hal_spi_master_port_t  master_port,
hal_spi_master_macro_select_t  macro_select 
)

SPI master macro group configuration.

If the GPIO selected doesn't belong to SPI pad macro group A, user should call this function to config it to the right pad macro.

Parameters
[in]master_portis the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]macro_selectis the parameter for macro group selection.
Returns
HAL_SPI_MASTER_STATUS_ERROR_PORT, master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_ERROR_BUSY, the port of SPI master is busy and not available for use;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER, an invalid macro selection parameter is given by the user;
HAL_SPI_MASTER_STATUS_OK, the operation completed successfully.
Note
This function must be called after hal_spi_master_init().
Example
Sample code please refers to How to use this driver.