Collaboration diagram for SPI:

Data Structures
struct	rt_spi_message

struct	rt_spi_configuration

struct	rt_spi_bus

struct	rt_spi_ops

struct	rt_spi_device

struct	rt_qspi_message

struct	rt_qspi_configuration

struct	rt_qspi_device

Macros
#define	RT_SPI_CPHA (1<<0)

#define	RT_SPI_CPOL (1<<1)

#define	RT_SPI_LSB (0<<2)

#define	RT_SPI_MSB (1<<2)

#define	RT_SPI_MASTER (0<<3)

#define	RT_SPI_SLAVE (1<<3)

#define	RT_SPI_CS_HIGH (1<<4)

#define	RT_SPI_NO_CS (1<<5)

#define	RT_SPI_3WIRE (1<<6)

#define	RT_SPI_READY (1<<7)

#define	RT_SPI_MODE_0 (0 \| 0)

#define	RT_SPI_MODE_1 (0 \| RT_SPI_CPHA)

#define	RT_SPI_MODE_2 (RT_SPI_CPOL \| 0)

#define	RT_SPI_MODE_3 (RT_SPI_CPOL \| RT_SPI_CPHA)

Functions
rt_err_t	rt_spi_bus_register (struct rt_spi_bus bus, const char name, const struct rt_spi_ops *ops)

rt_err_t	rt_spi_bus_attach_device (struct rt_spi_device device, const char name, const char bus_name, void user_data)

rt_err_t	rt_spi_bus_detach_device (struct rt_spi_device *device)

rt_err_t	rt_spi_bus_attach_device_cspin (struct rt_spi_device device, const char name, const char bus_name, rt_base_t cs_pin, void user_data)

rt_err_t	rt_spi_bus_detach_device_cspin (struct rt_spi_device *device)

rt_err_t	rt_spi_bus_configure (struct rt_spi_device *device)

rt_err_t	rt_spi_take_bus (struct rt_spi_device *device)

rt_err_t	rt_spi_release_bus (struct rt_spi_device *device)

rt_err_t	rt_spi_take (struct rt_spi_device *device)

rt_err_t	rt_spi_release (struct rt_spi_device *device)

rt_err_t	rt_spi_configure (struct rt_spi_device device, struct rt_spi_configuration cfg)

rt_err_t	rt_spi_send_then_recv (struct rt_spi_device device, const void send_buf, rt_size_t send_length, void *recv_buf, rt_size_t recv_length)

rt_err_t	rt_spi_send_then_send (struct rt_spi_device device, const void send_buf1, rt_size_t send_length1, const void *send_buf2, rt_size_t send_length2)

rt_ssize_t	rt_spi_transfer (struct rt_spi_device device, const void send_buf, void *recv_buf, rt_size_t length)

rt_err_t	rt_spi_sendrecv8 (struct rt_spi_device device, rt_uint8_t senddata, rt_uint8_t recvdata)

rt_err_t	rt_spi_sendrecv16 (struct rt_spi_device device, rt_uint16_t senddata, rt_uint16_t recvdata)

struct rt_spi_message *	rt_spi_transfer_message (struct rt_spi_device device, struct rt_spi_message message)

rt_inline rt_size_t	rt_spi_recv (struct rt_spi_device device, void recv_buf, rt_size_t length)

rt_inline rt_size_t	rt_spi_send (struct rt_spi_device device, const void send_buf, rt_size_t length)

rt_inline void	rt_spi_message_append (struct rt_spi_message list, struct rt_spi_message message)

rt_err_t	rt_qspi_configure (struct rt_qspi_device device, struct rt_qspi_configuration cfg)

rt_err_t	rt_qspi_bus_register (struct rt_spi_bus bus, const char name, const struct rt_spi_ops *ops)

rt_ssize_t	rt_qspi_transfer_message (struct rt_qspi_device device, struct rt_qspi_message message)

rt_ssize_t	rt_qspi_send_then_recv (struct rt_qspi_device device, const void send_buf, rt_size_t send_length, void *recv_buf, rt_size_t recv_length)

rt_ssize_t	rt_qspi_send (struct rt_qspi_device device, const void send_buf, rt_size_t length)

Detailed Description

SPI driver api.

Example

#include <rtthread.h>
#include <rtdevice.h>
 
#define W25Q_SPI_DEVICE_NAME     "qspi10"
 
static void spi_w25q_sample(int argc, char *argv[])
{
    struct rt_spi_device *spi_dev_w25q;
    char name[RT_NAME_MAX];
    rt_uint8_t w25x_read_id = 0x90;
    rt_uint8_t id[5] = {0};
 
    if (argc == 2)
    {
        rt_strncpy(name, argv[1], RT_NAME_MAX);
    }
    else
    {
        rt_strncpy(name, W25Q_SPI_DEVICE_NAME, RT_NAME_MAX);
    }
 
    // 查找 spi 设备获取设备句柄
    spi_dev_w25q = (struct rt_spi_device *)rt_device_find(name);
    if (!spi_dev_w25q)
    {
        rt_kprintf("spi sample run failed! can't find %s device!\n", name);
    }
    else
    {
        // 方式1：使用 rt_spi_send_then_recv()发送命令读取ID
        rt_spi_send_then_recv(spi_dev_w25q, &w25x_read_id, 1, id, 5);
        rt_kprintf("use rt_spi_send_then_recv() read w25q ID is:%x%x\n", id[3], id[4]);
 
        // 方式2：使用 rt_spi_transfer_message()发送命令读取ID
        struct rt_spi_message msg1, msg2;
 
        msg1.send_buf   = &w25x_read_id;
        msg1.recv_buf   = RT_NULL;
        msg1.length     = 1;
        msg1.cs_take    = 1;
        msg1.cs_release = 0;
        msg1.next       = &msg2;
 
        msg2.send_buf   = RT_NULL;
        msg2.recv_buf   = id;
        msg2.length     = 5;
        msg2.cs_take    = 0;
        msg2.cs_release = 1;
        msg2.next       = RT_NULL;
 
        rt_spi_transfer_message(spi_dev_w25q, &msg1);
        rt_kprintf("use rt_spi_transfer_message() read w25q ID is:%x%x\n", id[3], id[4]);
 
    }
}
// 导出到 msh 命令列表中
MSH_CMD_EXPORT(spi_w25q_sample, spi w25q sample);

Macro Definition Documentation

◆ RT_SPI_CPHA

#define RT_SPI_CPHA (1<<0)

At CPOL=0 the base value of the clock is zero

For CPHA=0, data are captured on the clock's rising edge (low->high transition) and data are propagated on a falling edge (high->low clock transition).
For CPHA=1, data are captured on the clock's falling edge and data are propagated on a rising edge. At CPOL=1 the base value of the clock is one (inversion of CPOL=0)
For CPHA=0, data are captured on clock's falling edge and data are propagated on a rising edge.
For CPHA=1, data are captured on clock's rising edge and data are propagated on a falling edge. bit[0]:CPHA, clock phase

◆ RT_SPI_CPOL

#define RT_SPI_CPOL (1<<1)

bit[1]:CPOL, clock polarity

◆ RT_SPI_LSB

#define RT_SPI_LSB (0<<2)

bit[2]: 0-LSB

◆ RT_SPI_MSB

#define RT_SPI_MSB (1<<2)

bit[2]: 1-MSB

◆ RT_SPI_MASTER

#define RT_SPI_MASTER (0<<3)

SPI master device

◆ RT_SPI_SLAVE

#define RT_SPI_SLAVE (1<<3)

SPI slave device

◆ RT_SPI_CS_HIGH

#define RT_SPI_CS_HIGH (1<<4)

Chipselect active high

◆ RT_SPI_NO_CS

#define RT_SPI_NO_CS (1<<5)

No chipselect

◆ RT_SPI_3WIRE

#define RT_SPI_3WIRE (1<<6)

SI/SO pin shared

◆ RT_SPI_READY

#define RT_SPI_READY (1<<7)

Slave pulls low to pause

◆ RT_SPI_MODE_0

#define RT_SPI_MODE_0 (0 | 0)

CPOL = 0, CPHA = 0

◆ RT_SPI_MODE_1

#define RT_SPI_MODE_1 (0 | RT_SPI_CPHA)

CPOL = 0, CPHA = 1

◆ RT_SPI_MODE_2

#define RT_SPI_MODE_2 (RT_SPI_CPOL | 0)

CPOL = 1, CPHA = 0

◆ RT_SPI_MODE_3

#define RT_SPI_MODE_3 (RT_SPI_CPOL | RT_SPI_CPHA)

CPOL = 1, CPHA = 1

Function Documentation

◆ rt_spi_bus_register()

rt_err_t rt_spi_bus_register	(	struct rt_spi_bus *	bus,
		const char *	name,
		const struct rt_spi_ops *	ops
	)

register a SPI bus

Parameters

bus	the SPI bus
name	the name of SPI bus
ops	the operations of SPI bus

Returns: rt_err_t error code

◆ rt_spi_bus_attach_device()

rt_err_t rt_spi_bus_attach_device	(	struct rt_spi_device *	device,
		const char *	name,
		const char *	bus_name,
		void *	user_data
	)

attach a device on SPI bus

Parameters

device	the SPI device
name	the name of SPI device
bus_name	the name of SPI bus
user_data	the user data of SPI device

Returns: rt_err_t error code

◆ rt_spi_bus_detach_device()

rt_err_t rt_spi_bus_detach_device ( struct rt_spi_device * device )

Detach a device from the SPI bus.

This function serves as the high-level API to detach a SPI device from its bus. It unregisters the device from the device framework and ensures all associated resources, such as the chip select pin, are properly released by calling the underlying implementation.

Parameters

device The SPI device to be detached.

Returns: rt_err_t The result of the operation. RT_EOK on success, otherwise an error code.

◆ rt_spi_bus_attach_device_cspin()

rt_err_t rt_spi_bus_attach_device_cspin	(	struct rt_spi_device *	device,
		const char *	name,
		const char *	bus_name,
		rt_base_t	cs_pin,
		void *	user_data
	)

attach a device on SPI bus with CS pin

Parameters

device	the SPI device
name	the name of SPI device
bus_name	the name of SPI bus
cs_pin	the CS pin of SPI device
user_data	the user data of SPI device

Returns: rt_err_t error code

◆ rt_spi_bus_detach_device_cspin()

rt_err_t rt_spi_bus_detach_device_cspin ( struct rt_spi_device * device )

Detach a device from the SPI bus and release its CS pin.

This function provides the low-level implementation for detaching a device from the SPI bus. It specifically handles the operations for the chip select (CS) pin, resetting it to input mode to release it. This function is typically called by the higher-level rt_spi_bus_detach_device() and should not be called directly by the user application.

Parameters

device The SPI device to be detached.

Returns: rt_err_t The result of the operation. RT_EOK on success, otherwise an error code.

◆ rt_spi_bus_configure()

rt_err_t rt_spi_bus_configure ( struct rt_spi_device * device )

Reconfigure the SPI bus for the specified device.

Parameters

device Pointer to the SPI device attached to the SPI bus.

Return values

RT_EOK if the SPI device was successfully released and the bus was configured. RT_EBUSY if the SPI bus is currently in use; the new configuration will take effect once the device releases the bus. Other return values indicate failure to configure the SPI bus due to various reasons.

Note: If the configuration of the SPI device has been updated and requires bus re-initialization, call this function directly. This function will reconfigure the SPI bus for the specified device. If this is the first time to initialize the SPI device, please call rt_spi_configure or rt_qspi_configure. This function is used to reconfigure the SPI bus when the SPI device is already in use. For further details, refer to: https://github.com/RT-Thread/rt-thread/pull/8528

◆ rt_spi_take_bus()

rt_err_t rt_spi_take_bus ( struct rt_spi_device * device )

This function takes SPI bus.

Parameters

device the SPI device attached to SPI bus

Returns: RT_EOK on taken SPI bus successfully. others on taken SPI bus failed.

◆ rt_spi_release_bus()

rt_err_t rt_spi_release_bus ( struct rt_spi_device * device )

This function releases SPI bus.

Parameters

device the SPI device attached to SPI bus

Returns: RT_EOK on release SPI bus successfully.

◆ rt_spi_take()

rt_err_t rt_spi_take ( struct rt_spi_device * device )

This function take SPI device (takes CS of SPI device).

Parameters

device the SPI device attached to SPI bus

Returns: RT_EOK on release SPI bus successfully. others on taken SPI bus failed.

◆ rt_spi_release()

rt_err_t rt_spi_release ( struct rt_spi_device * device )

This function releases SPI device (releases CS of SPI device).

Parameters

device the SPI device attached to SPI bus

Returns: RT_EOK on release SPI device successfully.

◆ rt_spi_configure()

rt_err_t rt_spi_configure	(	struct rt_spi_device *	device,
		struct rt_spi_configuration *	cfg
	)

This function can set configuration on SPI device.

Parameters

device	the SPI device attached to SPI bus
cfg	the configuration pointer.

Return values

RT_EOK on release SPI device successfully. RT_EBUSY is not an error condition and the configuration will take effect once the device has the bus others on taken SPI bus failed.

◆ rt_spi_send_then_recv()

rt_err_t rt_spi_send_then_recv	(	struct rt_spi_device *	device,
		const void *	send_buf,
		rt_size_t	send_length,
		void *	recv_buf,
		rt_size_t	recv_length
	)

This function can send data then receive data from SPI device.

Parameters

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
send_length	the number of data to be transmitted.
recv_buf	the buffer to be recivied from SPI device.
recv_length	the data to be recivied.

Returns: rt_err_t error code

◆ rt_spi_send_then_send()

rt_err_t rt_spi_send_then_send	(	struct rt_spi_device *	device,
		const void *	send_buf1,
		rt_size_t	send_length1,
		const void *	send_buf2,
		rt_size_t	send_length2
	)

This function can send data then send data from SPI device.

Parameters

device	the SPI device attached to SPI bus
send_buf1	the buffer to be transmitted to SPI device.
send_length1	the number of data to be transmitted.
send_buf2	the buffer to be transmitted to SPI device.
send_length2	the number of data to be transmitted.

Returns: the status of transmit.

◆ rt_spi_transfer()

rt_ssize_t rt_spi_transfer	(	struct rt_spi_device *	device,
		const void *	send_buf,
		void *	recv_buf,
		rt_size_t	length
	)

This function transmits data to SPI device.

Parameters

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
recv_buf	the buffer to save received data from SPI device.
length	the length of transmitted data.

Returns: the actual length of transmitted.

◆ rt_spi_sendrecv8()

rt_err_t rt_spi_sendrecv8	(	struct rt_spi_device *	device,
		rt_uint8_t	senddata,
		rt_uint8_t *	recvdata
	)

The SPI device transmits 8 bytes of data.

Parameters

device	the SPI device attached to SPI bus
senddata	send data buffer
recvdata	receive data buffer

Returns: rt_err_t error code

◆ rt_spi_sendrecv16()

rt_err_t rt_spi_sendrecv16	(	struct rt_spi_device *	device,
		rt_uint16_t	senddata,
		rt_uint16_t *	recvdata
	)

The SPI device transmits 16 bytes of data.

Parameters

device	the SPI device attached to SPI bus
senddata	send data buffer
recvdata	receive data buffer

Returns: rt_err_t error code

◆ rt_spi_transfer_message()

struct rt_spi_message* rt_spi_transfer_message	(	struct rt_spi_device *	device,
		struct rt_spi_message *	message
	)

This function transfers a message list to the SPI device.

Parameters

device	the SPI device attached to SPI bus
message	the message list to be transmitted to SPI device

Returns: RT_NULL if transmits message list successfully, SPI message which be transmitted failed.

◆ rt_spi_recv()

rt_inline rt_size_t rt_spi_recv	(	struct rt_spi_device *	device,
		void *	recv_buf,
		rt_size_t	length
	)

This function receives data from SPI device.

Parameters

device	the SPI device attached to SPI bus
recv_buf	the buffer to be recivied from SPI device.
length	the data to be recivied.

Returns: the actual length of received.

◆ rt_spi_send()

rt_inline rt_size_t rt_spi_send	(	struct rt_spi_device *	device,
		const void *	send_buf,
		rt_size_t	length
	)

This function sends data to SPI device.

Parameters

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
length	the number of data to be transmitted.

Returns: the actual length of send.

◆ rt_spi_message_append()

rt_inline void rt_spi_message_append	(	struct rt_spi_message *	list,
		struct rt_spi_message *	message
	)

This function appends a message to the SPI message list.

Parameters

list	the SPI message list header.
message	the message pointer to be appended to the message list.

◆ rt_qspi_configure()

rt_err_t rt_qspi_configure	(	struct rt_qspi_device *	device,
		struct rt_qspi_configuration *	cfg
	)

This function can set configuration on QSPI device.

Parameters

device	the QSPI device attached to QSPI bus.
cfg	the configuration pointer.

Returns: the actual length of transmitted.

◆ rt_qspi_bus_register()

rt_err_t rt_qspi_bus_register	(	struct rt_spi_bus *	bus,
		const char *	name,
		const struct rt_spi_ops *	ops
	)

This function can register a SPI bus for QSPI mode.

Parameters

bus	the SPI bus for QSPI mode.
name	The name of the spi bus.
ops	the SPI bus instance to be registered.

Returns: the actual length of transmitted.

◆ rt_qspi_transfer_message()

rt_ssize_t rt_qspi_transfer_message	(	struct rt_qspi_device *	device,
		struct rt_qspi_message *	message
	)

This function transmits data to QSPI device.

Parameters

device	the QSPI device attached to QSPI bus.
message	the message pointer.

Returns: the actual length of transmitted.

◆ rt_qspi_send_then_recv()

rt_ssize_t rt_qspi_send_then_recv	(	struct rt_qspi_device *	device,
		const void *	send_buf,
		rt_size_t	send_length,
		void *	recv_buf,
		rt_size_t	recv_length
	)

This function can send data then receive data from QSPI device.

Parameters

device	the QSPI device attached to QSPI bus.
send_buf	the buffer to be transmitted to QSPI device.
send_length	the number of data to be transmitted.
recv_buf	the buffer to be recivied from QSPI device.
recv_length	the data to be recivied.

Returns: the status of transmit.

◆ rt_qspi_send()

rt_ssize_t rt_qspi_send	(	struct rt_qspi_device *	device,
		const void *	send_buf,
		rt_size_t	length
	)

This function can send data to QSPI device.

Parameters

device	the QSPI device attached to QSPI bus.
send_buf	the buffer to be transmitted to QSPI device.
length	the number of data to be transmitted.

Returns: the status of transmit.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RT_SPI_CPHA

◆ RT_SPI_CPOL

◆ RT_SPI_LSB

◆ RT_SPI_MSB

◆ RT_SPI_MASTER

◆ RT_SPI_SLAVE

◆ RT_SPI_CS_HIGH

◆ RT_SPI_NO_CS

◆ RT_SPI_3WIRE

◆ RT_SPI_READY

◆ RT_SPI_MODE_0

◆ RT_SPI_MODE_1

◆ RT_SPI_MODE_2

◆ RT_SPI_MODE_3

Function Documentation

◆ rt_spi_bus_register()

◆ rt_spi_bus_attach_device()

◆ rt_spi_bus_detach_device()

◆ rt_spi_bus_attach_device_cspin()

◆ rt_spi_bus_detach_device_cspin()

◆ rt_spi_bus_configure()

◆ rt_spi_take_bus()

◆ rt_spi_release_bus()

◆ rt_spi_take()

◆ rt_spi_release()

◆ rt_spi_configure()

◆ rt_spi_send_then_recv()

◆ rt_spi_send_then_send()

◆ rt_spi_transfer()

◆ rt_spi_sendrecv8()

◆ rt_spi_sendrecv16()

◆ rt_spi_transfer_message()

◆ rt_spi_recv()

◆ rt_spi_send()

◆ rt_spi_message_append()

◆ rt_qspi_configure()

◆ rt_qspi_bus_register()

◆ rt_qspi_transfer_message()

◆ rt_qspi_send_then_recv()

◆ rt_qspi_send()