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