yashi
commented
7 years ago I just write up a draft version of the spec while reading the source code. Note that I'm not an English native, so please bare with me. The file is written in org-mode and exported to ASCII. It's just easier for me to edit document and I don't have any intent to keep the format. Once the content is done, we can fix the style later, IMO. If anyone want the file in org, let me know.
I've added some comment in the doc with the form "[blah blah blah -- yashi]" I appreciate if you can give me some feed back.
Without further ado:
FORMAT OF I.MX LOADER CONFIGURATION FILE
A configuration file is basically divided up to three sections, name,
transfer type and works.
Comment
=======
Before jump in to the meat of the configuration file, let's first
introduce you comments. Any file should have at least one way to
write comments and this configuration file format have one. A comment
line starts with a sharp / a hash sign "#" and ends at the end of the
line. The format allows you to have any number of comment lines.
,----
| # This is a comment line.
| # It's just like Shell script, Ruby, or Python.
`----
Name
====
A configuration file start with a name. This does not do anything but
name the file. You can put any number of empty lines or comment lines
before the name line but the name line must be the first non-empty,
non-comment line in a configuration file.
Transfer Type
=============
Next non-empty, non-comment line following the Name line is Transfer
Type line. A transfer type line starts with either "hid" or "bulk".
This tells the i.MX Loader to use USB HID (Human Interface Device
class) or USB Bulk transfer.
Following "hid" or "bulk", you select a header type you are using.
The default is Image Vector Table (IVT) type. It is selected if you
omit this field. The other options you can select are "uboot_header"
or "old_header". "uboot_header" is for u-boot and the "old_header" is
for i.MX51. [I have no idea what "old_header" is. Needs some help.
-- yashi]
The following field is the max packet size for your transfer.
The next field is the address of a temporary location for your DCD
(Device Configuration Data).
The last field is to specify valid RAM areas. This field consist of
one or more of 'RAM start address' and 'RAM size' pair. If you
specify "0x90000000,512M,0x1ffe2000,0x16000", this means that the
first area starts at 0x90000000 and the size is 512 MB and the second
area starts at 0x1ffe2000 and the size is 0x16000 (88 KB).
Works
=====
All the above lines is more like meta info for things you really want
to do. The rest of the file has the definition of the things you
actually want to do. And those are called Work.
There are two different kinds of work you can write to a configuration
file. One is a memory work, which start with a colon ":" and the
other is a file work.
Memory Works
~~~~~~~~~~~~
A memory work is a simple line to tell your Boot ROM to read, write or
modify the system register / memory address. The read and the write
work corresponds to the command READ_REGISTER (0x0101) and
WRITE_REGISTER (0x0202) of Serial Download Protocol (SDP). The modify
is a combination of a read and a write.
All memory work starts with a colon ":" and an access method "read",
"write", or "modify".
"read" must be followed by an address in base 16 (a hex decimal
number).
"write" must be followed by two values, an address and a value, in
base 16.
"modify" must be followed by three values, an address, a value of
bit-fields you are interested in, and a value to logical OR. modify
can be think of bit change method. If you want to set the fist / LSB
bit and drop the third bit, but leave the second in the register at
0x42, you can write:
,----
| modify,0x42,0x5,0x1
`----
You can omit the prefix of "0x" for all values.
File Works
~~~~~~~~~~
A File work is a main job i.MX Loader is designed for; it downloads
the specified file to your target board.
Synopsis:
,----
| /path/to/file:[dcd,][clear_dcd,][clear_boot_data,][plug,][load nnn,][jump [nnn/header]]
`----
A file work line starts with a file name. Be care full that the file
name cannot have spaces (' '), hashes ('#'), colons (':'), commas
(',') nor some other non-printable characters. Stay with ASCII
character is your best bet.
A colon (':') is used to distinguish the file name and the following
options. All options are separated with a comma (',').
"dcd" tells imx_loader that the given file has a DCD entry. It will
parse the file header to find out DCD info and write DCD to the target
board.
"clear_dcd" tells imx_loader to clear DCD pointer in the header.
"clear_boot_data" tells imx_loader to clear "boot data" pointer in the
header. This option is valid only for i.MX53 image type.
"plug" tells imx_loader that the given file is a "Plugin image".
Please refer your Reference manual about "Plugin image".
"load" tells imx_loader to write the given file at the given address.
The address must be base 16, with or without the leading "0x" or "0X".
Without this option, imx_loader defaults to the first "RAM start
address" at the Transfer Type line + 0x03f00000. 0x03f00000 is hard
coded in the source file. If this is what you want, make sure to
specify your target address.
"jump" tells imx_loader to jump and start executing from there.
Target address can be specified with a hex decimal like "load" or with
a string "header". If you specify "header" then the actual jump
address is taken from the file header. [is there any difference
between "header" and "header2"? I just can't find it -- yashi]
I played arround a little bit with the "advanced" features of this tool. I tried to upload not only the u-boot to "debrick" or initially install the device. I also pushed more data to the target. This was possible with the help of the source and the commented lines in the config file for imx6 (mx6_usb_work.conf). ...
file:dcd,plug,load nnn,jump [nnn/header/header2]
jump nnn - header is after last downloaded word
entire file is loaded before jump, needs load nnn as well
i.e. file:load nnn,jump nnn
jump header - only length parameter is downloaded
header - uses existing header(error if none), but clears plug and dcd values unless plug also specified
header2 - uses 2nd header found(error if none)
plug - without jump uses header but clears plug flag to stop after plug execution
load nnn - load entire file to address
../u-boot-imx6/u-boot.bin:dcd,plug,jump header
...
What I figured out so far:
file:dcd,plug,load nnn,jump [nnn/header/header2]
dcd - this flags if the uploaded images contains a dcd or not. clear_dcd, - this skips the execution of the dcd. Maybe skip_dcd we have been a better name.
jump nnn - header is after last downloaded word
entire file is loaded before jump, needs load nnn as well
The jump header/header2 command makes only sense in combination of a dcd contained or maybe plug image. I am not sure what header2 exactly is.
plug - without jump uses header but clears plug flag to stop after plug execution
I am a little confused about this. I not had really gathered a jigsaw puzzle peaces in place.
load nnn - load entire file to address
For me this was only applicable to none dcd images. Otherewise the dcd was parsed and the image loaded to the containing address.
I got things working when I did the following steps:
I had some really trouble to boot a pure .bin image without dcd. I tried to upload the image with load and then execute a jump. The board was not booting. Then I remembered after execution of the ROM Code the CPU maybe is still in Thumb mode and I tried to prepend the image with a hack to switch from thum to arm what we are using during BDM debugging. But the board is still not booting. Maybe I'll debug this with BDI/PEEDI.