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