This section introduces the SPI Slave 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 SPI Slave 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).
GPIO	General Purpose Inputs-Outputs. For more details, please refer to GPIO.
IRQ	Interrupt Request. For more information, please refer to IRQ.
MISO	Master Input, Slave Output. Output from the SPI slave.
MOSI	Master Output, Slave Input. Output from the SPI master.
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.
SCLK	Serial Clock. Output from the SPI master.
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 refer to Serial Peripheral Interface Bus in Wikipedia.
SS	Slave Select. Output from the SPI master, active low.

Supported features

Emerging sensor applications support SPI interface communication. An SPI slave interface is required to communicate with an SPI master interface. This controller is the SPI slave interface with five functional registers for communication.

Support functional registers.
There are six registers in this slave controller:
- Reg00 - reads data from the bus.
- Reg01 - writes data to the bus.
- Reg02 - the address to write/read to/from the bus, the configured value should correspond to a physical address in the system.
- Reg03 - the bus protocol command.
- Reg04 - the polling status to check whether the bus is idle or busy.
- Reg05 - the software IRQ command.
Support standard mode and fast mode programming sequences.
Fast mode supports address auto increment to reduce bus address write time when the SPI slave accesses the system memory. Example 1 and 2 use standard mode. Example 3 and 4 use fast mode. The default driver settings are on fast mode to provide better throughput.
Example 1: Write 0x0123_4567 data to the address 0x1013_0004.
- Step 1. Prepare command to access the bus, the SPI master asserts the following data on MOSI.
  {8'h80,8'h04,16'h4567} // Put bus write data[15:0] into the SPI slave reg01[15:0].
  {8'h80,8'h06,16'h0123} // Put bus write data[31:16] into the SPI slave reg01[31:16].
  {8'h80,8'h08,16'h0004} // Put bus address[15:0] into the SPI slave reg02[15:0].
  {8'h80,8'h0A,16'h1013} // Put bus address[31:16] into the SPI slave reg02[31:16].
  {8'h80,8'h0c,{13'b0,2'b10,1'b1}} // Start the bus write access.
Example 2: Read 0x0123_4567 data from the address 0x1013_0004. Note: Check if the status is busy before reading data from the SPI slave controller.
- Step 1. Prepare command to access the bus, the SPI master asserts the following data on MOSI.
  {8'h80,8'h08,16'h0004} // Put bus address[15:0] into the SPI slave reg02[15:0].
  {8'h80,8'h0A,16'h1013} // Put bus address[31:16] into the SPI slave reg02[31:16].
  {8'h80,8'h0c,{13'b0,2'b10,1'b0}} // Access the bus to read data.
- Step 2. Wait bus accessing done, the SPI master asserts the following data on MOSI.
  {8'h00,8'h10,16'hxxxx} // Read the SPI slave bus interface status.
  Wait until the MISO returned data bit[0]=0, make sure that bus access has finished.
- Step 3. Get read data, the SPI master asserts the following data on MOSI.
  {8'h00,8'h00,16'hxxxx} // Get bus read data[15:0] from the SPI slave reg00[15:0],
  MISO return data 16'h4567.
  {8'h00,8'h02,16'hxxxx} // Get bus read data[31:16] from the SPI slave reg00[31:16],
  MISO return data 16'h0123.
Example 3: Write 0x0123_4567 data to the address 0x1013_0004. Write 0x89ab_cdef data to the address 0x1013_0008. SPI master sends software IRQ command to trigger SPI slave IRQ.
- Step 1. Prepare command to access the bus, the SPI master asserts the following data on MOSI.
  {8'h80,8'h04,16'h4567} // Put bus write data[15:0] into the SPI slave reg01[15:0].
  {8'h80,8'h06,16'h0123} // Put bus write data[31:16] into the SPI slave reg01[31:16].
  {8'h80,8'h08,16'h0004} // Put bus address[15:0] into the SPI slave reg02[15:0].
  {8'h80,8'h0A,16'h1013} // Put bus address[31:16] into the SPI slave reg02[31:16].
  {8'h80,8'h0c,{13'b0,2'b10,1'b1}} // Start the bus write access.
- Step 2. // Address will auto-increment by 4 bytes after the last master transaction.
  Prepare command to access the bus, the SPI master asserts the following data on MOSI.
  {8'h80,8'h04,16'hcdef} // Put bus write data[15:0] into the SPI slave reg01[15:0].
  {8'h80,8'h06,16'h89ab} // Put bus write data[31:16] into the SPI slave reg01[31:16].
  // No need to write the bus address.
  {8'h80,8'h0c,{13'b0,2'b10,1'b1}} // Start the bus write access.
- Step 3. Prepare software IRQ command to access the bus, the SPI master asserts the following data on MOSI.
  {8'h80,8'h14,16'h0001} // Write 1 into the SPI slave reg05[0].
  Example 4: Read 0x0123_4567 data from the address 0x1013_0004. Read 0x89ab_cdef data from the address 0x1013_0008. Note: User needs to check busy status before reading the bus data from the SPI slave controller.
- Step 1. Prepare command for bus accessing, SPI master asserts following data on MOSI respectively.
  {8'h80,8'h08,16'h0004} // Put bus address[15:0] into the SPI slave reg02[15:0].
  {8'h80,8'h0A,16'h1013} // Put bus address[31:16] into the SPI slave reg02[31:16].
  {8'h80,8'h0c,{13'b0,2'b10,1'b0}} // Start the bus read access.
- Step 2. Wait till the bus access is complete, then the SPI master asserts the following data on MOSI.
  {8'h00,8'h10,16'hxxxx} // Read the SPI slave bus interface status.
  Wait until the MISO returned data bit[0]=0, make sure that bus access has finished.
- Step 3. Get read data, the SPI master asserts the following data on MOSI.
  {8'h00,8'h00,16'hxxxx} // Get bus read data[15:0] from the SPI slave reg00[15:0],
  MISO return data 16'h4567.
  {8'h00,8'h02,16'hxxxx} // Get bus read data[31:16] from the SPI slave reg00[31:16],
  MISO return data 16'h0123.
- Step 4. // No need to write address into reg02.
  // User can start reading from the bus immediately.
  {8'h80,8'h0c,{13'b0,2'b10,1'b0}} // Start the bus read access.
- Step 5. Wait till the bus access is complete, then the SPI master asserts the following data on MOSI.
  {8'h00,8'h10,16'hxxxx} // Read the SPI slave bus interface status.
  Wait until the MISO returned data bit[0]=0, make sure that bus access has finished.
- Step 6. Get read data at address 0x1013_0008, the SPI master asserts the following data on MOSI.
  {8'h00,8'h00,16'hxxxx} // Get bus read data[15:0] from the SPI slave reg00[15:0],
  MISO return data 16'hcdef.
  {8'h00,8'h02,16'hxxxx} // Get bus read data[31:16] from the SPI slave reg00[31:16],
  MISO return data 16'h89ab.

Software architecture of the SPI slave

The architecture is similar to the interrupt mode architecture in HAL overview. See HAL Driver Model for interrupt mode architecture.

How to use this driver

Call hal_pinmux_set_function() to pinmux the GPIO pins to four SPI pins (SS, SCLK, MOSI, and MISO) based on the user's hardware platform design. Please note that user should choose the SPI pins for SPI slave, which can support 20MHz SPI clock, to get a better throughput. Then call hal_spi_slave_init() to apply basic settings for SPI slave hardware. After that call hal_spi_slave_register_callback() to register a user callback function. The steps are shown below:

Step 1. Call hal_gpio_init() to init the pins, if EPT tool hasn't been used to configure the related pinmux.
Step 2. Call hal_pinmux_set_function() to set the GPIO pinmux, if the EPT tool wasn't used to configure the related pinmux. For more details about hal_pinmux_set_function(), please refer to GPIO.
Step 3. Call hal_spi_slave_init() to configure the SPI slave hardware settings.
Step 4. Call hal_spi_slave_register_callback() to register a user callback.
An example implementation of the SPI slave.
hal_spi_slave_config_t spi_configure;
spi_configure.phase = HAL_SPI_SLAVE_CLOCK_PHASE0;
spi_configure.polarity = HAL_SPI_SLAVE_CLOCK_POLARITY0;
// Initialize the GPIO, set the GPIO pinmux, if it wasn't configured by the EPT tool.
hal_gpio_init(HAL_GPIO_29);
hal_gpio_init(HAL_GPIO_30);
hal_gpio_init(HAL_GPIO_31);
hal_gpio_init(HAL_GPIO_32);
// 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.
//function_index = HAL_GPIO_29_SPI_MOSI_S_CM4.
hal_pinmux_set_function(HAL_GPIO_29, function_index);// No need to configure the pinmux, if EPT tool is used.
//function_index = HAL_GPIO_30_SPI_MISO_S_CM4.
hal_pinmux_set_function(HAL_GPIO_30, function_index);// No need to configure the pinmux, if EPT tool is used.
//function_index = HAL_GPIO_31_SPI_SCK_S_CM4.
hal_pinmux_set_function(HAL_GPIO_31, function_index); // No need to configure the pinmux, if EPT tool is used.
//function_index = HAL_GPIO_32_SPI_CS_0_S_CM4.
hal_pinmux_set_function(HAL_GPIO_32, function_index);// No need to configure the pinmux, if EPT tool is used.
ret_status = hal_spi_slave_init(HAL_SPI_SLAVE_0, &spi_configure);
hal_spi_slave_register_callback(HAL_SPI_SLAVE_0,user_spi_callback,NULL)// Register a user callback.

How to adjust the driving current of the SPI master.

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

sample code:
// To adjust the MISO pin (corresponds to GPIO26) of the SPI slave, call #hal_gpio_init(),
// then #hal_pinmux_set_function() to initialize this SPI pin.
hal_gpio_init(HAL_GPIO_26);
hal_pinmux_set_function(HAL_GPIO_26, SPIS_PIN_FUNC_MISO);
// Then 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_slave_init() to initialize the SPI slave.
hal_spi_slave_init(HAL_SPI_SLAVE_0 ,&spi_config);

Functions
hal_spi_slave_status_t	hal_spi_slave_init (hal_spi_slave_port_t spi_port, hal_spi_slave_config_t *spi_configure)
	This function initializes the SPI slave and sets user defined common parameters including clock polarity and clock phase, always setup internal configuration for 20MHz SPI clock for better throughput. More...

hal_spi_slave_status_t	hal_spi_slave_register_callback (hal_spi_slave_port_t spi_port, hal_spi_slave_callback_t callback_function, void *user_data)
	This function registers user's callback in the SPI slave driver. More...

Modules
	Enum

	Struct

	Typedef

Function Documentation

hal_spi_slave_status_t hal_spi_slave_init	(	hal_spi_slave_port_t	spi_port,
		hal_spi_slave_config_t *	spi_configure
	)

This function initializes the SPI slave and sets user defined common parameters including clock polarity and clock phase, always setup internal configuration for 20MHz SPI clock for better throughput.

Note that the SPI slave supports only MSB bit order and can't be config to LSB bit order.

Parameters

[in]	spi_port	is the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]	spi_configure	is the SPI slave configure parameters. Details are described at hal_spi_slave_config_t.

Returns: HAL_SPI_SLAVE_STATUS_ERROR_PORT, if the SPI slave port is invalid.
HAL_SPI_SLAVE_STATUS_INVALID_PARAMETER, if an invalid parameter is given by user.
HAL_SPI_SLAVE_STATUS_OK, if this function returned successfully.

hal_spi_slave_status_t hal_spi_slave_register_callback	(	hal_spi_slave_port_t	spi_port,
		hal_spi_slave_callback_t	callback_function,
		void *	user_data
	)

This function registers user's callback in the SPI slave driver.

This function may be called when using the SPI slave driver, the callback will be called in SPI interrupt service routine.