rt-thread/components/drivers/include/drivers/dev_spi.h

/*
 * Copyright (c) 2006-2025 RT-Thread Development Team
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * Change Logs:
 * Date           Author       Notes
 * 2012-11-23     Bernard      Add extern "C"
 * 2020-06-13     armink       fix the 3 wires issue
 * 2022-09-01     liYony       fix api rt_spi_sendrecv16 about MSB and LSB bug
 * 2025-10-30     wdfk-prog    enable interrupt-safe operations using spinlocks
 */

#ifndef __DEV_SPI_H__
#define __DEV_SPI_H__

#include <stdlib.h>
#include <rtthread.h>
#include <drivers/dev_pin.h>
#include <drivers/core/driver.h>

/**
 * @defgroup    group_drivers_spi SPI
 * @brief       SPI driver api
 * @ingroup     group_device_driver
 *
 * <b>Example</b>
 * @code {.c}
 * #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);
 * @endcode
 */

/*!
 * @addtogroup group_drivers_spi
 * @{
 */
#ifdef __cplusplus
extern "C"{
#endif

/**
 * 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.
 */
#define RT_SPI_CPHA     (1<<0)                             /*!< bit[0]:CPHA, clock phase */
#define RT_SPI_CPOL     (1<<1)                             /*!< bit[1]:CPOL, clock polarity */

#define RT_SPI_LSB      (0<<2)                             /*!< bit[2]: 0-LSB */
#define RT_SPI_MSB      (1<<2)                             /*!< bit[2]: 1-MSB */

#define RT_SPI_MASTER   (0<<3)                             /*!< SPI master device */
#define RT_SPI_SLAVE    (1<<3)                             /*!< SPI slave device */

#define RT_SPI_CS_HIGH  (1<<4)                             /*!< Chipselect active high */
#define RT_SPI_NO_CS    (1<<5)                             /*!< No chipselect */
#define RT_SPI_3WIRE    (1<<6)                             /*!< SI/SO pin shared */
#define RT_SPI_READY    (1<<7)                             /*!< Slave pulls low to pause */

#define RT_SPI_MODE_MASK    (RT_SPI_CPHA | RT_SPI_CPOL | RT_SPI_MSB | RT_SPI_SLAVE | RT_SPI_CS_HIGH | RT_SPI_NO_CS | RT_SPI_3WIRE | RT_SPI_READY)

#define RT_SPI_MODE_0       (0 | 0)                        /*!< CPOL = 0, CPHA = 0 */
#define RT_SPI_MODE_1       (0 | RT_SPI_CPHA)              /*!< CPOL = 0, CPHA = 1 */
#define RT_SPI_MODE_2       (RT_SPI_CPOL | 0)              /*!< CPOL = 1, CPHA = 0 */
#define RT_SPI_MODE_3       (RT_SPI_CPOL | RT_SPI_CPHA)    /*!< CPOL = 1, CPHA = 1 */

#define RT_SPI_BUS_MODE_SPI         (1<<0)
#define RT_SPI_BUS_MODE_QSPI        (1<<1)

#define RT_SPI_CS_CNT_MAX           16

/**
 * @brief SPI message structure
 */
struct rt_spi_message
{
    const void *send_buf;
    void *recv_buf;
    rt_size_t length;
    struct rt_spi_message *next;

    unsigned cs_take    : 1;
    unsigned cs_release : 1;
};

/**
 * @brief SPI configuration structure
 */
struct rt_spi_configuration
{
    rt_uint8_t mode;
    rt_uint8_t data_width;
#ifdef RT_USING_DM
    rt_uint8_t data_width_tx;
    rt_uint8_t data_width_rx;
#else
    rt_uint16_t reserved;
#endif

    rt_uint32_t max_hz;
};

struct rt_spi_ops;

/**
 * @brief SPI bus structure
 */
struct rt_spi_bus
{
    struct rt_device parent;
    rt_uint8_t mode;
    const struct rt_spi_ops *ops;

#ifdef RT_USING_DM
    rt_base_t cs_pins[RT_SPI_CS_CNT_MAX];
    rt_uint8_t cs_active_vals[RT_SPI_CS_CNT_MAX];
    rt_bool_t slave;
    int num_chipselect;
#endif /* RT_USING_DM */

    struct rt_mutex lock;
#ifdef RT_USING_SPI_ISR
    rt_base_t _isr_lvl;
    struct rt_spinlock _spinlock;
#endif /* RT_USING_SPI_ISR */
    struct rt_spi_device *owner;
};

/**
 * @brief SPI operators
 */
struct rt_spi_ops
{
    rt_err_t (*configure)(struct rt_spi_device *device, struct rt_spi_configuration *configuration);
    rt_ssize_t (*xfer)(struct rt_spi_device *device, struct rt_spi_message *message);
};

#ifdef RT_USING_DM
/**
 * @brief SPI delay info
 */
struct rt_spi_delay
{
#define RT_SPI_DELAY_UNIT_USECS 0
#define RT_SPI_DELAY_UNIT_NSECS 1
#define RT_SPI_DELAY_UNIT_SCK   2
    rt_uint16_t value;
    rt_uint8_t  unit;
};
#endif /* RT_USING_DM */

/**
 * @brief SPI Virtual BUS, one device must connected to a virtual BUS
 */
struct rt_spi_device
{
    struct rt_device parent;
    struct rt_spi_bus *bus;

#ifdef RT_USING_DM
    const char *name;
    const struct rt_spi_device_id *id;
    const struct rt_ofw_node_id *ofw_id;

    rt_uint8_t chip_select[RT_SPI_CS_CNT_MAX];
    struct rt_spi_delay cs_setup;
    struct rt_spi_delay cs_hold;
    struct rt_spi_delay cs_inactive;
#endif

    struct rt_spi_configuration config;
    rt_base_t cs_pin;
    void   *user_data;
};

/**
 * @brief QSPI message structure
 */
struct rt_qspi_message
{
    struct rt_spi_message parent;

    /* instruction stage */
    struct
    {
        rt_uint8_t content;
        rt_uint8_t qspi_lines;
    } instruction;

    /* address and alternate_bytes stage */
    struct
    {
        rt_uint32_t content;
        rt_uint8_t size;
        rt_uint8_t qspi_lines;
    } address, alternate_bytes;

    /* dummy_cycles stage */
    rt_uint32_t dummy_cycles;

    /* number of lines in qspi data stage, the other configuration items are in parent */
    rt_uint8_t qspi_data_lines;
};

/**
 * @brief QSPI configuration structure
 */
struct rt_qspi_configuration
{
    struct rt_spi_configuration parent;
    /* The size of medium */
    rt_uint32_t medium_size;
    /* double data rate mode */
    rt_uint8_t ddr_mode;
    /* the data lines max width which QSPI bus supported, such as 1, 2, 4 */
    rt_uint8_t qspi_dl_width ;
};

/**
 * @brief QSPI operators
 */
struct rt_qspi_device
{
    struct rt_spi_device parent;

    struct rt_qspi_configuration config;

    void (*enter_qspi_mode)(struct rt_qspi_device *device);

    void (*exit_qspi_mode)(struct rt_qspi_device *device);
};

#define SPI_DEVICE(dev) ((struct rt_spi_device *)(dev))

#ifdef RT_USING_DM
struct rt_spi_device_id
{
    char name[20];
    void *data;
};

struct rt_spi_driver
{
    struct rt_driver parent;

    const struct rt_spi_device_id *ids;
    const struct rt_ofw_node_id *ofw_ids;

    rt_err_t (*probe)(struct rt_spi_device *device);
    rt_err_t (*remove)(struct rt_spi_device *device);
    rt_err_t (*shutdown)(struct rt_spi_device *device);
};

rt_err_t rt_spi_driver_register(struct rt_spi_driver *driver);
rt_err_t rt_spi_device_register(struct rt_spi_device *device);

#define RT_SPI_DRIVER_EXPORT(driver)  RT_DRIVER_EXPORT(driver, spi, BUILIN)

rt_inline const void *rt_spi_device_id_data(struct rt_spi_device *device)
{
    return device->id ? device->id->data : (device->ofw_id ? device->ofw_id->data : RT_NULL);
}
#endif /* RT_USING_DM */

/**
 * @brief register a SPI bus
 *
 * @param bus the SPI bus
 * @param name the name of SPI bus
 * @param ops the operations of SPI bus
 *
 * @return rt_err_t error code
 */
rt_err_t rt_spi_bus_register(struct rt_spi_bus       *bus,
                             const char              *name,
                             const struct rt_spi_ops *ops);


/**
 * @brief attach a device on SPI bus
 *
 * @param device the SPI device
 * @param name the name of SPI device
 * @param bus_name the name of SPI bus
 * @param user_data the user data of SPI device
 *
 * @return rt_err_t error code
 */
rt_err_t rt_spi_bus_attach_device(struct rt_spi_device *device,
                                  const char           *name,
                                  const char           *bus_name,
                                  void                 *user_data);

/**
 * @brief 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.
 *
 * @param device The SPI device to be detached.
 *
 * @return rt_err_t The result of the operation. RT_EOK on success, otherwise an error code.
 */
rt_err_t rt_spi_bus_detach_device(struct rt_spi_device *device);

/**
 * @brief attach a device on SPI bus with CS pin
 *
 * @param device the SPI device
 * @param name the name of SPI device
 * @param bus_name the name of SPI bus
 * @param cs_pin the CS pin of SPI device
 * @param user_data the user data of SPI device
 *
 * @return rt_err_t error code
 */
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);

/**
 * @brief 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.
 *
 * @param device The SPI device to be detached.
 *
 * @return rt_err_t The result of the operation. RT_EOK on success, otherwise an error code.
 */
rt_err_t rt_spi_bus_detach_device_cspin(struct rt_spi_device *device);

/**
 * @brief  Reconfigure the SPI bus for the specified device.
 *
 * @param  device: Pointer to the SPI device attached to the SPI bus.
 * @retval 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_err_t rt_spi_bus_configure(struct rt_spi_device *device);

/**
 * @brief This function takes SPI bus.
 *
 * @param device the SPI device attached to SPI bus
 *
 * @return RT_EOK on taken SPI bus successfully. others on taken SPI bus failed.
 */
rt_err_t rt_spi_take_bus(struct rt_spi_device *device);

/**
 * @brief This function releases SPI bus.
 *
 * @param device the SPI device attached to SPI bus
 *
 * @return RT_EOK on release SPI bus successfully.
 */
rt_err_t rt_spi_release_bus(struct rt_spi_device *device);

/**
 * @brief This function take SPI device (takes CS of SPI device).
 *
 * @param device the SPI device attached to SPI bus
 *
 * @return RT_EOK on release SPI bus successfully. others on taken SPI bus failed.
 */
rt_err_t rt_spi_take(struct rt_spi_device *device);

/**
 * @brief This function releases SPI device (releases CS of SPI device).
 *
 * @param device the SPI device attached to SPI bus
 *
 * @return RT_EOK on release SPI device successfully.
 */
rt_err_t rt_spi_release(struct rt_spi_device *device);

/**
 * @brief  This function can set configuration on SPI device.
 *
 * @param  device: the SPI device attached to SPI bus
 * @param  cfg: the configuration pointer.
 *
 * @retval 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_err_t rt_spi_configure(struct rt_spi_device        *device,
                          struct rt_spi_configuration *cfg);


/**
 * @brief This function can send data then receive data from SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param send_buf the buffer to be transmitted to SPI device.
 * @param send_length the number of data to be transmitted.
 * @param recv_buf the buffer to be recivied from SPI device.
 * @param recv_length the data to be recivied.
 *
 * @return rt_err_t error code
 */
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);

/**
 * @brief This function can send data then send data from SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param send_buf1 the buffer to be transmitted to SPI device.
 * @param send_length1 the number of data to be transmitted.
 * @param send_buf2 the buffer to be transmitted to SPI device.
 * @param send_length2 the number of data to be transmitted.
 *
 * @return the status of transmit.
 */
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);

/**
 * @brief This function transmits data to SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param send_buf the buffer to be transmitted to SPI device.
 * @param recv_buf the buffer to save received data from SPI device.
 * @param length the length of transmitted data.
 *
 * @return the actual length of transmitted.
 */
rt_ssize_t rt_spi_transfer(struct rt_spi_device *device,
                           const void           *send_buf,
                           void                 *recv_buf,
                           rt_size_t             length);

/**
 * @brief The SPI device transmits 8 bytes of data
 *
 * @param device the SPI device attached to SPI bus
 * @param senddata send data buffer
 * @param recvdata receive data buffer
 *
 * @return rt_err_t error code
 */
rt_err_t rt_spi_sendrecv8(struct rt_spi_device *device,
                          rt_uint8_t            senddata,
                          rt_uint8_t           *recvdata);

/**
 * @brief The SPI device transmits 16 bytes of data
 *
 * @param device the SPI device attached to SPI bus
 * @param senddata send data buffer
 * @param recvdata receive data buffer
 *
 * @return rt_err_t error code
 */
rt_err_t rt_spi_sendrecv16(struct rt_spi_device *device,
                           rt_uint16_t           senddata,
                           rt_uint16_t          *recvdata);

/**
 * @brief This function transfers a message list to the SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param message the message list to be transmitted to SPI device
 *
 * @return RT_NULL if transmits message list successfully,
 *         SPI message which be transmitted failed.
 */
struct rt_spi_message *rt_spi_transfer_message(struct rt_spi_device  *device,
                                               struct rt_spi_message *message);

/**
 * @brief This function receives data from SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param recv_buf the buffer to be recivied from SPI device.
 * @param length the data to be recivied.
 *
 * @return the actual length of received.
*/
rt_inline rt_size_t rt_spi_recv(struct rt_spi_device *device,
                                void                 *recv_buf,
                                rt_size_t             length)
{
    return rt_spi_transfer(device, RT_NULL, recv_buf, length);
}

/**
 * @brief This function sends data to SPI device.
 *
 * @param device the SPI device attached to SPI bus
 * @param send_buf the buffer to be transmitted to SPI device.
 * @param length the number of data to be transmitted.
 *
 * @return the actual length of send.
 */
rt_inline rt_size_t rt_spi_send(struct rt_spi_device *device,
                                const void           *send_buf,
                                rt_size_t             length)
{
    return rt_spi_transfer(device, send_buf, RT_NULL, length);
}

/**
 * @brief This function appends a message to the SPI message list.
 *
 * @param list the SPI message list header.
 * @param message the message pointer to be appended to the message list.
 */
rt_inline void rt_spi_message_append(struct rt_spi_message *list,
                                     struct rt_spi_message *message)
{
    RT_ASSERT(list != RT_NULL);
    if (message == RT_NULL)
        return; /* not append */

    while (list->next != RT_NULL)
    {
        list = list->next;
    }

    list->next = message;
    message->next = RT_NULL;
}

/**
 * @brief This function can set configuration on QSPI device.
 *
 * @param device the QSPI device attached to QSPI bus.
 * @param cfg the configuration pointer.
 *
 * @return the actual length of transmitted.
 */
rt_err_t rt_qspi_configure(struct rt_qspi_device *device, struct rt_qspi_configuration *cfg);

/**
 * @brief This function can register a SPI bus for QSPI mode.
 *
 * @param bus the SPI bus for QSPI mode.
 * @param name The name of the spi bus.
 * @param ops the SPI bus instance to be registered.
 *
 * @return the actual length of transmitted.
 */
rt_err_t rt_qspi_bus_register(struct rt_spi_bus *bus, const char *name, const struct rt_spi_ops *ops);

/**
 * @brief This function transmits data to QSPI device.
 *
 * @param device the QSPI device attached to QSPI bus.
 * @param message the message pointer.
 *
 * @return the actual length of transmitted.
 */
rt_ssize_t rt_qspi_transfer_message(struct rt_qspi_device  *device, struct rt_qspi_message *message);

/**
 * @brief This function can send data then receive data from QSPI device
 *
 * @param device the QSPI device attached to QSPI bus.
 * @param send_buf the buffer to be transmitted to QSPI device.
 * @param send_length the number of data to be transmitted.
 * @param recv_buf the buffer to be recivied from QSPI device.
 * @param recv_length the data to be recivied.
 *
 * @return the status of transmit.
 */
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);

/**
 * @brief This function can send data to QSPI device
 *
 * @param device the QSPI device attached to QSPI bus.
 * @param send_buf the buffer to be transmitted to QSPI device.
 * @param length the number of data to be transmitted.
 *
 * @return the status of transmit.
 */
rt_ssize_t rt_qspi_send(struct rt_qspi_device *device, const void *send_buf, rt_size_t length);

#ifdef __cplusplus
}
#endif

/*! @}*/

#endif