Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml

   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
   7 title: Broadcom STB NAND Controller
   8
   9 maintainers:
  10   - Brian Norris <computersforpeace@gmail.com>
  11   - Kamal Dasu <kdasu.kdev@gmail.com>
  12   - William Zhang <william.zhang@broadcom.com>
  13
  14 description: |
  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
  41 properties:
  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
 123 patternProperties:
 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
 160 allOf:
 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
 222 unevaluatedProperties: false
 223
 224 required:
 225   - reg
 226   - reg-names
 227
 228 examples:
 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     };