Line data Source code
1 1 : /*
2 : * Copyright (c) 2025, Ambiq Micro Inc. <www.ambiq.com>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public APIs for MSPI driver
10 : * @since 3.7
11 : * @version 0.1.0
12 : */
13 :
14 : #ifndef ZEPHYR_INCLUDE_MSPI_H_
15 : #define ZEPHYR_INCLUDE_MSPI_H_
16 :
17 : #include <errno.h>
18 :
19 : #include <zephyr/sys/__assert.h>
20 : #include <zephyr/types.h>
21 : #include <zephyr/kernel.h>
22 : #include <zephyr/device.h>
23 : #include <zephyr/drivers/gpio.h>
24 :
25 : #ifdef __cplusplus
26 : extern "C" {
27 : #endif
28 :
29 : /**
30 : * @brief MSPI Driver APIs
31 : * @defgroup mspi_interface MSPI Driver APIs
32 : * @ingroup io_interfaces
33 : * @{
34 : */
35 :
36 : /**
37 : * @brief MSPI operational mode
38 : */
39 0 : enum mspi_op_mode {
40 : MSPI_OP_MODE_CONTROLLER = 0,
41 : MSPI_OP_MODE_PERIPHERAL = 1,
42 : };
43 :
44 : /**
45 : * @brief MSPI duplex mode
46 : */
47 0 : enum mspi_duplex {
48 : MSPI_HALF_DUPLEX = 0,
49 : MSPI_FULL_DUPLEX = 1,
50 : };
51 :
52 : /**
53 : * @brief MSPI I/O mode capabilities
54 : * Postfix like 1_4_4 stands for the number of lines used for
55 : * command, address and data phases.
56 : * Mode with no postfix has the same number of lines for all phases.
57 : */
58 0 : enum mspi_io_mode {
59 : MSPI_IO_MODE_SINGLE = 0,
60 : MSPI_IO_MODE_DUAL = 1,
61 : MSPI_IO_MODE_DUAL_1_1_2 = 2,
62 : MSPI_IO_MODE_DUAL_1_2_2 = 3,
63 : MSPI_IO_MODE_QUAD = 4,
64 : MSPI_IO_MODE_QUAD_1_1_4 = 5,
65 : MSPI_IO_MODE_QUAD_1_4_4 = 6,
66 : MSPI_IO_MODE_OCTAL = 7,
67 : MSPI_IO_MODE_OCTAL_1_1_8 = 8,
68 : MSPI_IO_MODE_OCTAL_1_8_8 = 9,
69 : MSPI_IO_MODE_HEX = 10,
70 : MSPI_IO_MODE_HEX_8_8_16 = 11,
71 : MSPI_IO_MODE_HEX_8_16_16 = 12,
72 : MSPI_IO_MODE_MAX,
73 : };
74 :
75 : /**
76 : * @brief MSPI data rate capabilities
77 : * SINGLE stands for single data rate for all phases.
78 : * DUAL stands for dual data rate for all phases.
79 : * S_S_D stands for single data rate for command and address phases but
80 : * dual data rate for data phase.
81 : * S_D_D stands for single data rate for command phase but dual data rate
82 : * for address and data phases.
83 : */
84 0 : enum mspi_data_rate {
85 : MSPI_DATA_RATE_SINGLE = 0,
86 : MSPI_DATA_RATE_S_S_D = 1,
87 : MSPI_DATA_RATE_S_D_D = 2,
88 : MSPI_DATA_RATE_DUAL = 3,
89 : MSPI_DATA_RATE_MAX,
90 : };
91 :
92 : /**
93 : * @brief MSPI Polarity & Phase Modes
94 : */
95 0 : enum mspi_cpp_mode {
96 : MSPI_CPP_MODE_0 = 0,
97 : MSPI_CPP_MODE_1 = 1,
98 : MSPI_CPP_MODE_2 = 2,
99 : MSPI_CPP_MODE_3 = 3,
100 : };
101 :
102 : /**
103 : * @brief MSPI Endian
104 : */
105 0 : enum mspi_endian {
106 : MSPI_XFER_LITTLE_ENDIAN = 0,
107 : MSPI_XFER_BIG_ENDIAN = 1,
108 : };
109 :
110 : /**
111 : * @brief MSPI chip enable polarity
112 : */
113 0 : enum mspi_ce_polarity {
114 : MSPI_CE_ACTIVE_LOW = 0,
115 : MSPI_CE_ACTIVE_HIGH = 1,
116 : };
117 :
118 : /**
119 : * @brief MSPI bus event.
120 : * This is a preliminary list of events. I encourage the community
121 : * to fill it up.
122 : */
123 0 : enum mspi_bus_event {
124 : MSPI_BUS_RESET = 0,
125 : MSPI_BUS_ERROR = 1,
126 : MSPI_BUS_XFER_COMPLETE = 2,
127 : MSPI_BUS_EVENT_MAX,
128 : };
129 :
130 : /**
131 : * @brief MSPI bus event callback mask
132 : * This is a preliminary list same as mspi_bus_event. I encourage the
133 : * community to fill it up.
134 : */
135 0 : enum mspi_bus_event_cb_mask {
136 : MSPI_BUS_NO_CB = 0,
137 : MSPI_BUS_RESET_CB = BIT(0),
138 : MSPI_BUS_ERROR_CB = BIT(1),
139 : MSPI_BUS_XFER_COMPLETE_CB = BIT(2),
140 : };
141 :
142 : /**
143 : * @brief MSPI transfer modes
144 : */
145 0 : enum mspi_xfer_mode {
146 : MSPI_PIO,
147 : MSPI_DMA,
148 : };
149 :
150 : /**
151 : * @brief MSPI transfer priority
152 : * This is a preliminary list of priorities that are typically used with DMA
153 : */
154 0 : enum mspi_xfer_priority {
155 : MSPI_XFER_PRIORITY_LOW,
156 : MSPI_XFER_PRIORITY_MEDIUM,
157 : MSPI_XFER_PRIORITY_HIGH,
158 : };
159 :
160 : /**
161 : * @brief MSPI transfer directions
162 : */
163 0 : enum mspi_xfer_direction {
164 : MSPI_RX,
165 : MSPI_TX,
166 : };
167 :
168 : /**
169 : * @brief MSPI controller device specific configuration mask
170 : */
171 0 : enum mspi_dev_cfg_mask {
172 : MSPI_DEVICE_CONFIG_NONE = 0,
173 : MSPI_DEVICE_CONFIG_CE_NUM = BIT(0),
174 : MSPI_DEVICE_CONFIG_FREQUENCY = BIT(1),
175 : MSPI_DEVICE_CONFIG_IO_MODE = BIT(2),
176 : MSPI_DEVICE_CONFIG_DATA_RATE = BIT(3),
177 : MSPI_DEVICE_CONFIG_CPP = BIT(4),
178 : MSPI_DEVICE_CONFIG_ENDIAN = BIT(5),
179 : MSPI_DEVICE_CONFIG_CE_POL = BIT(6),
180 : MSPI_DEVICE_CONFIG_DQS = BIT(7),
181 : MSPI_DEVICE_CONFIG_RX_DUMMY = BIT(8),
182 : MSPI_DEVICE_CONFIG_TX_DUMMY = BIT(9),
183 : MSPI_DEVICE_CONFIG_READ_CMD = BIT(10),
184 : MSPI_DEVICE_CONFIG_WRITE_CMD = BIT(11),
185 : MSPI_DEVICE_CONFIG_CMD_LEN = BIT(12),
186 : MSPI_DEVICE_CONFIG_ADDR_LEN = BIT(13),
187 : MSPI_DEVICE_CONFIG_MEM_BOUND = BIT(14),
188 : MSPI_DEVICE_CONFIG_BREAK_TIME = BIT(15),
189 : MSPI_DEVICE_CONFIG_ALL = BIT_MASK(16),
190 : };
191 :
192 : /**
193 : * @brief MSPI XIP access permissions
194 : */
195 0 : enum mspi_xip_permit {
196 : MSPI_XIP_READ_WRITE = 0,
197 : MSPI_XIP_READ_ONLY = 1,
198 : };
199 :
200 : /**
201 : * @brief MSPI Configure API
202 : * @defgroup mspi_configure_api MSPI Configure API
203 : * @{
204 : */
205 :
206 : /**
207 : * @brief Stub for timing parameter
208 : */
209 0 : enum mspi_timing_param {
210 : MSPI_TIMING_PARAM_DUMMY
211 : };
212 :
213 : /**
214 : * @brief Stub for struct timing_cfg
215 : */
216 1 : struct mspi_timing_cfg {
217 : #ifdef __cplusplus
218 : /* For C++ compatibility. */
219 : uint8_t dummy;
220 : #endif
221 : };
222 :
223 : /**
224 : * @brief MSPI device ID
225 : * The controller can identify its devices and determine whether the access is
226 : * allowed in a multiple device scheme.
227 : */
228 1 : struct mspi_dev_id {
229 : /** @brief device gpio ce */
230 1 : struct gpio_dt_spec ce;
231 : /** @brief device index on DT */
232 1 : uint16_t dev_idx;
233 : };
234 :
235 : /**
236 : * @brief MSPI controller configuration
237 : */
238 1 : struct mspi_cfg {
239 : /** @brief mspi channel number */
240 1 : uint8_t channel_num;
241 : /** @brief Configure operation mode */
242 1 : enum mspi_op_mode op_mode;
243 : /** @brief Configure duplex mode */
244 1 : enum mspi_duplex duplex;
245 : /** @brief DQS support flag */
246 1 : bool dqs_support;
247 : /** @brief Software managed multi peripheral enable */
248 1 : bool sw_multi_periph;
249 : /** @brief GPIO chip select lines (optional) */
250 1 : struct gpio_dt_spec *ce_group;
251 : /** @brief GPIO chip-select line numbers (optional) */
252 1 : uint32_t num_ce_gpios;
253 : /** @brief Peripheral number from 0 to host controller peripheral limit. */
254 1 : uint32_t num_periph;
255 : /** @brief Maximum supported frequency in MHz */
256 1 : uint32_t max_freq;
257 : /** @brief Whether to re-initialize controller */
258 1 : bool re_init;
259 : };
260 :
261 : /**
262 : * @brief MSPI DT information
263 : */
264 1 : struct mspi_dt_spec {
265 : /** @brief MSPI bus */
266 1 : const struct device *bus;
267 : /** @brief MSPI hardware specific configuration */
268 1 : struct mspi_cfg config;
269 : };
270 :
271 : /**
272 : * @brief MSPI controller device specific configuration
273 : */
274 1 : struct mspi_dev_cfg {
275 : /** @brief Configure CE0 or CE1 or more */
276 1 : uint8_t ce_num;
277 : /** @brief Configure frequency */
278 1 : uint32_t freq;
279 : /** @brief Configure I/O mode */
280 1 : enum mspi_io_mode io_mode;
281 : /** @brief Configure data rate */
282 1 : enum mspi_data_rate data_rate;
283 : /** @brief Configure clock polarity and phase */
284 1 : enum mspi_cpp_mode cpp;
285 : /** @brief Configure transfer endian */
286 1 : enum mspi_endian endian;
287 : /** @brief Configure chip enable polarity */
288 1 : enum mspi_ce_polarity ce_polarity;
289 : /** @brief Configure DQS mode */
290 1 : bool dqs_enable;
291 : /** @brief Configure number of clock cycles between
292 : * addr and data in RX direction
293 : */
294 1 : uint16_t rx_dummy;
295 : /** @brief Configure number of clock cycles between
296 : * addr and data in TX direction
297 : */
298 1 : uint16_t tx_dummy;
299 : /** @brief Configure read command */
300 1 : uint32_t read_cmd;
301 : /** @brief Configure write command */
302 1 : uint32_t write_cmd;
303 : /** @brief Configure command length */
304 1 : uint8_t cmd_length;
305 : /** @brief Configure address length */
306 1 : uint8_t addr_length;
307 : /** @brief Configure memory boundary */
308 1 : uint32_t mem_boundary;
309 : /** @brief Configure the time to break up a transfer into 2 */
310 1 : uint32_t time_to_break;
311 : };
312 :
313 : /**
314 : * @brief MSPI controller XIP configuration
315 : */
316 1 : struct mspi_xip_cfg {
317 : /** @brief XIP enable */
318 1 : bool enable;
319 : /** @brief XIP region start address =
320 : * hardware default + address offset
321 : */
322 1 : uint32_t address_offset;
323 : /** @brief XIP region size */
324 1 : uint32_t size;
325 : /** @brief XIP access permission */
326 1 : enum mspi_xip_permit permission;
327 : };
328 :
329 : /**
330 : * @brief MSPI controller scramble configuration
331 : */
332 1 : struct mspi_scramble_cfg {
333 : /** @brief scramble enable */
334 1 : bool enable;
335 : /** @brief scramble region start address =
336 : * hardware default + address offset
337 : */
338 1 : uint32_t address_offset;
339 : /** @brief scramble region size */
340 1 : uint32_t size;
341 : };
342 :
343 : /** @} */
344 :
345 : /**
346 : * @brief MSPI Transfer API
347 : * @defgroup mspi_transfer_api MSPI Transfer API
348 : * @{
349 : */
350 :
351 : /**
352 : * @brief MSPI Chip Select control structure
353 : *
354 : * This can be used to control a CE line via a GPIO line, instead of
355 : * using the controller inner CE logic.
356 : *
357 : */
358 1 : struct mspi_ce_control {
359 : /**
360 : * @brief GPIO devicetree specification of CE GPIO.
361 : * The device pointer can be set to NULL to fully inhibit CE control if
362 : * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
363 : * the same as in MSPI configuration.
364 : */
365 1 : struct gpio_dt_spec gpio;
366 : /**
367 : * @brief Delay to wait.
368 : * In microseconds before starting the
369 : * transmission and before releasing the CE line.
370 : */
371 1 : uint32_t delay;
372 : };
373 :
374 : /**
375 : * @brief MSPI peripheral xfer packet format
376 : */
377 1 : struct mspi_xfer_packet {
378 : /** @brief Direction (Transmit/Receive) */
379 1 : enum mspi_xfer_direction dir;
380 : /** @brief Bus event callback masks */
381 1 : enum mspi_bus_event_cb_mask cb_mask;
382 : /** @brief Transfer command */
383 1 : uint32_t cmd;
384 : /** @brief Transfer Address */
385 1 : uint32_t address;
386 : /** @brief Number of bytes to transfer */
387 1 : uint32_t num_bytes;
388 : /** @brief Data Buffer */
389 1 : uint8_t *data_buf;
390 : };
391 :
392 : /**
393 : * @brief MSPI peripheral xfer format
394 : * This includes transfer related settings that may
395 : * require configuring the hardware.
396 : */
397 1 : struct mspi_xfer {
398 : /** @brief Async or sync transfer */
399 1 : bool async;
400 : /** @brief Transfer Mode */
401 1 : enum mspi_xfer_mode xfer_mode;
402 : /** @brief Configure TX dummy cycles */
403 1 : uint16_t tx_dummy;
404 : /** @brief Configure RX dummy cycles */
405 1 : uint16_t rx_dummy;
406 : /** @brief Configure command length */
407 1 : uint8_t cmd_length;
408 : /** @brief Configure address length */
409 1 : uint8_t addr_length;
410 : /** @brief Hold CE active after xfer */
411 1 : bool hold_ce;
412 : /** @brief Software CE control */
413 1 : struct mspi_ce_control ce_sw_ctrl;
414 : /** @brief MSPI transfer priority */
415 1 : enum mspi_xfer_priority priority;
416 : /** @brief Transfer packets */
417 1 : const struct mspi_xfer_packet *packets;
418 : /** @brief Number of transfer packets */
419 1 : uint32_t num_packet;
420 : /** @brief Transfer timeout value(ms) */
421 1 : uint32_t timeout;
422 : };
423 :
424 : /** @} */
425 :
426 : /**
427 : * @brief MSPI callback API
428 : * @defgroup mspi_callback_api MSPI callback API
429 : * @{
430 : */
431 :
432 : /**
433 : * @brief MSPI event data
434 : */
435 1 : struct mspi_event_data {
436 : /** @brief Pointer to the bus controller */
437 1 : const struct device *controller;
438 : /** @brief Pointer to the peripheral device ID */
439 1 : const struct mspi_dev_id *dev_id;
440 : /** @brief Pointer to a transfer packet */
441 1 : const struct mspi_xfer_packet *packet;
442 : /** @brief MSPI event status */
443 1 : uint32_t status;
444 : /** @brief Packet index */
445 1 : uint32_t packet_idx;
446 : };
447 :
448 : /**
449 : * @brief MSPI event
450 : */
451 1 : struct mspi_event {
452 : /** Event type */
453 1 : enum mspi_bus_event evt_type;
454 : /** Data associated to the event */
455 1 : struct mspi_event_data evt_data;
456 : };
457 :
458 : /**
459 : * @brief MSPI callback context
460 : */
461 1 : struct mspi_callback_context {
462 : /** @brief MSPI event */
463 1 : struct mspi_event mspi_evt;
464 : /** @brief user defined context */
465 1 : void *ctx;
466 : };
467 :
468 : /**
469 : * @typedef mspi_callback_handler_t
470 : * @brief Define the application callback handler function signature.
471 : *
472 : * @param mspi_cb_ctx Pointer to the MSPI callback context
473 : *
474 : */
475 1 : typedef void (*mspi_callback_handler_t)(struct mspi_callback_context *mspi_cb_ctx, ...);
476 :
477 : /** @} */
478 :
479 : /**
480 : * MSPI driver API definition and system call entry points
481 : */
482 1 : typedef int (*mspi_api_config)(const struct mspi_dt_spec *spec);
483 :
484 0 : typedef int (*mspi_api_dev_config)(const struct device *controller,
485 : const struct mspi_dev_id *dev_id,
486 : const enum mspi_dev_cfg_mask param_mask,
487 : const struct mspi_dev_cfg *cfg);
488 :
489 0 : typedef int (*mspi_api_get_channel_status)(const struct device *controller, uint8_t ch);
490 :
491 0 : typedef int (*mspi_api_transceive)(const struct device *controller,
492 : const struct mspi_dev_id *dev_id,
493 : const struct mspi_xfer *req);
494 :
495 0 : typedef int (*mspi_api_register_callback)(const struct device *controller,
496 : const struct mspi_dev_id *dev_id,
497 : const enum mspi_bus_event evt_type,
498 : mspi_callback_handler_t cb,
499 : struct mspi_callback_context *ctx);
500 :
501 0 : typedef int (*mspi_api_xip_config)(const struct device *controller,
502 : const struct mspi_dev_id *dev_id,
503 : const struct mspi_xip_cfg *xip_cfg);
504 :
505 0 : typedef int (*mspi_api_scramble_config)(const struct device *controller,
506 : const struct mspi_dev_id *dev_id,
507 : const struct mspi_scramble_cfg *scramble_cfg);
508 :
509 0 : typedef int (*mspi_api_timing_config)(const struct device *controller,
510 : const struct mspi_dev_id *dev_id, const uint32_t param_mask,
511 : void *timing_cfg);
512 :
513 0 : __subsystem struct mspi_driver_api {
514 0 : mspi_api_config config;
515 0 : mspi_api_dev_config dev_config;
516 0 : mspi_api_get_channel_status get_channel_status;
517 0 : mspi_api_transceive transceive;
518 0 : mspi_api_register_callback register_callback;
519 0 : mspi_api_xip_config xip_config;
520 0 : mspi_api_scramble_config scramble_config;
521 0 : mspi_api_timing_config timing_config;
522 : };
523 :
524 : /**
525 : * @addtogroup mspi_configure_api
526 : * @{
527 : */
528 :
529 : /**
530 : * @brief Configure a MSPI controller.
531 : *
532 : * This routine provides a generic interface to override MSPI controller
533 : * capabilities.
534 : *
535 : * In the controller driver, one may implement this API to initialize or
536 : * re-initialize their controller hardware. Additional SoC platform specific
537 : * settings that are not in struct mspi_cfg may be added to one's own
538 : * binding(xxx,mspi-controller.yaml) so that one may derive the settings from
539 : * DTS and configure it in this API. In general, these settings should not
540 : * change during run-time. The bindings for @see mspi_cfg can be found in
541 : * mspi-controller.yaml.
542 : *
543 : * @param spec Pointer to MSPI DT information.
544 : *
545 : * @retval 0 If successful.
546 : * @retval -EIO General input / output error, failed to configure device.
547 : * @retval -EINVAL invalid capabilities, failed to configure device.
548 : * @retval -ENOTSUP capability not supported by MSPI peripheral.
549 : */
550 1 : __syscall int mspi_config(const struct mspi_dt_spec *spec);
551 :
552 : static inline int z_impl_mspi_config(const struct mspi_dt_spec *spec)
553 : {
554 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)spec->bus->api;
555 :
556 : return api->config(spec);
557 : }
558 :
559 : /**
560 : * @brief Configure a MSPI controller with device specific parameters.
561 : *
562 : * This routine provides a generic interface to override MSPI controller
563 : * device specific settings that should be derived from device datasheets.
564 : *
565 : * With @see mspi_dev_id defined as the device index and CE GPIO from device
566 : * tree, the API supports multiple devices on the same controller instance.
567 : * It is up to the controller driver implementation whether to support device
568 : * switching either by software or by hardware or not at all. If by software,
569 : * the switching should be done in this API's implementation.
570 : * The implementation may also support individual parameter configurations
571 : * specified by @see mspi_dev_cfg_mask.
572 : * The settings within @see mspi_dev_cfg don't typically change once the mode
573 : * of operation is determined after the device initialization.
574 : * The bindings for @see mspi_dev_cfg can be found in mspi-device.yaml.
575 : *
576 : * @param controller Pointer to the device structure for the driver instance.
577 : * @param dev_id Pointer to the device ID structure from a device.
578 : * @param param_mask Macro definition of what to be configured in cfg.
579 : * @param cfg The device runtime configuration for the MSPI controller.
580 : *
581 : * @retval 0 If successful.
582 : * @retval -EIO General input / output error, failed to configure device.
583 : * @retval -EINVAL invalid capabilities, failed to configure device.
584 : * @retval -ENOTSUP capability not supported by MSPI peripheral.
585 : */
586 1 : __syscall int mspi_dev_config(const struct device *controller,
587 : const struct mspi_dev_id *dev_id,
588 : const enum mspi_dev_cfg_mask param_mask,
589 : const struct mspi_dev_cfg *cfg);
590 :
591 : static inline int z_impl_mspi_dev_config(const struct device *controller,
592 : const struct mspi_dev_id *dev_id,
593 : const enum mspi_dev_cfg_mask param_mask,
594 : const struct mspi_dev_cfg *cfg)
595 : {
596 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
597 :
598 : return api->dev_config(controller, dev_id, param_mask, cfg);
599 : }
600 :
601 : /**
602 : * @brief Query to see if it a channel is ready.
603 : *
604 : * This routine allows to check if logical channel is ready before use.
605 : * Note that queries for channels not supported will always return false.
606 : *
607 : * @param controller Pointer to the device structure for the driver instance.
608 : * @param ch the MSPI channel for which status is to be retrieved.
609 : *
610 : * @retval 0 If MSPI channel is ready.
611 : */
612 1 : __syscall int mspi_get_channel_status(const struct device *controller, uint8_t ch);
613 :
614 : static inline int z_impl_mspi_get_channel_status(const struct device *controller, uint8_t ch)
615 : {
616 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
617 :
618 : return api->get_channel_status(controller, ch);
619 : }
620 :
621 : /** @} */
622 :
623 : /**
624 : * @addtogroup mspi_transfer_api
625 : * @{
626 : */
627 :
628 : /**
629 : * @brief Transfer request over MSPI.
630 : *
631 : * This routines provides a generic interface to transfer a request
632 : * synchronously/asynchronously.
633 : *
634 : * The @see mspi_xfer allows for dynamically changing the transfer related
635 : * settings once the mode of operation is determined and configured.
636 : * The API supports bulk transfers with different starting addresses and sizes
637 : * with @see mspi_xfer_packet. However, it is up to the controller
638 : * implementation whether to support scatter IO and callback management.
639 : * The controller can determine which user callback to trigger based on
640 : * @see mspi_bus_event_cb_mask upon completion of each async/sync transfer
641 : * if the callback had been registered. Or not to trigger any callback at all
642 : * with MSPI_BUS_NO_CB even if the callbacks are already registered.
643 : *
644 : * @param controller Pointer to the device structure for the driver instance.
645 : * @param dev_id Pointer to the device ID structure from a device.
646 : * @param req Content of the request and request specific settings.
647 : *
648 : * @retval 0 If successful.
649 : * @retval -ENOTSUP
650 : * @retval -EIO General input / output error, failed to send over the bus.
651 : */
652 1 : __syscall int mspi_transceive(const struct device *controller,
653 : const struct mspi_dev_id *dev_id,
654 : const struct mspi_xfer *req);
655 :
656 : static inline int z_impl_mspi_transceive(const struct device *controller,
657 : const struct mspi_dev_id *dev_id,
658 : const struct mspi_xfer *req)
659 : {
660 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
661 :
662 : if (!api->transceive) {
663 : return -ENOTSUP;
664 : }
665 :
666 : return api->transceive(controller, dev_id, req);
667 : }
668 :
669 : /** @} */
670 :
671 : /**
672 : * @addtogroup mspi_configure_api
673 : * @{
674 : */
675 :
676 : /**
677 : * @brief Configure a MSPI XIP settings.
678 : *
679 : * This routine provides a generic interface to configure the XIP feature.
680 : *
681 : * @param controller Pointer to the device structure for the driver instance.
682 : * @param dev_id Pointer to the device ID structure from a device.
683 : * @param cfg The controller XIP configuration for MSPI.
684 : *
685 : * @retval 0 If successful.
686 : * @retval -EIO General input / output error, failed to configure device.
687 : * @retval -EINVAL invalid capabilities, failed to configure device.
688 : * @retval -ENOTSUP capability not supported by MSPI peripheral.
689 : */
690 1 : __syscall int mspi_xip_config(const struct device *controller,
691 : const struct mspi_dev_id *dev_id,
692 : const struct mspi_xip_cfg *cfg);
693 :
694 : static inline int z_impl_mspi_xip_config(const struct device *controller,
695 : const struct mspi_dev_id *dev_id,
696 : const struct mspi_xip_cfg *cfg)
697 : {
698 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
699 :
700 : if (!api->xip_config) {
701 : return -ENOTSUP;
702 : }
703 :
704 : return api->xip_config(controller, dev_id, cfg);
705 : }
706 :
707 : /**
708 : * @brief Configure a MSPI scrambling settings.
709 : *
710 : * This routine provides a generic interface to configure the scrambling
711 : * feature.
712 : *
713 : * @param controller Pointer to the device structure for the driver instance.
714 : * @param dev_id Pointer to the device ID structure from a device.
715 : * @param cfg The controller scramble configuration for MSPI.
716 : *
717 : * @retval 0 If successful.
718 : * @retval -EIO General input / output error, failed to configure device.
719 : * @retval -EINVAL invalid capabilities, failed to configure device.
720 : * @retval -ENOTSUP capability not supported by MSPI peripheral.
721 : */
722 1 : __syscall int mspi_scramble_config(const struct device *controller,
723 : const struct mspi_dev_id *dev_id,
724 : const struct mspi_scramble_cfg *cfg);
725 :
726 : static inline int z_impl_mspi_scramble_config(const struct device *controller,
727 : const struct mspi_dev_id *dev_id,
728 : const struct mspi_scramble_cfg *cfg)
729 : {
730 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
731 :
732 : if (!api->scramble_config) {
733 : return -ENOTSUP;
734 : }
735 :
736 : return api->scramble_config(controller, dev_id, cfg);
737 : }
738 :
739 : /**
740 : * @brief Configure a MSPI timing settings.
741 : *
742 : * This routine provides a generic interface to configure MSPI controller
743 : * timing if necessary.
744 : *
745 : * @param controller Pointer to the device structure for the driver instance.
746 : * @param dev_id Pointer to the device ID structure from a device.
747 : * @param param_mask The macro definition of what should be configured in cfg.
748 : * @param cfg The controller timing configuration for MSPI.
749 : *
750 : * @retval 0 If successful.
751 : * @retval -EIO General input / output error, failed to configure device.
752 : * @retval -EINVAL invalid capabilities, failed to configure device.
753 : * @retval -ENOTSUP capability not supported by MSPI peripheral.
754 : */
755 1 : __syscall int mspi_timing_config(const struct device *controller,
756 : const struct mspi_dev_id *dev_id,
757 : const uint32_t param_mask, void *cfg);
758 :
759 : static inline int z_impl_mspi_timing_config(const struct device *controller,
760 : const struct mspi_dev_id *dev_id,
761 : const uint32_t param_mask, void *cfg)
762 : {
763 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
764 :
765 : if (!api->timing_config) {
766 : return -ENOTSUP;
767 : }
768 :
769 : return api->timing_config(controller, dev_id, param_mask, cfg);
770 : }
771 :
772 : /** @} */
773 :
774 : /**
775 : * @addtogroup mspi_callback_api
776 : * @{
777 : */
778 :
779 : /**
780 : * @brief Register the mspi callback functions.
781 : *
782 : * This routines provides a generic interface to register mspi callback functions.
783 : * In generally it should be called before mspi_transceive.
784 : *
785 : * @param controller Pointer to the device structure for the driver instance.
786 : * @param dev_id Pointer to the device ID structure from a device.
787 : * @param evt_type The event type associated the callback.
788 : * @param cb Pointer to the user implemented callback function.
789 : * @param ctx Pointer to the callback context.
790 : *
791 : * @retval 0 If successful.
792 : * @retval -ENOTSUP
793 : */
794 1 : static inline int mspi_register_callback(const struct device *controller,
795 : const struct mspi_dev_id *dev_id,
796 : const enum mspi_bus_event evt_type,
797 : mspi_callback_handler_t cb,
798 : struct mspi_callback_context *ctx)
799 : {
800 : const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
801 :
802 : if (!api->register_callback) {
803 : return -ENOTSUP;
804 : }
805 :
806 : return api->register_callback(controller, dev_id, evt_type, cb, ctx);
807 : }
808 :
809 : /** @} */
810 :
811 : #ifdef __cplusplus
812 : }
813 : #endif
814 :
815 : #include <zephyr/drivers/mspi/devicetree.h>
816 :
817 : /**
818 : * @addtogroup mspi_util
819 : * @{
820 : */
821 : #include <zephyr/sys/util_macro.h>
822 :
823 : /**
824 : * @brief Declare the optional XIP config in peripheral driver.
825 : */
826 1 : #define MSPI_XIP_CFG_STRUCT_DECLARE(_name) \
827 : IF_ENABLED(CONFIG_MSPI_XIP, (struct mspi_xip_cfg _name;))
828 :
829 : /**
830 : * @brief Declare the optional XIP base address in peripheral driver.
831 : */
832 1 : #define MSPI_XIP_BASE_ADDR_DECLARE(_name) \
833 : IF_ENABLED(CONFIG_MSPI_XIP, (uint32_t _name;))
834 :
835 : /**
836 : * @brief Declare the optional scramble config in peripheral driver.
837 : */
838 1 : #define MSPI_SCRAMBLE_CFG_STRUCT_DECLARE(_name) \
839 : IF_ENABLED(CONFIG_MSPI_SCRAMBLE, (struct mspi_scramble_cfg _name;))
840 :
841 : /**
842 : * @brief Declare the optional timing config in peripheral driver.
843 : */
844 1 : #define MSPI_TIMING_CFG_STRUCT_DECLARE(_name) \
845 : IF_ENABLED(CONFIG_MSPI_TIMING, (mspi_timing_cfg _name;))
846 :
847 : /**
848 : * @brief Declare the optional timing parameter in peripheral driver.
849 : */
850 1 : #define MSPI_TIMING_PARAM_DECLARE(_name) \
851 : IF_ENABLED(CONFIG_MSPI_TIMING, (mspi_timing_param _name;))
852 :
853 : /**
854 : * @brief Initialize the optional config structure in peripheral driver.
855 : */
856 1 : #define MSPI_OPTIONAL_CFG_STRUCT_INIT(code, _name, _object) \
857 : IF_ENABLED(code, (._name = _object,))
858 :
859 : /**
860 : * @brief Initialize the optional XIP base address in peripheral driver.
861 : */
862 1 : #define MSPI_XIP_BASE_ADDR_INIT(_name, _bus) \
863 : IF_ENABLED(CONFIG_MSPI_XIP, (._name = DT_REG_ADDR_BY_IDX(_bus, 1),))
864 :
865 : /** @} */
866 :
867 : /**
868 : * @}
869 : */
870 : #include <zephyr/syscalls/mspi.h>
871 : #endif /* ZEPHYR_INCLUDE_MSPI_H_ */
|
