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     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
 114 patternProperties:
 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
 142 allOf:
 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
 187 unevaluatedProperties: false
 188
 189 required:
 190   - reg
 191   - reg-names
 192   - interrupts
 193
 194 examples:
 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     };