doc/README.ublimage

   1 ---------------------------------------------
   2 UBL image Boot Image generation using mkimage
   3 ---------------------------------------------
   4
   5 This document describes how to set up an U-Boot image that can be directly
   6 booted by a DaVinci processor via NAND boot mode, using an UBL header,
   7 but without need for UBL.
   8
   9 For more details see section 11.2 "ARM ROM Boot Modes" of
  10 http://focus.ti.com/lit/ug/sprufg5a/sprufg5a.pdf
  11
  12 Command syntax:
  13 --------------
  14 ./tools/mkimage -l <u-boot_file>
  15                 to list the UBL image file details
  16
  17 ./tools/mkimage -T ublimage \
  18                 -n <board specific configuration file> \
  19                 -d <u-boot binary>  <output image file>
  20
  21 For example, for the davinci dm365evm board:
  22 ./tools/mkimage -n ./board/davinci/dm365evm/ublimage.cfg \
  23                 -T ublimage \
  24                 -d u-boot-nand.bin u-boot.ubl
  25
  26 You can generate the image directly when you compile u-boot with:
  27
  28 $ make u-boot.ubl
  29
  30 The output image can be flashed into the NAND.
  31
  32 Please check the DaVinci documentation for further details.
  33
  34 Board specific configuration file specifications:
  35 -------------------------------------------------
  36 1. This file must present in the $(BOARDDIR) and the name should be
  37         ublimage.cfg (since this is used in Makefile).
  38 2. This file can have empty lines and lines starting with "#" as first
  39         character to put comments.
  40 3. This file can have configuration command lines as mentioned below,
  41         any other information in this file is treated as invalid.
  42
  43 Configuration command line syntax:
  44 ---------------------------------
  45 1. Each command line must have two strings, first one command or address
  46         and second one data string
  47 2. Following are the valid command strings and associated data strings:-
  48         Command string          data string
  49         --------------          -----------
  50         MODE                    UBL special mode, on of:
  51                                 safe
  52                                 Example:
  53                                 MODE    safe
  54
  55         ENTRY                   Entry point address for the user
  56                                 bootloader (absolute address) = TEXT_BASE
  57                                 nand_spl loader.
  58                                 Example:
  59                                 ENTRY   0x00000020
  60
  61         PAGES                   Number of pages (size of user bootloader
  62                                 in number of pages)
  63                                 Example:
  64                                 PAGES   27
  65
  66         START_BLOCK             Block number where user bootloader is present
  67                                 Example:
  68                                 START_BLOCK     5
  69
  70         START_PAGE              Page number where user bootloader is present
  71                                 (for RBL always 0)
  72                                 Example:
  73                                 START_PAGE      0
  74
  75 ------------------------------------------------
  76
  77 Structure of the u-boot.ubl binary:
  78
  79 compile steps:
  80
  81 1) nand_spl code compile, with pad_to = (TEXT_BASE +
  82    (CONFIG_SYS_NROF_PAGES_NAND_SPL * pagesize))
  83    Example: cam_enc_4xx pad_to = 0x20 + (6 * 0x800) = 0x3020 = 12320
  84    -> u-boot-spl-16k.bin
  85
  86    !! TEXT_BASE = 0x20, as the RBL starts at 0x20
  87
  88 2) compile u-boot.bin ("normal" u-boot)
  89    -> u-boot.bin
  90
  91 3) create u-boot-nand.bin = u-boot-spl-16k.bin + u-boot.bin
  92
  93 4) create u-boot.ubl, size = 1 page size NAND
  94    create UBL header and paste it before u-boot.bin
  95
  96 This steps are done automagically if you do a "make all"
  97
  98 -> You get an u-boot.ubl binary, which you can flash
  99    into your NAND.
 100
 101 Structure of this binary (Example for the cam_enc_4xx board with a NAND
 102 page size = 0x800):
 103
 104 offset :    0x00000 | 0x800       | 0x3800
 105 content:    UBL     | nand_spl    | u-boot code
 106             Header  | code        |
 107
 108 The NAND layout looks for example like this:
 109
 110 (Example for the cam_enc_4xx board with a NAND page size = 0x800, block
 111 size = 0x20000 and CONFIG_SYS_NROF_UBL_HEADER 5):
 112
 113 offset :    0x80000 | 0xa0000     | 0xa3000
 114 content:    UBL     | nand_spl    | u-boot code
 115             Header  | code        |
 116             ^         ^
 117             ^         0xa0000 = CONFIG_SYS_NROF_UBL_HEADER * 0x20000
 118             ^
 119             0x80000 = Block 4 * 0x20000
 120
 121 If the cpu starts in NAND boot mode, it checks the UBL descriptor
 122 starting with block 1 (page 0).  When a valid UBL signature is found,
 123 the corresponding block number (from 1 to 24) is written to the last 32
 124 bits of ARM internal memory (0x7ffc-0x8000).  This feature is provided
 125 as a basic debug mechanism.  If not found, it continues with block 2
 126 ... last possible block is 24
 127
 128 If a valid UBL descriptor is found, the UBL descriptor is read and
 129 processed.  The descriptor gives the information required for loading
 130 and control transfer to the nand_spl code.  The nand_spl code is then
 131 read and processed.
 132
 133 Once the user-specified start-up conditions are set, the RBL copies the
 134 nand_spl into ARM internal RAM, starting at address 0x0000: 0020.
 135                                                             ^^^^
 136
 137 The nand_spl code itself now does necessary intializations, and at least,
 138 copies the u-boot code from NAND into RAM, and jumps to it ...
 139
 140 ------------------------------------------------
 141 Author: Heiko Schocher <hs@denx.de>