MT7687 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, such as 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_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_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() is called.

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 means the SPI master is in busy status;
HAL_SPI_MASTER_IDLE means the SPI master is in idle status, user can use it to transfer data now.
Returns
HAL_SPI_MASTER_STATUS_ERROR means this API is called before hal_spi_master_init() is called;
HAL_SPI_MASTER_STATUS_ERROR_PORT means master_port parameter is an invalid port number;
HAL_SPI_MASTER_STATUS_INVALID_PARAMETER means running_status parameter is NULL;
HAL_SPI_MASTER_STATUS_OK means this function return 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.
Example
1 hal_spi_master_config_t spi_config;
2 spi_config.bit_order = HAL_SPI_MASTER_MSB_FIRST;
3 spi_config.clock_frequency = 0x400000;
4 spi_config.phase = HAL_SPI_MASTER_CLOCK_PHASE1;
5 spi_config.polarity = HAL_SPI_MASTER_CLOCK_POLARITY1;
6 ret = hal_spi_master_init(HAL_SPI_MASTER_1, &spi_config);
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_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 definition for details. But user should judge whether the data received while sending command is valid or not, and this information can get from SPI device's datasheet. For example, if user uses ADIS16375 as full duplex communication mode, the data received while sending command is valid. If user uses PAH8001EI-2G sensor, the data received while sending command is invalid.
Returns
HAL_SPI_MASTER_STATUS_ERROR means the byte_order parameter is not configured rightly for the FIFO mode;
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 in spi_send_and_receive_config is given;
HAL_SPI_MASTER_STATUS_OK means this function return 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_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 buffer of data to be sent, this parameter cannot be NULL.
[in]sizeis the number of bytes to send. Note user can't send data size larger than HAL_SPI_MAXIMUM_POLLING_TRANSACTION_SIZE bytes.
Returns
HAL_SPI_MASTER_STATUS_ERROR means the byte_order parameter is not configured rightly for the FIFO mode;
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.
Example
1 ret = hal_spi_master_send_polling(HAL_SPI_MASTER_1,data,size);
See also
hal_spi_master_send_and_receive_polling()