4  * SPDX-License-Identifier: Apache-2.0
9  * @brief Public APIs for MSPI driver
22 #include <zephyr/device.h>
30  * @brief MSPI Driver APIs
31  * @defgroup mspi_interface MSPI Driver APIs
37  * @brief MSPI operational mode
45  * @brief MSPI duplex mode
53  * @brief MSPI I/O mode capabilities
76  * @brief MSPI data rate capabilities
93  * @brief MSPI Polarity & Phase Modes
103  * @brief MSPI Endian
111  * @brief MSPI chip enable polarity
119  * @brief MSPI bus event.
131  * @brief MSPI bus event callback mask
143  * @brief MSPI transfer modes
151  * @brief MSPI transfer directions
159  * @brief MSPI controller device specific configuration mask
183  * @brief MSPI XIP access permissions
191  * @brief MSPI Configure API
192  * @defgroup mspi_configure_api MSPI Configure API
214  * @brief MSPI device ID
216  * allowed in a multiple device scheme.
219 	/** @brief device gpio ce */
221 	/** @brief device index on DT */
226  * @brief MSPI controller configuration
229 	/** @brief mspi channel number */
241 	/** @brief GPIO chip-select line numbers (optional) */
247 	/** @brief Whether to re-initialize controller */
252  * @brief MSPI DT information
255 	/** @brief MSPI bus */
256 	const struct device     *bus;
257 	/** @brief MSPI hardware specific configuration */
262  * @brief MSPI controller device specific configuration
304  * @brief MSPI controller XIP configuration
320  * @brief MSPI controller scramble configuration
336  * @brief MSPI Transfer API
337  * @defgroup mspi_transfer_api MSPI Transfer API
342  * @brief MSPI Chip Select control structure
351 	 * The device pointer can be set to NULL to fully inhibit CE control if
353 	 * the same as in MSPI configuration.
365  * @brief MSPI peripheral xfer packet format
383  * @brief MSPI peripheral xfer format
419  * @brief MSPI callback API
420  * @defgroup mspi_callback_api MSPI callback API
425  * @brief MSPI event data
429 	const struct device         *controller;
430 	/** @brief Pointer to the peripheral device ID */
434 	/** @brief MSPI event status */
441  * @brief MSPI event
451  * @brief MSPI callback context
454 	/** @brief MSPI event  */
464  * @param mspi_cb_ctx Pointer to the MSPI callback context
472  * MSPI driver API definition and system call entry points
476 typedef int (*mspi_api_dev_config)(const struct device *controller,
481 typedef int (*mspi_api_get_channel_status)(const struct device *controller, uint8_t ch);
483 typedef int (*mspi_api_transceive)(const struct device *controller,
487 typedef int (*mspi_api_register_callback)(const struct device *controller,
493 typedef int (*mspi_api_xip_config)(const struct device *controller,
497 typedef int (*mspi_api_scramble_config)(const struct device *controller,
501 typedef int (*mspi_api_timing_config)(const struct device *controller,
522  * @brief Configure a MSPI controller.
524  * This routine provides a generic interface to override MSPI controller
528  * re-initialize their controller hardware. Additional SoC platform specific
530  * binding(xxx,mspi-controller.yaml) so that one may derive the settings from
532  * change during run-time. The bindings for @see mspi_cfg can be found in
533  * mspi-controller.yaml.
535  * @param spec Pointer to MSPI DT information.
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.
546 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)spec->bus->api;  in z_impl_mspi_config()
548 	return api->config(spec);  in z_impl_mspi_config()
552  * @brief Configure a MSPI controller with device specific parameters.
554  * This routine provides a generic interface to override MSPI controller
555  * device specific settings that should be derived from device datasheets.
557  * With @see mspi_dev_id defined as the device index and CE GPIO from device
559  * It is up to the controller driver implementation whether to support device
565  * of operation is determined after the device initialization.
566  * The bindings for @see mspi_dev_cfg can be found in mspi-device.yaml.
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.
571  * @param cfg The device runtime configuration for the MSPI controller.
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.
578 __syscall int mspi_dev_config(const struct device *controller,
583 static inline int z_impl_mspi_dev_config(const struct device *controller,  in z_impl_mspi_dev_config()
588 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_dev_config()
590 	return api->dev_config(controller, dev_id, param_mask, cfg);  in z_impl_mspi_dev_config()
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.
602  * @retval 0 If MSPI channel is ready.
604 __syscall int mspi_get_channel_status(const struct device *controller, uint8_t ch);
606 static inline int z_impl_mspi_get_channel_status(const struct device *controller, uint8_t ch)  in z_impl_mspi_get_channel_status()
608 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_get_channel_status()
610 	return api->get_channel_status(controller, ch);  in z_impl_mspi_get_channel_status()
621  * @brief Transfer request over MSPI.
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.
641  * @retval -ENOTSUP
642  * @retval -EIO General input / output error, failed to send over the bus.
644 __syscall int mspi_transceive(const struct device *controller,
648 static inline int z_impl_mspi_transceive(const struct device *controller,  in z_impl_mspi_transceive()
652 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_transceive()
654 	if (!api->transceive) {  in z_impl_mspi_transceive()
655 		return -ENOTSUP;  in z_impl_mspi_transceive()
658 	return api->transceive(controller, dev_id, req);  in z_impl_mspi_transceive()
669  * @brief Configure a MSPI XIP settings.
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.
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.
682 __syscall int mspi_xip_config(const struct device *controller,
686 static inline int z_impl_mspi_xip_config(const struct device *controller,  in z_impl_mspi_xip_config()
690 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_xip_config()
692 	if (!api->xip_config) {  in z_impl_mspi_xip_config()
693 		return -ENOTSUP;  in z_impl_mspi_xip_config()
696 	return api->xip_config(controller, dev_id, cfg);  in z_impl_mspi_xip_config()
700  * @brief Configure a MSPI scrambling settings.
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.
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.
714 __syscall int mspi_scramble_config(const struct device *controller,
718 static inline int z_impl_mspi_scramble_config(const struct device *controller,  in z_impl_mspi_scramble_config()
722 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_scramble_config()
724 	if (!api->scramble_config) {  in z_impl_mspi_scramble_config()
725 		return -ENOTSUP;  in z_impl_mspi_scramble_config()
728 	return api->scramble_config(controller, dev_id, cfg);  in z_impl_mspi_scramble_config()
732  * @brief Configure a MSPI timing settings.
734  * This routine provides a generic interface to configure MSPI controller
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.
740  * @param cfg The controller timing configuration for MSPI.
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.
747 __syscall int mspi_timing_config(const struct device *controller,
751 static inline int z_impl_mspi_timing_config(const struct device *controller,  in z_impl_mspi_timing_config()
755 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in z_impl_mspi_timing_config()
757 	if (!api->timing_config) {  in z_impl_mspi_timing_config()
758 		return -ENOTSUP;  in z_impl_mspi_timing_config()
761 	return api->timing_config(controller, dev_id, param_mask, cfg);  in z_impl_mspi_timing_config()
772  * @brief Register the mspi callback functions.
774  * This routines provides a generic interface to register mspi callback functions.
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.
784  * @retval -ENOTSUP
786 static inline int mspi_register_callback(const struct device *controller,  in mspi_register_callback()
792 	const struct mspi_driver_api *api = (const struct mspi_driver_api *)controller->api;  in mspi_register_callback()
794 	if (!api->register_callback) {  in mspi_register_callback()
795 		return -ENOTSUP;  in mspi_register_callback()
798 	return api->register_callback(controller, dev_id, evt_type, cb, ctx);  in mspi_register_callback()
807 #include <zephyr/drivers/mspi/devicetree.h>
812 #include <zephyr/syscalls/mspi.h>