Zephyr API Documentation  3.7.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
mspi.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2024, Ambiq Micro Inc. <www.ambiq.com>
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
12#ifndef ZEPHYR_INCLUDE_MSPI_H_
13#define ZEPHYR_INCLUDE_MSPI_H_
14
15#include <errno.h>
16
17#include <zephyr/sys/__assert.h>
18#include <zephyr/types.h>
19#include <zephyr/kernel.h>
20#include <zephyr/device.h>
21#include <zephyr/drivers/gpio.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
40};
41
48};
49
71};
72
88};
89
98};
99
106};
107
114};
115
126};
127
138};
139
146};
147
154};
155
178};
179
186};
187
200
205
206};
207
218};
219
223struct mspi_cfg {
244};
245
251 const struct device *bus;
254};
255
296};
297
303 bool enable;
312};
313
319 bool enable;
326};
327
357};
358
375};
376
382struct mspi_xfer {
384 bool async;
409};
410
424 const struct device *controller;
426 const struct mspi_dev_id *dev_id;
433};
434
443};
444
452 void *ctx;
453};
454
462typedef void (*mspi_callback_handler_t)(struct mspi_callback_context *mspi_cb_ctx, ...);
463
469typedef int (*mspi_api_config)(const struct mspi_dt_spec *spec);
470
471typedef int (*mspi_api_dev_config)(const struct device *controller,
472 const struct mspi_dev_id *dev_id,
473 const enum mspi_dev_cfg_mask param_mask,
474 const struct mspi_dev_cfg *cfg);
475
476typedef int (*mspi_api_get_channel_status)(const struct device *controller, uint8_t ch);
477
478typedef int (*mspi_api_transceive)(const struct device *controller,
479 const struct mspi_dev_id *dev_id,
480 const struct mspi_xfer *req);
481
482typedef int (*mspi_api_register_callback)(const struct device *controller,
483 const struct mspi_dev_id *dev_id,
484 const enum mspi_bus_event evt_type,
486 struct mspi_callback_context *ctx);
487
488typedef int (*mspi_api_xip_config)(const struct device *controller,
489 const struct mspi_dev_id *dev_id,
490 const struct mspi_xip_cfg *xip_cfg);
491
492typedef int (*mspi_api_scramble_config)(const struct device *controller,
493 const struct mspi_dev_id *dev_id,
494 const struct mspi_scramble_cfg *scramble_cfg);
495
496typedef int (*mspi_api_timing_config)(const struct device *controller,
497 const struct mspi_dev_id *dev_id, const uint32_t param_mask,
498 void *timing_cfg);
499
500__subsystem struct mspi_driver_api {
509};
510
537__syscall int mspi_config(const struct mspi_dt_spec *spec);
538
539static inline int z_impl_mspi_config(const struct mspi_dt_spec *spec)
540{
541 const struct mspi_driver_api *api = (const struct mspi_driver_api *)spec->bus->api;
542
543 return api->config(spec);
544}
545
573__syscall int mspi_dev_config(const struct device *controller,
574 const struct mspi_dev_id *dev_id,
575 const enum mspi_dev_cfg_mask param_mask,
576 const struct mspi_dev_cfg *cfg);
577
578static inline int z_impl_mspi_dev_config(const struct device *controller,
579 const struct mspi_dev_id *dev_id,
580 const enum mspi_dev_cfg_mask param_mask,
581 const struct mspi_dev_cfg *cfg)
582{
583 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
584
585 return api->dev_config(controller, dev_id, param_mask, cfg);
586}
587
599__syscall int mspi_get_channel_status(const struct device *controller, uint8_t ch);
600
601static inline int z_impl_mspi_get_channel_status(const struct device *controller, uint8_t ch)
602{
603 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
604
605 return api->get_channel_status(controller, ch);
606}
607
639__syscall int mspi_transceive(const struct device *controller,
640 const struct mspi_dev_id *dev_id,
641 const struct mspi_xfer *req);
642
643static inline int z_impl_mspi_transceive(const struct device *controller,
644 const struct mspi_dev_id *dev_id,
645 const struct mspi_xfer *req)
646{
647 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
648
649 if (!api->transceive) {
650 return -ENOTSUP;
651 }
652
653 return api->transceive(controller, dev_id, req);
654}
655
677__syscall int mspi_xip_config(const struct device *controller,
678 const struct mspi_dev_id *dev_id,
679 const struct mspi_xip_cfg *cfg);
680
681static inline int z_impl_mspi_xip_config(const struct device *controller,
682 const struct mspi_dev_id *dev_id,
683 const struct mspi_xip_cfg *cfg)
684{
685 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
686
687 if (!api->xip_config) {
688 return -ENOTSUP;
689 }
690
691 return api->xip_config(controller, dev_id, cfg);
692}
693
709__syscall int mspi_scramble_config(const struct device *controller,
710 const struct mspi_dev_id *dev_id,
711 const struct mspi_scramble_cfg *cfg);
712
713static inline int z_impl_mspi_scramble_config(const struct device *controller,
714 const struct mspi_dev_id *dev_id,
715 const struct mspi_scramble_cfg *cfg)
716{
717 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
718
719 if (!api->scramble_config) {
720 return -ENOTSUP;
721 }
722
723 return api->scramble_config(controller, dev_id, cfg);
724}
725
742__syscall int mspi_timing_config(const struct device *controller,
743 const struct mspi_dev_id *dev_id,
744 const uint32_t param_mask, void *cfg);
745
746static inline int z_impl_mspi_timing_config(const struct device *controller,
747 const struct mspi_dev_id *dev_id,
748 const uint32_t param_mask, void *cfg)
749{
750 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
751
752 if (!api->timing_config) {
753 return -ENOTSUP;
754 }
755
756 return api->timing_config(controller, dev_id, param_mask, cfg);
757}
758
781static inline int mspi_register_callback(const struct device *controller,
782 const struct mspi_dev_id *dev_id,
783 const enum mspi_bus_event evt_type,
785 struct mspi_callback_context *ctx)
786{
787 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
788
789 if (!api->register_callback) {
790 return -ENOTSUP;
791 }
792
793 return api->register_callback(controller, dev_id, evt_type, cb, ctx);
794}
795
798#ifdef __cplusplus
799}
800#endif
801
803
807#include <zephyr/syscalls/mspi.h>
808#endif /* ZEPHYR_INCLUDE_MSPI_H_ */
Public APIs for GPIO drivers.
System error numbers.
void(* mspi_callback_handler_t)(struct mspi_callback_context *mspi_cb_ctx,...)
Define the application callback handler function signature.
Definition: mspi.h:462
static 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)
Register the mspi callback functions.
Definition: mspi.h:781
int mspi_config(const struct mspi_dt_spec *spec)
Configure a MSPI controller.
int mspi_get_channel_status(const struct device *controller, uint8_t ch)
Query to see if it a channel is ready.
mspi_timing_param
Stub for timing parameter.
Definition: mspi.h:197
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)
Configure a MSPI controller with device specific parameters.
int mspi_xip_config(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_xip_cfg *cfg)
Configure a MSPI XIP settings.
int mspi_scramble_config(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_scramble_cfg *cfg)
Configure a MSPI scrambling settings.
int mspi_timing_config(const struct device *controller, const struct mspi_dev_id *dev_id, const uint32_t param_mask, void *cfg)
Configure a MSPI timing settings.
@ MSPI_TIMING_PARAM_DUMMY
Definition: mspi.h:198
mspi_xip_permit
MSPI XIP access permissions.
Definition: mspi.h:183
int(* mspi_api_scramble_config)(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_scramble_cfg *scramble_cfg)
Definition: mspi.h:492
mspi_xfer_mode
MSPI transfer modes.
Definition: mspi.h:143
int(* mspi_api_transceive)(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_xfer *req)
Definition: mspi.h:478
mspi_duplex
MSPI duplex mode.
Definition: mspi.h:45
mspi_ce_polarity
MSPI chip enable polarity.
Definition: mspi.h:111
int(* mspi_api_config)(const struct mspi_dt_spec *spec)
MSPI driver API definition and system call entry points.
Definition: mspi.h:469
mspi_endian
MSPI Endian.
Definition: mspi.h:103
mspi_op_mode
MSPI operational mode.
Definition: mspi.h:37
int(* mspi_api_timing_config)(const struct device *controller, const struct mspi_dev_id *dev_id, const uint32_t param_mask, void *timing_cfg)
Definition: mspi.h:496
mspi_xfer_direction
MSPI transfer directions.
Definition: mspi.h:151
mspi_bus_event
MSPI bus event.
Definition: mspi.h:121
mspi_cpp_mode
MSPI Polarity & Phase Modes.
Definition: mspi.h:93
mspi_dev_cfg_mask
MSPI controller device specific configuration mask.
Definition: mspi.h:159
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)
Definition: mspi.h:471
int(* mspi_api_xip_config)(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_xip_cfg *xip_cfg)
Definition: mspi.h:488
mspi_io_mode
MSPI I/O mode capabilities Postfix like 1_4_4 stands for the number of lines used for command,...
Definition: mspi.h:56
mspi_data_rate
MSPI data rate capabilities SINGLE stands for single data rate for all phases.
Definition: mspi.h:82
mspi_bus_event_cb_mask
MSPI bus event callback mask This is a preliminary list same as mspi_bus_event.
Definition: mspi.h:133
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)
Definition: mspi.h:482
int(* mspi_api_get_channel_status)(const struct device *controller, uint8_t ch)
Definition: mspi.h:476
@ MSPI_XIP_READ_WRITE
Definition: mspi.h:184
@ MSPI_XIP_READ_ONLY
Definition: mspi.h:185
@ MSPI_DMA
Definition: mspi.h:145
@ MSPI_PIO
Definition: mspi.h:144
@ MSPI_FULL_DUPLEX
Definition: mspi.h:47
@ MSPI_HALF_DUPLEX
Definition: mspi.h:46
@ MSPI_CE_ACTIVE_HIGH
Definition: mspi.h:113
@ MSPI_CE_ACTIVE_LOW
Definition: mspi.h:112
@ MSPI_XFER_BIG_ENDIAN
Definition: mspi.h:105
@ MSPI_XFER_LITTLE_ENDIAN
Definition: mspi.h:104
@ MSPI_OP_MODE_PERIPHERAL
Definition: mspi.h:39
@ MSPI_OP_MODE_CONTROLLER
Definition: mspi.h:38
@ MSPI_RX
Definition: mspi.h:152
@ MSPI_TX
Definition: mspi.h:153
@ MSPI_BUS_EVENT_MAX
Definition: mspi.h:125
@ MSPI_BUS_XFER_COMPLETE
Definition: mspi.h:124
@ MSPI_BUS_ERROR
Definition: mspi.h:123
@ MSPI_BUS_RESET
Definition: mspi.h:122
@ MSPI_CPP_MODE_3
Definition: mspi.h:97
@ MSPI_CPP_MODE_1
Definition: mspi.h:95
@ MSPI_CPP_MODE_2
Definition: mspi.h:96
@ MSPI_CPP_MODE_0
Definition: mspi.h:94
@ MSPI_DEVICE_CONFIG_CPP
Definition: mspi.h:165
@ MSPI_DEVICE_CONFIG_DATA_RATE
Definition: mspi.h:164
@ MSPI_DEVICE_CONFIG_RX_DUMMY
Definition: mspi.h:169
@ MSPI_DEVICE_CONFIG_FREQUENCY
Definition: mspi.h:162
@ MSPI_DEVICE_CONFIG_CMD_LEN
Definition: mspi.h:173
@ MSPI_DEVICE_CONFIG_CE_NUM
Definition: mspi.h:161
@ MSPI_DEVICE_CONFIG_IO_MODE
Definition: mspi.h:163
@ MSPI_DEVICE_CONFIG_CE_POL
Definition: mspi.h:167
@ MSPI_DEVICE_CONFIG_DQS
Definition: mspi.h:168
@ MSPI_DEVICE_CONFIG_TX_DUMMY
Definition: mspi.h:170
@ MSPI_DEVICE_CONFIG_ALL
Definition: mspi.h:177
@ MSPI_DEVICE_CONFIG_WRITE_CMD
Definition: mspi.h:172
@ MSPI_DEVICE_CONFIG_ADDR_LEN
Definition: mspi.h:174
@ MSPI_DEVICE_CONFIG_ENDIAN
Definition: mspi.h:166
@ MSPI_DEVICE_CONFIG_NONE
Definition: mspi.h:160
@ MSPI_DEVICE_CONFIG_BREAK_TIME
Definition: mspi.h:176
@ MSPI_DEVICE_CONFIG_MEM_BOUND
Definition: mspi.h:175
@ MSPI_DEVICE_CONFIG_READ_CMD
Definition: mspi.h:171
@ MSPI_IO_MODE_HEX
Definition: mspi.h:67
@ MSPI_IO_MODE_QUAD_1_4_4
Definition: mspi.h:63
@ MSPI_IO_MODE_OCTAL_1_8_8
Definition: mspi.h:66
@ MSPI_IO_MODE_HEX_8_16_16
Definition: mspi.h:69
@ MSPI_IO_MODE_SINGLE
Definition: mspi.h:57
@ MSPI_IO_MODE_DUAL_1_1_2
Definition: mspi.h:59
@ MSPI_IO_MODE_DUAL
Definition: mspi.h:58
@ MSPI_IO_MODE_MAX
Definition: mspi.h:70
@ MSPI_IO_MODE_DUAL_1_2_2
Definition: mspi.h:60
@ MSPI_IO_MODE_QUAD_1_1_4
Definition: mspi.h:62
@ MSPI_IO_MODE_OCTAL_1_1_8
Definition: mspi.h:65
@ MSPI_IO_MODE_OCTAL
Definition: mspi.h:64
@ MSPI_IO_MODE_HEX_8_8_16
Definition: mspi.h:68
@ MSPI_IO_MODE_QUAD
Definition: mspi.h:61
@ MSPI_DATA_RATE_SINGLE
Definition: mspi.h:83
@ MSPI_DATA_RATE_S_S_D
Definition: mspi.h:84
@ MSPI_DATA_RATE_MAX
Definition: mspi.h:87
@ MSPI_DATA_RATE_S_D_D
Definition: mspi.h:85
@ MSPI_DATA_RATE_DUAL
Definition: mspi.h:86
@ MSPI_BUS_ERROR_CB
Definition: mspi.h:136
@ MSPI_BUS_RESET_CB
Definition: mspi.h:135
@ MSPI_BUS_XFER_COMPLETE_CB
Definition: mspi.h:137
@ MSPI_BUS_NO_CB
Definition: mspi.h:134
int mspi_transceive(const struct device *controller, const struct mspi_dev_id *dev_id, const struct mspi_xfer *req)
Transfer request over MSPI.
#define BIT(n)
Unsigned integer with bit position n set (signed in assembly language).
Definition: util_macro.h:44
#define BIT_MASK(n)
Bit mask with bits 0 through n-1 (inclusive) set, or 0 if n is 0.
Definition: util_macro.h:68
#define ENOTSUP
Unsupported value.
Definition: errno.h:115
Public kernel APIs.
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
__UINT8_TYPE__ uint8_t
Definition: stdint.h:88
__UINT16_TYPE__ uint16_t
Definition: stdint.h:89
Runtime device structure (in ROM) per driver instance.
Definition: device.h:403
const void * api
Address of the API structure exposed by the device instance.
Definition: device.h:409
Container for GPIO pin information specified in devicetree.
Definition: gpio.h:288
MSPI callback context.
Definition: mspi.h:448
struct mspi_event mspi_evt
MSPI event
Definition: mspi.h:450
void * ctx
user defined context
Definition: mspi.h:452
MSPI Chip Select control structure.
Definition: mspi.h:343
struct gpio_dt_spec gpio
GPIO devicetree specification of CE GPIO.
Definition: mspi.h:350
uint32_t delay
Delay to wait.
Definition: mspi.h:356
MSPI controller configuration.
Definition: mspi.h:223
bool sw_multi_periph
Software managed multi peripheral enable.
Definition: mspi.h:233
uint32_t num_ce_gpios
GPIO chip-select line numbers (optional)
Definition: mspi.h:237
bool dqs_support
DQS support flag.
Definition: mspi.h:231
struct gpio_dt_spec * ce_group
GPIO chip select lines (optional)
Definition: mspi.h:235
enum mspi_duplex duplex
Configure duplex mode.
Definition: mspi.h:229
uint32_t num_periph
Peripheral number from 0 to host controller peripheral limit.
Definition: mspi.h:239
uint32_t max_freq
Maximum supported frequency in MHz.
Definition: mspi.h:241
enum mspi_op_mode op_mode
Configure operation mode.
Definition: mspi.h:227
uint8_t channel_num
mspi channel number
Definition: mspi.h:225
bool re_init
Whether to re-initialize controller.
Definition: mspi.h:243
MSPI controller device specific configuration.
Definition: mspi.h:259
uint8_t cmd_length
Configure command length
Definition: mspi.h:289
enum mspi_data_rate data_rate
Configure data rate.
Definition: mspi.h:267
enum mspi_endian endian
Configure transfer endian.
Definition: mspi.h:271
enum mspi_cpp_mode cpp
Configure clock polarity and phase.
Definition: mspi.h:269
uint32_t mem_boundary
Configure memory boundary
Definition: mspi.h:293
uint32_t time_to_break
Configure the time to break up a transfer into 2.
Definition: mspi.h:295
uint8_t addr_length
Configure address length
Definition: mspi.h:291
uint32_t freq
Configure frequency.
Definition: mspi.h:263
uint16_t tx_dummy
Configure number of clock cycles between addr and data in TX direction.
Definition: mspi.h:283
uint16_t rx_dummy
Configure number of clock cycles between addr and data in RX direction.
Definition: mspi.h:279
enum mspi_ce_polarity ce_polarity
Configure chip enable polarity.
Definition: mspi.h:273
uint8_t ce_num
Configure CE0 or CE1 or more.
Definition: mspi.h:261
uint32_t read_cmd
Configure read command
Definition: mspi.h:285
uint32_t write_cmd
Configure write command
Definition: mspi.h:287
enum mspi_io_mode io_mode
Configure I/O mode.
Definition: mspi.h:265
bool dqs_enable
Configure DQS mode.
Definition: mspi.h:275
MSPI device ID The controller can identify its devices and determine whether the access is allowed in...
Definition: mspi.h:213
uint16_t dev_idx
device index on DT
Definition: mspi.h:217
struct gpio_dt_spec ce
device gpio ce
Definition: mspi.h:215
Definition: mspi.h:500
mspi_api_config config
Definition: mspi.h:501
mspi_api_register_callback register_callback
Definition: mspi.h:505
mspi_api_dev_config dev_config
Definition: mspi.h:502
mspi_api_get_channel_status get_channel_status
Definition: mspi.h:503
mspi_api_timing_config timing_config
Definition: mspi.h:508
mspi_api_scramble_config scramble_config
Definition: mspi.h:507
mspi_api_transceive transceive
Definition: mspi.h:504
mspi_api_xip_config xip_config
Definition: mspi.h:506
MSPI DT information.
Definition: mspi.h:249
struct mspi_cfg config
MSPI hardware specific configuration.
Definition: mspi.h:253
const struct device * bus
MSPI bus.
Definition: mspi.h:251
MSPI event data.
Definition: mspi.h:422
const struct mspi_xfer_packet * packet
Pointer to a transfer packet.
Definition: mspi.h:428
uint32_t status
MSPI event status.
Definition: mspi.h:430
uint32_t packet_idx
Packet index.
Definition: mspi.h:432
const struct mspi_dev_id * dev_id
Pointer to the peripheral device ID.
Definition: mspi.h:426
const struct device * controller
Pointer to the bus controller.
Definition: mspi.h:424
MSPI event.
Definition: mspi.h:438
enum mspi_bus_event evt_type
Event type.
Definition: mspi.h:440
struct mspi_event_data evt_data
Data associated to the event.
Definition: mspi.h:442
MSPI controller scramble configuration.
Definition: mspi.h:317
bool enable
scramble enable
Definition: mspi.h:319
uint32_t size
scramble region size
Definition: mspi.h:325
uint32_t address_offset
scramble region start address = hardware default + address offset
Definition: mspi.h:323
Stub for struct timing_cfg.
Definition: mspi.h:204
MSPI peripheral xfer packet format.
Definition: mspi.h:362
uint32_t num_bytes
Number of bytes to transfer
Definition: mspi.h:372
uint32_t address
Transfer Address
Definition: mspi.h:370
uint8_t * data_buf
Data Buffer
Definition: mspi.h:374
uint32_t cmd
Transfer command
Definition: mspi.h:368
enum mspi_bus_event_cb_mask cb_mask
Bus event callback masks
Definition: mspi.h:366
enum mspi_xfer_direction dir
Direction (Transmit/Receive)
Definition: mspi.h:364
MSPI peripheral xfer format This includes transfer related settings that may require configuring the ...
Definition: mspi.h:382
bool hold_ce
Hold CE active after xfer
Definition: mspi.h:396
uint8_t cmd_length
Configure command length
Definition: mspi.h:392
uint32_t num_packet
Number of transfer packets
Definition: mspi.h:406
const struct mspi_xfer_packet * packets
Transfer packets
Definition: mspi.h:404
uint8_t priority
Priority 0 = Low (best effort) 1 = High (service immediately)
Definition: mspi.h:402
uint16_t rx_dummy
Configure RX dummy cycles
Definition: mspi.h:390
bool async
Async or sync transfer
Definition: mspi.h:384
uint8_t addr_length
Configure address length
Definition: mspi.h:394
uint16_t tx_dummy
Configure TX dummy cycles
Definition: mspi.h:388
struct mspi_ce_control ce_sw_ctrl
Software CE control
Definition: mspi.h:398
enum mspi_xfer_mode xfer_mode
Transfer Mode
Definition: mspi.h:386
uint32_t timeout
Transfer timeout value
Definition: mspi.h:408
MSPI controller XIP configuration.
Definition: mspi.h:301
enum mspi_xip_permit permission
XIP access permission.
Definition: mspi.h:311
bool enable
XIP enable.
Definition: mspi.h:303
uint32_t address_offset
XIP region start address = hardware default + address offset.
Definition: mspi.h:307
uint32_t size
XIP region size.
Definition: mspi.h:309