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

   1 * Broadcom STB NAND Controller
   2
   3 The Broadcom Set-Top Box NAND controller supports low-level access to raw NAND
   4 flash chips. It has a memory-mapped register interface for both control
   5 registers and for its data input/output buffer. On some SoCs, this controller is
   6 paired with a custom DMA engine (inventively named "Flash DMA") which supports
   7 basic PROGRAM and READ functions, among other features.
   8
   9 This controller was originally designed for STB SoCs (BCM7xxx) but is now
  10 available on a variety of Broadcom SoCs, including some BCM3xxx, BCM63xx, and
  11 iProc/Cygnus. Its history includes several similar (but not fully register
  12 compatible) versions.
  13
  14 Required properties:
  15 - compatible       : May contain an SoC-specific compatibility string (see below)
  16                      to account for any SoC-specific hardware bits that may be
  17                      added on top of the base core controller.
  18                      In addition, must contain compatibility information about
  19                      the core NAND controller, of the following form:
  20                      "brcm,brcmnand" and an appropriate version compatibility
  21                      string, like "brcm,brcmnand-v7.0"
  22                      Possible values:
  23                          brcm,brcmnand-v2.1
  24                          brcm,brcmnand-v2.2
  25                          brcm,brcmnand-v4.0
  26                          brcm,brcmnand-v5.0
  27                          brcm,brcmnand-v6.0
  28                          brcm,brcmnand-v6.1
  29                          brcm,brcmnand-v6.2
  30                          brcm,brcmnand-v7.0
  31                          brcm,brcmnand-v7.1
  32                          brcm,brcmnand-v7.2
  33                          brcm,brcmnand-v7.3
  34                          brcm,brcmnand
  35 - reg              : the register start and length for NAND register region.
  36                      (optional) Flash DMA register range (if present)
  37                      (optional) NAND flash cache range (if at non-standard offset)
  38 - reg-names        : a list of the names corresponding to the previous register
  39                      ranges. Should contain "nand" and (optionally)
  40                      "flash-dma" or "flash-edu" and/or "nand-cache".
  41 - interrupts       : The NAND CTLRDY interrupt, (if Flash DMA is available)
  42                      FLASH_DMA_DONE and if EDU is avaialble and used FLASH_EDU_DONE
  43 - interrupt-names  : May be "nand_ctlrdy" or "flash_dma_done" or "flash_edu_done",
  44                      if broken out as individual interrupts.
  45                      May be "nand", if the SoC has the individual NAND
  46                      interrupts multiplexed behind another custom piece of
  47                      hardware
  48 - #address-cells   : <1> - subnodes give the chip-select number
  49 - #size-cells      : <0>
  50
  51 Optional properties:
  52 - clock                     : reference to the clock for the NAND controller
  53 - clock-names               : "nand" (required for the above clock)
  54 - brcm,nand-has-wp          : Some versions of this IP include a write-protect
  55                               (WP) control bit. It is always available on >=
  56                               v7.0. Use this property to describe the rare
  57                               earlier versions of this core that include WP
  58
  59  -- Additional SoC-specific NAND controller properties --
  60
  61 The NAND controller is integrated differently on the variety of SoCs on which it
  62 is found. Part of this integration involves providing status and enable bits
  63 with which to control the 8 exposed NAND interrupts, as well as hardware for
  64 configuring the endianness of the data bus. On some SoCs, these features are
  65 handled via standard, modular components (e.g., their interrupts look like a
  66 normal IRQ chip), but on others, they are controlled in unique and interesting
  67 ways, sometimes with registers that lump multiple NAND-related functions
  68 together. The former case can be described simply by the standard interrupts
  69 properties in the main controller node. But for the latter exceptional cases,
  70 we define additional 'compatible' properties and associated register resources within the NAND controller node above.
  71
  72  - compatible: Can be one of several SoC-specific strings. Each SoC may have
  73    different requirements for its additional properties, as described below each
  74    bullet point below.
  75
  76    * "brcm,nand-bcm63138"
  77      - reg: (required) the 'NAND_INT_BASE' register range, with separate status
  78        and enable registers
  79      - reg-names: (required) "nand-int-base"
  80
  81    * "brcm,nand-bcm6368"
  82      - compatible: should contain "brcm,nand-bcm<soc>", "brcm,nand-bcm6368"
  83      - reg: (required) the 'NAND_INTR_BASE' register range, with combined status
  84        and enable registers, and boot address registers
  85      - reg-names: (required) "nand-int-base"
  86
  87    * "brcm,nand-iproc"
  88      - reg: (required) the "IDM" register range, for interrupt enable and APB
  89        bus access endianness configuration, and the "EXT" register range,
  90        for interrupt status/ack.
  91      - reg-names: (required) a list of the names corresponding to the previous
  92        register ranges. Should contain "iproc-idm" and "iproc-ext".
  93
  94
  95 * NAND chip-select
  96
  97 Each controller (compatible: "brcm,brcmnand") may contain one or more subnodes
  98 to represent enabled chip-selects which (may) contain NAND flash chips. Their
  99 properties are as follows.
 100
 101 Required properties:
 102 - compatible                : should contain "brcm,nandcs"
 103 - reg                       : a single integer representing the chip-select
 104                               number (e.g., 0, 1, 2, etc.)
 105 - #address-cells            : see partition.txt
 106 - #size-cells               : see partition.txt
 107
 108 Optional properties:
 109 - nand-ecc-strength         : see nand-controller.yaml
 110 - nand-ecc-step-size        : must be 512 or 1024. See nand-controller.yaml
 111 - nand-on-flash-bbt         : boolean, to enable the on-flash BBT for this
 112                               chip-select. See nand-controller.yaml
 113 - brcm,nand-oob-sector-size : integer, to denote the spare area sector size
 114                               expected for the ECC layout in use. This size, in
 115                               addition to the strength and step-size,
 116                               determines how the hardware BCH engine will lay
 117                               out the parity bytes it stores on the flash.
 118                               This property can be automatically determined by
 119                               the flash geometry (particularly the NAND page
 120                               and OOB size) in many cases, but when booting
 121                               from NAND, the boot controller has only a limited
 122                               number of available options for its default ECC
 123                               layout.
 124
 125 Each nandcs device node may optionally contain sub-nodes describing the flash
 126 partition mapping. See partition.txt for more detail.
 127
 128
 129 Example:
 130
 131 nand@f0442800 {
 132         compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand";
 133         reg = <0xF0442800 0x600>,
 134               <0xF0443000 0x100>;
 135         reg-names = "nand", "flash-dma";
 136         interrupt-parent = <&hif_intr2_intc>;
 137         interrupts = <24>, <4>;
 138
 139         #address-cells = <1>;
 140         #size-cells = <0>;
 141
 142         nandcs@1 {
 143                 compatible = "brcm,nandcs";
 144                 reg = <1>; // Chip select 1
 145                 nand-on-flash-bbt;
 146                 nand-ecc-strength = <12>;
 147                 nand-ecc-step-size = <512>;
 148
 149                 // Partitions
 150                 #address-cells = <1>;  // <2>, for 64-bit offset
 151                 #size-cells = <1>;     // <2>, for 64-bit length
 152                 flash0.rootfs@0 {
 153                         reg = <0 0x10000000>;
 154                 };
 155                 flash0@0 {
 156                         reg = <0 0>; // MTDPART_SIZ_FULL
 157                 };
 158                 flash0.kernel@10000000 {
 159                         reg = <0x10000000 0x400000>;
 160                 };
 161         };
 162 };
 163
 164 nand@10000200 {
 165         compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368",
 166                 "brcm,brcmnand-v4.0", "brcm,brcmnand";
 167         reg = <0x10000200 0x180>,
 168               <0x10000600 0x200>,
 169               <0x100000b0 0x10>;
 170         reg-names = "nand", "nand-cache", "nand-int-base";
 171         interrupt-parent = <&periph_intc>;
 172         interrupts = <50>;
 173         clocks = <&periph_clk 20>;
 174         clock-names = "nand";
 175
 176         #address-cells = <1>;
 177         #size-cells = <0>;
 178
 179         nand0: nandcs@0 {
 180                 compatible = "brcm,nandcs";
 181                 reg = <0>;
 182                 nand-on-flash-bbt;
 183                 nand-ecc-strength = <1>;
 184                 nand-ecc-step-size = <512>;
 185         };
 186 };