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