# Copyright (c) 2024, Ambiq Micro Inc. <www.ambiq.com>
# SPDX-License-Identifier: Apache-2.0

# Common fields for MSPI controllers

include: base.yaml

bus: mspi

properties:
  clock-frequency:
    type: int
    description: |
      Clock frequency the MSPI peripheral is being driven at, in Hz.
  "#address-cells":
    required: true
    const: 1
  "#size-cells":
    required: true
    const: 0

  op-mode:
    type: string
    enum:
      - "MSPI_CONTROLLER"
      - "MSPI_PERIPHERAL"
    description: |
      Indicate MSPI controller or peripheral mode of the controller.
      The controller driver may use this during initialization.

  duplex:
    type: string
    enum:
      - "MSPI_HALF_DUPLEX"
      - "MSPI_FULL_DUPLEX"
    description: |
      Indicate MSPI Duplex mode, full or half.
      The controller driver may check this setting against its
      capabilities.

  dqs-support:
    type: boolean
    description: |
      Indicate whether the hardware supports DQS.
      The controller driver may check this setting against its
      capabilities.

  software-multiperipheral:
    type: boolean
    description: |
      Indicate whether the controller driver enables support for
      software managed multi peripheral feature.
      At the minimum, the controller driver should use it to allow
      or disallow calling mspi_dev_config with MSPI_DEVICE_CONFIG_NONE.

  ce-gpios:
    type: phandle-array
    description: |
      An array of chip select GPIOs to use. Each element
      in the array specifies a GPIO. The index in the array
      corresponds to the child node that the CE gpio controls.

      Example:

        mspi@... {
                ce-gpios = <&gpio0 23 GPIO_ACTIVE_LOW>,
                              <&gpio1 10 GPIO_ACTIVE_LOW>,
                              ...;

                mspi-device@0 {
                        reg = <0>;
                        ...
                };
                mspi-device@1 {
                        reg = <1>;
                        ...
                };
                ...
        };

      The child node "mspi-device@0" specifies a mspi device with
      chip select controller gpio0, pin 23, and devicetree
      GPIO flags GPIO_ACTIVE_LOW. Similarly, "mspi-device@1" has CE GPIO
      controller gpio1, pin 10, and flags GPIO_ACTIVE_LOW. Additional
      devices can be configured in the same way.

      If unsure about the flags cell, GPIO_ACTIVE_LOW is generally a safe
      choice for a typical "CEn" pin. GPIO_ACTIVE_HIGH may be used if
      intervening hardware inverts the signal to the peripheral device or
      the line itself is active high.

      Regardless of whether the CE pin may need software control or MSPI
      controller has dedicated CE pin, this field should be defined to
      help manage multiple devices on the same MSPI controller.
