cros/dts/bindings/flashmap.txt

   1 Chrome OS Flash Map Binding
   2 ===========================
   3
   4 The device tree node which describes the contents of the firmware flash
   5 memory is as follows:
   6
   7 Required properties :
   8 - name = "flash" or "flash@<addr>";
   9
  10 (note there is no compatible string required.)
  11
  12
  13 Sub-nodes describe each section of the flash. The idea is that the
  14 sections cover the entire contents of the flash and thus describe its
  15 entire contents. Gaps are allowed, but will generate warnings. Overlaps
  16 are not allowed, although sections which contain nothing are ignored
  17 and so can overlap with others.
  18
  19 Required properties :
  20
  21  - label : Label for this section (a user readable string)
  22
  23 Optional properties :
  24
  25  - reg : Two cells :
  26             - start offset of this section
  27             - size of this section
  28
  29  - size : Size of this section (the start offset is assumed to be
  30       immediately after the previous section.)
  31
  32 (note that only one of 'reg' and 'size' should be specified.)
  33
  34  - read-only : Boolean property, which if present, indicates that this
  35       section is in read-only flash
  36
  37  - required : Indicates that this section is required for the firmware
  38       to boot. If it is not present then there will be a vital piece
  39       missing. This is used to mark the minimum sections that must be
  40       present. For example, where there is a RO section and two RW
  41       sections, only the RO section is marked required. Note that if
  42       the firmware is built with only 'required' sections, then it will
  43       only operate with non-verified boot.
  44
  45  - type : If present this describes the type of this section of the
  46       flash. Allowable types are described below.
  47
  48
  49 Section Types
  50 -------------
  51
  52 Here are described the section types and the required properties for
  53 each.
  54
  55 Empty :
  56  - no 'type' property
  57  - ignored by the flash image creation tool (cros_bundle_firmware)
  58
  59
  60 Blob : Contains data read from a list of files
  61  - type = "blob <list_of_files>"
  62
  63   <list_of_files> is a comma-separated list of files to put into the
  64     section. For example: type = "blob boot,dtb" means to put the files
  65     'boot' and 'dtb' into this section. These files are just a convenient
  66     names for files on the disk - they are set up (i.e. hard coded)
  67     by the firmware bundler.
  68
  69  For blobs where there is more than one file, we provide a way to access
  70  the content, through a sub-node for each entry. That subnode should have a
  71  standard reg property (with offset and size). The name of the subnode is the
  72  same as the name of the file. Using the previous example:
  73
  74    type = "blob boot,dtb";
  75    boot {
  76       reg = <0 0x12345>;
  77    };
  78    dtb {
  79       reg = <0x12348 0x33dc>;
  80    };
  81
  82  Currently supported files are:
  83    - coreboot : A coreboot.rom file
  84    - bootstub : An Nvidia Tegra BCT + bootloader
  85    - signed : A signed bootstub (signed Nvidia Tegra BCT + bootloader)
  86    - exynos-bl1 : A Samsung Exynos BL1 (first stage boot loader)
  87    - exynos-bl2 : A Samsung Exynos BL2 (second stage boot loader)
  88         This has special handling - please see below.
  89    - boot : The U-Boot binary
  90    - dtb : The device tree binary
  91    - skeleton : The coreboot skeleton file
  92    - gbb : Google Binary Block, containing settings and recovery bitmaps
  93
  94 Fmap : Contains a 'flashrom' FMAP which is a description of the flash
  95     contents used by the 'flashrom' tool.
  96  - type = "fmap"
  97  - ver-major : Major version number (normally 1)
  98  - ver-minor : Minor version number (normally 0)
  99
 100 Wiped : Contains the same byte value throughout
 101  - type = "wiped"
 102  - wipe-value : Value to put in section. For example:
 103       wipe_value = <0> means that the section will be all zeroes
 104       wipe_value = <0xff> means that the section will be all 0xff
 105
 106 Blobstring : Contains a single string
 107  - type = "blobstring <name>"
 108
 109   <name> is the name of the string to include. The name is just a
 110     convenient name for the string - the strings are set up (i.e.
 111     hard-coded) by the firmware packer.
 112
 113   Currently supported names are:
 114     - fwid : Firmware ID, made from the machine model and the Chrome OS
 115         version (e.g. Google_Daisy.2401.0.2012_06_18_2004)
 116
 117 Keyblock : Contains a key block
 118  - type = "keyblock <list_of_files>"
 119  - keyblock : Filename (within key directory) of the key block to use,
 120         e.g. keyblock = "firmware.keyblock"
 121  - signprivate : Filename (within key directory) of the private key
 122         to use. e.g. signprivate = "firmware_data_key.vbprivk"
 123  - version : Version number to pass to vbutil
 124  - kernelkey : Filename (within key directory) of the kernel key
 125         to use. e.g. kernelkey = "kernel_subkey.vbpubk"
 126  - preamble-flags : Value for preamble flags
 127
 128  <list_of_files> is as for blob.
 129
 130   The files are joined together and signed with vbutil to produce a
 131   key block, and it is this key block which is put into the section.
 132
 133
 134
 135 Samsung Exynos BL2
 136 ------------------
 137
 138 This file is used to load U-Boot. Within U-Boot this is called SPL,
 139 Secondary Program Loader. Samsung calls it BL2, boot loader 2, since
 140 BL1 is the first think loaded by the IROM.
 141
 142 BL2 also contains a machine parameter block, which can be configured
 143 from the firmware bundler. Each parameter consists of a 32-bit word with a
 144 character tag. The currently-defined parameters are below. Note that
 145 many of these come from the device tree, so we show the node and
 146 property that they come from, and the value for the property where
 147 relevant.
 148
 149   Code         Name
 150   ====         ========
 151   a            ARM clock frequency in MHz (/dmc 'arm-frequency')
 152   b            Boot source: Where to load U-Boot from:
 153                   4 : emmc: MMC
 154                   20 : spi : Serial Flash (SPI)
 155                   32 : straps : Load according to the OM pins
 156                   33 : usb: USB download
 157   f            Memory frequency in MHz (/dmc 'clock-frequency')
 158   i            i2c base address for early access (meant for PMIC). This
 159                   is the physical register address of the relevant
 160                   i2c controller in the Exynos memory map.
 161   m            Memory type from /dmc property 'mem-type'
 162                   0 : ddr2
 163                   1 : ddr3
 164                   2 : lpddr2
 165                   3 : lpddr3
 166   M            Memory Manufacturer name from /dmc property 'mem-manuf'
 167                   0 : autodetect : Auto-detect if possible
 168                   1 : elpida : Elpida memory
 169                   2 : samsung : Samsung memory
 170   r            board rev GPIO numbers used to read board revision
 171                        (lower halfword=first gpio, upper=second gpio)
 172   s            Serial base address (physical register address of UART
 173                   in Exynos memory map)
 174   u            U-Boot size
 175                   Size of data to be loaded by SPL
 176                    (calculated by the bundle tool)
 177   v            Memory interleave size from /dmc property
 178                'mem-interleave-size' (normally 31)
 179
 180 See smdk5250_spl.c and spl.h in the U-Boot source for the C structure.