← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to roms/u-boot/doc/README.mxsimage

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
roms/u-boot/doc/README.mxsimage
 
1
Freescale i.MX233/i.MX28 SB image generator via mkimage
 
2
=======================================================
 
3
 
 
4
This tool allows user to produce SB BootStream encrypted with a zero key.
 
5
Such a BootStream is then bootable on i.MX23/i.MX28.
 
6
 
 
7
Usage -- producing image:
 
8
=========================
 
9
The mxsimage tool is targeted to be a simple replacement for the elftosb2 .
 
10
To generate an image, write an image configuration file and run:
 
11
 
 
12
 mkimage -A arm -O u-boot -T mxsimage -n <path to configuration file> \
 
13
         <output bootstream file>
 
14
 
 
15
The output bootstream file is usually using the .sb file extension. Note
 
16
that the example configuration files for producing bootable BootStream with
 
17
the U-Boot bootloader can be found under arch/arm/boot/cpu/arm926ejs/mxs/
 
18
directory. See the following files:
 
19
 
 
20
 mxsimage.mx23.cfg -- This is an example configuration for i.MX23
 
21
 mxsimage.mx28.cfg -- This is an example configuration for i.MX28
 
22
 
 
23
Each configuration file uses very simple instruction semantics and a few
 
24
additional rules have to be followed so that a useful image can be produced.
 
25
These semantics and rules will be outlined now.
 
26
 
 
27
- Each line of the configuration file contains exactly one instruction.
 
28
- Every numeric value must be encoded in hexadecimal and in format 0xabcdef12 .
 
29
- The configuration file is a concatenation of blocks called "sections" and
 
30
  optionally "DCD blocks" (see below).
 
31
  - Each "section" is started by the "SECTION" instruction.
 
32
  - The "SECTION" instruction has the following semantics:
 
33
 
 
34
      SECTION u32_section_number [BOOTABLE]
 
35
      - u32_section_number :: User-selected ID of the section
 
36
      - BOOTABLE           :: Sets the section as bootable
 
37
 
 
38
  - A bootable section is one from which the BootROM starts executing
 
39
    subsequent instructions or code. Exactly one section must be selected
 
40
    as bootable, usually the one containing the instructions and data to
 
41
    load the bootloader.
 
42
 
 
43
  - A "SECTION" must be immediatelly followed by a "TAG" instruction.
 
44
  - The "TAG" instruction has the following semantics:
 
45
 
 
46
      TAG [LAST]
 
47
      - LAST               :: Flag denoting the last section in the file
 
48
 
 
49
  - After a "TAG" unstruction, any of the following instructions may follow
 
50
    in any order and any quantity:
 
51
 
 
52
      NOOP
 
53
      - This instruction does nothing
 
54
 
 
55
      LOAD     u32_address string_filename
 
56
      - Instructs the BootROM to load file pointed by "string_filename" onto
 
57
        address "u32_address".
 
58
 
 
59
      LOAD IVT u32_address u32_IVT_entry_point
 
60
      - Crafts and loads IVT onto address "u32_address" with the entry point
 
61
        of u32_IVT_entry_point.
 
62
      - i.MX28-specific instruction!
 
63
 
 
64
      LOAD DCD u32_address u32_DCD_block_ID
 
65
      - Loads the DCD block with ID "u32_DCD_block_ID" onto address
 
66
        "u32_address" and executes the contents of this DCD block
 
67
      - i.MX28-specific instruction!
 
68
 
 
69
      FILL u32_address u32_pattern u32_length
 
70
      - Starts to write memory from addres "u32_address" with a pattern
 
71
        specified by "u32_pattern". Writes exactly "u32_length" bytes of the
 
72
        pattern.
 
73
 
 
74
      JUMP [HAB] u32_address [u32_r0_arg]
 
75
      - Jumps onto memory address specified by "u32_address" by setting this
 
76
        address in PT. The BootROM will pass the "u32_r0_arg" value in ARM
 
77
        register "r0" to the executed code if this option is specified.
 
78
        Otherwise, ARM register "r0" will default to value 0x00000000. The
 
79
        optional "HAB" flag is i.MX28-specific flag turning on the HAB boot.
 
80
 
 
81
      CALL [HAB] u32_address [u32_r0_arg]
 
82
      - See JUMP instruction above, as the operation is exactly the same with
 
83
        one difference. The CALL instruction does allow returning into the
 
84
        BootROM from the executed code. U-Boot makes use of this in it's SPL
 
85
        code.
 
86
 
 
87
      MODE string_mode
 
88
      - Restart the CPU and start booting from device specified by the
 
89
        "string_mode" argument. The "string_mode" differs for each CPU
 
90
        and can be:
 
91
         i.MX23, string_mode = USB/I2C/SPI1_FLASH/SPI2_FLASH/NAND_BCH
 
92
                               JTAG/SPI3_EEPROM/SD_SSP0/SD_SSP1
 
93
         i.MX28, string_mode = USB/I2C/SPI2_FLASH/SPI3_FLASH/NAND_BCH
 
94
                               JTAG/SPI2_EEPROM/SD_SSP0/SD_SSP1
 
95
 
 
96
  - An optional "DCD" blocks can be added at the begining of the configuration
 
97
    file. Note that the DCD is only supported on i.MX28.
 
98
    - The DCD blocks must be inserted before the first "section" in the
 
99
      configuration file.
 
100
    - The DCD block has the following semantics:
 
101
 
 
102
        DCD u32_DCD_block_ID
 
103
        - u32_DCD_block_ID      :: The ID number of the DCD block, must match
 
104
                                   the ID number used by "LOAD DCD" instruction.
 
105
 
 
106
    - The DCD block must be followed by one of the following instructions. All
 
107
      of the instructions operate either on 1, 2 or 4 bytes. This is selected by
 
108
      the 'n' suffix of the instruction:
 
109
 
 
110
        WRITE.n u32_address u32_value
 
111
        - Write the "u32_value" to the "u32_address" address.
 
112
 
 
113
        ORR.n u32_address u32_value
 
114
        - Read the "u32_address", perform a bitwise-OR with the "u32_value" and
 
115
          write the result back to "u32_address".
 
116
 
 
117
        ANDC.n u32_address u32_value
 
118
        - Read the "u32_address", perform a bitwise-AND with the complement of
 
119
          "u32_value" and write the result back to "u32_address".
 
120
 
 
121
        EQZ.n u32_address u32_count
 
122
        - Read the "u32_address" at most "u32_count" times and test if the value
 
123
          read is zero. If it is, break the loop earlier.
 
124
 
 
125
        NEZ.n u32_address u32_count
 
126
        - Read the "u32_address" at most "u32_count" times and test if the value
 
127
          read is non-zero. If it is, break the loop earlier.
 
128
 
 
129
        EQ.n u32_address u32_mask
 
130
        - Read the "u32_address" in a loop and test if the result masked with
 
131
          "u32_mask" equals the "u32_mask". If the values are equal, break the
 
132
          reading loop.
 
133
 
 
134
        NEQ.n u32_address u32_mask
 
135
        - Read the "u32_address" in a loop and test if the result masked with
 
136
          "u32_mask" does not equal the "u32_mask". If the values are not equal,
 
137
          break the reading loop.
 
138
 
 
139
        NOOP
 
140
        - This instruction does nothing.
 
141
 
 
142
- If the verbose output from the BootROM is enabled, the BootROM will produce a
 
143
  letter on the Debug UART for each instruction it started processing. Here is a
 
144
  mapping between the above instructions and the BootROM verbose output:
 
145
 
 
146
   H -- SB Image header loaded
 
147
   T -- TAG instruction
 
148
   N -- NOOP instruction
 
149
   L -- LOAD instruction
 
150
   F -- FILL instruction
 
151
   J -- JUMP instruction
 
152
   C -- CALL instruction
 
153
   M -- MODE instruction
 
154
 
 
155
Usage -- verifying image:
 
156
=========================
 
157
 
 
158
The mxsimage can also verify and dump contents of an image. Use the following
 
159
syntax to verify and dump contents of an image:
 
160
 
 
161
 mkimage -l <input bootstream file>
 
162
 
 
163
This will output all the information from the SB image header and all the
 
164
instructions contained in the SB image. It will also check if the various
 
165
checksums in the SB image are correct.