summaryrefslogtreecommitdiffstats
path: root/Documentation/boards/imx.rst
blob: 35a180b0ddcf9a2b01b14265d148625673bd71f8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
Freescale i.MX
==============

Freescale i.MX is traditionally very well supported under barebox.
Depending on the SoC, there are different Boot Modes supported. Older
SoCs up to i.MX31 support only the external Boot Mode. Newer SoCs
can be configured for internal or external Boot Mode with the internal
boot mode being the more popular mode. The i.MX23 and i.MX28, also
known as i.MXs, are special. These SoCs have a completely different
boot mechanism, see :doc:`mxs` instead.

Internal Boot Mode
------------------

The Internal Boot Mode is supported on:

* i.MX25
* i.MX35
* i.MX50
* i.MX51
* i.MX53
* i.MX6
* i.MX7
* i.MX8MQ

With the Internal Boot Mode, the images contain a header which describes
where the binary shall be loaded and started. These headers also contain
a so-called DCD table which consists of register/value pairs. These are
executed by the Boot ROM and are used to configure the SDRAM. In barebox,
the i.MX images are generated with the ``scripts/imx/imx-image`` tool.
Normally it's not necessary to call this tool manually, it is executed
automatically at the end of the build process.

The images generated by the build process can be directly written to an
SD card:

.. code-block:: sh

  # with Multi Image support:
  cat images/barebox-freescale-imx51-babbage.img > /dev/sdd
  # otherwise:
  cat barebox-flash-image > /dev/sdd

The above will overwrite the MBR (and consequently the partition table)
on the destination SD card. To preserve the MBR while writing the rest
of the image to the card, use::

  dd if=images/barebox-freescale-imx51-babbage.img of=/dev/sdd bs=1024 skip=1 seek=1

NOTE: MaskROM on i.MX8 expects image to start at +33KiB mark, so the
following command has to be used instead:

  dd if=images/barebox-nxp-imx8mq-evk.img of=/dev/sdd bs=1024 skip=33 seek=33

Or, in case of NAND:

  dd if=images/barebox-nxp-imx8mq-evk.img of=/dev/nand bs=1024 skip=33 seek=1

The images can also always be started second stage::

  bootm /mnt/tftp/barebox-freescale-imx51-babbage.img

Using GPT on i.MX
^^^^^^^^^^^^^^^^^

For i.MX SoCs that place vendor specific header at +1KiB mark of a
boot medium, special care needs to be taken when parition that medium
with GPT. In order to make room for i.MX boot header GPT Partition
Entry Array needs to be moved from its typical location, LBA 2, to an
offset past vendor specific information. One way to do this would be
to use ``-j`` or ``--adjust-main-table`` option of ``sgdisk``. For
example, the following sequence:

  sgdisk -Z <block device>
  sgdisk -o -j 2048 -n 1:8192:+100M <block device>

will create a single GPT partition starting at LBA 8192 and would
place Partition Entry Array starting at LBA 2048 which should leave
enough room for Barebox/i.MX boot header. Once that is done ``dd``
command above can be used to place Barebox on the same medium.

Information about the ``imx-image`` tool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The imx-image tool can be used to generate imximages from raw binaries.
It requires an configuration file describing how to setup the SDRAM on
a particular board. This mainly consists of a poke table. The recognized
options in this file are:

Header:

+----------------+--------------------------------------------------------------+
| soc <soctype>  |soctype can be one of imx35, imx51, imx53, imx6, imx7, vf610, |
|                |                             imx8mq                           |
+----------------+--------------------------------------------------------------+
| loadaddr <adr> |     The address the binary is uploaded to                    |
+----------------+--------------------------------------------------------------+
| dcdofs <ofs>   | The offset of the image header in the image. This should be: |
|                | * ``0x400``:  MMC/SD, NAND, serial ROM, PATA, SATA           |
|                | * ``0x1000``: NOR Flash                                      |
|                | * ``0x100``: OneNAND                                         |
+----------------+--------------------------------------------------------------+

Memory manipulation:

+------------------------------------+-----------------------------------------+
| wm 8 <addr> <value>                | write <value> into byte <addr>          |
+------------------------------------+-----------------------------------------+
| wm 16 <addr> <value>               | write <value> into short <addr>         |
+------------------------------------+-----------------------------------------+
| wm 32 <addr> <value>               | write <value> into word <addr>          |
+------------------------------------+-----------------------------------------+
| set_bits <width> <addr> <value>    | set set bits in <value> in <addr>       |
+------------------------------------+-----------------------------------------+
| clear_bits <width> <addr> <value>  | clear set bits in <value> in <addr>     |
+------------------------------------+-----------------------------------------+
| nop                                | do nothing (just waste time)            |
+------------------------------------+-----------------------------------------+

<width> can be of 8, 16 or 32.

Checking conditions:

+------------------------------------+-----------------------------------------+
| check <width> <cond> <addr> <mask> | Poll until condition becomes true.      |
|                                    | with <cond> being one of:               |
|                                    | * ``until_all_bits_clear``              |
|                                    | * ``until_all_bits_set``                |
|                                    | * ``until_any_bit_clear``               |
|                                    | * ``until_any_bit_set``                 |
+------------------------------------+-----------------------------------------+

Some notes about the mentioned *conditions*.

 - ``until_all_bits_clear`` waits until ``(*addr & mask) == 0`` is true
 - ``until_all_bits_set`` waits until ``(*addr & mask) == mask`` is true
 - ``until_any_bit_clear`` waits until ``(*addr & mask) != mask`` is true
 - ``until_any_bit_set`` waits until ``(*addr & mask) != 0`` is true.

USB Boot
^^^^^^^^

Most boards can be explicitly configured for USB Boot Mode or fall back
to USB Boot when no other medium can be found. The barebox repository
contains a USB upload tool. As it depends on the libusb development headers,
it is not built by default. Enable it explicitly in ``make menuconfig``
and install the libusb development package. On Debian, this can be done
with ``apt-get install libusb-dev``. After compilation, the tool can be used
with only the image name as argument:

.. code-block:: sh

  scripts/imx/imx-usb-loader images/barebox-freescale-imx51-babbage.img

External Boot Mode
------------------

The External Boot Mode is supported by the older i.MX SoCs:

* i.MX1
* i.MX21
* i.MX27
* i.MX31
* i.MX35

The External Boot Mode supports booting only from NOR and NAND flash. On NOR
flash, the binary is started directly on its physical address in memory. Booting
from NAND flash is more complicated. The NAND flash controller copies the first
2kb of the image to the NAND Controller's internal SRAM. This initial binary
portion then has to:

* Set up the SDRAM
* Copy the initial binary to SDRAM to make the internal SRAM in the NAND flash
  controller free for use for the controller
* Copy the whole barebox image to SDRAM
* Start the image

It is possible to write the image directly to NAND. However, since NAND flash
can have bad blocks which must be skipped during writing the image and also
by the initial loader, it is recommended to use the :ref:`command_barebox_update`
command for writing to NAND flash.

i.MX boards
-----------

Not all supported boards have a description here. Many newer boards also do
not have individual defconfig files, they are covered by ``imx_v7_defconfig``
or ``imx_defconfig`` instead.

.. toctree::
  :glob:
  :maxdepth: 1

  imx/*