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.

Support transaction format.
- Half-duplex transaction: There is only one valid transaction at a time on a single direction; either send or receive. The functions using half-duplex transaction are:
- Full-duplex transaction: There are two valid mutually inclusive transactions; send and receive. Functions using full-duplex transaction are:
Support transaction mode.
- Polling mode transaction: In polling mode, hal_spi_master_send_polling() and hal_spi_master_send_and_receive_polling() return a value once the transaction is complete. Then the user checks the output of the return value for the transaction result and error handling if any.
  
  See Software architecture of the SPI for the software architecture of polling mode.
- DMA mode transaction: In DMA mode, hal_spi_master_send_dma() and hal_spi_master_send_and_receive_dma() return a value once the SPI hardware register is assigned and the DMA configured. During this process the transaction is usually incomplete, once it completes, an interrupt is triggered and a related user callback is called in the SPI interrupt service routine.
  
  See Software architecture of the SPI for the software architecture of DMA mode.
- DMA blocking mode transaction: In DMA blocking mode, hal_spi_master_send_dma_blocking() and hal_spi_master_send_and_receive_dma_blocking() return a value once the SPI DMA transaction is complete after hardware register is assigned and the DMA configured.
  
  See Software architecture of the SPI for the software architecture of DMA blocking mode.

Software architecture of the SPI

Polling mode architecture.
Polling mode architecture is similar to the polling mode architecture in HAL overview. See HAL Driver Model for polling mode architecture.
DMA mode architecture.
DMA mode architecture is similar to the interrupt mode architecture in HAL overview. See HAL Driver Model for interrupt mode architecture.
DMA blocking mode architecture.
DMA blocking mode architecture is similar to the polling mode architecture in HAL overview. See HAL Driver Model for polling mode architecture.

How to use this driver

Using SPI master polling mode.
Call hal_pinmux_set_function() to pinmux GPIO pins to four SPI pins (CS_N, SCK, MOSI, and MISO) based on the user's hardware platform design.
Once a transaction is complete, call hal_spi_master_deinit() function to release the SPI master resource to make it available for other users.
The steps are shown below:
- Step 1. Call hal_gpio_init() to inite the pins, if EPT tool hasn't been used to configure the related pinmux.
- Step 2. Call hal_pinmux_set_function() to set GPIO pinmux, if EPT tool hasn't been used to configure the related pinmux. For more details about hal_pinmux_set_function(), please refer to GPIO.
- Step 3. Call hal_spi_master_init() to initialize one SPI master. If the SPI master is already initialized by another user, user will get HAL_SPI_MASTER_STATUS_ERROR_BUSY.
- Step 4. Call hal_spi_master_send_polling() to send data in the polling mode.
- Step 5. Call hal_spi_master_send_and_receive_polling() to send and receive data in the polling mode.
- Step 6. Call hal_spi_master_deinit() to deinitialize the SPI master, if it's no longer in use.
- sample code:
  hal_spi_master_config_t spi_config;
  hal_spi_master_send_and_receive_config_t spi_send_and_receive_config;
  uint8_t status_cmd = SPIS_STATUS_CMD;
  uint8_t status_receive[2];
  uint8_t data[2] = {0x7E, 0x55};
  uint32_t size = 2;
  spi_config.bit_order = HAL_SPI_MASTER_LSB_FIRST;
  spi_config.slave_port = HAL_SPI_MASTER_SLAVE_0;
  spi_config.clock_frequency = 1000000;
  spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE0;
  spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY0;
  status_receive[1] = 0;
  spi_send_and_receive_config.receive_length = 2;
  spi_send_and_receive_config.send_length = 1;
  spi_send_and_receive_config.send_data = &status_cmd;
  spi_send_and_receive_config.receive_buffer = status_receive;
  // Initialize the GPIO, set GPIO pinmux (if EPT tool hasn't been used to configure the related pinmux).
  hal_gpio_init(HAL_GPIO_25);
  hal_gpio_init(HAL_GPIO_26);
  hal_gpio_init(HAL_GPIO_27);
  hal_gpio_init(HAL_GPIO_28);
  // Call hal_pinmux_set_function() to set GPIO pinmux, for more information, please refer to hal_pinmux_define.h
  // Configure the pinmux, if EPT tool is used.
  hal_pinmux_set_function(HAL_GPIO_25, HAL_GPIO_25_MA_SPI3_A_CS);// Set the pin to be used as CS signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_26, HAL_GPIO_26_MA_SPI3_A_SCK);// Set the pin to be used as SCK signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_27, HAL_GPIO_27_MA_SPI3_A_MOSI);// Set the pin to be used as MOSI signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_28, HAL_GPIO_28_MA_SPI3_A_MISO);// Set the pin to be used as MISO signal of SPI.
  // Initialize the SPI master.
  if (HAL_SPI_MASTER_STATUS_OK == hal_spi_master_init(HAL_SPI_MASTER_3,&spi_config)) {
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_polling(HAL_SPI_MASTER_3,data,size)) {
  // Error handler;
  }
  //send and receive data at the same time
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_and_receive_polling(HAL_SPI_MASTER_3,&spi_send_and_receive_config)) {
  // Error handler;
  }
  hal_spi_master_deinit(HAL_SPI_MASTER_3); // Deinitialize, if the SPI master is no longer in use.
  } else {
  // Error handler;
  }
Using SPI master DMA mode.
Call hal_pinmux_set_function() to pinmux GPIO pins to four SPI pins (CS_N, SCK, MOSI, and MISO) based on the user's hardware platform design.
Then call hal_spi_master_register_callback() to register a callback function.
Once a transaction is complete, call hal_spi_master_deinit() function in your callback function to release the SPI master resource to make it available for other users.
The steps are shown below:
- Step 1. Call hal_gpio_init() to inite the pins, if EPT tool hasn't been used to configure the related pinmux.
- Step 2. Call hal_pinmux_set_function() to set GPIO pinmux, if EPT tool hasn't been used to configure the related pinmux. For more details about hal_pinmux_set_function(), please refer to GPIO.
- Step 3. Call hal_spi_master_init() to init one SPI master. If the SPI master is already initialized by another user, user will get HAL_SPI_MASTER_STATUS_ERROR_BUSY.
- Step 4. Call hal_spi_master_register_callback() to register a user callback.
- Step 5. Call hal_spi_master_send_dma() to send data in the DMA mode.
- Step 6. Call hal_spi_master_send_and_receive_dma() to send and receive data in the DMA mode.
- Step 7. Call hal_spi_master_deinit() to deinit the SPI master, if it's no longer in use.
- sample code:
  hal_spi_master_config_t spi_config;
  hal_spi_master_send_and_receive_config_t spi_send_and_receive_config;
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t status_cmd = SPIS_STATUS_CMD;
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t status_receive[2];
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t data[2] = {0x7E, 0x55};
  uint32_t size = 2;
  spi_config.bit_order = HAL_SPI_MASTER_LSB_FIRST;
  spi_config.slave_port = HAL_SPI_MASTER_SLAVE_0;
  spi_config.clock_frequency = 1000000;
  spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE0;
  spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY0;
  status_receive[1] = 0;
  spi_send_and_receive_config.receive_length = 2;
  spi_send_and_receive_config.send_length = 1;
  spi_send_and_receive_config.send_data = &status_cmd;
  spi_send_and_receive_config.receive_buffer = status_receive;
  // Initialize the GPIO, set GPIO pinmux (if EPT tool hasn't been used to configure the related pinmux).
  hal_gpio_init(HAL_GPIO_25);
  hal_gpio_init(HAL_GPIO_26);
  hal_gpio_init(HAL_GPIO_27);
  hal_gpio_init(HAL_GPIO_28);
  // Call #hal_pinmux_set_function() to set the GPIO pinmux, for more information, please refer to hal_pinmux_define.h.
  // No need to configure the pinmux, if EPT tool is used.
  hal_pinmux_set_function(HAL_GPIO_25, HAL_GPIO_25_MA_SPI3_A_CS);// Set the pin to be used as CS signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_26, HAL_GPIO_26_MA_SPI3_A_SCK);// Set the pin to be used as SCK signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_27, HAL_GPIO_27_MA_SPI3_A_MOSI);// Set the pin to be used as MOSI signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_28, HAL_GPIO_28_MA_SPI3_A_MISO);// Set the pin to be used as MISO signal of SPI.
  // Initialize the SPI master.
  if (HAL_SPI_MASTER_STATUS_OK == hal_spi_master_init(HAL_SPI_MASTER_3 ,&spi_config)) {
  hal_spi_master_register_callback(HAL_SPI_MASTER_3 ,user_spi_callback,NULL); // Register a user callback.
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_dma(HAL_SPI_MASTER_3 ,data,size)) {
  // Error handler;
  }
  // Send and receive data simultaneously.
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_and_receive_dma(HAL_SPI_MASTER_3, &spi_send_and_receive_config)) {
  // Error handler;
  }
  } else {
  // Error handler;
  }
  
  // Callback function sample code. Pass this function to the driver while calling #hal_spi_master_register_callback().
  void user_spi_callback (hal_spi_master_callback_event_t event,void *user_data)
  {
  if (HAL_SPI_MASTER_EVENT_SEND_FINISHED == event) {
  // Send finish event handler;
  // User code;
  hal_spi_master_deinit(HAL_SPI_MASTER_3); // Deinitialize, if no longer in use.
  } else if (HAL_SPI_MASTER_EVENT_RECEIVE_FINISHED == event) {
  // Receive finish event handler;
  // User code;
  hal_spi_master_deinit(HAL_SPI_MASTER_3); // Deinitialize, if no longer in use.
  }
  }
Using SPI master DMA blocking mode.
Call hal_pinmux_set_function() to pinmux GPIO pins to four SPI pins (CS_N, SCK, MOSI, and MISO) based on the user's hardware platform design.
Once a transaction is complete, call hal_spi_master_deinit() function to release the SPI master resource to make it available for other users.
The steps are shown below:
- Step 1. Call hal_gpio_init() to inite the pins, if EPT tool hasn't been used to configure the related pinmux.
- Step 2. Call hal_pinmux_set_function() to set GPIO pinmux, if EPT tool hasn't been used to configure the related pinmux. For more details about hal_pinmux_set_function(), please refer to GPIO.
- Step 3. Call hal_spi_master_init() to initialize one SPI master. If the SPI master is already initialized by another user, user will get HAL_SPI_MASTER_STATUS_ERROR_BUSY.
- Step 4. Call hal_spi_master_send_dma_blocking() to send data in the DMA blocking mode.
- Step 5. Call hal_spi_master_send_and_receive_dma_blocking() to send and receive data in the DMA blocking mode.
- Step 6. Call hal_spi_master_deinit() to deinitialize the SPI master, if it's no longer in use.
- sample code:
  hal_spi_master_config_t spi_config;
  hal_spi_master_send_and_receive_config_t spi_send_and_receive_config;
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t status_cmd = SPIS_STATUS_CMD;
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t status_receive[2];
  ATTR_ZIDATA_IN_NONCACHED_RAM_4BYTE_ALIGN uint8_t data[2] = {0x7E, 0x55};
  uint32_t size = 2;
  spi_config.bit_order = HAL_SPI_MASTER_LSB_FIRST;
  spi_config.slave_port = HAL_SPI_MASTER_SLAVE_0;
  spi_config.clock_frequency = 1000000;
  spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE0;
  spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY0;
  status_receive[1] = 0;
  spi_send_and_receive_config.receive_length = 2;
  spi_send_and_receive_config.send_length = 1;
  spi_send_and_receive_config.send_data = &status_cmd;
  spi_send_and_receive_config.receive_buffer = status_receive;
  // Initialize the GPIO, set GPIO pinmux (if EPT tool hasn't been used to configure the related pinmux).
  hal_gpio_init(HAL_GPIO_25);
  hal_gpio_init(HAL_GPIO_26);
  hal_gpio_init(HAL_GPIO_27);
  hal_gpio_init(HAL_GPIO_28);
  // Call hal_pinmux_set_function() to set GPIO pinmux, for more information, please refer to hal_pinmux_define.h
  // Configure the pinmux, if EPT tool is used.
  hal_pinmux_set_function(HAL_GPIO_25, HAL_GPIO_25_MA_SPI3_A_CS);// Set the pin to be used as CS signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_26, HAL_GPIO_26_MA_SPI3_A_SCK);// Set the pin to be used as SCK signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_27, HAL_GPIO_27_MA_SPI3_A_MOSI);// Set the pin to be used as MOSI signal of SPI.
  hal_pinmux_set_function(HAL_GPIO_28, HAL_GPIO_28_MA_SPI3_A_MISO);// Set the pin to be used as MISO signal of SPI.
  // Initialize the SPI master.
  if (HAL_SPI_MASTER_STATUS_OK == hal_spi_master_init(HAL_SPI_MASTER_3,&spi_config)) {
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_dma_blocking(HAL_SPI_MASTER_3,data,size)) {
  // Error handler;
  }
  //send and receive data at the same time
  if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_and_receive_dma_blocking(HAL_SPI_MASTER_3,&spi_send_and_receive_config)) {
  // Error handler;
  }
  hal_spi_master_deinit(HAL_SPI_MASTER_3); // Deinitialize, if the SPI master is no longer in use.
  } else {
  // Error handler;
  }

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_port is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[out]	running_status	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	spi_config	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	callback	is the callback function given by user, which will be called at SPI master interrupt service routine.
[in]	user_data	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	spi_send_and_receive_config	is 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 4 bytes align 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	spi_send_and_receive_config	is 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 4 bytes align 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	spi_send_and_receive_config	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	data	is the data buffer to send, this parameter cannot be NULL, also the address must be a non-cacheable and 4 bytes align address.
[in]	size	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	data	is the data buffer to send, this parameter cannot be NULL, also the address must be a non-cacheable and 4 bytes align address.
[in]	size	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	data	is the data buffer to send, this parameter cannot be NULL.
[in]	size	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	advanced_config	provides 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	chip_select_timing	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	deassert	is 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_port	is the SPI master port number, the value is defined in hal_spi_master_port_t.
[in]	macro_select	is 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.

Overview

Terms and acronyms

Supported features

Software architecture of the SPI

How to use this driver

Functions

Modules

Function Documentation