Missing documentation of extra features

[christianege]

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:

1. Load a dcd enabled image to the target. This will setup the DDR-RAM and upload the image. For the first Image no jump is allowed.
2. Now mostly any image can be uploaded to the target. "But keep in mind that u-boot" writes to some portions of the memory to detect the size of the memory while booting.
3. After everything is in place a image which can be execute can be loaded into RAM. For this image I had to use the command "clear_dcd". Otherwise the dcd is executed a second time which will cause a system which is noct booting.

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.

[yashi]

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]