1# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/mtd/brcm,brcmnand.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Broadcom STB NAND Controller
8
9maintainers:
10  - Brian Norris <computersforpeace@gmail.com>
11  - Kamal Dasu <kdasu.kdev@gmail.com>
12
13description: |
14  The Broadcom Set-Top Box NAND controller supports low-level access to raw NAND
15  flash chips. It has a memory-mapped register interface for both control
16  registers and for its data input/output buffer. On some SoCs, this controller
17  is paired with a custom DMA engine (inventively named "Flash DMA") which
18  supports basic PROGRAM and READ functions, among other features.
19
20  This controller was originally designed for STB SoCs (BCM7xxx) but is now
21  available on a variety of Broadcom SoCs, including some BCM3xxx, BCM63xx, and
22  iProc/Cygnus. Its history includes several similar (but not fully register
23  compatible) versions.
24
25  -- Additional SoC-specific NAND controller properties --
26
27  The NAND controller is integrated differently on the variety of SoCs on which
28  it is found. Part of this integration involves providing status and enable
29  bits with which to control the 8 exposed NAND interrupts, as well as hardware
30  for configuring the endianness of the data bus. On some SoCs, these features
31  are handled via standard, modular components (e.g., their interrupts look like
32  a normal IRQ chip), but on others, they are controlled in unique and
33  interesting ways, sometimes with registers that lump multiple NAND-related
34  functions together. The former case can be described simply by the standard
35  interrupts properties in the main controller node. But for the latter
36  exceptional cases, we define additional 'compatible' properties and associated
37  register resources within the NAND controller node above.
38
39properties:
40  compatible:
41    oneOf:
42      - items:
43          - enum:
44              - brcm,brcmnand-v2.1
45              - brcm,brcmnand-v2.2
46              - brcm,brcmnand-v4.0
47              - brcm,brcmnand-v5.0
48              - brcm,brcmnand-v6.0
49              - brcm,brcmnand-v6.1
50              - brcm,brcmnand-v6.2
51              - brcm,brcmnand-v7.0
52              - brcm,brcmnand-v7.1
53              - brcm,brcmnand-v7.2
54              - brcm,brcmnand-v7.3
55          - const: brcm,brcmnand
56      - description: BCM63138 SoC-specific NAND controller
57        items:
58          - const: brcm,nand-bcm63138
59          - enum:
60              - brcm,brcmnand-v7.0
61              - brcm,brcmnand-v7.1
62          - const: brcm,brcmnand
63      - description: iProc SoC-specific NAND controller
64        items:
65          - const: brcm,nand-iproc
66          - const: brcm,brcmnand-v6.1
67          - const: brcm,brcmnand
68      - description: BCM63168 SoC-specific NAND controller
69        items:
70          - const: brcm,nand-bcm63168
71          - const: brcm,nand-bcm6368
72          - const: brcm,brcmnand-v4.0
73          - const: brcm,brcmnand
74
75  reg:
76    minItems: 1
77    maxItems: 6
78
79  reg-names:
80    minItems: 1
81    maxItems: 6
82    items:
83      enum: [ nand, flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ]
84
85  interrupts:
86    minItems: 1
87    items:
88      - description: NAND CTLRDY interrupt
89      - description: FLASH_DMA_DONE (if flash DMA is available) or FLASH_EDU_DONE (if EDU is available)
90
91  interrupt-names:
92    minItems: 1
93    items:
94      - const: nand_ctlrdy
95      - enum:
96          - flash_dma_done
97          - flash_edu_done
98
99  clocks:
100    maxItems: 1
101    description: reference to the clock for the NAND controller
102
103  clock-names:
104    const: nand
105
106  brcm,nand-has-wp:
107    description: >
108      Some versions of this IP include a write-protect
109      (WP) control bit. It is always available on >=
110      v7.0. Use this property to describe the rare
111      earlier versions of this core that include WP
112    type: boolean
113
114patternProperties:
115  "^nand@[a-f0-9]$":
116    type: object
117    $ref: raw-nand-chip.yaml
118    properties:
119      compatible:
120        const: brcm,nandcs
121
122      nand-ecc-step-size:
123        enum: [ 512, 1024 ]
124
125      brcm,nand-oob-sector-size:
126        description: |
127          integer, to denote the spare area sector size
128          expected for the ECC layout in use. This size, in
129          addition to the strength and step-size,
130          determines how the hardware BCH engine will lay
131          out the parity bytes it stores on the flash.
132          This property can be automatically determined by
133          the flash geometry (particularly the NAND page
134          and OOB size) in many cases, but when booting
135          from NAND, the boot controller has only a limited
136          number of available options for its default ECC
137          layout.
138        $ref: /schemas/types.yaml#/definitions/uint32
139
140    unevaluatedProperties: false
141
142allOf:
143  - $ref: nand-controller.yaml#
144  - if:
145      properties:
146        compatible:
147          contains:
148            const: brcm,nand-bcm63138
149    then:
150      properties:
151        reg-names:
152          items:
153            - const: nand
154            - const: nand-int-base
155  - if:
156      properties:
157        compatible:
158          contains:
159            const: brcm,nand-bcm6368
160    then:
161      properties:
162        reg-names:
163          items:
164            - const: nand
165            - const: nand-int-base
166            - const: nand-cache
167  - if:
168      properties:
169        compatible:
170          contains:
171            const: brcm,nand-iproc
172    then:
173      properties:
174        reg-names:
175          items:
176            - const: nand
177            - const: iproc-idm
178            - const: iproc-ext
179  - if:
180      properties:
181        interrupts:
182          minItems: 2
183    then:
184      required:
185        - interrupt-names
186
187unevaluatedProperties: false
188
189required:
190  - reg
191  - reg-names
192  - interrupts
193
194examples:
195  - |
196    nand-controller@f0442800 {
197        compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand";
198        reg = <0xf0442800 0x600>,
199              <0xf0443000 0x100>;
200        reg-names = "nand", "flash-dma";
201        interrupt-parent = <&hif_intr2_intc>;
202        interrupts = <24>, <4>;
203        interrupt-names = "nand_ctlrdy", "flash_dma_done";
204
205        #address-cells = <1>;
206        #size-cells = <0>;
207
208        nand@1 {
209            compatible = "brcm,nandcs";
210            reg = <1>; // Chip select 1
211            nand-on-flash-bbt;
212            nand-ecc-strength = <12>;
213            nand-ecc-step-size = <512>;
214
215            #address-cells = <1>;
216            #size-cells = <1>;
217        };
218    };
219  - |
220    nand-controller@10000200 {
221        compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368",
222                     "brcm,brcmnand-v4.0", "brcm,brcmnand";
223        reg = <0x10000200 0x180>,
224              <0x100000b0 0x10>,
225              <0x10000600 0x200>;
226        reg-names = "nand", "nand-int-base", "nand-cache";
227        interrupt-parent = <&periph_intc>;
228        interrupts = <50>;
229        clocks = <&periph_clk 20>;
230        clock-names = "nand";
231
232        #address-cells = <1>;
233        #size-cells = <0>;
234
235        nand@0 {
236            compatible = "brcm,nandcs";
237            reg = <0>;
238            nand-on-flash-bbt;
239            nand-ecc-strength = <1>;
240            nand-ecc-step-size = <512>;
241
242            #address-cells = <1>;
243            #size-cells = <1>;
244        };
245    };
246