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