MT2523 API Reference  LinkIt SDK v4
SPI_SLAVE

This section introduces the Serial Peripheral Interface (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 Serial Peripheral Interface (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 SPI 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 example application is a sensor hub. SPI slave interface is required to communicate with SPI master interface. This controller is a common SPI slave interface that only supports the DMA mode. The SPI slave hardware is enabled to receive a set of commands from the SPI master to handle specific operations. The SPI slave software provides automatic error handling and status update, if the SPI slave hardware detects any malfunction.

Software architecture of the SPI slave

How to use this driver

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 such as timeout threshold, bit order, clock polarity and clock phase. More...
 
hal_spi_slave_status_t hal_spi_slave_deinit (hal_spi_slave_port_t spi_port)
 This function resets the SPI slave, gates its clock and disables interrupts. 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...
 
hal_spi_slave_status_t hal_spi_slave_send (hal_spi_slave_port_t spi_port, const uint8_t *data, uint32_t size)
 This function sends data asynchronously with DMA mode, this function should be called from user's callback function. More...
 
hal_spi_slave_status_t hal_spi_slave_get_master_read_config (hal_spi_slave_port_t spi_port, uint32_t *address, uint32_t *length)
 This function queries the address and length from the config read command sent by the SPI master. More...
 
hal_spi_slave_status_t hal_spi_slave_receive (hal_spi_slave_port_t spi_port, uint8_t *buffer, uint32_t size)
 This function receives data asynchronously with DMA mode. More...
 
hal_spi_slave_status_t hal_spi_slave_get_master_write_config (hal_spi_slave_port_t spi_port, uint32_t *address, uint32_t *length)
 This function querys the address and the length from the config write command sent by the SPI master. More...
 
hal_spi_slave_status_t hal_spi_slave_set_early_miso (hal_spi_slave_port_t spi_port, hal_spi_slave_early_miso_t early_miso)
 This function configures the SPI slave send MISO early half SCLK cycle parameter. More...
 
hal_spi_slave_status_t hal_spi_slave_set_command (hal_spi_slave_port_t spi_port, hal_spi_slave_command_type_t command, uint8_t value)
 This function configures the SPI slave command value. More...
 

Modules

 Enum
 
 Struct
 
 Typedef
 

Function Documentation

hal_spi_slave_status_t hal_spi_slave_deinit ( hal_spi_slave_port_t  spi_port)

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

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
Returns
HAL_SPI_SLAVE_STATUS_ERROR_PORT, if the SPI slave port is invalid.
HAL_SPI_SLAVE_STATUS_OK, if this function returned successfully.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_slave_init()
hal_spi_slave_status_t hal_spi_slave_get_master_read_config ( hal_spi_slave_port_t  spi_port,
uint32_t *  address,
uint32_t *  length 
)

This function queries the address and length from the config read command sent by the SPI master.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]addressis the address of data to read from.
[in]lengthis the data length to read.
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_ERROR, if the address and length of data cannot be queried.
HAL_SPI_SLAVE_STATUS_OK, if this function returned successfully.
Example
1 hal_spi_slave_status_t user_spi_slave_callback(hal_spi_slave_transaction_status_t status,void *user_data)
2 {
3 
4  hal_spi_slave_callback_event_t slave_status;
5  uint32_t request_address, request_length;
6  uint32_t actual_address, actual_length;
7  bool need_convert;
8 
9  if (HAL_SPI_SLAVE_FSM_SUCCESS_OPERATION == (status.fsm_status)) {
10  slave_status = status.slave_status;
11  switch (slave_status) {
12  case HAL_SPI_SLAVE_EVENT_CRD_FINISH:
13  hal_spi_slave_get_master_read_config(HAL_SPI_SLAVE_0, &request_address, &request_length);
14  need_convert = user_check_convert(); // User decides whether to convert the requested address to an actual address.
15  if (need_convert == true) {
16  actual_address = user_convert_address(request_address, request_length); // Convert the requested address to an actual.
17  }
18  else {
19  actual_address = request_address; // Use the requested address as an actual address.
20  }
21  actual_length = request_length; // Actual length should always be the same as the requested length.
22  user_prepare_buffer(actual_address, actual_length); // Prepare a buffer before sending or receiving data.
23  hal_spi_slave_send(HAL_SPI_SLAVE_0, (uint8_t *)actual_address, actual_length);
24  break;
25  // Other event handler;
26  }
27 }
See also
hal_spi_slave_send()
hal_spi_slave_status_t hal_spi_slave_get_master_write_config ( hal_spi_slave_port_t  spi_port,
uint32_t *  address,
uint32_t *  length 
)

This function querys the address and the length from the config write command sent by the SPI master.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]addressis the address of data the master want to write to.
[in]lengthis the data length to write.
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_ERROR, if the address and length of data cannot be queried.
HAL_SPI_SLAVE_STATUS_OK, if this function returned successfully.
Example
1 hal_spi_slave_status_t user_spi_slave_callback(hal_spi_slave_transaction_status_t status,void *user_data)
2 {
3 
4  hal_spi_slave_callback_event_t slave_status;
5  uint32_t request_address, request_length;
6  uint32_t actual_address, actual_length;
7  bool need_convert;
8 
9  if (HAL_SPI_SLAVE_FSM_SUCCESS_OPERATION == (status.fsm_status)) {
10  slave_status = status.slave_status;
11  switch (slave_status) {
12  case HAL_SPI_SLAVE_EVENT_CWR_FINISH:
13  hal_spi_slave_get_master_write_config(HAL_SPI_SLAVE_0, &request_address, &request_length);
14  need_convert = user_check_convert(); // User decides whether to convert the requested address to an actual address.
15  if (need_convert == true) {
16  actual_address = user_convert_address(request_address, request_length); // Convert the requested address to an actual.
17  }
18  else {
19  actual_address = request_address; // Use the requested address as an actual address.
20  }
21  actual_length = request_length; // Actual length should always be the same as the requested length.
22  user_prepare_buffer(actual_address, actual_length); // Prepare a buffer before sending or receiving data.
23  hal_spi_slave_receive(HAL_SPI_SLAVE_0, (uint8_t *)actual_address, actual_length);
24  break;
25  // Other event handler;
26  }
27 }
See also
hal_spi_slave_receive()
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 such as timeout threshold, bit order, clock polarity and clock phase.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]spi_configureis the SPI slave configure parameters. Details are described at hal_spi_slave_config_t.
Returns
HAL_SPI_SLAVE_STATUS_ERROR, if the SPI slave port is in use.
HAL_SPI_SLAVE_STATUS_ERROR_BUSY, if the SPI slave port is busy and not available for use;
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.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_slave_deinit()
hal_spi_slave_status_t hal_spi_slave_receive ( hal_spi_slave_port_t  spi_port,
uint8_t *  buffer,
uint32_t  size 
)

This function receives data asynchronously with DMA mode.

This function should be called from user's callback function.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]bufferis the data buffer where the received data are stored, this parameter cannot be NULL, also the address must be as non-cacheable address.
[in]sizeis the number of bytes to receive.
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.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_slave_get_master_write_config()
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 should always be called when using the SPI slave driver, the callback will be called in SPI ISR.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]callback_functionis the callback function given by user, which will be called at SPI slave 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_slave_callback_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.
Example
Sample code please refer to How to use this driver.
hal_spi_slave_status_t hal_spi_slave_send ( hal_spi_slave_port_t  spi_port,
const uint8_t *  data,
uint32_t  size 
)

This function sends data asynchronously with DMA mode, this function should be called from user's callback function.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]datais the buffer of data to be sent, this parameter cannot be NULL, also the address must be as non-cacheable address.
[in]sizeis the number of bytes to send.
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.
Example
Sample code please refers to How to use this driver.
See also
hal_spi_slave_get_master_read_config()
hal_spi_slave_status_t hal_spi_slave_set_command ( hal_spi_slave_port_t  spi_port,
hal_spi_slave_command_type_t  command,
uint8_t  value 
)

This function configures the SPI slave command value.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]commandis the SPI slave command type, the value is defined at hal_spi_slave_command_type_t.
[in]valueis the command value that needs to be configured.
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.
Example
Sample code please refers to How to use this driver.
hal_spi_slave_status_t hal_spi_slave_set_early_miso ( hal_spi_slave_port_t  spi_port,
hal_spi_slave_early_miso_t  early_miso 
)

This function configures the SPI slave send MISO early half SCLK cycle parameter.

Parameters
[in]spi_portis the SPI slave port number, the value is defined at hal_spi_slave_port_t.
[in]early_misois the parameter to enable the send MISO data half SCLK cycle early feature or disable it.
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.
Example
Sample code please refers to How to use this driver.