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
  13 description: |
  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
  39 properties:
  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     maxItems: 3
  88     items:
  89       - description: NAND CTLRDY interrupt
  90       - description: FLASH_DMA_DONE if flash DMA is available
  91       - description: FLASH_EDU_DONE if EDU is available
  92
  93   interrupt-names:
  94     minItems: 1
  95     maxItems: 3
  96     items:
  97       - const: nand_ctlrdy
  98       - const: flash_dma_done
  99       - const: 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 patternProperties:
 117   "^nand@[a-f0-9]$":
 118     type: object
 119     properties:
 120       compatible:
 121         const: brcm,nandcs
 122
 123       nand-ecc-step-size:
 124         enum: [ 512, 1024 ]
 125
 126       brcm,nand-oob-sector-size:
 127         description: |
 128           integer, to denote the spare area sector size
 129           expected for the ECC layout in use. This size, in
 130           addition to the strength and step-size,
 131           determines how the hardware BCH engine will lay
 132           out the parity bytes it stores on the flash.
 133           This property can be automatically determined by
 134           the flash geometry (particularly the NAND page
 135           and OOB size) in many cases, but when booting
 136           from NAND, the boot controller has only a limited
 137           number of available options for its default ECC
 138           layout.
 139         $ref: /schemas/types.yaml#/definitions/uint32
 140
 141 allOf:
 142   - $ref: nand-controller.yaml#
 143   - if:
 144       properties:
 145         compatible:
 146           contains:
 147             const: brcm,nand-bcm63138
 148     then:
 149       properties:
 150         reg-names:
 151           minItems: 2
 152           maxItems: 2
 153           items:
 154             - const: nand
 155             - const: nand-int-base
 156   - if:
 157       properties:
 158         compatible:
 159           contains:
 160             const: brcm,nand-bcm6368
 161     then:
 162       properties:
 163         reg-names:
 164           minItems: 3
 165           maxItems: 3
 166           items:
 167             - const: nand
 168             - const: nand-int-base
 169             - const: nand-cache
 170   - if:
 171       properties:
 172         compatible:
 173           contains:
 174             const: brcm,nand-iproc
 175     then:
 176       properties:
 177         reg-names:
 178           minItems: 3
 179           maxItems: 3
 180           items:
 181             - const: nand
 182             - const: iproc-idm
 183             - const: iproc-ext
 184
 185 unevaluatedProperties: false
 186
 187 required:
 188   - reg
 189   - reg-names
 190   - interrupts
 191
 192 examples:
 193   - |
 194     nand-controller@f0442800 {
 195             compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand";
 196             reg = <0xf0442800 0x600>,
 197                   <0xf0443000 0x100>;
 198             reg-names = "nand", "flash-dma";
 199             interrupt-parent = <&hif_intr2_intc>;
 200             interrupts = <24>, <4>;
 201
 202             #address-cells = <1>;
 203             #size-cells = <0>;
 204
 205             nand@1 {
 206                     compatible = "brcm,nandcs";
 207                     reg = <1>; // Chip select 1
 208                     nand-on-flash-bbt;
 209                     nand-ecc-strength = <12>;
 210                     nand-ecc-step-size = <512>;
 211
 212                     #address-cells = <1>;
 213                     #size-cells = <1>;
 214             };
 215     };
 216   - |
 217     nand-controller@10000200 {
 218             compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368",
 219                          "brcm,brcmnand-v4.0", "brcm,brcmnand";
 220             reg = <0x10000200 0x180>,
 221                   <0x100000b0 0x10>,
 222                   <0x10000600 0x200>;
 223             reg-names = "nand", "nand-int-base", "nand-cache";
 224             interrupt-parent = <&periph_intc>;
 225             interrupts = <50>;
 226             clocks = <&periph_clk 20>;
 227             clock-names = "nand";
 228
 229             #address-cells = <1>;
 230             #size-cells = <0>;
 231
 232             nand@0 {
 233                     compatible = "brcm,nandcs";
 234                     reg = <0>;
 235                     nand-on-flash-bbt;
 236                     nand-ecc-strength = <1>;
 237                     nand-ecc-step-size = <512>;
 238
 239                     #address-cells = <1>;
 240                     #size-cells = <1>;
 241             };
 242     };