1 /*
2 * Copyright (c) 2024, 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 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 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 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 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 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 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 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 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 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 enum mspi_xfer_mode {
146 MSPI_PIO,
147 MSPI_DMA,
148 };
149
150 /**
151 * @brief MSPI transfer directions
152 */
153 enum mspi_xfer_direction {
154 MSPI_RX,
155 MSPI_TX,
156 };
157
158 /**
159 * @brief MSPI controller device specific configuration mask
160 */
161 enum mspi_dev_cfg_mask {
162 MSPI_DEVICE_CONFIG_NONE = 0,
163 MSPI_DEVICE_CONFIG_CE_NUM = BIT(0),
164 MSPI_DEVICE_CONFIG_FREQUENCY = BIT(1),
165 MSPI_DEVICE_CONFIG_IO_MODE = BIT(2),
166 MSPI_DEVICE_CONFIG_DATA_RATE = BIT(3),
167 MSPI_DEVICE_CONFIG_CPP = BIT(4),
168 MSPI_DEVICE_CONFIG_ENDIAN = BIT(5),
169 MSPI_DEVICE_CONFIG_CE_POL = BIT(6),
170 MSPI_DEVICE_CONFIG_DQS = BIT(7),
171 MSPI_DEVICE_CONFIG_RX_DUMMY = BIT(8),
172 MSPI_DEVICE_CONFIG_TX_DUMMY = BIT(9),
173 MSPI_DEVICE_CONFIG_READ_CMD = BIT(10),
174 MSPI_DEVICE_CONFIG_WRITE_CMD = BIT(11),
175 MSPI_DEVICE_CONFIG_CMD_LEN = BIT(12),
176 MSPI_DEVICE_CONFIG_ADDR_LEN = BIT(13),
177 MSPI_DEVICE_CONFIG_MEM_BOUND = BIT(14),
178 MSPI_DEVICE_CONFIG_BREAK_TIME = BIT(15),
179 MSPI_DEVICE_CONFIG_ALL = BIT_MASK(16),
180 };
181
182 /**
183 * @brief MSPI XIP access permissions
184 */
185 enum mspi_xip_permit {
186 MSPI_XIP_READ_WRITE = 0,
187 MSPI_XIP_READ_ONLY = 1,
188 };
189
190 /**
191 * @brief MSPI Configure API
192 * @defgroup mspi_configure_api MSPI Configure API
193 * @{
194 */
195
196 /**
197 * @brief Stub for timing parameter
198 */
199 enum mspi_timing_param {
200 MSPI_TIMING_PARAM_DUMMY
201 };
202
203 /**
204 * @brief Stub for struct timing_cfg
205 */
206 struct mspi_timing_cfg {
207
208 };
209
210 /**
211 * @brief MSPI device ID
212 * The controller can identify its devices and determine whether the access is
213 * allowed in a multiple device scheme.
214 */
215 struct mspi_dev_id {
216 /** @brief device gpio ce */
217 struct gpio_dt_spec ce;
218 /** @brief device index on DT */
219 uint16_t dev_idx;
220 };
221
222 /**
223 * @brief MSPI controller configuration
224 */
225 struct mspi_cfg {
226 /** @brief mspi channel number */
227 uint8_t channel_num;
228 /** @brief Configure operation mode */
229 enum mspi_op_mode op_mode;
230 /** @brief Configure duplex mode */
231 enum mspi_duplex duplex;
232 /** @brief DQS support flag */
233 bool dqs_support;
234 /** @brief Software managed multi peripheral enable */
235 bool sw_multi_periph;
236 /** @brief GPIO chip select lines (optional) */
237 struct gpio_dt_spec *ce_group;
238 /** @brief GPIO chip-select line numbers (optional) */
239 uint32_t num_ce_gpios;
240 /** @brief Peripheral number from 0 to host controller peripheral limit. */
241 uint32_t num_periph;
242 /** @brief Maximum supported frequency in MHz */
243 uint32_t max_freq;
244 /** @brief Whether to re-initialize controller */
245 bool re_init;
246 };
247
248 /**
249 * @brief MSPI DT information
250 */
251 struct mspi_dt_spec {
252 /** @brief MSPI bus */
253 const struct device *bus;
254 /** @brief MSPI hardware specific configuration */
255 struct mspi_cfg config;
256 };
257
258 /**
259 * @brief MSPI controller device specific configuration
260 */
261 struct mspi_dev_cfg {
262 /** @brief Configure CE0 or CE1 or more */
263 uint8_t ce_num;
264 /** @brief Configure frequency */
265 uint32_t freq;
266 /** @brief Configure I/O mode */
267 enum mspi_io_mode io_mode;
268 /** @brief Configure data rate */
269 enum mspi_data_rate data_rate;
270 /** @brief Configure clock polarity and phase */
271 enum mspi_cpp_mode cpp;
272 /** @brief Configure transfer endian */
273 enum mspi_endian endian;
274 /** @brief Configure chip enable polarity */
275 enum mspi_ce_polarity ce_polarity;
276 /** @brief Configure DQS mode */
277 bool dqs_enable;
278 /** @brief Configure number of clock cycles between
279 * addr and data in RX direction
280 */
281 uint16_t rx_dummy;
282 /** @brief Configure number of clock cycles between
283 * addr and data in TX direction
284 */
285 uint16_t tx_dummy;
286 /** @brief Configure read command */
287 uint32_t read_cmd;
288 /** @brief Configure write command */
289 uint32_t write_cmd;
290 /** @brief Configure command length */
291 uint8_t cmd_length;
292 /** @brief Configure address length */
293 uint8_t addr_length;
294 /** @brief Configure memory boundary */
295 uint32_t mem_boundary;
296 /** @brief Configure the time to break up a transfer into 2 */
297 uint32_t time_to_break;
298 };
299
300 /**
301 * @brief MSPI controller XIP configuration
302 */
303 struct mspi_xip_cfg {
304 /** @brief XIP enable */
305 bool enable;
306 /** @brief XIP region start address =
307 * hardware default + address offset
308 */
309 uint32_t address_offset;
310 /** @brief XIP region size */
311 uint32_t size;
312 /** @brief XIP access permission */
313 enum mspi_xip_permit permission;
314 };
315
316 /**
317 * @brief MSPI controller scramble configuration
318 */
319 struct mspi_scramble_cfg {
320 /** @brief scramble enable */
321 bool enable;
322 /** @brief scramble region start address =
323 * hardware default + address offset
324 */
325 uint32_t address_offset;
326 /** @brief scramble region size */
327 uint32_t size;
328 };
329
330 /** @} */
331
332 /**
333 * @brief MSPI Transfer API
334 * @defgroup mspi_transfer_api MSPI Transfer API
335 * @{
336 */
337
338 /**
339 * @brief MSPI Chip Select control structure
340 *
341 * This can be used to control a CE line via a GPIO line, instead of
342 * using the controller inner CE logic.
343 *
344 */
345 struct mspi_ce_control {
346 /**
347 * @brief GPIO devicetree specification of CE GPIO.
348 * The device pointer can be set to NULL to fully inhibit CE control if
349 * necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be
350 * the same as in MSPI configuration.
351 */
352 struct gpio_dt_spec gpio;
353 /**
354 * @brief Delay to wait.
355 * In microseconds before starting the
356 * transmission and before releasing the CE line.
357 */
358 uint32_t delay;
359 };
360
361 /**
362 * @brief MSPI peripheral xfer packet format
363 */
364 struct mspi_xfer_packet {
365 /** @brief Direction (Transmit/Receive) */
366 enum mspi_xfer_direction dir;
367 /** @brief Bus event callback masks */
368 enum mspi_bus_event_cb_mask cb_mask;
369 /** @brief Transfer command */
370 uint32_t cmd;
371 /** @brief Transfer Address */
372 uint32_t address;
373 /** @brief Number of bytes to transfer */
374 uint32_t num_bytes;
375 /** @brief Data Buffer */
376 uint8_t *data_buf;
377 };
378
379 /**
380 * @brief MSPI peripheral xfer format
381 * This includes transfer related settings that may
382 * require configuring the hardware.
383 */
384 struct mspi_xfer {
385 /** @brief Async or sync transfer */
386 bool async;
387 /** @brief Transfer Mode */
388 enum mspi_xfer_mode xfer_mode;
389 /** @brief Configure TX dummy cycles */
390 uint16_t tx_dummy;
391 /** @brief Configure RX dummy cycles */
392 uint16_t rx_dummy;
393 /** @brief Configure command length */
394 uint8_t cmd_length;
395 /** @brief Configure address length */
396 uint8_t addr_length;
397 /** @brief Hold CE active after xfer */
398 bool hold_ce;
399 /** @brief Software CE control */
400 struct mspi_ce_control ce_sw_ctrl;
401 /** @brief Priority 0 = Low (best effort)
402 * 1 = High (service immediately)
403 */
404 uint8_t priority;
405 /** @brief Transfer packets */
406 const struct mspi_xfer_packet *packets;
407 /** @brief Number of transfer packets */
408 uint32_t num_packet;
409 /** @brief Transfer timeout value */
410 uint32_t timeout;
411 };
412
413 /** @} */
414
415 /**
416 * @brief MSPI callback API
417 * @defgroup mspi_callback_api MSPI callback API
418 * @{
419 */
420
421 /**
422 * @brief MSPI event data
423 */
424 struct mspi_event_data {
425 /** @brief Pointer to the bus controller */
426 const struct device *controller;
427 /** @brief Pointer to the peripheral device ID */
428 const struct mspi_dev_id *dev_id;
429 /** @brief Pointer to a transfer packet */
430 const struct mspi_xfer_packet *packet;
431 /** @brief MSPI event status */
432 uint32_t status;
433 /** @brief Packet index */
434 uint32_t packet_idx;
435 };
436
437 /**
438 * @brief MSPI event
439 */
440 struct mspi_event {
441 /** Event type */
442 enum mspi_bus_event evt_type;
443 /** Data associated to the event */
444 struct mspi_event_data evt_data;
445 };
446
447 /**
448 * @brief MSPI callback context
449 */
450 struct mspi_callback_context {
451 /** @brief MSPI event */
452 struct mspi_event mspi_evt;
453 /** @brief user defined context */
454 void *ctx;
455 };
456
457 /**
458 * @typedef mspi_callback_handler_t
459 * @brief Define the application callback handler function signature.
460 *
461 * @param mspi_cb_ctx Pointer to the MSPI callback context
462 *
463 */
464 typedef void (*mspi_callback_handler_t)(struct mspi_callback_context *mspi_cb_ctx, ...);
465
466 /** @} */
467
468 /**
469 * MSPI driver API definition and system call entry points
470 */
471 typedef int (*mspi_api_config)(const struct mspi_dt_spec *spec);
472
473 typedef int (*mspi_api_dev_config)(const struct device *controller,
474 const struct mspi_dev_id *dev_id,
475 const enum mspi_dev_cfg_mask param_mask,
476 const struct mspi_dev_cfg *cfg);
477
478 typedef int (*mspi_api_get_channel_status)(const struct device *controller, uint8_t ch);
479
480 typedef int (*mspi_api_transceive)(const struct device *controller,
481 const struct mspi_dev_id *dev_id,
482 const struct mspi_xfer *req);
483
484 typedef int (*mspi_api_register_callback)(const struct device *controller,
485 const struct mspi_dev_id *dev_id,
486 const enum mspi_bus_event evt_type,
487 mspi_callback_handler_t cb,
488 struct mspi_callback_context *ctx);
489
490 typedef int (*mspi_api_xip_config)(const struct device *controller,
491 const struct mspi_dev_id *dev_id,
492 const struct mspi_xip_cfg *xip_cfg);
493
494 typedef int (*mspi_api_scramble_config)(const struct device *controller,
495 const struct mspi_dev_id *dev_id,
496 const struct mspi_scramble_cfg *scramble_cfg);
497
498 typedef int (*mspi_api_timing_config)(const struct device *controller,
499 const struct mspi_dev_id *dev_id, const uint32_t param_mask,
500 void *timing_cfg);
501
502 __subsystem struct mspi_driver_api {
503 mspi_api_config config;
504 mspi_api_dev_config dev_config;
505 mspi_api_get_channel_status get_channel_status;
506 mspi_api_transceive transceive;
507 mspi_api_register_callback register_callback;
508 mspi_api_xip_config xip_config;
509 mspi_api_scramble_config scramble_config;
510 mspi_api_timing_config timing_config;
511 };
512
513 /**
514 * @addtogroup mspi_configure_api
515 * @{
516 */
517
518 /**
519 * @brief Configure a MSPI controller.
520 *
521 * This routine provides a generic interface to override MSPI controller
522 * capabilities.
523 *
524 * In the controller driver, one may implement this API to initialize or
525 * re-initialize their controller hardware. Additional SoC platform specific
526 * settings that are not in struct mspi_cfg may be added to one's own
527 * binding(xxx,mspi-controller.yaml) so that one may derive the settings from
528 * DTS and configure it in this API. In general, these settings should not
529 * change during run-time. The bindings for @see mspi_cfg can be found in
530 * mspi-controller.yaml.
531 *
532 * @param spec Pointer to MSPI DT information.
533 *
534 * @retval 0 If successful.
535 * @retval -EIO General input / output error, failed to configure device.
536 * @retval -EINVAL invalid capabilities, failed to configure device.
537 * @retval -ENOTSUP capability not supported by MSPI peripheral.
538 */
539 __syscall int mspi_config(const struct mspi_dt_spec *spec);
540
z_impl_mspi_config(const struct mspi_dt_spec * spec)541 static inline int z_impl_mspi_config(const struct mspi_dt_spec *spec)
542 {
543 const struct mspi_driver_api *api = (const struct mspi_driver_api *)spec->bus->api;
544
545 return api->config(spec);
546 }
547
548 /**
549 * @brief Configure a MSPI controller with device specific parameters.
550 *
551 * This routine provides a generic interface to override MSPI controller
552 * device specific settings that should be derived from device datasheets.
553 *
554 * With @see mspi_dev_id defined as the device index and CE GPIO from device
555 * tree, the API supports multiple devices on the same controller instance.
556 * It is up to the controller driver implementation whether to support device
557 * switching either by software or by hardware or not at all. If by software,
558 * the switching should be done in this API's implementation.
559 * The implementation may also support individual parameter configurations
560 * specified by @see mspi_dev_cfg_mask.
561 * The settings within @see mspi_dev_cfg don't typically change once the mode
562 * of operation is determined after the device initialization.
563 * The bindings for @see mspi_dev_cfg can be found in mspi-device.yaml.
564 *
565 * @param controller Pointer to the device structure for the driver instance.
566 * @param dev_id Pointer to the device ID structure from a device.
567 * @param param_mask Macro definition of what to be configured in cfg.
568 * @param cfg The device runtime configuration for the MSPI controller.
569 *
570 * @retval 0 If successful.
571 * @retval -EIO General input / output error, failed to configure device.
572 * @retval -EINVAL invalid capabilities, failed to configure device.
573 * @retval -ENOTSUP capability not supported by MSPI peripheral.
574 */
575 __syscall int mspi_dev_config(const struct device *controller,
576 const struct mspi_dev_id *dev_id,
577 const enum mspi_dev_cfg_mask param_mask,
578 const struct mspi_dev_cfg *cfg);
579
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)580 static inline int z_impl_mspi_dev_config(const struct device *controller,
581 const struct mspi_dev_id *dev_id,
582 const enum mspi_dev_cfg_mask param_mask,
583 const struct mspi_dev_cfg *cfg)
584 {
585 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
586
587 return api->dev_config(controller, dev_id, param_mask, cfg);
588 }
589
590 /**
591 * @brief Query to see if it a channel is ready.
592 *
593 * This routine allows to check if logical channel is ready before use.
594 * Note that queries for channels not supported will always return false.
595 *
596 * @param controller Pointer to the device structure for the driver instance.
597 * @param ch the MSPI channel for which status is to be retrieved.
598 *
599 * @retval 0 If MSPI channel is ready.
600 */
601 __syscall int mspi_get_channel_status(const struct device *controller, uint8_t ch);
602
z_impl_mspi_get_channel_status(const struct device * controller,uint8_t ch)603 static inline int z_impl_mspi_get_channel_status(const struct device *controller, uint8_t ch)
604 {
605 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
606
607 return api->get_channel_status(controller, ch);
608 }
609
610 /** @} */
611
612 /**
613 * @addtogroup mspi_transfer_api
614 * @{
615 */
616
617 /**
618 * @brief Transfer request over MSPI.
619 *
620 * This routines provides a generic interface to transfer a request
621 * synchronously/asynchronously.
622 *
623 * The @see mspi_xfer allows for dynamically changing the transfer related
624 * settings once the mode of operation is determined and configured.
625 * The API supports bulk transfers with different starting addresses and sizes
626 * with @see mspi_xfer_packet. However, it is up to the controller
627 * implementation whether to support scatter IO and callback management.
628 * The controller can determine which user callback to trigger based on
629 * @see mspi_bus_event_cb_mask upon completion of each async/sync transfer
630 * if the callback had been registered. Or not to trigger any callback at all
631 * with MSPI_BUS_NO_CB even if the callbacks are already registered.
632 *
633 * @param controller Pointer to the device structure for the driver instance.
634 * @param dev_id Pointer to the device ID structure from a device.
635 * @param req Content of the request and request specific settings.
636 *
637 * @retval 0 If successful.
638 * @retval -ENOTSUP
639 * @retval -EIO General input / output error, failed to send over the bus.
640 */
641 __syscall int mspi_transceive(const struct device *controller,
642 const struct mspi_dev_id *dev_id,
643 const struct mspi_xfer *req);
644
z_impl_mspi_transceive(const struct device * controller,const struct mspi_dev_id * dev_id,const struct mspi_xfer * req)645 static inline int z_impl_mspi_transceive(const struct device *controller,
646 const struct mspi_dev_id *dev_id,
647 const struct mspi_xfer *req)
648 {
649 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
650
651 if (!api->transceive) {
652 return -ENOTSUP;
653 }
654
655 return api->transceive(controller, dev_id, req);
656 }
657
658 /** @} */
659
660 /**
661 * @addtogroup mspi_configure_api
662 * @{
663 */
664
665 /**
666 * @brief Configure a MSPI XIP settings.
667 *
668 * This routine provides a generic interface to configure the XIP feature.
669 *
670 * @param controller Pointer to the device structure for the driver instance.
671 * @param dev_id Pointer to the device ID structure from a device.
672 * @param cfg The controller XIP configuration for MSPI.
673 *
674 * @retval 0 If successful.
675 * @retval -EIO General input / output error, failed to configure device.
676 * @retval -EINVAL invalid capabilities, failed to configure device.
677 * @retval -ENOTSUP capability not supported by MSPI peripheral.
678 */
679 __syscall int mspi_xip_config(const struct device *controller,
680 const struct mspi_dev_id *dev_id,
681 const struct mspi_xip_cfg *cfg);
682
z_impl_mspi_xip_config(const struct device * controller,const struct mspi_dev_id * dev_id,const struct mspi_xip_cfg * cfg)683 static inline int z_impl_mspi_xip_config(const struct device *controller,
684 const struct mspi_dev_id *dev_id,
685 const struct mspi_xip_cfg *cfg)
686 {
687 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
688
689 if (!api->xip_config) {
690 return -ENOTSUP;
691 }
692
693 return api->xip_config(controller, dev_id, cfg);
694 }
695
696 /**
697 * @brief Configure a MSPI scrambling settings.
698 *
699 * This routine provides a generic interface to configure the scrambling
700 * feature.
701 *
702 * @param controller Pointer to the device structure for the driver instance.
703 * @param dev_id Pointer to the device ID structure from a device.
704 * @param cfg The controller scramble configuration for MSPI.
705 *
706 * @retval 0 If successful.
707 * @retval -EIO General input / output error, failed to configure device.
708 * @retval -EINVAL invalid capabilities, failed to configure device.
709 * @retval -ENOTSUP capability not supported by MSPI peripheral.
710 */
711 __syscall int mspi_scramble_config(const struct device *controller,
712 const struct mspi_dev_id *dev_id,
713 const struct mspi_scramble_cfg *cfg);
714
z_impl_mspi_scramble_config(const struct device * controller,const struct mspi_dev_id * dev_id,const struct mspi_scramble_cfg * cfg)715 static inline int z_impl_mspi_scramble_config(const struct device *controller,
716 const struct mspi_dev_id *dev_id,
717 const struct mspi_scramble_cfg *cfg)
718 {
719 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
720
721 if (!api->scramble_config) {
722 return -ENOTSUP;
723 }
724
725 return api->scramble_config(controller, dev_id, cfg);
726 }
727
728 /**
729 * @brief Configure a MSPI timing settings.
730 *
731 * This routine provides a generic interface to configure MSPI controller
732 * timing if necessary.
733 *
734 * @param controller Pointer to the device structure for the driver instance.
735 * @param dev_id Pointer to the device ID structure from a device.
736 * @param param_mask The macro definition of what should be configured in cfg.
737 * @param cfg The controller timing configuration for MSPI.
738 *
739 * @retval 0 If successful.
740 * @retval -EIO General input / output error, failed to configure device.
741 * @retval -EINVAL invalid capabilities, failed to configure device.
742 * @retval -ENOTSUP capability not supported by MSPI peripheral.
743 */
744 __syscall int mspi_timing_config(const struct device *controller,
745 const struct mspi_dev_id *dev_id,
746 const uint32_t param_mask, void *cfg);
747
z_impl_mspi_timing_config(const struct device * controller,const struct mspi_dev_id * dev_id,const uint32_t param_mask,void * cfg)748 static inline int z_impl_mspi_timing_config(const struct device *controller,
749 const struct mspi_dev_id *dev_id,
750 const uint32_t param_mask, void *cfg)
751 {
752 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
753
754 if (!api->timing_config) {
755 return -ENOTSUP;
756 }
757
758 return api->timing_config(controller, dev_id, param_mask, cfg);
759 }
760
761 /** @} */
762
763 /**
764 * @addtogroup mspi_callback_api
765 * @{
766 */
767
768 /**
769 * @brief Register the mspi callback functions.
770 *
771 * This routines provides a generic interface to register mspi callback functions.
772 * In generally it should be called before mspi_transceive.
773 *
774 * @param controller Pointer to the device structure for the driver instance.
775 * @param dev_id Pointer to the device ID structure from a device.
776 * @param evt_type The event type associated the callback.
777 * @param cb Pointer to the user implemented callback function.
778 * @param ctx Pointer to the callback context.
779 *
780 * @retval 0 If successful.
781 * @retval -ENOTSUP
782 */
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)783 static inline int mspi_register_callback(const struct device *controller,
784 const struct mspi_dev_id *dev_id,
785 const enum mspi_bus_event evt_type,
786 mspi_callback_handler_t cb,
787 struct mspi_callback_context *ctx)
788 {
789 const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;
790
791 if (!api->register_callback) {
792 return -ENOTSUP;
793 }
794
795 return api->register_callback(controller, dev_id, evt_type, cb, ctx);
796 }
797
798 /** @} */
799
800 #ifdef __cplusplus
801 }
802 #endif
803
804 #include <zephyr/drivers/mspi/devicetree.h>
805
806 /**
807 * @}
808 */
809 #include <zephyr/syscalls/mspi.h>
810 #endif /* ZEPHYR_INCLUDE_MSPI_H_ */
811
