target/linux/etrax-2.6/image/e100boot/src/doc/e100boot.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>e100boot - Network and serial port bootloader for the ETRAX100 CPU.</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12 <p><a name="__index__"></a></p>
  13 <!-- INDEX BEGIN -->
  14
  15 <ul>
  16
  17         <li><a href="#name">NAME</a></li>
  18         <li><a href="#synopsis">SYNOPSIS</a></li>
  19         <li><a href="#description">DESCRIPTION</a></li>
  20         <ul>
  21
  22                 <li><a href="#debugging_printout">Debugging printout</a></li>
  23                 <li><a href="#creating_binaries">Creating binaries</a></li>
  24                 <li><a href="#how_it_works__things_you_don_t_want_to_know_">How it works, things you don't want to know.</a></li>
  25                 <li><a href="#compilation_and_code">Compilation and code</a></li>
  26         </ul>
  27
  28         <li><a href="#options">OPTIONS</a></li>
  29         <li><a href="#examples">EXAMPLES</a></li>
  30         <li><a href="#bugs">BUGS</a></li>
  31         <li><a href="#copying">COPYING</a></li>
  32         <li><a href="#author">AUTHOR</a></li>
  33         <li><a href="#see_also">SEE ALSO</a></li>
  34 </ul>
  35 <!-- INDEX END -->
  36
  37 <hr />
  38 <p>
  39 </p>
  40 <h1><a name="name">NAME</a></h1>
  41 <p>e100boot - Network and serial port bootloader for the ETRAX100 CPU.</p>
  42 <p>
  43 </p>
  44 <hr />
  45 <h1><a name="synopsis">SYNOPSIS</a></h1>
  46 <p><strong>e100boot</strong> [<strong>--device</strong> <em>devicename</em>]
  47 [<strong>--file</strong> <em>filename</em>|- <em>addr</em> [<em>size</em>]]
  48 [<strong>--flash</strong> <em>ram-source</em> <em>flash-offset</em> <em>size</em>] [<strong>--pause</strong> <em>iter</em>]
  49 [<strong>--memtest</strong> <em>addr</em> <em>addr</em>] [<strong>--memclear</strong> <em>addr</em> <em>addr</em>]
  50 [<strong>--memdump</strong> <em>addr</em> <em>addr</em>] [<strong>--setreg</strong> <em>addr</em>|<em>regname</em> <em>val</em>]
  51 [<strong>--getreg</strong> <em>addr</em>|<em>regname</em>] [<strong>--verify</strong> <em>addr</em> <em>val</em>]
  52 [<strong>--label</strong> <em>label</em>] [<strong>--loop</strong> <em>addr</em> <em>label</em>] [<strong>--5400</strong>] [<strong>--5600</strong>]
  53 [<strong>--testcard</strong>] [<strong>--devboard</strong>] [<strong>--testcardlx</strong>] [<strong>--network</strong>] [<strong>--serial</strong>]
  54 [<strong>--baudrate</strong> <em>baudrate</em>] [<strong>--bootfile</strong> <em>file</em>] [<strong>--jump</strong> <em>addr</em>]
  55 [<strong>--tofiles</strong>] [<strong>--cmdsonly</strong>] [<strong>--images</strong>] [<strong>--noleds</strong>] [<strong>--help</strong>]</p>
  56 <p>
  57 </p>
  58 <hr />
  59 <h1><a name="description">DESCRIPTION</a></h1>
  60 <p>This boot loader facilitates loading of files over the network or a
  61 serial port to an ETRAX100. It can also be used for fairly extensive
  62 hardware debugging as you can read and write to any memory addresses,
  63 including the ETRAX100 registers. You can also perform memory checks
  64 and dumps and copy data to flash memories.</p>
  65 <p>The first packet (or the first 784 bytes in the case of serial boot)
  66 sent to Etrax100 is loaded into the cache. The code in this packet is
  67 executed and loads the rest of the boot loader into the cache. The
  68 cache is the only thing we can be sure of exists on all ETRAX100
  69 products, so the boot loader is limited to the size of the cache,
  70 8KB. If further boot loading code is needed you have to set up
  71 external memory and load another boot loader into it, but this is
  72 rarely needed.</p>
  73 <p>Two programs are involved in this boot loading, one is the program on
  74 your workstation that sends the packets to ETRAX100, this is called
  75 the server boot loader or SBL. The other program is the one in
  76 ETRAX100 that receives packets from the SBL and acts upon the data
  77 therein, this is called the client boot loader or CBL.</p>
  78 <p>We don't want to edit and recompile the CBL each time we want to load
  79 level two to different parts of memory, like we do on different
  80 products. We also want to change things like the setup of external
  81 memory before we load data into it. To make the boot loading as
  82 flexible as possible and separate the CBL from level two we send a
  83 configuration packet to it. After this packet we load other files, if
  84 we want to.</p>
  85 <p>The configuration packet can contain information to the CBL which lets
  86 you: initialize external memory, read and write to all ETRAX100
  87 registers, read and write to any part of memory, load as many other
  88 files as you like to any part of memory you like, etc. The
  89 configuration packet is generated on the fly by the SBL.</p>
  90 <p>Since the CBL is unaware of which product it will be loaded on, it
  91 doesn't do product specific initialization like setting up the
  92 memory. This must be done with the configuration packet.</p>
  93 <p>
  94 </p>
  95 <h2><a name="debugging_printout">Debugging printout</a></h2>
  96 <p>When doing network boot the debugging printout from the CBL in ETRAX
  97 is transmitted back over the network and printed by e100boot. When
  98 doing serial boot that interface will be used. So in either case you
  99 will not need any other software or hardware to receive the debugging
 100 printout.</p>
 101 <p>
 102 </p>
 103 <h2><a name="creating_binaries">Creating binaries</a></h2>
 104 <p>The files containing code to be loaded on the ETRAX100 must be
 105 stripped using the standard GCC binutils.</p>
 106 <p>
 107 </p>
 108 <h2><a name="how_it_works__things_you_don_t_want_to_know_">How it works, things you don't want to know.</a></h2>
 109 <p>ack, timeout bla, bla... RTFS.</p>
 110 <p>
 111 </p>
 112 <h2><a name="compilation_and_code">Compilation and code</a></h2>
 113 <p>Noteworthy is that two separate ETRAX100 binaries are created, one for
 114 network boot and one for serial boot. They actually contain exactly
 115 the same code, but linked in different order. This is because the code
 116 to load the rest of the bootloader over a specific interface must be
 117 contained in the first data sent to the ETRAX100 and it is too
 118 difficult to cram the code for both interfaces in the beginning of the
 119 same binary. Hence two files.</p>
 120 <p>Other stuff you don't want to know is that the cache is mapped from
 121 0x380000f0 to 0x380020f0. Code starts at the first address followed by
 122 data up to the symbol <em>Ebss</em>. At the other end is the buffer for boot
 123 commands (addresses defined by <em>IO_BUF_START</em> and <em>IO_BUF_END</em> below
 124 which the stack lies and hopefully the stack and <em>Ebss</em> will never
 125 meet...</p>
 126 <p>The serial data is loaded from 0x380000f0 to 0x380003ff before
 127 execution starts.</p>
 128 <p>
 129 </p>
 130 <hr />
 131 <h1><a name="options">OPTIONS</a></h1>
 132 <p>The options are done in the order specified on the command line, so
 133 you probably want to do any memory setup before loading a file to the
 134 memory, and you probably do not want to perform a memory test after
 135 you have loaded a file to that memory.</p>
 136 <p>All addresses and sizes must be in hex with optional '0x' prefix, or a
 137 ETRAX100 register name. Since the <strong>--setreg</strong> and <strong>--getreg</strong> options
 138 only can be performed on dword aligned dwords only the registers that
 139 conform to this can be named.</p>
 140 <p>Note also that all addresses must be in uncached memory (bit 31 set),
 141 as the bootloader lies in the cache. If you access any uncached
 142 address during boot, the bootloader will be destroyed without warning.</p>
 143 <p>It is also possible to specify an address as <em>+address</em>, in which
 144 case it is considered to be relative to <em>IO_BUF_START</em>. This is
 145 especially useful in combination with the <strong>--loop</strong> option below.</p>
 146 <dl>
 147 <dt><strong><a name="item__2d_2dbaudrate_baudrate"><strong>--baudrate</strong> <em>baudrate</em></a></strong>
 148
 149 <dd>
 150 <p>Set baudrate for files loaded after the boot loader.</p>
 151 </dd>
 152 </li>
 153 <dt><strong><a name="item__2d_2dbootfile_filename"><strong>--bootfile</strong> <em>filename</em></a></strong>
 154
 155 <dd>
 156 <p>Which boot image to send to ETRAX instead of the default ones.</p>
 157 </dd>
 158 </li>
 159 <dt><strong><a name="item__2d_2dcmdsonly"><strong>--cmdsonly</strong></a></strong>
 160
 161 <dd>
 162 <p>Write the commands to file e100boot.cmds.</p>
 163 </dd>
 164 </li>
 165 <dt><strong><a name="item__2d_2ddevboard"><strong>--devboard</strong></a></strong>
 166
 167 <dd>
 168 <p>Sets registers for the developer board.</p>
 169 </dd>
 170 </li>
 171 <dt><strong><a name="item__2d_2ddevice_devicename"><strong>--device</strong> <em>devicename</em></a></strong>
 172
 173 <dd>
 174 <p>Which device to send packets on. For network boot the default is
 175 eth0. For serial boot it is ttyS0.</p>
 176 </dd>
 177 </li>
 178 <dt><strong><a name="item__2d_2dfile_filename_7c_2d_address__5bsize_5d"><strong>--file</strong> <em>filename</em>|- <em>address</em> [<em>size</em>]</a></strong>
 179
 180 <dd>
 181 <p>The file to load and the address to load it to. If file is loaded on
 182 stdin, specify filename '-' followed by a size. Size need only be
 183 given in this case. You can load as many files as you want, each
 184 specified with a <strong>--file</strong>.</p>
 185 </dd>
 186 </li>
 187 <dt><strong><a name="item__2d_2dflash_ram_2dsource_flash_2doffset_size"><strong>--flash</strong> <em>ram-source flash-offset size</em></a></strong>
 188
 189 <dd>
 190 <p>Copies the specified RAM area to the flash.</p>
 191 </dd>
 192 </li>
 193 <dt><strong><a name="item__2d_2dgetreg_address_7cregname"><strong>--getreg</strong> <em>address</em>|<em>regname</em></a></strong>
 194
 195 <dd>
 196 <p>Print value of memory location. Must be uncached address.</p>
 197 </dd>
 198 </li>
 199 <dt><strong><a name="item__2d_2dhelp"><strong>--help</strong></a></strong>
 200
 201 <dd>
 202 <p>Print the help information.</p>
 203 </dd>
 204 </li>
 205 <dt><strong><a name="item__2d_2dimages"><strong>--images</strong></a></strong>
 206
 207 <dd>
 208 <p>Print information about the internal boot images, then exit.</p>
 209 </dd>
 210 </li>
 211 <dt><strong><a name="item__2d_2djump_address"><strong>--jump</strong> <em>address</em></a></strong>
 212
 213 <dd>
 214 <p>Jump to specified address.</p>
 215 </dd>
 216 </li>
 217 <dt><strong><a name="item__2d_2dlabel_label"><strong>--label</strong> <em>label</em></a></strong>
 218
 219 <dd>
 220 <p>Define a label to be used as target by the <strong>--loop</strong> command. This
 221 command is only used by the SBL to calculate the address for the
 222 <strong>--loop</strong> and does not take up any space in the configuration packet.</p>
 223 </dd>
 224 </li>
 225 <dt><strong><a name="item__2d_2dloop_check_2daddress_label"><strong>--loop</strong> <em>check-address label</em></a></strong>
 226
 227 <dd>
 228 <p>If the contents of check-address is nonzero it is decremented and the
 229 command parser continues parsing at the label.</p>
 230 </dd>
 231 <dd>
 232 <p>If no external memory is initialized yet it can be convenient to use
 233 an address in the area occupied by the configuration packet. Run
 234 e100boot with <strong>--help</strong> to see which addresses the commands are stored
 235 at. The size of the commands are four bytes for each command plus four
 236 bytes per argument to the command.</p>
 237 </dd>
 238 </li>
 239 <dt><strong><a name="item__2d_2dmemclear_start_2daddress_end_2daddress"><strong>--memclear</strong> <em>start-address end-address</em></a></strong>
 240
 241 <dd>
 242 <p>Clears the specified memory area.</p>
 243 </dd>
 244 </li>
 245 <dt><strong><a name="item__2d_2dmemdump_start_2daddress_end_2daddress"><strong>--memdump</strong> <em>start-address end-address</em></a></strong>
 246
 247 <dd>
 248 <p>Prints the contents of the specified memory area.</p>
 249 </dd>
 250 </li>
 251 <dt><strong><a name="item__2d_2dmemtest_start_2daddress_end_2daddress"><strong>--memtest</strong> <em>start-address end-address</em></a></strong>
 252
 253 <dd>
 254 <p>Does a fairly extensive test of the specified memory area. Not only
 255 catches defect memories but also catches things like wrong memory
 256 setups where memory addresses are mirrored onto each other.</p>
 257 </dd>
 258 </li>
 259 <dt><strong><a name="item__2d_2dnetwork"><strong>--network</strong></a></strong>
 260
 261 <dd>
 262 <p>Perform a network boot.</p>
 263 </dd>
 264 </li>
 265 <dt><strong><a name="item__2d_2dnoleds"><strong>--noleds</strong></a></strong>
 266
 267 <dd>
 268 <p>When using the internal images use a version that does not toggle
 269 general port PA or PB in ETRAX during the boot procedure.</p>
 270 </dd>
 271 </li>
 272 <dt><strong><a name="item__2d_2dpause_iterations"><strong>--pause</strong> <em>iterations</em></a></strong>
 273
 274 <dd>
 275 <p>How many <em>iterations</em> to do of an empty loop.</p>
 276 </dd>
 277 </li>
 278 <dt><strong><a name="item__2d_2dserial"><strong>--serial</strong></a></strong>
 279
 280 <dd>
 281 <p>Do a serial boot.</p>
 282 </dd>
 283 </li>
 284 <dt><strong><a name="item__2d_2dsetreg_address_7cregname_value"><strong>--setreg</strong> <em>address</em>|<em>regname</em> <em>value</em></a></strong>
 285
 286 <dd>
 287 <p>Load dword to dword aligned memory location.</p>
 288 </dd>
 289 </li>
 290 <dt><strong><a name="item__2d_2dtestcard"><strong>--testcard</strong></a></strong>
 291
 292 <dd>
 293 <p>Configures the memories for the ETRAX 100 testcard.</p>
 294 </dd>
 295 </li>
 296 <dt><strong><a name="item__2d_2dtestcardlx"><strong>--testcardlx</strong></a></strong>
 297
 298 <dd>
 299 <p>Configures the memories for the ETRAX100 LX testcard.</p>
 300 </dd>
 301 </li>
 302 <dt><strong><a name="item__2d_2dtofiles"><strong>--tofiles</strong></a></strong>
 303
 304 <dd>
 305 <p>Write packets to files e100boot.seq[0..]. Does not transmit the data.</p>
 306 </dd>
 307 </li>
 308 <dt><strong><a name="item__2d_2dverify_address_value"><strong>--verify</strong> <em>address value</em></a></strong>
 309
 310 <dd>
 311 <p>Verify that memory contains dword. If not loader will stop. This is to
 312 avoid booting the wrong unit. If you have the units ethernet address
 313 in the flash memory you can check for that.</p>
 314 </dd>
 315 </li>
 316 <dt><strong><a name="item__2d_2d5400"><strong>--5400</strong></a></strong>
 317
 318 <dd>
 319 <p>Sets R_WAITSTATES, R_DRAM_TIMING and R_DRAM_CONFIG for the 5400
 320 printserver.</p>
 321 </dd>
 322 </li>
 323 <dt><strong><a name="item__2d_2d5600"><strong>--5600</strong></a></strong>
 324
 325 <dd>
 326 <p>Sets R_WAITSTATES, R_DRAM_TIMING and R_DRAM_CONFIG for the 5600
 327 printserver.</p>
 328 </dd>
 329 </li>
 330 </dl>
 331 <p>
 332 </p>
 333 <hr />
 334 <h1><a name="examples">EXAMPLES</a></h1>
 335 <p>If you have a stripped binary (file.ima) linked to 0x08000000 that you want
 336 to boot via the network, do this:</p>
 337 <p><strong>e100boot --file file.ima 88000000 --jump 08000000</strong></p>
 338 <p>Or something like this. Sets waitstates to zero and loads two files,
 339 the first from stdin:</p>
 340 <p><strong>cat file.ima | e100boot --memtest 88000000 8801ffff --memclear
 341 88000000 8801ffff --setreg b0000000 0 --getreg b0000000 --file -
 342 88000000 a000 --file file2.ima 88010000 --memdump 88000000 880000ff
 343 --jump 08000000</strong></p>
 344 <p>Or this, enables 16 bit parallel port and flashes the led on PA0:</p>
 345 <p><strong>e100boot --testcardlx --setreg R_PORT_PA_SET 0x00000000 --setreg
 346 R_GEN_CONFIG 0x80000004 --setreg R_PAR0_CONFIG 0x00000200 --setreg
 347 R_PORT_G_DATA 0x00000000 --pause 0x02000000 --setreg R_PORT_G_DATA
 348 0xffffffff --pause 0x02000000 --setreg R_PORT_G_DATA 0x00000000 --loop
 349 0x38001e0b 0x38001e60</strong></p>
 350 <p>Setup the memory, test the SRAM, print the contents of the first 256
 351 bytes of SRAM, clear SRAM, test the DRAM, print R_DMA_CH0_CMD, load a
 352 file to SRAM, load another file to SRAM, load file to DRAM, jump to
 353 code in SRAM.</p>
 354 <p><strong>e100boot --setreg b0000000 1000 --setreg b0000008 00006543 --setreg
 355 b000000c 12966060 --memtest 88000000 80000 --memdump 88000000 880000ff
 356 --memclear 88000000 80000 --memtest c0000000 400000 --getreg b00001d0
 357 --file file1.ima 88000000 --file file2.ima 88010000 --file file3.ima
 358 c0000000 --jump 88000000</strong></p>
 359 <p>Boot Linux on the testcard.</p>
 360 <p><strong>e100boot --setreg b0000000 1000 --setreg b0000008 6557 --setreg
 361 b000000c 1b988080 --file timage c0000500 --jump 40000500</strong></p>
 362 <p>Booting over serial port and using labels to flash the leds on port
 363 PA.</p>
 364 <p><strong>e100boot --serial --device /dev/ttyS1 --baudrate 9600 --label first
 365 --setreg 0x380020e0 00000001 --setreg R_PORT_PA_SET 0x0000ff00 --pause
 366 0x02000000 --setreg R_PORT_PA_SET 0x0000ffff --pause 0x02000000 --loop
 367 0x380020e0 first</strong></p>
 368 <p>
 369 </p>
 370 <hr />
 371 <h1><a name="bugs">BUGS</a></h1>
 372 <p>You're kidding, right? Check <a href="#author">AUTHOR</a> below. The only thing
 373 would be the hubris of the author, but that I consider a feature. If
 374 you find any other 'features' report them to
 375 <a href="mailto:technology@axis.com.">technology@axis.com.</a> Don't bother the author directly, he is busy
 376 playing PlayStation2.</p>
 377 <p>
 378 </p>
 379 <hr />
 380 <h1><a name="copying">COPYING</a></h1>
 381 <p>Copyright © 1996-2002 Axis Communications AB.</p>
 382 <p>
 383 </p>
 384 <hr />
 385 <h1><a name="author">AUTHOR</a></h1>
 386 <p>Written by Ronny Ranerup.</p>
 387 <p>
 388 </p>
 389 <hr />
 390 <h1><a name="see_also">SEE ALSO</a></h1>
 391 <p>The fine source, which you can get at <a href="http://developer.axis.com.">http://developer.axis.com.</a></p>
 392
 393 </body>
 394
 395 </html>