mspi.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025, Ambiq Micro Inc. <www.ambiq.com>
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_MSPI_H_
#define ZEPHYR_INCLUDE_MSPI_H_
 
#include <errno.h>
 
#include <zephyr/sys/__assert.h>
#include <zephyr/types.h>
#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/drivers/gpio.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum mspi_op_mode {
        MSPI_OP_MODE_CONTROLLER     = 0,
        MSPI_OP_MODE_PERIPHERAL     = 1,
};
 
enum mspi_duplex {
        MSPI_HALF_DUPLEX            = 0,
        MSPI_FULL_DUPLEX            = 1,
};
 
enum mspi_io_mode {
        MSPI_IO_MODE_SINGLE         = 0,
        MSPI_IO_MODE_DUAL           = 1,
        MSPI_IO_MODE_DUAL_1_1_2     = 2,
        MSPI_IO_MODE_DUAL_1_2_2     = 3,
        MSPI_IO_MODE_QUAD           = 4,
        MSPI_IO_MODE_QUAD_1_1_4     = 5,
        MSPI_IO_MODE_QUAD_1_4_4     = 6,
        MSPI_IO_MODE_OCTAL          = 7,
        MSPI_IO_MODE_OCTAL_1_1_8    = 8,
        MSPI_IO_MODE_OCTAL_1_8_8    = 9,
        MSPI_IO_MODE_HEX            = 10,
        MSPI_IO_MODE_HEX_8_8_16     = 11,
        MSPI_IO_MODE_HEX_8_16_16    = 12,
        MSPI_IO_MODE_MAX,
};
 
enum mspi_data_rate {
        MSPI_DATA_RATE_SINGLE       = 0,
        MSPI_DATA_RATE_S_S_D        = 1,
        MSPI_DATA_RATE_S_D_D        = 2,
        MSPI_DATA_RATE_DUAL         = 3,
        MSPI_DATA_RATE_MAX,
};
 
enum mspi_cpp_mode {
        MSPI_CPP_MODE_0             = 0,
        MSPI_CPP_MODE_1             = 1,
        MSPI_CPP_MODE_2             = 2,
        MSPI_CPP_MODE_3             = 3,
};
 
enum mspi_endian {
        MSPI_XFER_LITTLE_ENDIAN     = 0,
        MSPI_XFER_BIG_ENDIAN        = 1,
};
 
enum mspi_ce_polarity {
        MSPI_CE_ACTIVE_LOW          = 0,
        MSPI_CE_ACTIVE_HIGH         = 1,
};
 
enum mspi_bus_event {
        MSPI_BUS_RESET              = 0,
        MSPI_BUS_ERROR              = 1,
        MSPI_BUS_XFER_COMPLETE      = 2,
        MSPI_BUS_TIMEOUT            = 3,
        MSPI_BUS_EVENT_MAX,
};
 
enum mspi_bus_event_cb_mask {
        MSPI_BUS_NO_CB              = 0,
        MSPI_BUS_RESET_CB           = BIT(0),
        MSPI_BUS_ERROR_CB           = BIT(1),
        MSPI_BUS_XFER_COMPLETE_CB   = BIT(2),
        MSPI_BUS_TIMEOUT_CB         = BIT(3),
};
 
enum mspi_xfer_mode {
        MSPI_PIO,
        MSPI_DMA,
};
 
enum mspi_xfer_priority {
        MSPI_XFER_PRIORITY_LOW,
        MSPI_XFER_PRIORITY_MEDIUM,
        MSPI_XFER_PRIORITY_HIGH,
};
 
enum mspi_xfer_direction {
        MSPI_RX,
        MSPI_TX,
};
 
enum mspi_dev_cfg_mask {
        MSPI_DEVICE_CONFIG_NONE         = 0,
        MSPI_DEVICE_CONFIG_CE_NUM       = BIT(0),
        MSPI_DEVICE_CONFIG_FREQUENCY    = BIT(1),
        MSPI_DEVICE_CONFIG_IO_MODE      = BIT(2),
        MSPI_DEVICE_CONFIG_DATA_RATE    = BIT(3),
        MSPI_DEVICE_CONFIG_CPP          = BIT(4),
        MSPI_DEVICE_CONFIG_ENDIAN       = BIT(5),
        MSPI_DEVICE_CONFIG_CE_POL       = BIT(6),
        MSPI_DEVICE_CONFIG_DQS          = BIT(7),
        MSPI_DEVICE_CONFIG_RX_DUMMY     = BIT(8),
        MSPI_DEVICE_CONFIG_TX_DUMMY     = BIT(9),
        MSPI_DEVICE_CONFIG_READ_CMD     = BIT(10),
        MSPI_DEVICE_CONFIG_WRITE_CMD    = BIT(11),
        MSPI_DEVICE_CONFIG_CMD_LEN      = BIT(12),
        MSPI_DEVICE_CONFIG_ADDR_LEN     = BIT(13),
        MSPI_DEVICE_CONFIG_MEM_BOUND    = BIT(14),
        MSPI_DEVICE_CONFIG_BREAK_TIME   = BIT(15),
        MSPI_DEVICE_CONFIG_ALL          = BIT_MASK(16),
};
 
enum mspi_xip_permit {
        MSPI_XIP_READ_WRITE     = 0,
        MSPI_XIP_READ_ONLY      = 1,
};
 
enum mspi_timing_param {
        MSPI_TIMING_PARAM_DUMMY
};
 
struct mspi_timing_cfg {
#ifdef __cplusplus
        /* For C++ compatibility. */
        uint8_t dummy;
#endif
};
 
struct mspi_dev_id {
        struct gpio_dt_spec     ce;
        uint16_t                dev_idx;
};
 
struct mspi_cfg {
        uint8_t                 channel_num;
        enum mspi_op_mode       op_mode;
        enum mspi_duplex        duplex;
        bool                    dqs_support;
        bool                    sw_multi_periph;
        struct gpio_dt_spec     *ce_group;
        uint32_t                num_ce_gpios;
        uint32_t                num_periph;
        uint32_t                max_freq;
        bool                    re_init;
};
 
struct mspi_dt_spec {
        const struct device     *bus;
        struct mspi_cfg         config;
};
 
struct mspi_dev_cfg {
        uint8_t                 ce_num;
        uint32_t                freq;
        enum mspi_io_mode       io_mode;
        enum mspi_data_rate     data_rate;
        enum mspi_cpp_mode      cpp;
        enum mspi_endian        endian;
        enum mspi_ce_polarity   ce_polarity;
        bool                    dqs_enable;
        uint16_t                rx_dummy;
        uint16_t                tx_dummy;
        uint32_t                read_cmd;
        uint32_t                write_cmd;
        uint8_t                 cmd_length;
        uint8_t                 addr_length;
        uint32_t                mem_boundary;
        uint32_t                time_to_break;
};
 
struct mspi_xip_cfg {
        bool                    enable;
        uint32_t                address_offset;
        uint32_t                size;
        enum mspi_xip_permit    permission;
};
 
struct mspi_scramble_cfg {
        bool                    enable;
        uint32_t                address_offset;
        uint32_t                size;
};
 
struct mspi_ce_control {
        struct gpio_dt_spec         gpio;
        uint32_t                    delay;
};
 
struct mspi_xfer_packet {
        enum mspi_xfer_direction    dir;
        enum mspi_bus_event_cb_mask cb_mask;
        uint32_t                    cmd;
        uint32_t                    address;
        uint32_t                    num_bytes;
        uint8_t                     *data_buf;
};
 
struct mspi_xfer {
        bool                        async;
        enum mspi_xfer_mode         xfer_mode;
        uint16_t                    tx_dummy;
        uint16_t                    rx_dummy;
        uint8_t                     cmd_length;
        uint8_t                     addr_length;
        bool                        hold_ce;
        struct mspi_ce_control      ce_sw_ctrl;
        enum mspi_xfer_priority     priority;
        const struct mspi_xfer_packet *packets;
        uint32_t                    num_packet;
        uint32_t                    timeout;
};
 
struct mspi_event_data {
        const struct device         *controller;
        const struct mspi_dev_id    *dev_id;
        const struct mspi_xfer_packet *packet;
        uint32_t                    status;
        uint32_t                    packet_idx;
};
 
struct mspi_event {
        enum mspi_bus_event         evt_type;
        struct mspi_event_data      evt_data;
};
 
struct mspi_callback_context {
        struct mspi_event           mspi_evt;
        void                        *ctx;
};
 
typedef void (*mspi_callback_handler_t)(struct mspi_callback_context *mspi_cb_ctx, ...);
 
typedef int (*mspi_api_config)(const struct mspi_dt_spec *spec);
 
typedef int (*mspi_api_dev_config)(const struct device *controller,
                                   const struct mspi_dev_id *dev_id,
                                   const enum mspi_dev_cfg_mask param_mask,
                                   const struct mspi_dev_cfg *cfg);
 
typedef int (*mspi_api_get_channel_status)(const struct device *controller, uint8_t ch);
 
typedef int (*mspi_api_transceive)(const struct device *controller,
                                   const struct mspi_dev_id *dev_id,
                                   const struct mspi_xfer *req);
 
typedef int (*mspi_api_register_callback)(const struct device *controller,
                                          const struct mspi_dev_id *dev_id,
                                          const enum mspi_bus_event evt_type,
                                          mspi_callback_handler_t cb,
                                          struct mspi_callback_context *ctx);
 
typedef int (*mspi_api_xip_config)(const struct device *controller,
                                   const struct mspi_dev_id *dev_id,
                                   const struct mspi_xip_cfg *xip_cfg);
 
typedef int (*mspi_api_scramble_config)(const struct device *controller,
                                        const struct mspi_dev_id *dev_id,
                                        const struct mspi_scramble_cfg *scramble_cfg);
 
typedef int (*mspi_api_timing_config)(const struct device *controller,
                                      const struct mspi_dev_id *dev_id, const uint32_t param_mask,
                                      void *timing_cfg);
 
__subsystem struct mspi_driver_api {
        mspi_api_config                config;
        mspi_api_dev_config            dev_config;
        mspi_api_get_channel_status    get_channel_status;
        mspi_api_transceive            transceive;
        mspi_api_register_callback     register_callback;
        mspi_api_xip_config            xip_config;
        mspi_api_scramble_config       scramble_config;
        mspi_api_timing_config         timing_config;
};
 
__syscall int mspi_config(const struct mspi_dt_spec *spec);
 
static inline int z_impl_mspi_config(const struct mspi_dt_spec *spec)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)spec->bus->api;
 
        return api->config(spec);
}
 
__syscall int mspi_dev_config(const struct device *controller,
                              const struct mspi_dev_id *dev_id,
                              const enum mspi_dev_cfg_mask param_mask,
                              const struct mspi_dev_cfg *cfg);
 
static inline int z_impl_mspi_dev_config(const struct device *controller,
                                         const struct mspi_dev_id *dev_id,
                                         const enum mspi_dev_cfg_mask param_mask,
                                         const struct mspi_dev_cfg *cfg)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        return api->dev_config(controller, dev_id, param_mask, cfg);
}
 
__syscall int mspi_get_channel_status(const struct device *controller, uint8_t ch);
 
static inline int z_impl_mspi_get_channel_status(const struct device *controller, uint8_t ch)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        return api->get_channel_status(controller, ch);
}
 
__syscall int mspi_transceive(const struct device *controller,
                              const struct mspi_dev_id *dev_id,
                              const struct mspi_xfer *req);
 
static inline int z_impl_mspi_transceive(const struct device *controller,
                                         const struct mspi_dev_id *dev_id,
                                         const struct mspi_xfer *req)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        if (!api->transceive) {
                return -ENOTSUP;
        }
 
        return api->transceive(controller, dev_id, req);
}
 
__syscall int mspi_xip_config(const struct device *controller,
                              const struct mspi_dev_id *dev_id,
                              const struct mspi_xip_cfg *cfg);
 
static inline int z_impl_mspi_xip_config(const struct device *controller,
                                         const struct mspi_dev_id *dev_id,
                                         const struct mspi_xip_cfg *cfg)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        if (!api->xip_config) {
                return -ENOTSUP;
        }
 
        return api->xip_config(controller, dev_id, cfg);
}
 
__syscall int mspi_scramble_config(const struct device *controller,
                                   const struct mspi_dev_id *dev_id,
                                   const struct mspi_scramble_cfg *cfg);
 
static inline int z_impl_mspi_scramble_config(const struct device *controller,
                                              const struct mspi_dev_id *dev_id,
                                              const struct mspi_scramble_cfg *cfg)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        if (!api->scramble_config) {
                return -ENOTSUP;
        }
 
        return api->scramble_config(controller, dev_id, cfg);
}
 
__syscall int mspi_timing_config(const struct device *controller,
                                 const struct mspi_dev_id *dev_id,
                                 const uint32_t param_mask, void *cfg);
 
static inline int z_impl_mspi_timing_config(const struct device *controller,
                                            const struct mspi_dev_id *dev_id,
                                            const uint32_t param_mask, void *cfg)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        if (!api->timing_config) {
                return -ENOTSUP;
        }
 
        return api->timing_config(controller, dev_id, param_mask, cfg);
}
 
static inline int mspi_register_callback(const struct device *controller,
                                         const struct mspi_dev_id *dev_id,
                                         const enum mspi_bus_event evt_type,
                                         mspi_callback_handler_t cb,
                                         struct mspi_callback_context *ctx)
{
        const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
 
        if (!api->register_callback) {
                return -ENOTSUP;
        }
 
        return api->register_callback(controller, dev_id, evt_type, cb, ctx);
}
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/drivers/mspi/devicetree.h>
 
#include <zephyr/sys/util_macro.h>
 
#define MSPI_XIP_CFG_STRUCT_DECLARE(_name)                                                        \
        IF_ENABLED(CONFIG_MSPI_XIP, (struct mspi_xip_cfg _name;))
 
#define MSPI_XIP_BASE_ADDR_DECLARE(_name)                                                         \
        IF_ENABLED(CONFIG_MSPI_XIP, (uint32_t _name;))
 
#define MSPI_SCRAMBLE_CFG_STRUCT_DECLARE(_name)                                                   \
        IF_ENABLED(CONFIG_MSPI_SCRAMBLE, (struct mspi_scramble_cfg _name;))
 
#define MSPI_TIMING_CFG_STRUCT_DECLARE(_name)                                                     \
        IF_ENABLED(CONFIG_MSPI_TIMING, (mspi_timing_cfg _name;))
 
#define MSPI_TIMING_PARAM_DECLARE(_name)                                                          \
        IF_ENABLED(CONFIG_MSPI_TIMING, (mspi_timing_param _name;))
 
#define MSPI_OPTIONAL_CFG_STRUCT_INIT(code, _name, _object)                                       \
        IF_ENABLED(code, (._name = _object,))
 
#define MSPI_XIP_BASE_ADDR_INIT(_name, _bus)                                                      \
        IF_ENABLED(CONFIG_MSPI_XIP, (._name = DT_REG_ADDR_BY_IDX(_bus, 1),))
 
#include <zephyr/syscalls/mspi.h>
#endif /* ZEPHYR_INCLUDE_MSPI_H_ */