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