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

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "E100BOOT 1"
 132 .TH E100BOOT 1 "2003-12-16" "perl v5.8.8" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 e100boot \- Network and serial port bootloader for the ETRAX100 CPU.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBe100boot\fR [\fB\-\-device\fR \fIdevicename\fR]
 138 [\fB\-\-file\fR \fIfilename\fR|\- \fIaddr\fR [\fIsize\fR]]
 139 [\fB\-\-flash\fR \fIram-source\fR \fIflash-offset\fR \fIsize\fR] [\fB\-\-pause\fR \fIiter\fR]
 140 [\fB\-\-memtest\fR \fIaddr\fR \fIaddr\fR] [\fB\-\-memclear\fR \fIaddr\fR \fIaddr\fR]
 141 [\fB\-\-memdump\fR \fIaddr\fR \fIaddr\fR] [\fB\-\-setreg\fR \fIaddr\fR|\fIregname\fR \fIval\fR]
 142 [\fB\-\-getreg\fR \fIaddr\fR|\fIregname\fR] [\fB\-\-verify\fR \fIaddr\fR \fIval\fR]
 143 [\fB\-\-label\fR \fIlabel\fR] [\fB\-\-loop\fR \fIaddr\fR \fIlabel\fR] [\fB\-\-5400\fR] [\fB\-\-5600\fR]
 144 [\fB\-\-testcard\fR] [\fB\-\-devboard\fR] [\fB\-\-testcardlx\fR] [\fB\-\-network\fR] [\fB\-\-serial\fR]
 145 [\fB\-\-baudrate\fR \fIbaudrate\fR] [\fB\-\-bootfile\fR \fIfile\fR] [\fB\-\-jump\fR \fIaddr\fR]
 146 [\fB\-\-tofiles\fR] [\fB\-\-cmdsonly\fR] [\fB\-\-images\fR] [\fB\-\-noleds\fR] [\fB\-\-help\fR]
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 This boot loader facilitates loading of files over the network or a
 150 serial port to an \s-1ETRAX100\s0. It can also be used for fairly extensive
 151 hardware debugging as you can read and write to any memory addresses,
 152 including the \s-1ETRAX100\s0 registers. You can also perform memory checks
 153 and dumps and copy data to flash memories.
 154 .PP
 155 The first packet (or the first 784 bytes in the case of serial boot)
 156 sent to Etrax100 is loaded into the cache. The code in this packet is
 157 executed and loads the rest of the boot loader into the cache. The
 158 cache is the only thing we can be sure of exists on all \s-1ETRAX100\s0
 159 products, so the boot loader is limited to the size of the cache,
 160 8KB. If further boot loading code is needed you have to set up
 161 external memory and load another boot loader into it, but this is
 162 rarely needed.
 163 .PP
 164 Two programs are involved in this boot loading, one is the program on
 165 your workstation that sends the packets to \s-1ETRAX100\s0, this is called
 166 the server boot loader or \s-1SBL\s0. The other program is the one in
 167 \&\s-1ETRAX100\s0 that receives packets from the \s-1SBL\s0 and acts upon the data
 168 therein, this is called the client boot loader or \s-1CBL\s0.
 169 .PP
 170 We don't want to edit and recompile the \s-1CBL\s0 each time we want to load
 171 level two to different parts of memory, like we do on different
 172 products. We also want to change things like the setup of external
 173 memory before we load data into it. To make the boot loading as
 174 flexible as possible and separate the \s-1CBL\s0 from level two we send a
 175 configuration packet to it. After this packet we load other files, if
 176 we want to.
 177 .PP
 178 The configuration packet can contain information to the \s-1CBL\s0 which lets
 179 you: initialize external memory, read and write to all \s-1ETRAX100\s0
 180 registers, read and write to any part of memory, load as many other
 181 files as you like to any part of memory you like, etc. The
 182 configuration packet is generated on the fly by the \s-1SBL\s0.
 183 .PP
 184 Since the \s-1CBL\s0 is unaware of which product it will be loaded on, it
 185 doesn't do product specific initialization like setting up the
 186 memory. This must be done with the configuration packet.
 187 .Sh "Debugging printout"
 188 .IX Subsection "Debugging printout"
 189 When doing network boot the debugging printout from the \s-1CBL\s0 in \s-1ETRAX\s0
 190 is transmitted back over the network and printed by e100boot. When
 191 doing serial boot that interface will be used. So in either case you
 192 will not need any other software or hardware to receive the debugging
 193 printout.
 194 .Sh "Creating binaries"
 195 .IX Subsection "Creating binaries"
 196 The files containing code to be loaded on the \s-1ETRAX100\s0 must be
 197 stripped using the standard \s-1GCC\s0 binutils.
 198 .Sh "How it works, things you don't want to know."
 199 .IX Subsection "How it works, things you don't want to know."
 200 ack, timeout bla, bla... \s-1RTFS\s0.
 201 .Sh "Compilation and code"
 202 .IX Subsection "Compilation and code"
 203 Noteworthy is that two separate \s-1ETRAX100\s0 binaries are created, one for
 204 network boot and one for serial boot. They actually contain exactly
 205 the same code, but linked in different order. This is because the code
 206 to load the rest of the bootloader over a specific interface must be
 207 contained in the first data sent to the \s-1ETRAX100\s0 and it is too
 208 difficult to cram the code for both interfaces in the beginning of the
 209 same binary. Hence two files.
 210 .PP
 211 Other stuff you don't want to know is that the cache is mapped from
 212 0x380000f0 to 0x380020f0. Code starts at the first address followed by
 213 data up to the symbol \fIEbss\fR. At the other end is the buffer for boot
 214 commands (addresses defined by \fI\s-1IO_BUF_START\s0\fR and \fI\s-1IO_BUF_END\s0\fR below
 215 which the stack lies and hopefully the stack and \fIEbss\fR will never
 216 meet...
 217 .PP
 218 The serial data is loaded from 0x380000f0 to 0x380003ff before
 219 execution starts.
 220 .SH "OPTIONS"
 221 .IX Header "OPTIONS"
 222 The options are done in the order specified on the command line, so
 223 you probably want to do any memory setup before loading a file to the
 224 memory, and you probably do not want to perform a memory test after
 225 you have loaded a file to that memory.
 226 .PP
 227 All addresses and sizes must be in hex with optional '0x' prefix, or a
 228 \&\s-1ETRAX100\s0 register name. Since the \fB\-\-setreg\fR and \fB\-\-getreg\fR options
 229 only can be performed on dword aligned dwords only the registers that
 230 conform to this can be named.
 231 .PP
 232 Note also that all addresses must be in uncached memory (bit 31 set),
 233 as the bootloader lies in the cache. If you access any uncached
 234 address during boot, the bootloader will be destroyed without warning.
 235 .PP
 236 It is also possible to specify an address as \fI+address\fR, in which
 237 case it is considered to be relative to \fI\s-1IO_BUF_START\s0\fR. This is
 238 especially useful in combination with the \fB\-\-loop\fR option below.
 239 .IP "\fB\-\-baudrate\fR \fIbaudrate\fR" 4
 240 .IX Item "--baudrate baudrate"
 241 Set baudrate for files loaded after the boot loader.
 242 .IP "\fB\-\-bootfile\fR \fIfilename\fR" 4
 243 .IX Item "--bootfile filename"
 244 Which boot image to send to \s-1ETRAX\s0 instead of the default ones.
 245 .IP "\fB\-\-cmdsonly\fR" 4
 246 .IX Item "--cmdsonly"
 247 Write the commands to file e100boot.cmds.
 248 .IP "\fB\-\-devboard\fR" 4
 249 .IX Item "--devboard"
 250 Sets registers for the developer board.
 251 .IP "\fB\-\-device\fR \fIdevicename\fR" 4
 252 .IX Item "--device devicename"
 253 Which device to send packets on. For network boot the default is
 254 eth0. For serial boot it is ttyS0.
 255 .IP "\fB\-\-file\fR \fIfilename\fR|\- \fIaddress\fR [\fIsize\fR]" 4
 256 .IX Item "--file filename|- address [size]"
 257 The file to load and the address to load it to. If file is loaded on
 258 stdin, specify filename '\-' followed by a size. Size need only be
 259 given in this case. You can load as many files as you want, each
 260 specified with a \fB\-\-file\fR.
 261 .IP "\fB\-\-flash\fR \fIram-source flash-offset size\fR" 4
 262 .IX Item "--flash ram-source flash-offset size"
 263 Copies the specified \s-1RAM\s0 area to the flash.
 264 .IP "\fB\-\-getreg\fR \fIaddress\fR|\fIregname\fR" 4
 265 .IX Item "--getreg address|regname"
 266 Print value of memory location. Must be uncached address.
 267 .IP "\fB\-\-help\fR" 4
 268 .IX Item "--help"
 269 Print the help information.
 270 .IP "\fB\-\-images\fR" 4
 271 .IX Item "--images"
 272 Print information about the internal boot images, then exit.
 273 .IP "\fB\-\-jump\fR \fIaddress\fR" 4
 274 .IX Item "--jump address"
 275 Jump to specified address.
 276 .IP "\fB\-\-label\fR \fIlabel\fR" 4
 277 .IX Item "--label label"
 278 Define a label to be used as target by the \fB\-\-loop\fR command. This
 279 command is only used by the \s-1SBL\s0 to calculate the address for the
 280 \&\fB\-\-loop\fR and does not take up any space in the configuration packet.
 281 .IP "\fB\-\-loop\fR \fIcheck-address label\fR" 4
 282 .IX Item "--loop check-address label"
 283 If the contents of check-address is nonzero it is decremented and the
 284 command parser continues parsing at the label.
 285 .Sp
 286 If no external memory is initialized yet it can be convenient to use
 287 an address in the area occupied by the configuration packet. Run
 288 e100boot with \fB\-\-help\fR to see which addresses the commands are stored
 289 at. The size of the commands are four bytes for each command plus four
 290 bytes per argument to the command.
 291 .IP "\fB\-\-memclear\fR \fIstart-address end-address\fR" 4
 292 .IX Item "--memclear start-address end-address"
 293 Clears the specified memory area.
 294 .IP "\fB\-\-memdump\fR \fIstart-address end-address\fR" 4
 295 .IX Item "--memdump start-address end-address"
 296 Prints the contents of the specified memory area.
 297 .IP "\fB\-\-memtest\fR \fIstart-address end-address\fR" 4
 298 .IX Item "--memtest start-address end-address"
 299 Does a fairly extensive test of the specified memory area. Not only
 300 catches defect memories but also catches things like wrong memory
 301 setups where memory addresses are mirrored onto each other.
 302 .IP "\fB\-\-network\fR" 4
 303 .IX Item "--network"
 304 Perform a network boot.
 305 .IP "\fB\-\-noleds\fR" 4
 306 .IX Item "--noleds"
 307 When using the internal images use a version that does not toggle
 308 general port \s-1PA\s0 or \s-1PB\s0 in \s-1ETRAX\s0 during the boot procedure.
 309 .IP "\fB\-\-pause\fR \fIiterations\fR" 4
 310 .IX Item "--pause iterations"
 311 How many \fIiterations\fR to do of an empty loop.
 312 .IP "\fB\-\-serial\fR" 4
 313 .IX Item "--serial"
 314 Do a serial boot.
 315 .IP "\fB\-\-setreg\fR \fIaddress\fR|\fIregname\fR \fIvalue\fR" 4
 316 .IX Item "--setreg address|regname value"
 317 Load dword to dword aligned memory location.
 318 .IP "\fB\-\-testcard\fR" 4
 319 .IX Item "--testcard"
 320 Configures the memories for the \s-1ETRAX\s0 100 testcard.
 321 .IP "\fB\-\-testcardlx\fR" 4
 322 .IX Item "--testcardlx"
 323 Configures the memories for the \s-1ETRAX100\s0 \s-1LX\s0 testcard.
 324 .IP "\fB\-\-tofiles\fR" 4
 325 .IX Item "--tofiles"
 326 Write packets to files e100boot.seq[0..]. Does not transmit the data.
 327 .IP "\fB\-\-verify\fR \fIaddress value\fR" 4
 328 .IX Item "--verify address value"
 329 Verify that memory contains dword. If not loader will stop. This is to
 330 avoid booting the wrong unit. If you have the units ethernet address
 331 in the flash memory you can check for that.
 332 .IP "\fB\-\-5400\fR" 4
 333 .IX Item "--5400"
 334 Sets R_WAITSTATES, R_DRAM_TIMING and R_DRAM_CONFIG for the 5400
 335 printserver.
 336 .IP "\fB\-\-5600\fR" 4
 337 .IX Item "--5600"
 338 Sets R_WAITSTATES, R_DRAM_TIMING and R_DRAM_CONFIG for the 5600
 339 printserver.
 340 .SH "EXAMPLES"
 341 .IX Header "EXAMPLES"
 342 If you have a stripped binary (file.ima) linked to 0x08000000 that you want
 343 to boot via the network, do this:
 344 .PP
 345 \&\fBe100boot \-\-file file.ima 88000000 \-\-jump 08000000\fR
 346 .PP
 347 Or something like this. Sets waitstates to zero and loads two files,
 348 the first from stdin:
 349 .PP
 350 \&\fBcat file.ima | e100boot \-\-memtest 88000000 8801ffff \-\-memclear
 351 88000000 8801ffff \-\-setreg b0000000 0 \-\-getreg b0000000 \-\-file \-
 352 88000000 a000 \-\-file file2.ima 88010000 \-\-memdump 88000000 880000ff
 353 \&\-\-jump 08000000\fR
 354 .PP
 355 Or this, enables 16 bit parallel port and flashes the led on \s-1PA0:\s0
 356 .PP
 357 \&\fBe100boot \-\-testcardlx \-\-setreg R_PORT_PA_SET 0x00000000 \-\-setreg
 358 R_GEN_CONFIG 0x80000004 \-\-setreg R_PAR0_CONFIG 0x00000200 \-\-setreg
 359 R_PORT_G_DATA 0x00000000 \-\-pause 0x02000000 \-\-setreg R_PORT_G_DATA
 360 0xffffffff \-\-pause 0x02000000 \-\-setreg R_PORT_G_DATA 0x00000000 \-\-loop
 361 0x38001e0b 0x38001e60\fR
 362 .PP
 363 Setup the memory, test the \s-1SRAM\s0, print the contents of the first 256
 364 bytes of \s-1SRAM\s0, clear \s-1SRAM\s0, test the \s-1DRAM\s0, print R_DMA_CH0_CMD, load a
 365 file to \s-1SRAM\s0, load another file to \s-1SRAM\s0, load file to \s-1DRAM\s0, jump to
 366 code in \s-1SRAM\s0.
 367 .PP
 368 \&\fBe100boot \-\-setreg b0000000 1000 \-\-setreg b0000008 00006543 \-\-setreg
 369 b000000c 12966060 \-\-memtest 88000000 80000 \-\-memdump 88000000 880000ff
 370 \&\-\-memclear 88000000 80000 \-\-memtest c0000000 400000 \-\-getreg b00001d0
 371 \&\-\-file file1.ima 88000000 \-\-file file2.ima 88010000 \-\-file file3.ima
 372 c0000000 \-\-jump 88000000\fR
 373 .PP
 374 Boot Linux on the testcard.
 375 .PP
 376 \&\fBe100boot \-\-setreg b0000000 1000 \-\-setreg b0000008 6557 \-\-setreg
 377 b000000c 1b988080 \-\-file timage c0000500 \-\-jump 40000500\fR
 378 .PP
 379 Booting over serial port and using labels to flash the leds on port
 380 \&\s-1PA\s0.
 381 .PP
 382 \&\fBe100boot \-\-serial \-\-device /dev/ttyS1 \-\-baudrate 9600 \-\-label first
 383 \&\-\-setreg 0x380020e0 00000001 \-\-setreg R_PORT_PA_SET 0x0000ff00 \-\-pause
 384 0x02000000 \-\-setreg R_PORT_PA_SET 0x0000ffff \-\-pause 0x02000000 \-\-loop
 385 0x380020e0 first\fR
 386 .SH "BUGS"
 387 .IX Header "BUGS"
 388 You're kidding, right? Check \s-1AUTHOR\s0 below. The only thing
 389 would be the hubris of the author, but that I consider a feature. If
 390 you find any other 'features' report them to
 391 technology@axis.com. Don't bother the author directly, he is busy
 392 playing PlayStation2.
 393 .SH "COPYING"
 394 .IX Header "COPYING"
 395 Copyright © 1996\-2002 Axis Communications \s-1AB\s0.
 396 .SH "AUTHOR"
 397 .IX Header "AUTHOR"
 398 Written by Ronny Ranerup.
 399 .SH "SEE ALSO"
 400 .IX Header "SEE ALSO"
 401 The fine source, which you can get at http://developer.axis.com.