GoogleGit

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