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