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