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.

• Support transaction format.
  
  • Half-duplex transaction: There is only one valid transaction at a time on a single direction; either send or receive. The function using half-duplex transaction is:
    • hal_spi_master_send_polling().
  • Full-duplex transaction: There are two valid mutually inclusive transactions; send and receive. The function using full-duplex transaction is:
    • hal_spi_master_send_and_receive_polling().
• 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.

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.

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. Note, user should configure the chip select pin as GPIO mode, this driver will set the chip select signal as valid before starting the transaction, then set the chip select signal as invalid after finishing the transaction.
  • Step 3. Call hal_spi_master_init() to initialize one SPI master.
  • 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 send_data[2] = {0x7E, 0x55};
    uint32_t size = 2;
    spi_config.bit_order = HAL_SPI_MASTER_MSB_FIRST;
    spi_config.slave_port = HAL_SPI_MASTER_SLAVE_0;
    spi_config.clock_frequency = 1000000;
    spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE1;
    spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY1;
    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_29);
    hal_gpio_init(HAL_GPIO_30);
    hal_gpio_init(HAL_GPIO_31);
    hal_gpio_init(HAL_GPIO_32);
    // The chip select pin should be configured in GPIO mode. No need to configure the pinmux, if EPT tool is used.
    hal_pinmux_set_function(HAL_GPIO_29, HAL_GPIO_29_SPI_MOSI_M_CM4);
    hal_pinmux_set_function(HAL_GPIO_30, HAL_GPIO_30_SPI_MISO_M_CM4);
    hal_pinmux_set_function(HAL_GPIO_31, HAL_GPIO_31_SPI_SCK_M_CM4);
    hal_pinmux_set_function(HAL_GPIO_32, HAL_GPIO_32_GPIO32);
    
    // Initialize the SPI master.
    if (HAL_SPI_MASTER_STATUS_OK == hal_spi_master_init(HAL_SPI_MASTER_0,&spi_config)) {
        //send data
        if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_polling(HAL_SPI_MASTER_0,data,size)) {
            // Error handle.
        }
        //send and receive data at the same time
        if (HAL_SPI_MASTER_STATUS_OK != hal_spi_master_send_and_receive_polling(HAL_SPI_MASTER_0,&spi_send_and_receive_config)) {
            // Error handle.
        }
        hal_spi_master_deinit(HAL_SPI_MASTER_0); //Must call deinit when don't use SPI master
    } else {
        // Error handle.
    }

How to adjust the driving current of the SPI master.

When the SPI master is operating on a high frequency clock and the hardware environment is not well designed, the SPI master may malfunction because of bad signal integrity. Use an oscilloscope to find out which pin requires an adjustment. Normally it'll be clock pin and data pin. Then call #hal_gpio_set_driving() to adjust the driving current of a specific SPI pin.

• sample code:

  // To adjust the SCK pin (corresponds to GPIO26) of the SPI master,
  // call #hal_gpio_init() and then #hal_pinmux_set_function() to initialize this SPI pin.
  hal_gpio_init(HAL_GPIO_26);
  hal_pinmux_set_function(HAL_GPIO_26, HAL_GPIO_26_MA_SPI3_A_SCK);
  // Call #hal_gpio_set_driving() to set the proper driving current for this SPI pin.
  hal_gpio_set_driving(HAL_GPIO_26, HAL_GPIO_DRIVING_8MA);
  // Call #hal_spi_master_init() to initialize the SPI master.
  hal_spi_master_init(HAL_SPI_MASTER_0 ,&spi_config);

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_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_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_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...

Modules
	Define
	Enum
	Struct

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

hal_spi_master_status_t user_spi_master_init(void)
{
  hal_spi_master_port_t spi_port;
  hal_spi_master_config_t spi_configure;
  hal_spi_master_status_t error_status;
  uint32_t try_times = 0;

  spi_port = HAL_SPI_SLAVE_0;
  spi_config.bit_order = HAL_SPI_MASTER_LSB_FIRST;
  spi_config.clock_frequency = 1000000;
  spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE0;
  spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY0;

  while (try_times < 10) {
      error_status = hal_spi_master_init(spi_port, &spi_configure);
      if (error_status == HAL_SPI_MASTER_STATUS_ERROR_BUSY) {
          vTaskDelay((portTickType)100 / portTICK_RATE_MS);
          try_times ++;
      } else {
        break;
      }
   }
  return error_status;
}

See also

hal_spi_master_deinit()

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

hal_spi_master_send_and_receive_config_t spi_send_and_receive_config;
spi_send_and_receive_config.receive_buffer = receive_buffer;
spi_send_and_receive_config.send_data = send_data;
spi_send_and_receive_config.send_length = send_length;
spi_send_and_receive_config.receive_length = receive_length;
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_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

ret = hal_spi_master_send_polling(HAL_SPI_MASTER_1,data,size);

See also

hal_spi_master_send_and_receive_polling()