doc/hardware/peripherals/mspi.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _mspi_api:

 Multi-bit SPI Bus
 #################

 The MSPI (multi-bit SPI) is provided as a generic API to accommodate
 advanced SPI peripherals and devices that typically require command,
 address and data phases, and multiple signal lines during these phases.
 While the API supports advanced features such as :term:`XIP` and scrambling,
 it is also compatible with generic SPI.

 .. contents::
     :local:
     :depth: 2

 .. _mspi-controller-api:

 MSPI Controller API
 *******************

 Zephyr's MSPI controller API may be used when a multi-bit SPI controller
 is present. E.g. Ambiq MSPI, QSPI, OSPI, Flexspi, etc.
 The API supports single to hex SDR/DDR IO with variable latency and advanced
 features such as :term:`XIP` and scrambling. Applicable devices include but
 not limited to high-speed, high density flash/psram memory devices, displays
 and sensors.

 The MSPI interface contains controller drivers that are SoC platform specific
 and implement the MSPI APIs, and device drivers that reference these APIs.
 The relationship between the controller and device drivers is many-to-many to
 allow for easy switching between platforms.

 Here is a list of generic steps for initializing the MSPI controller and the
 MSPI bus inside the device driver initialization function:

 #. Initialize the data structure of the MSPI controller driver instance.
    The usual device defining macros such as :c:macro:`DEVICE_DT_INST_DEFINE`
    can be used, and the initialization function, config and data provided
    as a parameter to the macro.

 #. Initialize the hardware, including but not limited to:

    * Check :c:struct:`mspi_cfg` against hardware's own capabilities to prevent
      incorrect usages.

    * Setup default pinmux.

    * Setup the clock for the controller.

    * Power on the hardware.

    * Configure the hardware using :c:struct:`mspi_cfg` and possibly more
      platform specific settings.

    * Usually, the :c:struct:`mspi_cfg` is filled from device tree and contains
      static, boot time parameters. However, if needed, one can use :c:func:`mspi_config`
      to re-initialize the hardware with new parameters during runtime.

    * Release any lock if applicable.

 #. Perform device driver initialization. As usually, :c:macro:`DEVICE_DT_INST_DEFINE`
    can be used. Inside device driver initialization function, perform the following
    required steps.

    #. Call :c:func:`mspi_dev_config` with device specific hardware settings obtained
       from device datasheets.

       * The :c:struct:`mspi_dev_cfg` should be filled by device tree and helper macro
         :c:macro:`MSPI_DEVICE_CONFIG_DT` can be used.

       * The controller driver should then validate the members of :c:struct:`mspi_dev_cfg`
         to prevent incorrect usage.

       * The controller driver should implement a mutex to protect from accidental access.

       * The controller driver may also switch between different devices based on
         :c:struct:`mspi_dev_id`.

    #. Call API for additional setups if supported by hardware

       * :c:func:`mspi_xip_config` for :term:`XIP` feature

       * :c:func:`mspi_scramble_config` for scrambling feature

       * :c:func:`mspi_timing_config` for platform specific timing setup.

    #. Register any callback with :c:func:`mspi_register_callback` if needed.

    #. Release the controller mutex lock.

 Transceive
 ==========
 The transceive request is of type :c:struct:`mspi_xfer` which allows dynamic change to
 the transfer related settings once the mode of operation is determined and configured
 by :c:func:`mspi_dev_config`.

 The API also supports bulk transfers with different starting addresses and sizes with
 :c:struct:`mspi_xfer_packet`. However, it is up to the controller implementation
 whether to support scatter IO and callback management. The controller can determine
 which user callback to trigger based on :c:enum:`mspi_bus_event_cb_mask` upon completion
 of each async/sync transfer if the callback had been registered using
 :c:func:`mspi_register_callback`. Or not to trigger any callback at all with
 :c:enum:`MSPI_BUS_NO_CB` even if the callbacks are already registered.
 In which case that a controller supports hardware command queue, user could take full
 advantage of the hardware performance if scatter IO and callback management are supported
 by the driver implementation.

 Device Tree
 ===========

 Here is an example for defining an MSPI controller in device tree:
 The mspi controller's bindings should reference mspi-controller.yaml as one of the base.

 .. code-block:: devicetree

    mspi0: mspi@400 {
             status = "okay";
             compatible = "zephyr,mspi-emul-controller";

             reg = < 0x400 0x4 >;
             #address-cells = < 0x1 >;
             #size-cells = < 0x0 >;

             clock-frequency = < 0x17d7840 >;
             op-mode = "MSPI_CONTROLLER";
             duplex = "MSPI_HALF_DUPLEX";
             ce-gpios = < &gpio0 0x5 0x1 >, < &gpio0 0x12 0x1 >;
             dqs-support;

             pinctrl-0 = < &pinmux-mspi0 >;
             pinctrl-names = "default";
    };

 Here is an example for defining an MSPI device in device tree:
 The mspi device's bindings should reference mspi-device.yaml as one of the base.

 .. code-block:: devicetree

    &mspi0 {

             mspi_dev0: mspi_dev0@0 {
                      status = "okay";
                      compatible = "zephyr,mspi-emul-device";

                      reg = < 0x0 >;
                      size = < 0x10000 >;

                      mspi-max-frequency = < 0x2dc6c00 >;
                      mspi-io-mode = "MSPI_IO_MODE_QUAD";
                      mspi-data-rate = "MSPI_DATA_RATE_SINGLE";
                      mspi-hardware-ce-num = < 0x0 >;
                      read-instruction = < 0xb >;
                      write-instruction = < 0x2 >;
                      instruction-length = "INSTR_1_BYTE";
                      address-length = "ADDR_4_BYTE";
                      rx-dummy = < 0x8 >;
                      tx-dummy = < 0x0 >;
                      xip-config = < 0x0 0x0 0x0 0x0 >;
                      ce-break-config = < 0x0 0x0 >;
             };

    };

 User should specify target operating parameters in the DTS such as ``mspi-max-frequency``,
 ``mspi-io-mode`` and ``mspi-data-rate`` even though they may subject to change during runtime.
 It should represent the typical configuration of the device during normal operations.

 Multi Peripheral
 ================
 With :c:struct:`mspi_dev_id` defined as collection of the device index and CE GPIO from
 device tree, the API supports multiple devices on the same controller instance.
 The controller driver implementation may or may not support device switching,
 which can be performed either by software or by hardware. If the switching is handled
 by software, it should be performed in :c:func:`mspi_dev_config` call.

 The device driver should record the current operating conditions of the device to support
 software controlled device switching by saving and updating :c:struct:`mspi_dev_cfg` and
 other relevant mspi struct or private data structures. In particular, :c:struct:`mspi_dev_id`
 which contains the identity of the device needs to be used for every API call.


 Configuration Options
 *********************

 Related configuration options:

 * :kconfig:option:`CONFIG_MSPI`
 * :kconfig:option:`CONFIG_MSPI_ASYNC`
 * :kconfig:option:`CONFIG_MSPI_PERIPHERAL`
 * :kconfig:option:`CONFIG_MSPI_XIP`
 * :kconfig:option:`CONFIG_MSPI_SCRAMBLE`
 * :kconfig:option:`CONFIG_MSPI_TIMING`
 * :kconfig:option:`CONFIG_MSPI_INIT_PRIORITY`
 * :kconfig:option:`CONFIG_MSPI_COMPLETION_TIMEOUT_TOLERANCE`

 API Reference
 *************

 .. doxygengroup:: mspi_interface
	.. _mspi_api:

	Multi-bit SPI Bus
	#################

	The MSPI (multi-bit SPI) is provided as a generic API to accommodate
	advanced SPI peripherals and devices that typically require command,
	address and data phases, and multiple signal lines during these phases.
	While the API supports advanced features such as :term:`XIP` and scrambling,
	it is also compatible with generic SPI.

	.. contents::
	:local:
	:depth: 2

	.. _mspi-controller-api:

	MSPI Controller API
	*******************

	Zephyr's MSPI controller API may be used when a multi-bit SPI controller
	is present. E.g. Ambiq MSPI, QSPI, OSPI, Flexspi, etc.
	The API supports single to hex SDR/DDR IO with variable latency and advanced
	features such as :term:`XIP` and scrambling. Applicable devices include but
	not limited to high-speed, high density flash/psram memory devices, displays
	and sensors.

	The MSPI interface contains controller drivers that are SoC platform specific
	and implement the MSPI APIs, and device drivers that reference these APIs.
	The relationship between the controller and device drivers is many-to-many to
	allow for easy switching between platforms.

	Here is a list of generic steps for initializing the MSPI controller and the
	MSPI bus inside the device driver initialization function:

	#. Initialize the data structure of the MSPI controller driver instance.
	The usual device defining macros such as :c:macro:`DEVICE_DT_INST_DEFINE`
	can be used, and the initialization function, config and data provided
	as a parameter to the macro.

	#. Initialize the hardware, including but not limited to:

	* Check :c:struct:`mspi_cfg` against hardware's own capabilities to prevent
	incorrect usages.

	* Setup default pinmux.

	* Setup the clock for the controller.

	* Power on the hardware.

	* Configure the hardware using :c:struct:`mspi_cfg` and possibly more
	platform specific settings.

	* Usually, the :c:struct:`mspi_cfg` is filled from device tree and contains
	static, boot time parameters. However, if needed, one can use :c:func:`mspi_config`
	to re-initialize the hardware with new parameters during runtime.

	* Release any lock if applicable.

	#. Perform device driver initialization. As usually, :c:macro:`DEVICE_DT_INST_DEFINE`
	can be used. Inside device driver initialization function, perform the following
	required steps.

	#. Call :c:func:`mspi_dev_config` with device specific hardware settings obtained
	from device datasheets.

	* The :c:struct:`mspi_dev_cfg` should be filled by device tree and helper macro
	:c:macro:`MSPI_DEVICE_CONFIG_DT` can be used.

	* The controller driver should then validate the members of :c:struct:`mspi_dev_cfg`
	to prevent incorrect usage.

	* The controller driver should implement a mutex to protect from accidental access.

	* The controller driver may also switch between different devices based on
	:c:struct:`mspi_dev_id`.

	#. Call API for additional setups if supported by hardware

	* :c:func:`mspi_xip_config` for :term:`XIP` feature

	* :c:func:`mspi_scramble_config` for scrambling feature

	* :c:func:`mspi_timing_config` for platform specific timing setup.

	#. Register any callback with :c:func:`mspi_register_callback` if needed.

	#. Release the controller mutex lock.

	Transceive
	==========
	The transceive request is of type :c:struct:`mspi_xfer` which allows dynamic change to
	the transfer related settings once the mode of operation is determined and configured
	by :c:func:`mspi_dev_config`.

	The API also supports bulk transfers with different starting addresses and sizes with
	:c:struct:`mspi_xfer_packet`. However, it is up to the controller implementation
	whether to support scatter IO and callback management. The controller can determine
	which user callback to trigger based on :c:enum:`mspi_bus_event_cb_mask` upon completion
	of each async/sync transfer if the callback had been registered using
	:c:func:`mspi_register_callback`. Or not to trigger any callback at all with
	:c:enum:`MSPI_BUS_NO_CB` even if the callbacks are already registered.
	In which case that a controller supports hardware command queue, user could take full
	advantage of the hardware performance if scatter IO and callback management are supported
	by the driver implementation.

	Device Tree
	===========

	Here is an example for defining an MSPI controller in device tree:
	The mspi controller's bindings should reference mspi-controller.yaml as one of the base.

	.. code-block:: devicetree

	mspi0: mspi@400 {
	status = "okay";
	compatible = "zephyr,mspi-emul-controller";

	reg = < 0x400 0x4 >;
	#address-cells = < 0x1 >;
	#size-cells = < 0x0 >;

	clock-frequency = < 0x17d7840 >;
	op-mode = "MSPI_CONTROLLER";
	duplex = "MSPI_HALF_DUPLEX";
	ce-gpios = < &gpio0 0x5 0x1 >, < &gpio0 0x12 0x1 >;
	dqs-support;

	pinctrl-0 = < &pinmux-mspi0 >;
	pinctrl-names = "default";
	};

	Here is an example for defining an MSPI device in device tree:
	The mspi device's bindings should reference mspi-device.yaml as one of the base.

	.. code-block:: devicetree

	&mspi0 {

	mspi_dev0: mspi_dev0@0 {
	status = "okay";
	compatible = "zephyr,mspi-emul-device";

	reg = < 0x0 >;
	size = < 0x10000 >;

	mspi-max-frequency = < 0x2dc6c00 >;
	mspi-io-mode = "MSPI_IO_MODE_QUAD";
	mspi-data-rate = "MSPI_DATA_RATE_SINGLE";
	mspi-hardware-ce-num = < 0x0 >;
	read-instruction = < 0xb >;
	write-instruction = < 0x2 >;
	instruction-length = "INSTR_1_BYTE";
	address-length = "ADDR_4_BYTE";
	rx-dummy = < 0x8 >;
	tx-dummy = < 0x0 >;
	xip-config = < 0x0 0x0 0x0 0x0 >;
	ce-break-config = < 0x0 0x0 >;
	};

	};

	User should specify target operating parameters in the DTS such as ``mspi-max-frequency``,
	``mspi-io-mode`` and ``mspi-data-rate`` even though they may subject to change during runtime.
	It should represent the typical configuration of the device during normal operations.

	Multi Peripheral
	================
	With :c:struct:`mspi_dev_id` defined as collection of the device index and CE GPIO from
	device tree, the API supports multiple devices on the same controller instance.
	The controller driver implementation may or may not support device switching,
	which can be performed either by software or by hardware. If the switching is handled
	by software, it should be performed in :c:func:`mspi_dev_config` call.

	The device driver should record the current operating conditions of the device to support
	software controlled device switching by saving and updating :c:struct:`mspi_dev_cfg` and
	other relevant mspi struct or private data structures. In particular, :c:struct:`mspi_dev_id`
	which contains the identity of the device needs to be used for every API call.


	Configuration Options
	*********************

	Related configuration options:

	* :kconfig:option:`CONFIG_MSPI`
	* :kconfig:option:`CONFIG_MSPI_ASYNC`
	* :kconfig:option:`CONFIG_MSPI_PERIPHERAL`
	* :kconfig:option:`CONFIG_MSPI_XIP`
	* :kconfig:option:`CONFIG_MSPI_SCRAMBLE`
	* :kconfig:option:`CONFIG_MSPI_TIMING`
	* :kconfig:option:`CONFIG_MSPI_INIT_PRIORITY`
	* :kconfig:option:`CONFIG_MSPI_COMPLETION_TIMEOUT_TOLERANCE`

	API Reference
	*************

	.. doxygengroup:: mspi_interface