1# Copyright (c) 2024, Ambiq Micro Inc. <www.ambiq.com>
2# SPDX-License-Identifier: Apache-2.0
3
4# Common fields for MSPI devices
5
6include: [base.yaml, power.yaml]
7
8on-bus: mspi
9
10properties:
11  reg:
12    required: true
13
14  mspi-max-frequency:
15    type: int
16    required: true
17    description: |
18      Maximum clock frequency of device to configure in Hz.
19      In device tree, it is normally the target operating
20      frequency after initialization.
21
22  mspi-io-mode:
23    type: string
24    enum:
25      - "MSPI_IO_MODE_SINGLE"
26      - "MSPI_IO_MODE_DUAL"
27      - "MSPI_IO_MODE_DUAL_1_1_2"
28      - "MSPI_IO_MODE_DUAL_1_2_2"
29      - "MSPI_IO_MODE_QUAD"
30      - "MSPI_IO_MODE_QUAD_1_1_4"
31      - "MSPI_IO_MODE_QUAD_1_4_4"
32      - "MSPI_IO_MODE_OCTAL"
33      - "MSPI_IO_MODE_OCTAL_1_1_8"
34      - "MSPI_IO_MODE_OCTAL_1_8_8"
35      - "MSPI_IO_MODE_HEX"
36      - "MSPI_IO_MODE_HEX_8_8_16"
37      - "MSPI_IO_MODE_HEX_8_16_16"
38    description: |
39      MSPI I/O mode setting.
40      In device tree, it is normally the target io mode
41      after initialization.
42
43  mspi-data-rate:
44    type: string
45    enum:
46      - "MSPI_DATA_RATE_SINGLE"
47      - "MSPI_DATA_RATE_S_S_D"
48      - "MSPI_DATA_RATE_S_D_D"
49      - "MSPI_DATA_RATE_DUAL"
50    description:
51      MSPI data rate setting.
52      In device tree, it is normally the target data rate
53      after initialization.
54
55  mspi-hardware-ce-num:
56    type: int
57    description: |
58      MSPI hardware CE number.
59      MSPI controller may natively support multiple peripheral devices
60      on the same MSPI instance by assigning designated CE numbers.
61
62  mspi-cpp-mode:
63    type: string
64    enum:
65      - "MSPI_CPP_MODE_0"
66      - "MSPI_CPP_MODE_1"
67      - "MSPI_CPP_MODE_2"
68      - "MSPI_CPP_MODE_3"
69    description: |
70      MSPI clock polarity setting.
71      MSPI_CPP_MODE_0: CPOL=0, CPHA=0
72      MSPI_CPP_MODE_1: CPOL=0, CPHA=1
73      MSPI_CPP_MODE_2: CPOL=1, CPHA=0
74      MSPI_CPP_MODE_3: CPOL=1, CPHA=1
75
76  mspi-endian:
77    type: string
78    enum:
79      - "MSPI_LITTLE_ENDIAN"
80      - "MSPI_BIG_ENDIAN"
81    description: |
82      MSPI transfer MSB or LSB first.
83
84  mspi-ce-polarity:
85    type: string
86    enum:
87      - "MSPI_CE_ACTIVE_LOW"
88      - "MSPI_CE_ACTIVE_HIGH"
89    description: |
90      MSPI CE polarity. In most cases, it is active low.
91
92  mspi-dqs-enable:
93    type: boolean
94    description: |
95      Enable DQS mode for a device which supports it.
96      This will be checked against dqs-support and configure
97      the MSPI hardware if it supports DQS mode.
98
99  mspi-hold-ce:
100    type: boolean
101    description: |
102      In some cases, it is necessary for the controller to manage
103      MSPI chip enable (under software control), so that multiple
104      mspi transactions can be performed without releasing CE.
105      A typical use case is variable length MSPI packets where
106      the first mspi transaction reads the length and the second
107      mspi transaction reads length bytes.
108
109  rx-dummy:
110    type: int
111    description: |
112      The number of data or clock cycles between addr and data
113      in RX direction.
114      0 means the RX dummy phase is disabled.
115
116  tx-dummy:
117    type: int
118    description: |
119      The number of data or clock cycles between addr and data
120      in TX direction.
121      0 means the TX dummy phase is disabled.
122
123  read-command:
124    type: int
125    description: |
126      Read command to be sent in RX direction.
127
128  write-command:
129    type: int
130    description: |
131      Write command to be sent in RX direction.
132
133  command-length:
134    type: string
135    enum:
136      - "INSTR_DISABLED"
137      - "INSTR_1_BYTE"
138      - "INSTR_2_BYTE"
139    description: |
140      Length in bytes of the write and read commands.
141
142  address-length:
143    type: string
144    enum:
145      - "ADDR_DISABLED"
146      - "ADDR_1_BYTE"
147      - "ADDR_2_BYTE"
148      - "ADDR_3_BYTE"
149      - "ADDR_4_BYTE"
150    description: |
151      Length in bytes of address to be sent in address phase.
152
153  xip-config:
154    type: array
155    description: |
156      Array of parameters to configure the xip feature.
157      enable: whether XIP feature is enabled.
158      address_offset: The offset in bytes to the start of the
159                      platform specific XIP address region.
160      size: The size in bytes of the XIP address region one
161            wish to enable or disable.
162      permission: The permission granted to the region. (RW/RO)
163
164      For controller that support this feature. One may map the device
165      memory into Soc system memory map. i.e. XIP address region
166      So that the device may be used as an external RAM and execute code.
167
168      default =
169      <
170        .enable         = false;
171        .address_offset = 0;
172        .size           = 0;
173        .permission     = 0;
174      >
175
176  scramble-config:
177    type: array
178    description: |
179      Array of parameters to configure the scrambling feature.
180      enable: whether scrambling feature is enabled.
181      address_offset: The offset in bytes to the start address which
182                      can be the offset to the start of the platform
183                      specific XIP address region or phyiscal device address.
184
185      size: The size in bytes of the region one wish to enable or disable.
186      For controller that support hardware scrambling, one may use it for
187      additional security to protect data or code stored in external devices.
188
189      default =
190      <
191        .enable         = false;
192        .address_offset = 0;
193        .size           = 0;
194      >
195
196  ce-break-config:
197    type: array
198    description: |
199      Array of parameters to configure the auto CE break feature.
200      mem_boundary: Memory boundary in bytes of a device that a transfer
201                    should't cross.
202      time_to_break: The maximum time of a transfer should't exceed for
203                     a device in micro seconds(us).
204
205      This is typically used with devices that has memory boundaries or
206      requires periodic internal refresh. e.g. psram
207
208      default =
209      <
210        .mem_boundary    = 0;
211        .time_to_break   = 0;
212      >
213