packages/redboot/v2_0/doc/redboot_cmds.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     redboot_cmds.sgml                                           -->
   6 <!--                                                                 -->
   7 <!--     Documentation for RedBoot Commands                          -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <chapter id="RedBoot-Commands-and-Examples">
  33 <title>RedBoot Commands and Examples</title>
  34 <sect1>
  35 <title>Introduction</title>
  36 <para><indexterm><primary>RedBoot</primary><secondary>commands and examples
  37 </secondary></indexterm><indexterm><primary>commands and examples</primary>
  38 </indexterm>RedBoot provides three basic classes of commands:    <itemizedlist>
  39 <listitem><para>Program loading and execution</para>
  40 </listitem>
  41 <listitem><para>Flash image and configuration management</para>
  42 </listitem>
  43 <listitem><para>Miscellaneous commands</para>
  44 </listitem>
  45 </itemizedlist>Given the extensible and configurable nature of eCos and RedBoot,
  46 there may be extended or enhanced sets of commands available.</para>
  47 <para>The basic format for commands is:    <programlisting>RedBoot> COMMAND [-S]... [-s val]... operand
  48 </programlisting>
  49 </para>
  50 <para>
  51 Commands may require additional information beyond the basic
  52 command name. In most cases this additional information is optional, with
  53 suitable default values provided if they are not present.
  54
  55       <informaltable frame="all">
  56         <tgroup cols="3" colsep="1" rowsep="1" align="left">
  57           <colspec colname="c1">
  58           <colspec colname="c2">
  59           <colspec colname="c3">
  60           <thead>
  61             <row>
  62               <entry>Format</entry>
  63               <entry>Description</entry>
  64               <entry>Example</entry>
  65             </row>
  66           </thead>
  67           <tbody>
  68             <row>
  69               <entry>-S</entry>
  70               <entry>A boolean switch; the behavior of the command will differ, depending
  71 on the presence of the switch.  In this example, the <userinput>-f</userinput> switch
  72 indicates that a complete initialization of the FIS data should be performed.
  73 There may be many such switches available for any given command and any or all of
  74 them may be present, in any order.</entry>
  75               <entry>
  76                 <computeroutput> RedBoot> <userinput>fis init -f</userinput></computeroutput>
  77               </entry>
  78             </row>
  79             <row>
  80               <entry>-s<replaceable> val</replaceable></entry>
  81               <entry>A qualified value; the letter "s" introduces the value, qualifying it's meaning.  In the
  82 example, <userinput>-b 0x100000</userinput> specifies where the memory dump should begin.
  83 There may be many such switches available for any given command and any or all of
  84 them may be present, in any order.
  85 </entry>
  86               <entry>
  87                 <computeroutput> RedBoot> <userinput>dump -b 0x100000 -l 0x20</userinput></computeroutput>
  88               </entry>
  89             </row>
  90             <row>
  91               <entry><replaceable> operand</replaceable></entry>
  92               <entry>A simple value; some commands require a single parameter for which an additional
  93 <userinput>-X</userinput> switch would be redundant.  In the example, <userinput>JFFS2</userinput>
  94 is the name of a flash image.  The image name is always required, thus is no need to qualify it with
  95 a switch.
  96 Note that any un-qualified operand must always appear at the end of the command.</entry>
  97               <entry>
  98                 <computeroutput> RedBoot> <userinput>fis delete JFFS2</userinput></computeroutput>
  99               </entry>
 100             </row>
 101           </tbody>
 102         </tgroup>
 103       </informaltable>
 104
 105 </para>
 106 <para>The list of available commands, and their syntax, can be obtained by
 107 typing <command>help</command> at the command line:
 108 <screen>
 109 RedBoot> <userinput>help</userinput>
 110 Manage aliases kept in FLASH memory
 111       alias name [value]
 112 Set/Query the system console baud rate
 113       baudrate [-b &lt;rate>]
 114 Manage machine caches
 115       cache [ON | OFF]
 116 Display/switch console channel
 117       channel [-1|&lt;channel number>]
 118 Display disk partitions
 119       disks
 120 Display (hex dump) a range of memory
 121       dump -b &lt;location> [-l &lt;length>] [-s]
 122 Manage flash images
 123       fis {cmds}
 124 Manage configuration kept in FLASH memory
 125       fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
 126 Execute code at a location
 127       go [-w &lt;timeout>] [-c] [-n] [entry]
 128 Help about help?
 129       help [&lt;topic>]
 130 Set/change IP addresses
 131       ip_address [-l &lt;local_ip_address>[/&lt;mask_length>]] [-h &lt;server_address>]
 132 Load a file
 133       load [-r] [-v] [-d] [-c &lt;channel>] [-h &lt;host>] [-m {TFTP | HTTP | {x|y}MODEM | disk}]
 134       [-b &lt;base_address>] &lt;file_name>
 135 Network connectivity test
 136       ping [-v] [-n &lt;count>] [-t &lt;timeout>] [-i &lt;IP_addr]
 137       -h &lt;host>
 138 Reset the system
 139       reset
 140 Display RedBoot version information
 141       version
 142 Display (hex dump) a range of memory
 143       x -b &lt;location> [-l &lt;length>] [-s]
 144 </screen>
 145 </para>
 146 <para>
 147 Commands can be abbreviated to their shortest
 148 unique string. Thus in the list above, <command>d,du,dum</command>
 149 and dump are all valid for the <command>dump</command> command. The <command>fconfig</command>
 150 command can be abbreviated <command>fc</command>, but
 151 <command>f</command> would be ambiguous with <command>fis</command>.
 152 </para>
 153 <para>There is one additional, special command. When RedBoot detects '$' or '+'
 154 (unless escaped via '\') in a command, it switches to GDB protocol mode. At this
 155 point, the eCos GDB stubs take over, allowing connections from a GDB host.
 156 The only way to get back to RedBoot from GDB mode is to restart the platform.
 157 </para>
 158 <note><title>NOTE</title>
 159 <para>
 160 Multiple commands may be entered on a single line, separated by the semi-colon &ldquo;;&rdquo; character.
 161 </para>
 162 </note>
 163 <para>The standard RedBoot command set is structured around the bootstrap
 164 environment. These commands are designed to be simple to use and remember,
 165 while still providing sufficient power and flexibility to be useful. No attempt
 166 has been made to render RedBoot as the end-all product. As such, things such
 167 as the debug environment are left to other modules, such as GDB stubs, which
 168 are typically included in RedBoot. </para>
 169 <para>The command set may be also be extended on a platform basis. </para>
 170 </sect1>
 171
 172 <sect1 id="common-commands">
 173 <title>Common Commands</title>
 174 <para>
 175   <indexterm><primary>commands</primary><secondary>common</secondary>
 176   </indexterm>
 177 </para>
 178
 179 <!-- ******** alias *************************************************** -->
 180   <refentry id="alias-command">
 181     <refnamediv>
 182       <refname>alias</refname>
 183       <refpurpose>Manipulate command line aliases</refpurpose>
 184     </refnamediv>
 185     <refsynopsisdiv>
 186       <cmdsynopsis>
 187         <command>alias</command>
 188         <arg choice="req"><replaceable> name</replaceable></arg>
 189         <arg><replaceable> value</replaceable></arg>
 190       </cmdsynopsis>
 191     </refsynopsisdiv>
 192     <refsect1>
 193       <title>Arguments</title>
 194       <informaltable frame="all">
 195         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 196           <colspec colname="c1">
 197           <colspec colname="c2">
 198           <colspec colname="c3">
 199           <colspec colname="c4">
 200           <thead>
 201             <row>
 202               <entry>Name</entry>
 203               <entry>Type</entry>
 204               <entry>Description</entry>
 205               <entry>Default</entry>
 206             </row>
 207           </thead>
 208           <tbody>
 209             <row>
 210               <entry><replaceable>name</replaceable></entry>
 211               <entry>Name</entry>
 212               <entry>The name for this alias.</entry>
 213               <entry><emphasis>none</emphasis></entry>
 214             </row>
 215             <row>
 216               <entry><replaceable>value</replaceable></entry>
 217               <entry>String</entry>
 218               <entry>Replacement value for the alias.</entry>
 219               <entry><emphasis>none</emphasis></entry>
 220             </row>
 221           </tbody>
 222         </tgroup>
 223       </informaltable>
 224     </refsect1>
 225     <refsect1>
 226       <title>Description</title>
 227       <para>The <command>alias</command> command is used to maintain simple command
 228 line aliases.  These aliases are shorthand for longer expressions.
 229 When the pattern %{name} appears in a command line, including in a script,
 230 the corresponding value will be substituted.  Aliases may be nested.
 231       </para>
 232       <para>
 233 If no value is provided, then the current value of the alias is displayed.
 234       </para>
 235       <para>
 236 If the system supports non-volatile configuration data via the
 237 <command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
 238 then the value will be saved and used when the system is reset.
 239       </para>
 240     </refsect1>
 241     <refsect1>
 242       <title>Examples</title>
 243       <para>
 244 Set an alias.
 245 <screen>
 246 RedBoot> <userinput>alias joe "This is Joe"</userinput>
 247 Update RedBoot non-volatile configuration - continue (y/n)? n
 248 </screen>
 249 </para>
 250 <para>
 251 Display an alias.
 252 <screen>
 253 RedBoot> <userinput>alias joe</userinput>
 254 'joe' = 'This is Joe'
 255 </screen>
 256 </para>
 257 <para>
 258 Use an alias.  Note: the <command>"="</command> command simply echoes the command to to console.
 259 <screen>
 260 RedBoot> <userinput>= %{joe}</userinput>
 261 This is Joe
 262 </screen>
 263 </para>
 264 <para>
 265 Aliases can be nested.
 266 <screen>
 267 RedBoot> <userinput>alias frank "Who are you? %{joe}"</userinput>
 268 Update RedBoot non-volatile configuration - continue (y/n)? n
 269 RedBoot> <userinput>= %{frank}</userinput>
 270 Who are you? This is Joe
 271 </screen>
 272 </para>
 273 <para>
 274 Notice how the value of %{frank} changes when %{joe} is changed since
 275 the value of %{joe} is not evaluated until %{frank} is evaluated.
 276 <screen>
 277 RedBoot> <userinput>alias joe "This is now Josephine"</userinput>
 278 Update RedBoot non-volatile configuration - continue (y/n)? n
 279 RedBoot> <userinput>= %{frank}</userinput>
 280 Who are you? This is now Josephine
 281 </screen>
 282       </para>
 283     </refsect1>
 284   </refentry>
 285
 286 <!-- ******** baudrate *************************************************** -->
 287   <refentry id="baudrate-command">
 288     <refnamediv>
 289       <refname>baudrate</refname>
 290       <refpurpose>Set the baud rate for the system serial console</refpurpose>
 291     </refnamediv>
 292     <refsynopsisdiv>
 293       <cmdsynopsis>
 294         <command>baudrate</command>
 295         <arg>-b<replaceable> rate</replaceable></arg>
 296       </cmdsynopsis>
 297     </refsynopsisdiv>
 298     <refsect1>
 299       <title>Arguments</title>
 300       <informaltable frame="all">
 301         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 302           <colspec colname="c1">
 303           <colspec colname="c2">
 304           <colspec colname="c3">
 305           <colspec colname="c4">
 306           <thead>
 307             <row>
 308               <entry>Name</entry>
 309               <entry>Type</entry>
 310               <entry>Description</entry>
 311               <entry>Default</entry>
 312             </row>
 313           </thead>
 314           <tbody>
 315             <row>
 316               <entry>-b <replaceable>rate</replaceable></entry>
 317               <entry>Number</entry>
 318               <entry>The baud rate to use for the serial console.</entry>
 319               <entry><emphasis>none</emphasis></entry>
 320             </row>
 321           </tbody>
 322         </tgroup>
 323       </informaltable>
 324     </refsect1>
 325     <refsect1>
 326       <title>Description</title>
 327       <para>The <command>baudrate</command> command sets the baud rate for the system serial console.
 328       </para>
 329       <para>
 330 If no value is provided, then the current value of the console baud rate is displayed.
 331       </para>
 332       <para>
 333 If the system supports non-volatile configuration data via the
 334 <command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
 335 then the value will be saved and used when the system is reset.
 336       </para>
 337     </refsect1>
 338     <refsect1>
 339       <title>Examples</title>
 340       <para>
 341 Show the current baud rate.
 342 <screen>
 343 RedBoot> <userinput>baudrate</userinput>
 344 Baud rate = 38400
 345 </screen>
 346 </para>
 347 <para>
 348 Change the console baud rate.  In order to make this operation safer,
 349 there will be a slight pause after the
 350 first message to give you time to change to the new baud rate.
 351 If it doesn't work, or a less than affirmative answer is given to the
 352 "continue" prompt, then the baud rate will revert to the current value.
 353 Only after the baud rate has been firmly established will <emphasis>RedBoot</emphasis>
 354 give you an opportunity to save the value in persistent storage.
 355 <screen>
 356 RedBoot> <userinput>baudrate -b 57600</userinput>
 357 Baud rate will be changed to 57600 - update your settings
 358 <emphasis>Device baud rate changed at this point</emphasis>
 359 Baud rate changed to 57600 - continue (y/n)? y
 360 Update RedBoot non-volatile configuration - continue (y/n)? n
 361 </screen>
 362       </para>
 363     </refsect1>
 364   </refentry>
 365
 366 <!-- ******** cache *************************************************** -->
 367   <refentry id="cache-command">
 368     <refnamediv>
 369       <refname>cache</refname>
 370       <refpurpose>Control hardware caches</refpurpose>
 371     </refnamediv>
 372     <refsynopsisdiv>
 373       <cmdsynopsis>
 374         <command>cache</command>
 375         <group>
 376           <arg>on</arg>
 377           <arg>off</arg>
 378         </group>
 379       </cmdsynopsis>
 380     </refsynopsisdiv>
 381     <refsect1>
 382       <title>Arguments</title>
 383       <informaltable frame="all">
 384         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 385           <colspec colname="c1">
 386           <colspec colname="c2">
 387           <colspec colname="c3">
 388           <colspec colname="c4">
 389           <thead>
 390             <row>
 391               <entry>Name</entry>
 392               <entry>Type</entry>
 393               <entry>Description</entry>
 394               <entry>Default</entry>
 395             </row>
 396           </thead>
 397           <tbody>
 398             <row>
 399               <entry>on</entry>
 400               <entry></entry>
 401               <entry>Turn the caches on</entry>
 402               <entry><emphasis>none</emphasis></entry>
 403             </row>
 404             <row>
 405               <entry>off</entry>
 406               <entry></entry>
 407               <entry>Turn the caches off</entry>
 408               <entry><emphasis>none</emphasis></entry>
 409             </row>
 410           </tbody>
 411         </tgroup>
 412       </informaltable>
 413     </refsect1>
 414     <refsect1>
 415       <title>Description</title>
 416       <para>The <command>cache</command> command is used to manipulate the caches on the processor. </para>
 417       <para>With no options, this command specifies the state of the system caches.</para>
 418       <para>When an option is given, the caches are turned off or on appropriately.</para>
 419     </refsect1>
 420     <refsect1>
 421       <title>Examples</title>
 422       <para>
 423 Show the current cache state.
 424 <screen>
 425 RedBoot> <userinput>cache</userinput>
 426 Data cache: On, Instruction cache: On
 427 </screen>
 428 </para>
 429 <para>
 430 Disable the caches.
 431 <screen>
 432 RedBoot> <userinput>cache off</userinput>
 433 RedBoot> <userinput>cache</userinput>
 434 Data cache: Off, Instruction cache: Off
 435 </screen>
 436 </para>
 437 <para>
 438 Enable the caches.
 439 <screen>
 440 RedBoot> <userinput>cache on</userinput>
 441 RedBoot> <userinput>cache</userinput>
 442 Data cache: On, Instruction cache: On
 443 </screen>
 444       </para>
 445     </refsect1>
 446   </refentry>
 447
 448 <!-- ******** channel *************************************************** -->
 449   <refentry id="channel-command">
 450     <refnamediv>
 451       <refname>channel</refname>
 452       <refpurpose>Select the system console channel</refpurpose>
 453     </refnamediv>
 454     <refsynopsisdiv>
 455       <cmdsynopsis>
 456         <command>channel</command>
 457         <group>
 458           <arg>-1</arg>
 459           <arg><replaceable>channel_number</replaceable></arg>
 460         </group>
 461       </cmdsynopsis>
 462     </refsynopsisdiv>
 463     <refsect1>
 464       <title>Arguments</title>
 465       <informaltable frame="all">
 466         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 467           <colspec colname="c1">
 468           <colspec colname="c2">
 469           <colspec colname="c3">
 470           <colspec colname="c4">
 471           <thead>
 472             <row>
 473               <entry>Name</entry>
 474               <entry>Type</entry>
 475               <entry>Description</entry>
 476               <entry>Default</entry>
 477             </row>
 478           </thead>
 479           <tbody>
 480             <row>
 481               <entry>-1</entry>
 482               <entry></entry>
 483               <entry>Reset the console channel</entry>
 484               <entry><emphasis>none</emphasis></entry>
 485             </row>
 486             <row>
 487               <entry>channel_number</entry>
 488               <entry>Number</entry>
 489               <entry>Select a channel</entry>
 490               <entry><emphasis>none</emphasis></entry>
 491             </row>
 492           </tbody>
 493         </tgroup>
 494       </informaltable>
 495     </refsect1>
 496     <refsect1>
 497       <title>Description</title>
 498       <para>
 499 With no arguments, the <command>channel</command> command displays the current console channel number.
 500 </para><para>
 501 When passed an argument of 0 upward, this command switches the console
 502 channel to that channel number. The mapping between channel numbers and
 503 physical channels is platform specific but will typically be something like
 504 channel 0 is the first serial port, channel 1 is the second, etc.
 505 </para><para>
 506 When passed an argument of -1, this command reverts RedBoot to responding
 507 to whatever channel receives input first, as happens when RedBoot initially
 508 starts execution.
 509 </para>
 510     </refsect1>
 511     <refsect1>
 512       <title>Examples</title>
 513       <para>
 514 Show the current channel.
 515 <screen>
 516 RedBoot> <userinput>channel</userinput>
 517 Current console channel id: 0
 518 </screen>
 519 </para>
 520 <para>
 521 Change to an invalid channel.
 522 <screen>
 523 RedBoot> <userinput>channel 99</userinput>
 524 **Error: bad channel number '99'
 525 </screen>
 526 </para>
 527 <para>
 528 Revert to the default channel setting (any console mode).
 529 <screen>
 530 RedBoot> <userinput>channel -1</userinput>
 531 </screen>
 532       </para>
 533     </refsect1>
 534   </refentry>
 535
 536 <!-- ******** cksum *************************************************** -->
 537   <refentry id="cksum-command">
 538     <refnamediv>
 539       <refname>cksum</refname>
 540       <refpurpose>Compute POSIX checksums</refpurpose>
 541     </refnamediv>
 542     <refsynopsisdiv>
 543       <cmdsynopsis>
 544         <command>cksum</command>
 545             <arg choice="req">-b <replaceable>location</replaceable></arg>
 546             <arg choice="req">-l <replaceable>length</replaceable></arg>
 547       </cmdsynopsis>
 548     </refsynopsisdiv>
 549     <refsect1>
 550       <title>Arguments</title>
 551       <informaltable frame="all">
 552         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 553           <colspec colname="c1">
 554           <colspec colname="c2">
 555           <colspec colname="c3">
 556           <colspec colname="c4">
 557           <thead>
 558             <row>
 559               <entry>Name</entry>
 560               <entry>Type</entry>
 561               <entry>Description</entry>
 562               <entry>Default</entry>
 563             </row>
 564           </thead>
 565           <tbody>
 566             <row>
 567               <entry>-b <replaceable>location</replaceable></entry>
 568               <entry>Memory address</entry>
 569               <entry>Location in memory for stat of data.</entry>
 570               <entry><emphasis>none</emphasis></entry>
 571             </row>
 572             <row>
 573               <entry>-l <replaceable>length</replaceable></entry>
 574               <entry>Number</entry>
 575               <entry>Length of data</entry>
 576               <entry><emphasis>none</emphasis></entry>
 577             </row>
 578           </tbody>
 579         </tgroup>
 580       </informaltable>
 581     </refsect1>
 582     <refsect1>
 583       <title>Description</title>
 584           <para>Computes the POSIX checksum on a range of memory (either RAM or FLASH).
 585 The values printed (decimal cksum, decimal length, hexadecimal cksum,
 586           hexadecimal length) can be compared with the output from the Linux program 'cksum'.
 587 </para>
 588     </refsect1>
 589     <refsect1>
 590       <title>Examples</title>
 591       <para>
 592 Checksum a buffer.
 593 <screen>
 594 RedBoot> <userinput>cksum -b 0x100000 -l 0x100</userinput>
 595 POSIX cksum = 3286483632 256 (0xc3e3c2b0 0x00000100)
 596 </screen>
 597       </para>
 598       <para>
 599 Checksum an area of memory after loading a file. Note that the base
 600 address and length parameters are provided by the preceding
 601 load command.
 602 <screen>
 603 RedBoot> <userinput>load -r -b %{FREEMEMLO} redboot.bin</userinput>
 604 Raw file loaded 0x06012800-0x0602f0a8
 605 RedBoot> <userinput>cksum</userinput>
 606 Computing cksum for area 0x06012800-0x0602f0a8
 607 POSIX cksum = 2092197813 116904 (0x7cb467b5 0x0001c8a8)
 608 </screen>
 609       </para>
 610     </refsect1>
 611   </refentry>
 612
 613 <!-- ******** disks *************************************************** -->
 614   <refentry id="disks-command">
 615     <refnamediv>
 616       <refname>disks</refname>
 617       <refpurpose>List available disk partitions.</refpurpose>
 618     </refnamediv>
 619     <refsynopsisdiv>
 620       <cmdsynopsis>
 621         <command>disks</command>
 622       </cmdsynopsis>
 623     </refsynopsisdiv>
 624     <refsect1>
 625       <title>Arguments</title>
 626 <para>None.</para>
 627     </refsect1>
 628     <refsect1>
 629       <title>Description</title>
 630         <para>The <command>disks</command> command is used to list disk partitions recognized by RedBoot.</para>
 631     </refsect1>
 632     <refsect1>
 633       <title>Examples</title>
 634       <para>
 635 Show what disk partitions are available.
 636 <screen>
 637 RedBoot> <userinput>disks</userinput>
 638 hda1     Linux Swap
 639 hda2     Linux
 640 00100000: 00 3E 00 06 00 06 00 06  00 00 00 00 00 00 00 00  |.>..............|
 641 00100010: 00 00 00 78 00 70 00 60  00 60 00 60 00 60 00 60  |...x.p.`.`.`.`.`|
 642 </screen>
 643       </para>
 644     </refsect1>
 645   </refentry>
 646
 647 <!-- ******** dump *************************************************** -->
 648   <refentry id="dump-command">
 649     <refnamediv>
 650       <refname>dump</refname>
 651       <refpurpose>Display memory.</refpurpose>
 652     </refnamediv>
 653     <refsynopsisdiv>
 654       <cmdsynopsis>
 655         <command>dump</command>
 656             <arg choice="req">-b <replaceable>location</replaceable></arg>
 657             <arg>-l <replaceable>length</replaceable></arg>
 658             <arg>-s</arg>
 659           <group>
 660             <arg>-1</arg>
 661             <arg>-2</arg>
 662             <arg>-4</arg>
 663           </group>
 664       </cmdsynopsis>
 665     </refsynopsisdiv>
 666     <refsect1>
 667       <title>Arguments</title>
 668       <informaltable frame="all">
 669         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 670           <colspec colname="c1">
 671           <colspec colname="c2">
 672           <colspec colname="c3">
 673           <colspec colname="c4">
 674           <thead>
 675             <row>
 676               <entry>Name</entry>
 677               <entry>Type</entry>
 678               <entry>Description</entry>
 679               <entry>Default</entry>
 680             </row>
 681           </thead>
 682           <tbody>
 683             <row>
 684               <entry>-b <replaceable>location</replaceable></entry>
 685               <entry>Memory address</entry>
 686               <entry>Location in memory for start of data.</entry>
 687               <entry><emphasis>none</emphasis></entry>
 688             </row>
 689             <row>
 690               <entry>-l <replaceable>length</replaceable></entry>
 691               <entry>Number</entry>
 692               <entry>Length of data</entry>
 693               <entry>32</entry>
 694             </row>
 695             <row>
 696               <entry>-s</entry>
 697               <entry>Boolean</entry>
 698               <entry>Format data using Motorola S-records.</entry>
 699               <entry></entry>
 700             </row>
 701             <row>
 702               <entry>-1</entry>
 703               <entry></entry>
 704               <entry>Access one byte (8 bits) at a time.
 705 Only the least significant 8 bits of the pattern will be used.</entry>
 706               <entry>-1</entry>
 707             </row>
 708             <row>
 709               <entry>-2</entry>
 710               <entry></entry>
 711               <entry>Access two bytes (16 bits) at a time.
 712 Only the least significant 16 bits of the pattern will be used.</entry>
 713               <entry>-1</entry>
 714             </row>
 715             <row>
 716               <entry>-4</entry>
 717               <entry></entry>
 718               <entry>Access one word (32 bits) at a time.</entry>
 719               <entry>-1</entry>
 720             </row>
 721           </tbody>
 722         </tgroup>
 723       </informaltable>
 724     </refsect1>
 725     <refsect1>
 726       <title>Description</title>
 727         <para>Display a range of memory on the system console.</para>
 728         <para>The <command>x</command> is a synonym for <command>dump</command>.</para>
 729         <para>Note that this command could
 730 be detrimental if used on memory mapped hardware registers. </para>
 731         <para>The memory is displayed at most sixteen bytes per line, first as the
 732 raw hex value, followed by an ASCII interpretation of the data. </para>
 733     </refsect1>
 734     <refsect1>
 735       <title>Examples</title>
 736       <para>
 737 Display a buffer, one byte at a time.
 738 <screen>
 739 RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
 740 RedBoot> <userinput>x -b 0x100000</userinput>
 741 00100000: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
 742 00100010: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
 743 </screen>
 744 </para>
 745 <para>
 746 Display a buffer, one short (16 bit) word at a time.  Note in this case that
 747 the ASCII interpretation is suppressed.
 748 <screen>
 749 RedBoot> <userinput>dump -b 0x100000 -2</userinput>
 750 00100000: FACE DEAD FACE DEAD  FACE DEAD FACE DEAD
 751 00100010: FACE DEAD FACE DEAD  FACE DEAD FACE DEAD
 752 </screen>
 753 </para>
 754 <para>
 755 Display a buffer, one word (32 bit) word at a time.  Note in this case that
 756 the ASCII interpretation is suppressed.
 757 <screen>
 758 RedBoot> <userinput>dump -b 0x100000 -4</userinput>
 759 00100000: DEADFACE DEADFACE DEADFACE DEADFACE
 760 00100010: DEADFACE DEADFACE DEADFACE DEADFACE
 761 </screen>
 762 </para>
 763 <para>
 764 Display the same buffer, using Motorola S-record format.
 765 <screen>
 766 RedBoot> <userinput>dump -b 0x100000 -s</userinput>
 767 S31500100000CEFAADDECEFAADDECEFAADDECEFAADDE8E
 768 S31500100010CEFAADDECEFAADDECEFAADDECEFAADDE7E
 769 </screen>
 770 </para>
 771 <para>
 772 Display a buffer, with visible ASCII strings.
 773 <screen>
 774 RedBoot> <userinput>d -b 0xfe00b000 -l 0x80</userinput>
 775 0xFE00B000: 20 25 70 0A 00 00 00 00  41 74 74 65 6D 70 74 20 | %p.....Attempt |
 776 0xFE00B010: 74 6F 20 6C 6F 61 64 20  53 2D 72 65 63 6F 72 64 |to load S-record|
 777 0xFE00B020: 20 64 61 74 61 20 74 6F  20 61 64 64 72 65 73 73 | data to address|
 778 0xFE00B030: 3A 20 25 70 20 5B 6E 6F  74 20 69 6E 20 52 41 4D |: %p [not in RAM|
 779 0xFE00B040: 5D 0A 00 00 2A 2A 2A 20  57 61 72 6E 69 6E 67 21 |]...*** Warning!|
 780 0xFE00B050: 20 43 68 65 63 6B 73 75  6D 20 66 61 69 6C 75 72 | Checksum failur|
 781 0xFE00B060: 65 20 2D 20 41 64 64 72  3A 20 25 6C 78 2C 20 25 |e - Addr: %lx, %|
 782 0xFE00B070: 30 32 6C 58 20 3C 3E 20  25 30 32 6C 58 0A 00 00 |02lX &lt;> %02lX...|
 783 0xFE00B080: 45 6E 74 72 79 20 70 6F  69 6E 74 3A 20 25 70 2C |Entry point: %p,|
 784 </screen>
 785       </para>
 786     </refsect1>
 787   </refentry>
 788
 789 <!-- ******** help *************************************************** -->
 790   <refentry id="help-command">
 791     <refnamediv>
 792       <refname>help</refname>
 793       <refpurpose>Display help on available commands</refpurpose>
 794     </refnamediv>
 795     <refsynopsisdiv>
 796       <cmdsynopsis>
 797         <command>help</command>
 798         <arg><replaceable> topic</replaceable></arg>
 799       </cmdsynopsis>
 800     </refsynopsisdiv>
 801     <refsect1>
 802       <title>Arguments</title>
 803       <informaltable frame="all">
 804         <tgroup cols="4" colsep="1" rowsep="1" align="left">
 805           <colspec colname="c1">
 806           <colspec colname="c2">
 807           <colspec colname="c3">
 808           <colspec colname="c4">
 809           <thead>
 810             <row>
 811               <entry>Name</entry>
 812               <entry>Type</entry>
 813               <entry>Description</entry>
 814               <entry>Default</entry>
 815             </row>
 816           </thead>
 817           <tbody>
 818             <row>
 819               <entry><replaceable>topic</replaceable></entry>
 820               <entry>String</entry>
 821               <entry>Which command to provide help for.</entry>
 822               <entry>All commands</entry>
 823             </row>
 824           </tbody>
 825         </tgroup>
 826       </informaltable>
 827     </refsect1>
 828     <refsect1>
 829       <title>Description</title>
 830       <para>
 831 The <command>help</command> command displays information about the available
 832 RedBoot commands.  If a <emphasis>topic</emphasis> is given, then the display
 833 is restricted to information about that specific command.
 834       </para>
 835       <para>
 836 If the command has sub-commands, e.g. <command>fis</command>, then the topic
 837 specific display will print additional information about the available sub-commands.
 838 special (ICMP) packets to a specific host. These packets should be automatically
 839 returned by that host. The command will indicate how many of these round-trips
 840 were successfully completed.
 841       </para>
 842     </refsect1>
 843     <refsect1>
 844       <title>Examples</title>
 845       <para>
 846 Show generic help.  Note that the contents of this display will depend on the various configuration
 847 options for RedBoot when it was built.
 848 <screen>
 849 RedBoot> <userinput>help</userinput>
 850 Manage aliases kept in FLASH memory
 851    alias name [value]
 852 Manage machine caches
 853    cache [ON | OFF]
 854 Display/switch console channel
 855    channel [-1|&lt;channel number&gt;]
 856 Compute a 32bit checksum [POSIX algorithm] for a range of memory
 857    cksum -b &lt;location&gt; -l &lt;length&gt;
 858 Display (hex dump) a range of memory
 859    dump -b &lt;location&gt; [-l &lt;length&gt;] [-s] [-1|-2|-4]
 860 Manage FLASH images
 861    fis {cmds}
 862 Manage configuration kept in FLASH memory
 863    fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
 864 Execute code at a location
 865    go [-w &lt;timeout&gt;] [entry]
 866 Uncompress GZIP compressed data
 867    gunzip -s &lt;location&gt; -d &lt;location&gt;
 868 Help about help?
 869    help [&lt;topic&gt;]
 870 Read I/O location
 871    iopeek [-b &lt;location&gt;] [-1|2|4]
 872 Write I/O location
 873    iopoke [-b &lt;location&gt;] [-1|2|4] -v &lt;value&gt;
 874 Set/change IP addresses
 875    ip_address [-l &lt;local_ip_address&gt;[/&lt;mask_length&gt;]] [-h &lt;server_address&gt;]
 876 Load a file
 877    load [-r] [-v] [-d] [-h &lt;host&gt;] [-m {TFTP | HTTP | {x|y}MODEM -c &lt;channel_number&gt;}]
 878         [-f &lt;flash_address&gt;] [-b &lt;base_address&gt;]  &lt;file_name&gt;
 879 Compare two blocks of memory
 880    mcmp -s &lt;location&gt; -d &lt;location&gt; -l &lt;length&gt; [-1|-2|-4]
 881 Fill a block of memory with a pattern
 882    mfill -b &lt;location&gt; -l &lt;length&gt; -p &lt;pattern&gt;
 883   [-1|-2|-4]
 884 Network connectivity test
 885    ping [-v] [-n &lt;count&gt;] [-l &lt;length&gt;] [-t &lt;timeout&gt;] [-r &lt;rate&gt;]
 886         [-i &lt;IP_addr&gt;] -h &lt;IP_addr&gt;
 887 Reset the system
 888    reset
 889 Display RedBoot version information
 890    version
 891 Display (hex dump) a range of memory
 892    x -b &lt;location&gt; [-l &lt;length&gt;] [-s] [-1|-2|-4]
 893 </screen>
 894       </para>
 895       <para>
 896 Help about a command with sub-commands.
 897 <screen>
 898 RedBoot> <userinput>help fis</userinput>
 899 Manage FLASH images
 900    fis {cmds}
 901 Create an image
 902   fis create -b &lt;mem_base&gt; -l &lt;image_length&gt; [-s &lt;data_length&gt;]
 903       [-f &lt;flash_addr&gt;] [-e &lt;entry_point&gt;] [-r &lt;ram_addr&gt;] [-n] &lt;name&gt;
 904 Display an image from FLASH Image System [FIS]
 905   fis delete name
 906 Erase FLASH contents
 907   fis erase -f &lt;flash_addr&gt; -l &lt;length&gt;
 908 Display free [available] locations within FLASH Image System [FIS]
 909   fis free
 910 Initialize FLASH Image System [FIS]
 911   fis init [-f]
 912 Display contents of FLASH Image System [FIS]
 913   fis list [-c] [-d]
 914 Load image from FLASH Image System [FIS] into RAM
 915   fis load [-d] [-b &lt;memory_load_address&gt;] [-c] name
 916 Write raw data directly to FLASH
 917   fis write -f &lt;flash_addr&gt; -b &lt;mem_base&gt; -l &lt;image_length&gt;
 918 </screen>
 919       </para>
 920     </refsect1>
 921   </refentry>
 922
 923 <!-- ******** iopeek *************************************************** -->
 924   <refentry id="iopeek-command">
 925   <refnamediv>
 926     <refname>iopeek</refname>
 927     <refpurpose>Read I/O location</refpurpose>
 928   </refnamediv>
 929   <refsynopsisdiv>
 930     <cmdsynopsis>
 931       <command>iopeek</command>
 932       <arg>-b <replaceable> location</replaceable></arg>
 933       <group>
 934         <arg>-1</arg>
 935         <arg>-2</arg>
 936         <arg>-4</arg>
 937       </group>
 938     </cmdsynopsis>
 939   </refsynopsisdiv>
 940   <refsect1>
 941     <title>Arguments</title>
 942     <informaltable frame="all">
 943       <tgroup cols="4" colsep="1" rowsep="1" align="left">
 944         <colspec colname="c1">
 945         <colspec colname="c2">
 946         <colspec colname="c3">
 947         <colspec colname="c4">
 948         <thead>
 949           <row>
 950             <entry>Name</entry>
 951             <entry>Type</entry>
 952             <entry>Description</entry>
 953             <entry>Default</entry>
 954           </row>
 955         </thead>
 956         <tbody>
 957           <row>
 958             <entry>-b <replaceable>location</replaceable></entry>
 959             <entry>I/O address</entry>
 960             <entry>I/O Location.</entry>
 961             <entry><emphasis>none</emphasis></entry>
 962           </row>
 963           <row>
 964             <entry>-1</entry>
 965             <entry></entry>
 966             <entry>Access a one byte (8 bit) I/O location.</entry>
 967             <entry>-1</entry>
 968           </row>
 969           <row>
 970             <entry>-2</entry>
 971             <entry></entry>
 972             <entry>Access a two byte (16 bit) I/O location.</entry>
 973             <entry>-1</entry>
 974           </row>
 975           <row>
 976             <entry>-4</entry>
 977             <entry></entry>
 978             <entry>Access a one word (32 bit) I/O location.</entry>
 979             <entry>-1</entry>
 980           </row>
 981         </tbody>
 982       </tgroup>
 983     </informaltable>
 984   </refsect1>
 985   <refsect1>
 986     <title>Description</title>
 987       <para>Reads a value from the I/O address space.</para>
 988   </refsect1>
 989   <refsect1>
 990     <title>Examples</title>
 991     <para>
 992 Examine 8 bit value at I/O location 0x3F8.
 993 <screen>
 994 RedBoot> <userinput>iopeek -b 0x3f8</userinput>
 995 0x03f8 = 0x30
 996 </screen>
 997 </para>
 998      <para>
 999 Examine 32 bit value at I/O location 0x3f8.
1000 <screen>
1001 RedBoot> <userinput>iopeek -b 0x3f8 -4</userinput>
1002 0x03f8 = 0x03c10065
1003 </screen>
1004 </para>
1005     </refsect1>
1006   </refentry>
1007
1008 <!-- ******** iopoke *************************************************** -->
1009   <refentry id="iopoke-command">
1010   <refnamediv>
1011     <refname>iopoke</refname>
1012     <refpurpose>Write I/O location</refpurpose>
1013   </refnamediv>
1014   <refsynopsisdiv>
1015     <cmdsynopsis>
1016       <command>iopoke</command>
1017       <arg>-b <replaceable> location</replaceable></arg>
1018       <group>
1019         <arg>-1</arg>
1020         <arg>-2</arg>
1021         <arg>-4</arg>
1022       </group>
1023       <arg>-v <replaceable> value</replaceable></arg>
1024     </cmdsynopsis>
1025   </refsynopsisdiv>
1026   <refsect1>
1027     <title>Arguments</title>
1028     <informaltable frame="all">
1029       <tgroup cols="4" colsep="1" rowsep="1" align="left">
1030         <colspec colname="c1">
1031         <colspec colname="c2">
1032         <colspec colname="c3">
1033         <colspec colname="c4">
1034         <thead>
1035           <row>
1036             <entry>Name</entry>
1037             <entry>Type</entry>
1038             <entry>Description</entry>
1039             <entry>Default</entry>
1040           </row>
1041         </thead>
1042         <tbody>
1043           <row>
1044             <entry>-b <replaceable>location</replaceable></entry>
1045             <entry>I/O address</entry>
1046             <entry>I/O Location.</entry>
1047             <entry><emphasis>none</emphasis></entry>
1048           </row>
1049           <row>
1050             <entry>-1</entry>
1051             <entry></entry>
1052             <entry>Access a one byte (8 bit) I/O location.
1053 Only the 8 least significant bits of value will be used</entry>
1054             <entry>-1</entry>
1055           </row>
1056           <row>
1057             <entry>-2</entry>
1058             <entry></entry>
1059             <entry>Access a two byte (16 bit) I/O location.
1060 Only the 16 least significant bits of value will be used</entry>
1061             <entry>-1</entry>
1062           </row>
1063           <row>
1064             <entry>-4</entry>
1065             <entry></entry>
1066             <entry>Access a one word (32 bit) I/O location.</entry>
1067             <entry>-1</entry>
1068           </row>
1069         </tbody>
1070       </tgroup>
1071     </informaltable>
1072   </refsect1>
1073   <refsect1>
1074     <title>Description</title>
1075       <para>Writes a value to the I/O address space.</para>
1076   </refsect1>
1077   <refsect1>
1078     <title>Examples</title>
1079     <para>
1080 Write 0x0123 to 16 bit I/O location 0x200.
1081 <screen>
1082 RedBoot> <userinput>iopoke -b 0x200 -v 0x123 -2</userinput>
1083 </screen>
1084 </para>
1085     </refsect1>
1086   </refentry>
1087
1088 <!-- ******** gunzip *************************************************** -->
1089   <refentry id="gunzip-command">
1090   <refnamediv>
1091     <refname>gunzip</refname>
1092     <refpurpose>Uncompress GZIP compressed data</refpurpose>
1093   </refnamediv>
1094   <refsynopsisdiv>
1095     <cmdsynopsis>
1096       <command>gunzip</command>
1097       <arg choice="req">-s <replaceable>source</replaceable></arg>
1098           <arg choice="req">-d <replaceable>destination</replaceable></arg>
1099     </cmdsynopsis>
1100   </refsynopsisdiv>
1101   <refsect1>
1102     <title>Arguments</title>
1103     <informaltable frame="all">
1104       <tgroup cols="4" colsep="1" rowsep="1" align="left">
1105         <colspec colname="c1">
1106         <colspec colname="c2">
1107         <colspec colname="c3">
1108         <colspec colname="c4">
1109         <thead>
1110           <row>
1111             <entry>Name</entry>
1112             <entry>Type</entry>
1113             <entry>Description</entry>
1114             <entry>Default</entry>
1115           </row>
1116         </thead>
1117         <tbody>
1118               <row>
1119                 <entry>-s <replaceable>location1</replaceable></entry>
1120                 <entry>Memory address</entry>
1121                 <entry>Location of GZIP compressed data to uncompress.</entry>
1122                 <entry>Value set by last <command>load</command> or <command>fis load</command> command.</entry>
1123               </row>
1124               <row>
1125                 <entry>-d <replaceable>location2</replaceable></entry>
1126                 <entry>Memory address</entry>
1127                 <entry>Destination to write uncompressed data to.</entry>
1128                 <entry><emphasis>none</emphasis></entry>
1129               </row>
1130         </tbody>
1131       </tgroup>
1132     </informaltable>
1133   </refsect1>
1134   <refsect1>
1135     <title>Description</title>
1136       <para>Uncompress GZIP compressed data.</para>
1137   </refsect1>
1138   <refsect1>
1139     <title>Examples</title>
1140     <para>
1141 Uncompress data at location 0x100000 to 0x200000.
1142 <screen>
1143 RedBoot> <userinput>gunzip -s 0x100000 -d 0x200000</userinput>
1144 Decompressed 38804 bytes
1145 </screen>
1146 </para>
1147     </refsect1>
1148   </refentry>
1149
1150 <!-- ******** ip_address *************************************************** -->
1151   <refentry id="ip-address-command">
1152     <refnamediv>
1153       <refname>ip_address</refname>
1154       <refpurpose>Set IP addresses</refpurpose>
1155     </refnamediv>
1156     <refsynopsisdiv>
1157       <cmdsynopsis>
1158         <command>ip_address</command>
1159         <arg>-b</arg>
1160         <arg>-l <replaceable> local_IP_address</replaceable>
1161         <arg choice=opt>/<replaceable>netmask_length</replaceable></arg> </arg>
1162         <arg>-h <replaceable> server_IP_address</replaceable></arg>
1163         <arg>-d <replaceable>
1164 DNS_server_IP_address</replaceable></arg>
1165       </cmdsynopsis>
1166     </refsynopsisdiv>
1167     <refsect1>
1168       <title>Arguments</title>
1169       <informaltable frame="all">
1170         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1171           <colspec colname="c1">
1172           <colspec colname="c2">
1173           <colspec colname="c3">
1174           <colspec colname="c4">
1175           <thead>
1176             <row>
1177               <entry>Name</entry>
1178               <entry>Type</entry>
1179               <entry>Description</entry>
1180               <entry>Default</entry>
1181             </row>
1182           </thead>
1183           <tbody>
1184             <row>
1185               <entry>-b</entry>
1186               <entry>Boolean</entry>
1187               <entry>Obtain an IP address using BOOTP or DHCP.</entry>
1188               <entry>don't use BOOTP/DHCP</entry>
1189             </row>
1190             <row>
1191               <entry>-l <replaceable>
1192 local_IP_address</replaceable><option>[<replaceable>/netmask_length</replaceable>]</option></entry>
1193               <entry>Numeric IP or DNS name</entry>
1194               <entry>The IP address RedBoot should use, optionally
1195 with the network mask length.</entry>
1196               <entry><emphasis>none</emphasis></entry>
1197             </row>
1198             <row>
1199               <entry>-h <replaceable>
1200 server_IP_address</replaceable></entry>
1201               <entry>Numeric IP or DNS name</entry>
1202               <entry>The IP address of the default server. Use of this
1203 address is implied by other commands, such as
1204 <command>load</command>.</entry>
1205               <entry><emphasis>none</emphasis></entry>
1206             </row>
1207             <row>
1208               <entry>-d <replaceable>
1209 DNS_server_IP_address</replaceable></entry>
1210               <entry>Numeric IP or DNS name</entry>
1211               <entry>The IP address of the DNS server.</entry>
1212               <entry><emphasis>none</emphasis></entry>
1213             </row>
1214           </tbody>
1215         </tgroup>
1216       </informaltable>
1217     </refsect1>
1218     <refsect1>
1219       <title>Description</title>
1220       <para>The <command>ip_address</command> command is used to show and/or change the basic IP
1221 addresses used by RedBoot. IP addresses may be given as numeric
1222 values, e.g. 192.168.1.67, or as symbolic names such as www.redhat.com
1223 if DNS support is enabled.
1224       </para>
1225       <para>
1226 The <option>-b</option> option is used to cause the target to perform a bootp or dhcp negotiation to get an IP address.
1227       </para>
1228       <para>
1229 The <option>-l</option> option is used to set the IP address used by
1230 the target device. The network mask length can also be specified
1231       </para>
1232       <para>
1233 The <option>-h</option> option is used to set the default server
1234 address, such as is used by the <command>load</command> command.
1235       </para>
1236       <para>
1237 The <option>-d</option> option is used to set the default DNS server
1238 address which is used for resolving symbolic network addresses. Note
1239 that an address of 0.0.0.0 will disable DNS lookups.
1240       </para>
1241     </refsect1>
1242     <refsect1>
1243       <title>Examples</title>
1244       <para>
1245 Display the current network settings.
1246 <screen>
1247 RedBoot> <userinput>ip_address</userinput>
1248 IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 0.0.0.0, DNS domain name:
1249 </screen>
1250 </para>
1251 <para>
1252 Change the DNS server address.
1253 <screen>
1254 RedBoot> <userinput>ip_address -d 192.168.1.101</userinput>
1255 IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 192.168.1.101, DNS domain name:
1256 </screen>
1257 </para>
1258 <para>
1259 Change the DNS domain name.
1260 <screen>
1261 RedBoot> <userinput>ip_address -D example.com</userinput>
1262 IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 192.168.1.101, DNS domain name: example.com
1263 </screen>
1264 </para>
1265 <para>
1266 Change the default server address.
1267 <screen>
1268 RedBoot> <userinput>ip_address -h 192.168.1.104</userinput>
1269 IP: 192.168.1.31, Default server: 192.168.1.104, DNS server IP: 192.168.1.101, DNS domain name:
1270 </screen>
1271 </para>
1272 <para>
1273 Set the IP address to something new, with a 255.255.255.0 netmask
1274 <screen>
1275 RedBoot> <userinput>ip_address -l 192.168.1.32/24</userinput>
1276 IP: 192.168.1.32, Default server: 192.168.1.104, DNS server IP: 192.168.1.101, DNS domain name:
1277 </screen>
1278       </para>
1279     </refsect1>
1280   </refentry>
1281
1282 <!-- ******** load *************************************************** -->
1283   <refentry id="download-command">
1284     <refnamediv>
1285       <refname>load</refname>
1286       <refpurpose>Download programs or data to the RedBoot platform</refpurpose>
1287     </refnamediv>
1288     <refsynopsisdiv>
1289       <cmdsynopsis>
1290         <command>load</command>
1291         <arg>-v </arg>
1292         <arg>-d </arg>
1293         <arg>-r </arg>
1294         <arg>-m
1295           <group>
1296             <arg choice="req"><group>
1297               <arg>xmodem</arg>
1298               <arg>ymodem</arg>
1299               <arg>tftp</arg>
1300               <arg>disk</arg>
1301               <arg>file</arg></group>
1302             </arg>
1303           </group>
1304         </arg>
1305         <arg>-h <replaceable> server_IP_address</replaceable></arg>
1306         <arg>-f <replaceable> location</replaceable></arg>
1307         <arg>-b <replaceable> location</replaceable></arg>
1308         <arg>-c <replaceable> channel</replaceable></arg>
1309         <arg><replaceable>file_name</replaceable></arg>
1310       </cmdsynopsis>
1311     </refsynopsisdiv>
1312     <refsect1>
1313       <title>Arguments</title>
1314       <informaltable frame="all">
1315         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1316           <colspec colname="c1">
1317           <colspec colname="c2">
1318           <colspec colname="c3">
1319           <colspec colname="c4">
1320           <thead>
1321             <row>
1322               <entry>Name</entry>
1323               <entry>Type</entry>
1324               <entry>Description</entry>
1325               <entry>Default</entry>
1326             </row>
1327           </thead>
1328           <tbody>
1329             <row>
1330               <entry>-v</entry>
1331               <entry>Boolean</entry>
1332               <entry>Display a small spinner (indicator)
1333 while the download is in  progress. This is just for feedback, especially
1334 during long loads. Note that the option has no effect when using a
1335 serial download method since it would interfere with the protocol.</entry>
1336               <entry><emphasis>quiet</emphasis></entry>
1337             </row>
1338             <row>
1339               <entry>-d</entry>
1340               <entry>Boolean</entry>
1341               <entry>Decompress data stream (gzip data)</entry>
1342               <entry><emphasis>non-compressed data</emphasis></entry>
1343             </row>
1344             <row>
1345               <entry>-r</entry>
1346               <entry>Boolean</entry>
1347               <entry>Raw (or binary) data. -b or -f must be used</entry>
1348               <entry><emphasis>formatted (S-records, ELF image, etc)</emphasis></entry>
1349             </row>
1350             <row>
1351               <entry>-m tftp</entry>
1352               <entry></entry>
1353               <entry>Transfer data via the network using <acronym>TFTP</acronym> protocol.</entry>
1354               <entry><acronym>TFTP</acronym></entry>
1355             </row>
1356             <row>
1357               <entry>-m http</entry>
1358               <entry></entry>
1359               <entry>Transfer data via the network using <acronym>HTTP</acronym> protocol.</entry>
1360               <entry><acronym>TFTP</acronym></entry>
1361             </row>
1362             <row>
1363               <entry>-m xmodem</entry>
1364               <entry></entry>
1365               <entry>Transfer data using <emphasis>X-modem</emphasis> protocol.</entry>
1366               <entry><acronym>TFTP</acronym></entry>
1367             </row>
1368             <row>
1369               <entry>-m ymodem</entry>
1370               <entry></entry>
1371               <entry>Transfer data using <emphasis>Y-modem</emphasis> protocol.</entry>
1372               <entry><acronym>TFTP</acronym></entry>
1373             </row>
1374             <row>
1375               <entry>-m disk</entry>
1376               <entry></entry>
1377               <entry>Transfer data from a local disk.</entry>
1378               <entry><acronym>TFTP</acronym></entry>
1379             </row>
1380             <row>
1381               <entry>-m file</entry>
1382               <entry></entry>
1383               <entry>Transfer data from a local filesystem such as
1384                      JFFS2 or FAT.</entry>
1385               <entry><acronym>TFTP</acronym></entry>
1386             </row>
1387             <row>
1388               <entry>-h <replaceable>server_IP_address</replaceable></entry>
1389               <entry>Numeric IP or DNS name</entry>
1390               <entry>The IP address of the <acronym>TFTP</acronym> or <acronym>HTTP</acronym> server.</entry>
1391               <entry>Value set by <command>ip_address</command></entry>
1392             </row>
1393             <row>
1394               <entry>-b <replaceable>location</replaceable></entry>
1395               <entry>Number</entry>
1396               <entry>Address in memory to load the data.  Formatted data streams will have
1397 an implied load address which this option may override.</entry>
1398               <entry><emphasis>Depends on data format</emphasis></entry>
1399             </row>
1400             <row>
1401               <entry>-f <replaceable>location</replaceable></entry>
1402               <entry>Number</entry>
1403               <entry>Address in flash to load the data.  Formatted data streams will have
1404 an implied load address which this option may override.</entry>
1405               <entry><emphasis>Depends on data format</emphasis></entry>
1406             </row>
1407             <row>
1408               <entry>-c <replaceable>channel</replaceable></entry>
1409               <entry>Number</entry>
1410               <entry>Specify which I/O channel to
1411 use for download.  This option is only supported when using either
1412 xmodem or ymodem protocol.</entry>
1413               <entry><emphasis>Depends on data format</emphasis></entry>
1414             </row>
1415             <row>
1416               <entry><replaceable>file_name</replaceable></entry>
1417               <entry>String</entry>
1418               <entry>The name of the file on the <acronym>TFTP</acronym> or <acronym>HTTP</acronym>
1419 server or the local disk. Details of how this is specified for <acronym>TFTP</acronym> are
1420 host-specific. For local disk files, the name must be in <emphasis>disk</emphasis>:
1421 <emphasis>filename</emphasis> format. The disk portion must match one of the disk
1422 names listed by the <command>disks</command> command.</entry>
1423               <entry><emphasis>None</emphasis></entry>
1424             </row>
1425           </tbody>
1426         </tgroup>
1427       </informaltable>
1428     </refsect1>
1429     <refsect1>
1430       <title>Description</title>
1431       <para>
1432 The <command>load</command> command is used to download
1433 data into the target system. Data can be loaded via a network connection,
1434 using either the <acronym>TFTP</acronym> or <acronym>HTTP</acronym> protocols, or the console serial connection using the
1435 X/Y modem protocol. Files may also be loaded directly from local filesystems
1436 on disk. Files to be downloaded may either be executable images in
1437 ELF executable program format,
1438 Motorola S-record (SREC)
1439 format or raw data.
1440       </para>
1441     </refsect1>
1442     <refsect1>
1443       <title>Examples</title>
1444       <para>
1445 Download a Motorola S-record (or ELF) image, using <acronym>TFTP</acronym>, specifying the
1446 base memory address.
1447 <screen>
1448 RedBoot> <userinput>load redboot.ROM -b 0x8c400000</userinput>
1449 Address offset = 0x0c400000
1450 Entry point: 0x80000000, address range: 0x80000000-0x8000fe80
1451 </screen>
1452       </para>
1453       <para>
1454 Download a Motorola S-record (or ELF) image, using <acronym>HTTP</acronym>, specifying the
1455 host [server] address.
1456 <screen>
1457 RedBoot> <userinput>load /redboot.ROM -m HTTP -h 192.168.1.104</userinput>
1458 Address offset = 0x0c400000
1459 Entry point: 0x80000000, address range: 0x80000000-0x8000fe80
1460 </screen>
1461       </para>
1462       <para>
1463 Load an ELF file from /dev/hda1 which should be an EXT2 partition:
1464 <screen>
1465 RedBoot> <userinput>load -mode disk hda1:hello.elf</userinput>
1466 Entry point: 0x00020000, address range: 0x00020000-0x0002fd70
1467 </screen>
1468       </para>
1469       <para>
1470 Load an ELF file from /jffs2/applications which should be a directory
1471 in a JFFS2 filesystem:
1472 <screen>
1473 RedBoot> <userinput>load -mode file /jffs2/applications/hello.elf</userinput>
1474 Entry point: 0x00020000, address range: 0x00020000-0x0002fd70
1475 </screen>
1476       </para>
1477     </refsect1>
1478   </refentry>
1479
1480 <!-- ******** mcmp *************************************************** -->
1481   <refentry id="mcmp-command">
1482     <refnamediv>
1483       <refname>mcmp</refname>
1484       <refpurpose>Compare two segments of memory</refpurpose>
1485     </refnamediv>
1486     <refsynopsisdiv>
1487       <cmdsynopsis>
1488         <command>mcmp</command>
1489             <arg choice="req">-s <replaceable>location1</replaceable></arg>
1490             <arg choice="req">-d <replaceable>location1</replaceable></arg>
1491             <arg choice="req">-l <replaceable>length</replaceable></arg>
1492           <group>
1493             <arg>-1</arg>
1494             <arg>-2</arg>
1495             <arg>-4</arg>
1496           </group>
1497       </cmdsynopsis>
1498     </refsynopsisdiv>
1499     <refsect1>
1500       <title>Arguments</title>
1501       <informaltable frame="all">
1502         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1503           <colspec colname="c1">
1504           <colspec colname="c2">
1505           <colspec colname="c3">
1506           <colspec colname="c4">
1507           <thead>
1508             <row>
1509               <entry>Name</entry>
1510               <entry>Type</entry>
1511               <entry>Description</entry>
1512               <entry>Default</entry>
1513             </row>
1514           </thead>
1515           <tbody>
1516             <row>
1517               <entry>-s <replaceable>location1</replaceable></entry>
1518               <entry>Memory address</entry>
1519               <entry>Location for start of data.</entry>
1520               <entry><emphasis>none</emphasis></entry>
1521             </row>
1522             <row>
1523               <entry>-d <replaceable>location2</replaceable></entry>
1524               <entry>Memory address</entry>
1525               <entry>Location for start of data.</entry>
1526               <entry><emphasis>none</emphasis></entry>
1527             </row>
1528             <row>
1529               <entry>-l <replaceable>length</replaceable></entry>
1530               <entry>Number</entry>
1531               <entry>Length of data</entry>
1532               <entry><emphasis>none</emphasis></entry>
1533             </row>
1534             <row>
1535               <entry>-1</entry>
1536               <entry></entry>
1537               <entry>Access one byte (8 bits) at a time.
1538 Only the least significant 8 bits of the pattern will be used.</entry>
1539               <entry>-4</entry>
1540             </row>
1541             <row>
1542               <entry>-2</entry>
1543               <entry></entry>
1544               <entry>Access two bytes (16 bits) at a time.
1545 Only the least significant 16 bits of the pattern will be used.</entry>
1546               <entry>-4</entry>
1547             </row>
1548             <row>
1549               <entry>-4</entry>
1550               <entry></entry>
1551               <entry>Access one word (32 bits) at a time.</entry>
1552               <entry>-4</entry>
1553             </row>
1554           </tbody>
1555         </tgroup>
1556       </informaltable>
1557     </refsect1>
1558     <refsect1>
1559       <title>Description</title>
1560         <para>Compares the contents of two ranges of memory (RAM, ROM, FLASH, etc).</para>
1561     </refsect1>
1562     <refsect1>
1563       <title>Examples</title>
1564       <para>
1565 Compare two buffers which match (result is <emphasis>quiet</emphasis>).
1566 <screen>
1567 RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
1568 RedBoot> <userinput>mfill -b 0x200000 -l 0x20 -p 0xDEADFACE</userinput>
1569 RedBoot> <userinput>mcmp -s 0x100000 -d 0x200000 -l 0x20</userinput>
1570 </screen>
1571 </para>
1572 <para>
1573 Compare two buffers which don't match.
1574 Only the first non-matching element is displayed.
1575 <screen>
1576 RedBoot> <userinput>mcmp -s 0x100000 -d 0x200000 -l 0x30 -2</userinput>
1577 Buffers don't match - 0x00100020=0x6000, 0x00200020=0x0000
1578 </screen>
1579       </para>
1580     </refsect1>
1581   </refentry>
1582
1583 <!-- ******** mcopy *************************************************** -->
1584   <refentry id="mcopy-command">
1585     <refnamediv>
1586       <refname>mcopy</refname>
1587       <refpurpose>Copy memory</refpurpose>
1588     </refnamediv>
1589     <refsynopsisdiv>
1590       <cmdsynopsis>
1591         <command>mcopy</command>
1592             <arg choice="req">-s <replaceable>source</replaceable></arg>
1593             <arg choice="req">-d <replaceable>destination</replaceable></arg>
1594             <arg choice="req">-l <replaceable>length</replaceable></arg>
1595           <group>
1596             <arg>-1</arg>
1597             <arg>-2</arg>
1598             <arg>-4</arg>
1599           </group>
1600       </cmdsynopsis>
1601     </refsynopsisdiv>
1602     <refsect1>
1603       <title>Arguments</title>
1604       <informaltable frame="all">
1605         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1606           <colspec colname="c1">
1607           <colspec colname="c2">
1608           <colspec colname="c3">
1609           <colspec colname="c4">
1610           <thead>
1611             <row>
1612               <entry>Name</entry>
1613               <entry>Type</entry>
1614               <entry>Description</entry>
1615               <entry>Default</entry>
1616             </row>
1617           </thead>
1618           <tbody>
1619             <row>
1620               <entry>-s <replaceable>location1</replaceable></entry>
1621               <entry>Memory address</entry>
1622               <entry>Location of data to copy.</entry>
1623               <entry><emphasis>none</emphasis></entry>
1624             </row>
1625             <row>
1626               <entry>-d <replaceable>location2</replaceable></entry>
1627               <entry>Memory address</entry>
1628               <entry>Destination for copied data.</entry>
1629               <entry><emphasis>none</emphasis></entry>
1630             </row>
1631             <row>
1632               <entry>-l <replaceable>length</replaceable></entry>
1633               <entry>Number</entry>
1634               <entry>Length of data</entry>
1635               <entry><emphasis>none</emphasis></entry>
1636             </row>
1637             <row>
1638               <entry>-1</entry>
1639               <entry></entry>
1640               <entry>Copy one byte (8 bits) at a time.</entry>
1641               <entry>-4</entry>
1642             </row>
1643             <row>
1644               <entry>-2</entry>
1645               <entry></entry>
1646               <entry>Copy two bytes (16 bits) at a time.</entry>
1647               <entry>-4</entry>
1648             </row>
1649             <row>
1650               <entry>-4</entry>
1651               <entry></entry>
1652               <entry>Copy one word (32 bits) at a time.</entry>
1653               <entry>-4</entry>
1654             </row>
1655           </tbody>
1656         </tgroup>
1657       </informaltable>
1658     </refsect1>
1659     <refsect1>
1660       <title>Description</title>
1661         <para>Copies memory (RAM, ROM, FLASH, etc) from one area to another.</para>
1662     </refsect1>
1663     <refsect1>
1664       <title>Examples</title>
1665       <para>
1666 Copy 16 bits at a time.
1667 <screen>
1668 RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -2 -p 0xDEAD</userinput>
1669 RedBoot> <userinput>mfill -b 0x200000 -l 0x20 -2 -p 0x0</userinput>
1670 RedBoot> <userinput>dump  -b 0x200000 -l 0x20 -2</userinput>
1671 00200000: 0000 0000 0000 0000  0000 0000 0000 0000
1672 00200010: 0000 0000 0000 0000  0000 0000 0000 0000
1673 RedBoot> <userinput>mcopy -s 0x100000 -d 0x200000 -2 -l 0x20</userinput>
1674 RedBoot> <userinput>dump  -b 0x200000 -l 0x20 -2</userinput>
1675 00200000: DEAD DEAD DEAD DEAD  DEAD DEAD DEAD DEAD
1676 00200010: DEAD DEAD DEAD DEAD  DEAD DEAD DEAD DEAD
1677 </screen>
1678 </para>
1679     </refsect1>
1680   </refentry>
1681
1682 <!-- ******** mfill *************************************************** -->
1683   <refentry id="mfill-command">
1684     <refnamediv>
1685       <refname>mfill</refname>
1686       <refpurpose>Fill RAM with a specified pattern</refpurpose>
1687     </refnamediv>
1688     <refsynopsisdiv>
1689       <cmdsynopsis>
1690         <command>mfill</command>
1691             <arg choice="req">-b <replaceable>location</replaceable></arg>
1692             <arg choice="req">-l <replaceable>length</replaceable></arg>
1693             <arg choice="req">-p <replaceable>value</replaceable></arg>
1694           <group>
1695             <arg>-1</arg>
1696             <arg>-2</arg>
1697             <arg>-4</arg>
1698           </group>
1699       </cmdsynopsis>
1700     </refsynopsisdiv>
1701     <refsect1>
1702       <title>Arguments</title>
1703       <informaltable frame="all">
1704         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1705           <colspec colname="c1">
1706           <colspec colname="c2">
1707           <colspec colname="c3">
1708           <colspec colname="c4">
1709           <thead>
1710             <row>
1711               <entry>Name</entry>
1712               <entry>Type</entry>
1713               <entry>Description</entry>
1714               <entry>Default</entry>
1715             </row>
1716           </thead>
1717           <tbody>
1718             <row>
1719               <entry>-b <replaceable>location</replaceable></entry>
1720               <entry>Memory address</entry>
1721               <entry>Location in memory for start of data.</entry>
1722               <entry><emphasis>none</emphasis></entry>
1723             </row>
1724             <row>
1725               <entry>-l <replaceable>length</replaceable></entry>
1726               <entry>Number</entry>
1727               <entry>Length of data</entry>
1728               <entry><emphasis>none</emphasis></entry>
1729             </row>
1730             <row>
1731               <entry>-p <replaceable>pattern</replaceable></entry>
1732               <entry>Number</entry>
1733               <entry>Data value to fill with</entry>
1734               <entry>0</entry>
1735             </row>
1736             <row>
1737               <entry>-1</entry>
1738               <entry></entry>
1739               <entry>Access one byte (8 bits) at a time.
1740 Only the least significant 8 bits of the pattern will be used.</entry>
1741               <entry>-4</entry>
1742             </row>
1743             <row>
1744               <entry>-2</entry>
1745               <entry></entry>
1746               <entry>Access two bytes (16 bits) at a time.
1747 Only the least significant 16 bits of the pattern will be used.</entry>
1748               <entry>-4</entry>
1749             </row>
1750             <row>
1751               <entry>-4</entry>
1752               <entry></entry>
1753               <entry>Access one word (32 bits) at a time.</entry>
1754               <entry>-4</entry>
1755             </row>
1756           </tbody>
1757         </tgroup>
1758       </informaltable>
1759     </refsect1>
1760     <refsect1>
1761       <title>Description</title>
1762         <para>Fills a range of memory with the given pattern.</para>
1763     </refsect1>
1764     <refsect1>
1765       <title>Examples</title>
1766       <para>
1767 Fill a buffer with zeros.
1768 <screen>
1769 RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
1770 00100000: 00 3E 00 06 00 06 00 06  00 00 00 00 00 00 00 00  |.>..............|
1771 00100010: 00 00 00 78 00 70 00 60  00 60 00 60 00 60 00 60  |...x.p.`.`.`.`.`|
1772 RedBoot> <userinput>mfill -b 0x100000 -l 0x20</userinput>
1773 RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
1774 00100000: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
1775 00100010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
1776 </screen>
1777 </para>
1778 <para>
1779 Fill a buffer with a pattern.
1780 <screen>
1781 RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
1782 RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
1783 00100000: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
1784 00100010: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
1785 </screen>
1786       </para>
1787     </refsect1>
1788   </refentry>
1789
1790 <!-- ******** ping *************************************************** -->
1791   <refentry id="ping-command">
1792     <refnamediv>
1793       <refname>ping</refname>
1794       <refpurpose>Verify network connectivity</refpurpose>
1795     </refnamediv>
1796     <refsynopsisdiv>
1797       <cmdsynopsis>
1798         <command>ping</command>
1799         <arg>-v </arg>
1800         <arg>-i <replaceable> local_IP_address</replaceable></arg>
1801         <arg>-l <replaceable> length</replaceable></arg>
1802         <arg>-n <replaceable> count</replaceable></arg>
1803         <arg>-t <replaceable> timeout</replaceable></arg>
1804         <arg>-r <replaceable> rate</replaceable></arg>
1805         <arg choice="req">-h <replaceable> server_IP_address</replaceable></arg>
1806       </cmdsynopsis>
1807     </refsynopsisdiv>
1808     <refsect1>
1809       <title>Arguments</title>
1810       <informaltable frame="all">
1811         <tgroup cols="4" colsep="1" rowsep="1" align="left">
1812           <colspec colname="c1">
1813           <colspec colname="c2">
1814           <colspec colname="c3">
1815           <colspec colname="c4">
1816           <thead>
1817             <row>
1818               <entry>Name</entry>
1819               <entry>Type</entry>
1820               <entry>Description</entry>
1821               <entry>Default</entry>
1822             </row>
1823           </thead>
1824           <tbody>
1825             <row>
1826               <entry>-v</entry>
1827               <entry>Boolean</entry>
1828               <entry>Be verbose, displaying information about each packet sent.</entry>
1829               <entry><emphasis>quiet</emphasis></entry>
1830             </row>
1831             <row>
1832               <entry>-n <replaceable>local_IP_address</replaceable></entry>
1833               <entry>Number</entry>
1834               <entry>Controls the number of packets to be sent.</entry>
1835               <entry>10</entry>
1836             </row>
1837             <row>
1838               <entry>-i <replaceable>local_IP_address</replaceable></entry>
1839               <entry>Numeric IP or DNS name</entry>
1840               <entry>The IP address RedBoot should use.</entry>
1841               <entry>Value set by <command>ip_address</command></entry>
1842             </row>
1843             <row>
1844               <entry>-h <replaceable>server_IP_address</replaceable></entry>
1845               <entry>Numeric IP or DNS name</entry>
1846               <entry>The IP address of the host to contact.</entry>
1847               <entry><emphasis>none</emphasis></entry>
1848             </row>
1849             <row>
1850               <entry>-l <replaceable>length</replaceable></entry>
1851               <entry>Number</entry>
1852               <entry>The length of the ICMP data payload.</entry>
1853               <entry>64</entry>
1854             </row>
1855             <row>
1856               <entry>-r <replaceable>length</replaceable></entry>
1857               <entry>Number</entry>
1858               <entry>How fast to deliver packets, i.e. time between successive sends.
1859 A value of 0 sends packets as quickly as possible.</entry>
1860               <entry>1000ms (1 second)</entry>
1861             </row>
1862             <row>
1863               <entry>-t <replaceable>length</replaceable></entry>
1864               <entry>Number</entry>
1865               <entry>How long to wait for the round-trip to complete, specified in milliseconds.</entry>
1866               <entry>1000ms (1 second)</entry>
1867             </row>
1868           </tbody>
1869         </tgroup>
1870       </informaltable>
1871     </refsect1>
1872     <refsect1>
1873       <title>Description</title>
1874       <para>
1875 The <command>ping</command> command checks the connectivity of the local network by sending
1876 special (ICMP) packets to a specific host. These packets should be automatically
1877 returned by that host. The command will indicate how many of these round-trips
1878 were successfully completed.
1879       </para>
1880     </refsect1>
1881     <refsect1>
1882       <title>Examples</title>
1883       <para>
1884 Test connectivity to host 192.168.1.101.
1885 <screen>
1886 RedBoot> <userinput>ping -h 192.168.1.101</userinput>
1887 Network PING - from 192.168.1.31 to 192.168.1.101
1888 PING - received 10 of 10 expected
1889 </screen>
1890 </para>
1891 <para>
1892 Test connectivity to host 192.168.1.101, with verbose reporting.
1893 <screen>
1894 RedBoot> <userinput>ping -h 192.168.1.101 -v -n 4</userinput>
1895 Network PING - from 192.168.1.31 to 192.168.1.101
1896  seq: 1, time: 1 (ticks)
1897  seq: 2, time: 1 (ticks)
1898  seq: 3, time: 1 (ticks)
1899  seq: 4, time: 1 (ticks)
1900 PING - received 10 of 10 expected
1901 </screen>
1902 </para>
1903 <para>
1904 <screen>
1905 Test connectivity to a non-existent host (192.168.1.109).
1906 RedBoot> <userinput>ping -h 192.168.1.109 -v -n 4</userinput>
1907 PING: Cannot reach server '192.168.1.109' (192.168.1.109)
1908 </screen>
1909       </para>
1910     </refsect1>
1911   </refentry>
1912
1913 <!-- ******** reset *************************************************** -->
1914   <refentry id="reset-command">
1915     <refnamediv>
1916       <refname>reset</refname>
1917       <refpurpose>Reset the device</refpurpose>
1918     </refnamediv>
1919     <refsynopsisdiv>
1920       <cmdsynopsis>
1921         <command>reset</command>
1922       </cmdsynopsis>
1923     </refsynopsisdiv>
1924     <refsect1>
1925       <title>Arguments</title>
1926 <para><emphasis>None</emphasis></para>
1927     </refsect1>
1928     <refsect1>
1929       <title>Description</title>
1930       <para>
1931 The <command>reset</command> command causes the target platform to be reset.
1932 Where possible (hardware support permitting), this will be
1933 equivalent to a power-on reset condition.
1934       </para>
1935     </refsect1>
1936     <refsect1>
1937       <title>Examples</title>
1938       <para>
1939 Reset the platform.
1940 <screen>
1941 RedBoot> <userinput>reset</userinput>
1942 ... Resetting.+... Waiting for network card: .
1943 Socket Communications, Inc: Low Power Ethernet CF Revision C 5V/3.3V 08/27/98
1944 Ethernet eth0: MAC address 00:c0:1b:00:ba:28
1945 IP: 192.168.1.29, Default server: 192.168.1.101
1946
1947 RedBoot(tm) bootstrap and debug environment [ROM]
1948 Non-certified release, version UNKNOWN - built 10:41:41, May 14 2002
1949
1950 Platform: Compaq iPAQ Pocket PC (StrongARM 1110)
1951 Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
1952
1953 RAM: 0x00000000-0x01fc0000, 0x00014748-0x01f71000 available
1954 FLASH: 0x50000000 - 0x51000000, 64 blocks of 0x00040000 bytes each.
1955 RedBoot>
1956 </screen>
1957       </para>
1958     </refsect1>
1959   </refentry>
1960
1961
1962 <!-- ******** version *************************************************** -->
1963   <refentry id="version-command">
1964     <refnamediv>
1965       <refname>version</refname>
1966       <refpurpose>Display RedBoot version information</refpurpose>
1967     </refnamediv>
1968     <refsynopsisdiv>
1969       <cmdsynopsis>
1970         <command>version</command>
1971       </cmdsynopsis>
1972     </refsynopsisdiv>
1973     <refsect1>
1974       <title>Arguments</title>
1975       <para><emphasis>None</emphasis></para>
1976     </refsect1>
1977     <refsect1>
1978       <title>Description</title>
1979       <para>The <command>version</command> command simply displays version information about RedBoot.
1980       </para>
1981     </refsect1>
1982     <refsect1>
1983       <title>Examples</title>
1984       <para>
1985 Display RedBoot's version.
1986 <screen>
1987 RedBoot> <userinput>version</userinput>
1988 RedBoot(tm) debug environment - built 09:12:03, Feb 12 2001
1989 Platform: XYZ (PowerPC 860)
1990 Copyright (C) 2000, 2001, Red Hat, Inc.
1991 RAM: 0x00000000-0x00400000
1992 </screen>
1993       </para>
1994     </refsect1>
1995   </refentry>
1996
1997 </sect1>
1998
1999 <sect1 id="Flash-Image-System">
2000 <title>Flash Image System (FIS)</title>
2001 <para><indexterm><primary>commands</primary><secondary>flash image system
2002 </secondary></indexterm><indexterm><primary>flash image system commands</primary>
2003 </indexterm><indexterm><primary>commands</primary><secondary>fis</secondary>
2004 </indexterm><indexterm><primary>fis commands</primary></indexterm>If the platform
2005 has flash memory, RedBoot can use this for image storage. Executable images,
2006 as well as data, can be stored in flash in a simple file store. The <command>
2007 fis</command> command (fis is short for Flash Image System) is used to
2008 manipulate and maintain flash images.
2009 </para>
2010
2011 <!-- ******** fis init ************************************************ -->
2012
2013   <refentry id="fis-init-command">
2014     <refnamediv>
2015       <refname>fis init</refname>
2016       <refpurpose>Initialize Flash Image System (FIS)</refpurpose>
2017     </refnamediv>
2018     <refsynopsisdiv>
2019       <cmdsynopsis>
2020         <command>fis init</command>
2021         <arg><replaceable>-f</replaceable></arg>
2022       </cmdsynopsis>
2023     </refsynopsisdiv>
2024     <refsect1>
2025       <title>Arguments</title>
2026       <informaltable frame="all">
2027         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2028           <colspec colname="c1">
2029           <colspec colname="c2">
2030           <colspec colname="c3">
2031           <colspec colname="c4">
2032           <thead>
2033             <row>
2034               <entry>Name</entry>
2035               <entry>Type</entry>
2036               <entry>Description</entry>
2037               <entry>Default</entry>
2038             </row>
2039           </thead>
2040           <tbody>
2041             <row>
2042               <entry>-f</entry>
2043               <entry></entry>
2044               <entry>All blocks of flash memory (except for the boot
2045               blocks) will be erased as part of the initialization
2046               procedure.</entry>
2047               <entry></entry>
2048             </row>
2049           </tbody>
2050         </tgroup>
2051       </informaltable>
2052     </refsect1>
2053     <refsect1>
2054       <title>Description</title>
2055
2056        <para>This command is used to initialize the Flash Image System
2057        (FIS). It should normally only be executed once, when RedBoot
2058        is first installed on the hardware. If the reserved images or
2059        their sizes in the FIS change, due to a different configuration
2060        of RedBoot being used, it may be necessary to issue the command
2061        again though.
2062
2063         <note><para>Subsequent executions will cause loss of
2064        previously stored information in the FIS.</para></note>
2065      </para>
2066     </refsect1>
2067     <refsect1>
2068       <title>Examples</title>
2069       <para>
2070 Initialize the FIS directory.
2071 <screen>
2072 RedBoot> <userinput>fis init</userinput>
2073 About to initialize [format] flash image system - continue (y/n)? <userinput>y</userinput>
2074 *** Initialize FLASH Image System
2075     Warning: device contents not erased, some blocks may not be usable
2076 ... Erase from 0x00070000-0x00080000: .
2077 ... Program from 0x0606f000-0x0607f000 at 0x00070000: .
2078 </screen>
2079 </para>
2080
2081       <para>
2082 Initialize the FIS directory and all of flash memory, except for first
2083 blocks of the flash where the boot monitor resides.
2084 <screen>
2085 RedBoot> <userinput>fis init -f</userinput>
2086 About to initialize [format] flash image system - continue (y/n)? <userinput>y</userinput>
2087 *** Initialize FLASH Image System
2088 ... Erase from 0x00020000-0x00070000: .....
2089 ... Erase from 0x00080000-0x00080000:
2090 ... Erase from 0x00070000-0x00080000: .
2091 ... Program from 0x0606f000-0x0607f000 at 0x00070000: .
2092 </screen>
2093 </para>
2094 </refsect1>
2095 </refentry>
2096
2097 <!-- ******** fis list ************************************************ -->
2098   <refentry id="fis-list-command">
2099     <refnamediv>
2100       <refname>fis list</refname>
2101       <refpurpose>List Flash Image System directory</refpurpose>
2102     </refnamediv>
2103     <refsynopsisdiv>
2104       <cmdsynopsis>
2105         <command>fis list</command>
2106         <arg><replaceable>-c</replaceable></arg>
2107         <arg><replaceable>-d</replaceable></arg>
2108       </cmdsynopsis>
2109     </refsynopsisdiv>
2110     <refsect1>
2111       <title>Arguments</title>
2112       <informaltable frame="all">
2113         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2114           <colspec colname="c1">
2115           <colspec colname="c2">
2116           <colspec colname="c3">
2117           <colspec colname="c4">
2118           <thead>
2119             <row>
2120               <entry>Name</entry>
2121               <entry>Type</entry>
2122               <entry>Description</entry>
2123               <entry>Default</entry>
2124             </row>
2125           </thead>
2126           <tbody>
2127             <row>
2128               <entry>-c</entry>
2129               <entry></entry>
2130               <entry>Show image checksum instead of memory address
2131               (column <computeroutput>Mem addr</computeroutput> is
2132               replaced by
2133               <computeroutput>Checksum</computeroutput>).</entry>
2134               <entry></entry>
2135             </row>
2136             <row>
2137               <entry>-d</entry>
2138               <entry></entry>
2139               <entry>Show image data length instead of amount of flash
2140               occupied by image (column
2141               <computeroutput>Length</computeroutput> is replaced by
2142               <computeroutput>Datalen</computeroutput>).</entry>
2143               <entry></entry>
2144             </row>
2145           </tbody>
2146         </tgroup>
2147       </informaltable>
2148     </refsect1>
2149     <refsect1>
2150       <title>Description</title>
2151 <para>This command lists the images currently available in the FIS. Certain
2152 images used by RedBoot have fixed names and have reserved slots in the
2153 FIS (these can be seen after using the <command>fis init</command>
2154 command). Other images can be manipulated by the user.</para>
2155 <note><para>The images are listed in the order they appear in the FIS
2156 directory, not by name or creation time.</para></note>
2157     </refsect1>
2158
2159     <refsect1>
2160       <title>Examples</title>
2161       <para>
2162 List the FIS directory.
2163 <screen>
2164 RedBoot> <userinput>fis list</userinput>
2165 Name              FLASH addr  Mem addr    Length      Entry point
2166 RedBoot           0x00000000  0x00000000  0x00020000  0x00000000
2167 RedBoot config    0x0007F000  0x0007F000  0x00001000  0x00000000
2168 FIS directory     0x00070000  0x00070000  0x0000F000  0x00000000
2169 </screen>
2170 </para>
2171
2172       <para>
2173 List the FIS directory, with image checksums substituted for
2174 memory addresses.
2175 <screen>
2176 RedBoot> <userinput>fis list -c</userinput>
2177 Name              FLASH addr  Checksum    Length      Entry point
2178 RedBoot           0x00000000  0x00000000  0x00020000  0x00000000
2179 RedBoot config    0x0007F000  0x00000000  0x00001000  0x00000000
2180 FIS directory     0x00070000  0x00000000  0x0000F000  0x00000000
2181 </screen>
2182 </para>
2183
2184       <para>
2185 List the FIS directory with image data lengths substituted for flash
2186 block reservation lengths.
2187 <screen>
2188 RedBoot> <userinput>fis list -d</userinput>
2189 Name              FLASH addr  Mem addr    Datalen     Entry point
2190 RedBoot           0x00000000  0x00000000  0x00000000  0x00000000
2191 RedBoot config    0x0007F000  0x0007F000  0x00000000  0x00000000
2192 FIS directory     0x00070000  0x00070000  0x00000000  0x00000000
2193 </screen>
2194 </para>
2195 </refsect1>
2196 </refentry>
2197
2198 <!-- ******** fis free ************************************************ -->
2199
2200   <refentry id="fis-free-command">
2201     <refnamediv>
2202       <refname>fis free</refname>
2203       <refpurpose>Free flash image</refpurpose>
2204     </refnamediv>
2205     <refsynopsisdiv>
2206       <cmdsynopsis>
2207         <command>fis free</command>
2208       </cmdsynopsis>
2209     </refsynopsisdiv>
2210     <refsect1>
2211       <title>Description</title>
2212
2213
2214 <para>This command shows which areas of the flash memory are currently
2215 not in use. When a block contains non-erased contents it is considered
2216 in use. Since it is possible to force an image to be loaded at a
2217 particular flash location, this command can be used to check whether
2218 that location is in use by any other image.</para>
2219
2220 <note><para>There is currently no cross-checking between actual flash
2221 contents and the FIS directory, which mans that there could be a
2222 segment of flash which is not erased that does not correspond to a
2223 named image, or vice-versa.</para></note>
2224     </refsect1>
2225
2226     <refsect1>
2227       <title>Examples</title>
2228       <para>
2229 Show free flash areas.
2230 <screen>
2231 RedBoot> <userinput>fis free</userinput>
2232         0xA0040000 .. 0xA07C0000
2233         0xA0840000 .. 0xA0FC0000
2234 </screen></para>
2235 </refsect1>
2236 </refentry>
2237
2238 <!-- ******** fis create ************************************************ -->
2239
2240   <refentry id="fis-create-command">
2241     <refnamediv>
2242       <refname>fis create</refname>
2243       <refpurpose>Create flash image</refpurpose>
2244     </refnamediv>
2245     <refsynopsisdiv>
2246       <cmdsynopsis>
2247         <command>fis create</command>
2248         <arg choice="req">-b <replaceable> data address</replaceable></arg>
2249         <arg choice="req">-l <replaceable> length</replaceable></arg>
2250         <arg>-f <replaceable> flash address</replaceable></arg>
2251         <arg>-e <replaceable> entry</replaceable></arg>
2252         <arg>-r <replaceable> relocation address</replaceable></arg>
2253         <arg>-s <replaceable> data length</replaceable></arg>
2254         <arg>-n </arg>
2255         <arg><replaceable>name</replaceable></arg>
2256       </cmdsynopsis>
2257     </refsynopsisdiv>
2258     <refsect1>
2259       <title>Arguments</title>
2260       <informaltable frame="all">
2261         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2262           <colspec colname="c1">
2263           <colspec colname="c2">
2264           <colspec colname="c3">
2265           <colspec colname="c4">
2266           <thead>
2267             <row>
2268               <entry>Name</entry>
2269               <entry>Type</entry>
2270               <entry>Description</entry>
2271               <entry>Default</entry>
2272             </row>
2273           </thead>
2274           <tbody>
2275             <row>
2276               <entry>-b</entry>
2277               <entry>Number</entry>
2278               <entry>Address of data to be written to the flash.</entry>
2279               <entry>Address of last loaded file. If not set in a load
2280               operation, it must be specified.</entry>
2281             </row>
2282             <row>
2283               <entry>-l</entry>
2284               <entry>Number</entry>
2285               <entry>Length of flash area to occupy. If specified, and
2286               the named image already exists, the length must match
2287               the value in the FIS directory.</entry>
2288               <entry>Length of area reserved in FIS directory if the
2289               image already exists, or the length of the last loaded
2290               file. If neither are set, it must be specified.</entry>
2291             </row>
2292             <row>
2293               <entry>-f</entry>
2294               <entry>Number</entry>
2295               <entry>Address of flash area to occopy.</entry>
2296               <entry>The address of an area reserved in the FIS
2297               directory for extant images. Otherwise the first free block
2298               which is large enough will be used.</entry>
2299             </row>
2300             <row>
2301               <entry>-e</entry>
2302               <entry>Number</entry>
2303               <entry>Entry address for an executable image, used by
2304               the <command>fis load</command> command.</entry>
2305               <entry>The entry address of last loaded file.</entry>
2306             </row>
2307             <row>
2308               <entry>-r</entry>
2309               <entry>Number</entry>
2310               <entry>Address where the image should be relocated to by
2311               the <command>fis load</command> command. This is only
2312               relevant for images that will be loaded with the
2313               <command>fis load</command> command.</entry>
2314               <entry>The load address of the last loaded file.</entry>
2315             </row>
2316             <row>
2317               <entry>-s</entry>
2318               <entry>Number</entry>
2319               <entry>Actual length of data written to image. This is
2320               used to control the range over which the checksum is
2321               made.</entry>
2322               <entry>It defaults to the length of the last loaded
2323               file.</entry>
2324             </row>
2325             <row>
2326               <entry>-n</entry>
2327               <entry></entry>
2328               <entry>When set, no image data will be written to the
2329               flash. Only the FIS directory will be updated.</entry>
2330               <entry></entry>
2331             </row>
2332             <row>
2333               <entry><replaceable>name</replaceable></entry>
2334               <entry>String</entry>
2335               <entry>Name of flash image.</entry>
2336               <entry></entry>
2337             </row>
2338           </tbody>
2339         </tgroup>
2340       </informaltable>
2341     </refsect1>
2342     <refsect1>
2343       <title>Description</title>
2344 <para>This command creates an image in the FIS directory. The data for the
2345 image must exist in RAM memory before the copy. Typically, you would use the
2346 RedBoot <command>load</command> command to load file into
2347 RAM and then the <command>fis create</command> command to write
2348 it to a flash image.</para>
2349 </refsect1>
2350
2351     <refsect1>
2352       <title>Examples</title>
2353       <para>Trying to create an extant image, will require the action
2354       to be verified.
2355 <screen>
2356 RedBoot> <userinput>fis create RedBoot -f 0xa0000000 -b 0x8c400000 -l 0x20000</userinput>
2357 An image named &lsquo;RedBoot&rsquo; exists - continue (y/n)? <userinput>n</userinput>
2358 </screen>
2359 </para>
2360
2361 <para>Create a new test image, let the command find a suitable place.
2362 <screen>
2363 RedBoot> <userinput>fis create junk -b 0x8c400000 -l 0x20000</userinput>
2364 ... Erase from 0xa0040000-0xa0060000: .
2365 ... Program from 0x8c400000-0x8c420000 at 0xa0040000: .
2366 ... Erase from 0xa0fe0000-0xa1000000: .
2367 ... Program from 0x8c7d0000-0x8c7f0000 at 0xa0fe0000: .
2368 </screen>
2369 </para>
2370
2371 <para>Update the RedBoot[RAM] image.
2372 <screen>
2373 RedBoot> <userinput>load redboot_RAM.img</userinput>
2374 Entry point: 0x060213c0, address range: 0x06020000-0x06036cc0
2375 RedBoot> <userinput>fis create RedBoot[RAM]</userinput>
2376 No memory address set.
2377 An image named 'RedBoot[RAM]' exists - continue (y/n)? <userinput>y</userinput>
2378 * CAUTION * about to program 'RedBoot[RAM]'
2379             at 0x00020000..0x00036cbf from 0x06020000 - continue (y/n)? <userinput>y</userinput>
2380 ... Erase from 0x00020000-0x00040000: ..
2381 ... Program from 0x06020000-0x06036cc0 at 0x00020000: ..
2382 ... Erase from 0x00070000-0x00080000: .
2383 ... Program from 0x0606f000-0x0607f000 at 0x00070000: .
2384 </screen>
2385 </para>
2386 </refsect1>
2387 </refentry>
2388
2389 <!-- ******** fis load ************************************************ -->
2390
2391   <refentry id="fis-load-command">
2392     <refnamediv>
2393       <refname>fis load</refname>
2394       <refpurpose>Load flash image</refpurpose>
2395     </refnamediv>
2396     <refsynopsisdiv>
2397       <cmdsynopsis>
2398         <command>fis load</command>
2399         <arg>-b <replaceable> load address</replaceable></arg>
2400         <arg>-c </arg>
2401         <arg>-d </arg>
2402         <arg><replaceable>name</replaceable></arg>
2403       </cmdsynopsis>
2404     </refsynopsisdiv>
2405     <refsect1>
2406       <title>Arguments</title>
2407       <informaltable frame="all">
2408         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2409           <colspec colname="c1">
2410           <colspec colname="c2">
2411           <colspec colname="c3">
2412           <colspec colname="c4">
2413           <thead>
2414             <row>
2415               <entry>Name</entry>
2416               <entry>Type</entry>
2417               <entry>Description</entry>
2418               <entry>Default</entry>
2419             </row>
2420           </thead>
2421           <tbody>
2422             <row>
2423               <entry>-b</entry>
2424               <entry>Number</entry>
2425               <entry>Address the image should be loaded to. Executable
2426               images normally load at the location to which the file
2427               was linked. This option allows the image to be loaded to
2428               a specific memory location, possibly overriding any
2429               assumed location.</entry>
2430               <entry>If not specified, the address associated with the
2431               image in the FIS directory will be used.</entry>
2432             </row>
2433             <row>
2434               <entry>-c</entry>
2435               <entry></entry>
2436               <entry>Compute and print the checksum of the image data
2437               after it has been loaded into memory.</entry>
2438             </row>
2439             <row>
2440               <entry>-d</entry>
2441               <entry></entry>
2442               <entry>Decompress gzipped image while copying it from
2443               flash to RAM.</entry>
2444             </row>
2445             <row>
2446               <entry><replaceable>name</replaceable></entry>
2447               <entry>String</entry>
2448               <entry>The name of the file, as shown in the FIS
2449               directory.</entry>
2450             </row>
2451           </tbody>
2452         </tgroup>
2453       </informaltable>
2454     </refsect1>
2455     <refsect1>
2456       <title>Description</title>
2457 <para>This command is used to transfer an image from flash memory to RAM.
2458 </para>
2459 <para>Once the image has been loaded, it may be executed using the
2460 <command>go</command> command.</para>
2461 </refsect1>
2462
2463     <refsect1>
2464       <title>Examples</title>
2465 <para>Load and run RedBoot[RAM] image.
2466 <screen>
2467 RedBoot> <userinput>fis load RedBoot[RAM]</userinput>
2468 RedBoot> <userinput>go</userinput>
2469 </screen>
2470 </para>
2471 </refsect1>
2472 </refentry>
2473
2474 <!-- ******** fis delete ************************************************ -->
2475
2476   <refentry id="fis-delete-command">
2477     <refnamediv>
2478       <refname>fis delete</refname>
2479       <refpurpose>Delete flash image</refpurpose>
2480     </refnamediv>
2481     <refsynopsisdiv>
2482       <cmdsynopsis>
2483         <command>fis delete</command>
2484         <arg choice="req"><replaceable>name</replaceable></arg>
2485       </cmdsynopsis>
2486     </refsynopsisdiv>
2487     <refsect1>
2488       <title>Arguments</title>
2489       <informaltable frame="all">
2490         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2491           <colspec colname="c1">
2492           <colspec colname="c2">
2493           <colspec colname="c3">
2494           <colspec colname="c4">
2495           <thead>
2496             <row>
2497               <entry>Name</entry>
2498               <entry>Type</entry>
2499               <entry>Description</entry>
2500               <entry>Default</entry>
2501             </row>
2502           </thead>
2503           <tbody>
2504             <row>
2505               <entry><replaceable>name</replaceable></entry>
2506               <entry>Number</entry>
2507               <entry>Name of image that should be deleted.</entry>
2508               <entry></entry>
2509             </row>
2510           </tbody>
2511         </tgroup>
2512       </informaltable>
2513     </refsect1>
2514     <refsect1>
2515       <title>Description</title>
2516 <para>This command removes an image from the FIS. The flash memory will be
2517 erased as part of the execution of this command, as well as removal of the
2518 name from the FIS directory.</para>
2519
2520 <note><para>Certain images are reserved by RedBoot and cannot be deleted.
2521 RedBoot will issue a warning if this is attempted.</para></note>
2522 </refsect1>
2523     <refsect1>
2524       <title>Examples</title>
2525 <para>
2526 <screen>
2527 RedBoot> <userinput>fis list</userinput>
2528 Name              flash addr   Mem addr    Length    Entry point
2529 RedBoot          0xA0000000   0xA0000000  0x020000  0x80000000
2530 RedBoot config   0xA0FC0000   0xA0FC0000  0x020000  0x00000000
2531 FIS directory    0xA0FE0000   0xA0FE0000  0x020000  0x00000000
2532 junk             0xA0040000   0x8C400000  0x020000  0x80000000
2533 RedBoot> <userinput>fis delete junk</userinput>
2534 Delete image &lsquo;junk&rsquo; - continue (y/n)? <userinput>y</userinput>
2535 ... Erase from 0xa0040000-0xa0060000: .
2536 ... Erase from 0xa0fe0000-0xa1000000: .
2537 ... Program from 0x8c7d0000-0x8c7f0000 at 0xa0fe0000: .
2538 </screen>
2539 </para>
2540 </refsect1>
2541 </refentry>
2542
2543 <!-- ******** fis lock ************************************************ -->
2544
2545   <refentry id="fis-lock-command">
2546     <refnamediv>
2547       <refname>fis lock</refname>
2548       <refpurpose>Lock flash area</refpurpose>
2549     </refnamediv>
2550     <refsynopsisdiv>
2551       <cmdsynopsis>
2552         <command>fis lock</command>
2553         <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2554         <arg choice="req">-l <replaceable>length</replaceable></arg>
2555       </cmdsynopsis>
2556     </refsynopsisdiv>
2557     <refsect1>
2558       <title>Arguments</title>
2559       <informaltable frame="all">
2560         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2561           <colspec colname="c1">
2562           <colspec colname="c2">
2563           <colspec colname="c3">
2564           <colspec colname="c4">
2565           <thead>
2566             <row>
2567               <entry>Name</entry>
2568               <entry>Type</entry>
2569               <entry>Description</entry>
2570               <entry>Default</entry>
2571             </row>
2572           </thead>
2573           <tbody>
2574             <row>
2575               <entry><replaceable>flash_address</replaceable></entry>
2576               <entry>Number</entry>
2577               <entry>Address of area to be locked.</entry>
2578               <entry></entry>
2579             </row>
2580             <row>
2581               <entry><replaceable>length</replaceable></entry>
2582               <entry>Number</entry>
2583               <entry>Length of area to be locked.</entry>
2584               <entry></entry>
2585             </row>
2586           </tbody>
2587         </tgroup>
2588       </informaltable>
2589     </refsect1>
2590     <refsect1>
2591       <title>Description</title>
2592 <para>This command is used to write-protect (lock) a portion of flash memory,
2593 to prevent accidental overwriting of images. In order to make any modifications
2594 to the flash, a matching <command>fis unlock</command> command must be
2595 issued. This command is optional and will only be provided on hardware
2596 which can support write-protection of the flash space.</para>
2597 <note>
2598 <para>Depending on the system, attempting to write to write-protected flash
2599 may generate errors or warnings, or be benignly quiet.  </para>
2600 </note>
2601 </refsect1>
2602
2603     <refsect1>
2604       <title>Examples</title>
2605 <para>Lock an area of the flash
2606 <screen>
2607 RedBoot> <userinput>fis lock -f 0xa0040000 -l 0x20000</userinput>
2608 ... Lock from 0xa0040000-0xa0060000: .
2609 </screen>
2610 </para>
2611 </refsect1>
2612 </refentry>
2613
2614 <!-- ******** fis unlock ************************************************ -->
2615
2616   <refentry id="fis-unlock-command">
2617     <refnamediv>
2618       <refname>fis unlock</refname>
2619       <refpurpose>Unlock flash area</refpurpose>
2620     </refnamediv>
2621     <refsynopsisdiv>
2622       <cmdsynopsis>
2623         <command>fis unlock</command>
2624         <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2625         <arg choice="req">-l <replaceable>length</replaceable></arg>
2626       </cmdsynopsis>
2627     </refsynopsisdiv>
2628     <refsect1>
2629       <title>Arguments</title>
2630       <informaltable frame="all">
2631         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2632           <colspec colname="c1">
2633           <colspec colname="c2">
2634           <colspec colname="c3">
2635           <colspec colname="c4">
2636           <thead>
2637             <row>
2638               <entry>Name</entry>
2639               <entry>Type</entry>
2640               <entry>Description</entry>
2641               <entry>Default</entry>
2642             </row>
2643           </thead>
2644           <tbody>
2645             <row>
2646               <entry><replaceable>flash_address</replaceable></entry>
2647               <entry>Number</entry>
2648               <entry>Address of area to be unlocked.</entry>
2649               <entry></entry>
2650             </row>
2651             <row>
2652               <entry><replaceable>length</replaceable></entry>
2653               <entry>Number</entry>
2654               <entry>Length of area to be unlocked.</entry>
2655               <entry></entry>
2656             </row>
2657           </tbody>
2658         </tgroup>
2659       </informaltable>
2660     </refsect1>
2661     <refsect1>
2662       <title>Description</title>
2663 <para>This command is used to unlock a portion of flash memory forcibly, allowing
2664 it to be updated. It must be issued for regions which have been locked before
2665 the FIS can reuse those portions of flash.</para>
2666 <note>
2667 <para>Some flash devices power up in locked state and always need to
2668 be manually unlocked before they can be written to.</para></note>
2669 </refsect1>
2670
2671     <refsect1>
2672       <title>Examples</title>
2673 <para>Unlock an area of the flash
2674 <screen>
2675 RedBoot> <userinput>fis unlock -f 0xa0040000 -l 0x20000</userinput>
2676 ... Unlock from 0xa0040000-0xa0060000: .
2677 </screen>
2678 </para>
2679 </refsect1>
2680 </refentry>
2681
2682 <!-- ******** fis erase ************************************************ -->
2683
2684   <refentry id="fis-erase-command">
2685     <refnamediv>
2686       <refname>fis erase</refname>
2687       <refpurpose>Erase flash area</refpurpose>
2688     </refnamediv>
2689     <refsynopsisdiv>
2690       <cmdsynopsis>
2691         <command>fis erase</command>
2692         <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2693         <arg choice="req">-l <replaceable>length</replaceable></arg>
2694       </cmdsynopsis>
2695     </refsynopsisdiv>
2696     <refsect1>
2697       <title>Arguments</title>
2698       <informaltable frame="all">
2699         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2700           <colspec colname="c1">
2701           <colspec colname="c2">
2702           <colspec colname="c3">
2703           <colspec colname="c4">
2704           <thead>
2705             <row>
2706               <entry>Name</entry>
2707               <entry>Type</entry>
2708               <entry>Description</entry>
2709               <entry>Default</entry>
2710             </row>
2711           </thead>
2712           <tbody>
2713             <row>
2714               <entry><replaceable>flash_address</replaceable></entry>
2715               <entry>Number</entry>
2716               <entry>Address of area to be erased.</entry>
2717               <entry></entry>
2718             </row>
2719             <row>
2720               <entry><replaceable>length</replaceable></entry>
2721               <entry>Number</entry>
2722               <entry>Length of area to be erased.</entry>
2723               <entry></entry>
2724             </row>
2725           </tbody>
2726         </tgroup>
2727       </informaltable>
2728     </refsect1>
2729     <refsect1>
2730       <title>Description</title>
2731 <para>This command is used to erase a portion of flash memory forcibly. There
2732 is no cross-checking to ensure that the area being erased does not correspond
2733 to an existing image.</para>
2734 </refsect1>
2735
2736     <refsect1>
2737       <title>Examples</title>
2738 <para>Erase an area of the flash
2739 <screen>
2740 RedBoot> <userinput>fis erase -f 0xa0040000 -l 0x20000</userinput>
2741 ... Erase from 0xa0040000-0xa0060000: .
2742 </screen>
2743 </para>
2744 </refsect1>
2745 </refentry>
2746
2747 <!-- ******** fis write ************************************************ -->
2748
2749   <refentry id="fis-write-command">
2750     <refnamediv>
2751       <refname>fis write</refname>
2752       <refpurpose>Write flash area</refpurpose>
2753     </refnamediv>
2754     <refsynopsisdiv>
2755       <cmdsynopsis>
2756         <command>fis write</command>
2757         <arg choice="req">-b <replaceable>mem_address</replaceable></arg>
2758         <arg choice="req">-l <replaceable>length</replaceable></arg>
2759         <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2760       </cmdsynopsis>
2761     </refsynopsisdiv>
2762     <refsect1>
2763       <title>Arguments</title>
2764       <informaltable frame="all">
2765         <tgroup cols="4" colsep="1" rowsep="1" align="left">
2766           <colspec colname="c1">
2767           <colspec colname="c2">
2768           <colspec colname="c3">
2769           <colspec colname="c4">
2770           <thead>
2771             <row>
2772               <entry>Name</entry>
2773               <entry>Type</entry>
2774               <entry>Description</entry>
2775               <entry>Default</entry>
2776             </row>
2777           </thead>
2778           <tbody>
2779             <row>
2780               <entry><replaceable>mem_address</replaceable></entry>
2781               <entry>Number</entry>
2782               <entry>Address of data to be written to flash.</entry>
2783               <entry></entry>
2784             </row>
2785             <row>
2786               <entry><replaceable>length</replaceable></entry>
2787               <entry>Number</entry>
2788               <entry>Length of data to be writtem.</entry>
2789               <entry></entry>
2790             </row>
2791             <row>
2792               <entry><replaceable>flash_address</replaceable></entry>
2793               <entry>Number</entry>
2794               <entry>Address of flash to write to.</entry>
2795               <entry></entry>
2796             </row>
2797           </tbody>
2798         </tgroup>
2799       </informaltable>
2800     </refsect1>
2801     <refsect1>
2802       <title>Description</title>
2803 <para>This command is used to write data from memory to flash. There
2804 is no cross-checking to ensure that the area being written to does not
2805 correspond to an existing image.</para>
2806 </refsect1>
2807
2808     <refsect1>
2809       <title>Examples</title>
2810 <para>Write an area of data to the flash
2811 <screen>
2812 RedBoot> <userinput>fis write -b 0x0606f000 -l 0x1000 -f 0x00020000</userinput>
2813 * CAUTION * about to program FLASH
2814             at 0x00020000..0x0002ffff from 0x0606f000 - continue (y/n)? <userinput>y</userinput>
2815 ... Erase from 0x00020000-0x00030000: .
2816 ... Program from 0x0606f000-0x0607f000 at 0x00020000: .
2817 </screen>
2818 </para>
2819 </refsect1>
2820 </refentry>
2821 </sect1>
2822
2823 <sect1 id="filesystem-commands">
2824 <title>Filesystem Interface</title>
2825
2826 <para>
2827 <indexterm><primary>commands</primary><secondary>filesystem access
2828 </secondary></indexterm><indexterm><primary>filesystem commands</primary>
2829 </indexterm><indexterm><primary>commands</primary><secondary>fs</secondary>
2830 </indexterm><indexterm><primary>fs commands</primary></indexterm>
2831
2832 If the platform has access to secondary storage, then RedBoot may be
2833 able to access a filesystem stored on this device. RedBoot can access
2834 FAT filesystems stored on IDE disks or CompactFlash devices and can
2835 use JFFS2 filesystems stored in FLASH memory. The
2836 <command>fs</command> command is used to manipulate files on
2837 filesystems. Applications may be loaded into memory using the
2838 <emphasis>file</emphasis> mode of the <command>load</command> command.
2839 </para>
2840
2841 <!-- ******** fs info ************************************************ -->
2842
2843 <refentry id="fs-info-command">
2844   <refnamediv>
2845     <refname>fs info</refname>
2846     <refpurpose>Print filesystem information</refpurpose>
2847   </refnamediv>
2848   <refsynopsisdiv>
2849     <cmdsynopsis>
2850       <command>fs info</command>
2851     </cmdsynopsis>
2852   </refsynopsisdiv>
2853   <refsect1>
2854     <title>Arguments</title>
2855       <para>
2856         The command takes no arguments.
2857       </para>
2858   </refsect1>
2859   <refsect1>
2860     <title>Description</title>
2861 <para>This command prints information about the filesystems that are
2862 available. Three lists are produced. The first is a list of the
2863 filsystem implementations available in RedBoot; names from this list
2864 may be used in the <parameter>-t</parameter> option to the <command>fs
2865 mount</command> command. The second list describes the block devices
2866 that are available for mounting a filesystem; names from this list may
2867 be used in the <parameter>-d</parameter> option to the <command>fs
2868 mount</command> command. The last list describes the filesystems that
2869 are already mounted.
2870 </para>
2871 </refsect1>
2872
2873   <refsect1>
2874     <title>Examples</title>
2875     <para>
2876 <screen>
2877 RedBoot> <userinput>fs info</userinput>
2878 Filesystems available:
2879 ramfs
2880 jffs2
2881
2882 Devices available:
2883 /dev/flash1
2884
2885 Mounted filesystems:
2886          Device Filesystem Mounted on
2887     &lt;undefined&gt;      ramfs /
2888     /dev/flash1      jffs2 /flash
2889 RedBoot></screen>
2890     </para>
2891   </refsect1>
2892 </refentry>
2893
2894 <!-- ******** fs mount ************************************************ -->
2895
2896 <refentry id="fs-mount-command">
2897   <refnamediv>
2898     <refname>fs mount</refname>
2899     <refpurpose>Mount a filesystem</refpurpose>
2900   </refnamediv>
2901   <refsynopsisdiv>
2902     <cmdsynopsis>
2903       <command>fs mount</command>
2904       <arg choice="opt">-d <replaceable>device</replaceable></arg>
2905       <arg choice="req">-t <replaceable>fstype</replaceable></arg>
2906       <arg choice="req">mountpoint</arg>
2907     </cmdsynopsis>
2908   </refsynopsisdiv>
2909   <refsect1>
2910     <title>Arguments</title>
2911     <informaltable frame="all">
2912       <tgroup cols="4" colsep="1" rowsep="1" align="left">
2913         <colspec colname="c1">
2914         <colspec colname="c2">
2915         <colspec colname="c3">
2916         <colspec colname="c4">
2917         <thead>
2918           <row>
2919             <entry>Name</entry>
2920             <entry>Type</entry>
2921             <entry>Description</entry>
2922             <entry>Default</entry>
2923           </row>
2924         </thead>
2925         <tbody>
2926           <row>
2927             <entry><replaceable>device</replaceable></entry>
2928             <entry>Number</entry>
2929             <entry>Device containing filsystem to mount.</entry>
2930             <entry>undefined</entry>
2931           </row>
2932           <row>
2933             <entry><replaceable>fstype</replaceable></entry>
2934             <entry>Number</entry>
2935             <entry>Filesystem type.</entry>
2936             <entry></entry>
2937           </row>
2938             <row>
2939               <entry><replaceable>mountpoint</replaceable></entry>
2940               <entry>String</entry>
2941               <entry>Pathname for filesystem root.</entry>
2942               <entry>/</entry>
2943             </row>
2944         </tbody>
2945       </tgroup>
2946     </informaltable>
2947   </refsect1>
2948   <refsect1>
2949     <title>Description</title>
2950 <para>This command is used make a filesystem available for access with
2951 the filesystem access commands. Three things need to be defined to do
2952 this. First, the name of the device on which the filesystem is stored
2953 needs to be given to the <parameter>-d</parameter> option. Secondly,
2954 the type of filesystem it is needs to be given to the
2955 <parameter>-t</parameter> option. Finally, the pathname by which the
2956 new filesystem will be accessed needs to be supplied. Following a
2957 successful mount, the root of the filesystem will be accessible
2958 at the mountpoint.
2959 </para>
2960 </refsect1>
2961
2962   <refsect1>
2963     <title>Examples</title>
2964 <para>Mount a JFF2 partititon:
2965 <screen>
2966 RedBoot> <userinput>fs info</userinput>
2967 Filesystems available:
2968 ramfs
2969 jffs2
2970
2971 Devices available:
2972 /dev/flash1
2973
2974 Mounted filesystems:
2975          Device Filesystem Mounted on
2976     &lt;undefined&gt;      ramfs /
2977 RedBoot> <userinput>fs mount -d /dev/flash1 -t jffs2 /flash</userinput>
2978 RedBoot> <userinput>fs info</userinput>
2979 Filesystems available:
2980 ramfs
2981 jffs2
2982
2983 Devices available:
2984 /dev/flash1
2985
2986 Mounted filesystems:
2987          Device Filesystem Mounted on
2988     &lt;undefined&gt;      ramfs /
2989     /dev/flash1      jffs2 /flash
2990 RedBoot>
2991 </screen>
2992     </para>
2993   </refsect1>
2994 </refentry>
2995
2996 <!-- ******** fs umount ************************************************ -->
2997
2998 <refentry id="fs-umount-command">
2999   <refnamediv>
3000     <refname>fs umount</refname>
3001     <refpurpose>Unmount filesystem</refpurpose>
3002   </refnamediv>
3003   <refsynopsisdiv>
3004     <cmdsynopsis>
3005       <command>fs umount</command>
3006       <arg choice="req"><replaceable>mountpoint</replaceable></arg>
3007     </cmdsynopsis>
3008   </refsynopsisdiv>
3009   <refsect1>
3010     <title>Arguments</title>
3011     <informaltable frame="all">
3012       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3013         <colspec colname="c1">
3014         <colspec colname="c2">
3015         <colspec colname="c3">
3016         <colspec colname="c4">
3017         <thead>
3018           <row>
3019             <entry>Name</entry>
3020             <entry>Type</entry>
3021             <entry>Description</entry>
3022             <entry>Default</entry>
3023           </row>
3024         </thead>
3025         <tbody>
3026             <row>
3027               <entry><replaceable>mountpoint</replaceable></entry>
3028               <entry>String</entry>
3029               <entry>Mountpoint of filesystem to unmount.</entry>
3030               <entry></entry>
3031             </row>
3032         </tbody>
3033       </tgroup>
3034     </informaltable>
3035   </refsect1>
3036   <refsect1>
3037     <title>Description</title>
3038 <para>This command removes a filesystem from being accessible using
3039 the filesystem commands. The single argument needs to be the
3040 mountpoint that was used when mounting the filesystem. This command
3041 will fail if the current directory is currently within the filesystem
3042 to be unmounted.
3043 </para>
3044 </refsect1>
3045
3046   <refsect1>
3047     <title>Examples</title>
3048 <para>Unmount a JFF2 partititon:
3049 <screen>
3050 RedBoot> <userinput>fs info</userinput>
3051 Filesystems available:
3052 ramfs
3053 jffs2
3054
3055 Devices available:
3056 /dev/flash1
3057
3058 Mounted filesystems:
3059          Device Filesystem Mounted on
3060     &lt;undefined&gt;      ramfs /
3061     /dev/flash1      jffs2 /flash
3062 RedBoot> <userinput>fs umount /flash</userinput>
3063 RedBoot> <userinput>fs info</userinput>
3064 Filesystems available:
3065 ramfs
3066 jffs2
3067
3068 Devices available:
3069 /dev/flash1
3070
3071 Mounted filesystems:
3072          Device Filesystem Mounted on
3073     &lt;undefined&gt;      ramfs /
3074 RedBoot>
3075 </screen>
3076     </para>
3077   </refsect1>
3078 </refentry>
3079
3080 <!-- ******** fs cd ************************************************ -->
3081
3082 <refentry id="fs-cd-command">
3083   <refnamediv>
3084     <refname>fs cd</refname>
3085     <refpurpose>Change filesystem directory</refpurpose>
3086   </refnamediv>
3087   <refsynopsisdiv>
3088     <cmdsynopsis>
3089       <command>fs cd</command>
3090       <arg choice="opt"><replaceable>directory</replaceable></arg>
3091     </cmdsynopsis>
3092   </refsynopsisdiv>
3093   <refsect1>
3094     <title>Arguments</title>
3095     <informaltable frame="all">
3096       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3097         <colspec colname="c1">
3098         <colspec colname="c2">
3099         <colspec colname="c3">
3100         <colspec colname="c4">
3101         <thead>
3102           <row>
3103             <entry>Name</entry>
3104             <entry>Type</entry>
3105             <entry>Description</entry>
3106             <entry>Default</entry>
3107           </row>
3108         </thead>
3109         <tbody>
3110             <row>
3111               <entry><replaceable>directory</replaceable></entry>
3112               <entry>String</entry>
3113               <entry>Pathname to directory to change to.</entry>
3114               <entry>Root directory</entry>
3115             </row>
3116         </tbody>
3117       </tgroup>
3118     </informaltable>
3119   </refsect1>
3120   <refsect1>
3121     <title>Description</title>
3122 <para>This command changes the current filesystem
3123 directory. Subsequent filesystem commands will be executed in the new
3124 directory. If no argument is given, then the current directory is set
3125 back to the root of the filesystem name space.
3126 </para>
3127 </refsect1>
3128
3129   <refsect1>
3130     <title>Examples</title>
3131     <para>Change current directory:
3132 <screen>
3133 RedBoot> <userinput>fs list</userinput>
3134 212416 d---------  3 size    128 .
3135 212416 d---------  3 size    128 ..
3136 211392 d---------  2 size     96 tests
3137 210368 ----------  1 size   4096 image
3138 RedBoot> <userinput>fs cd tests</userinput>
3139 RedBoot> <userinput>fs list</userinput>
3140 211392 d---------  2 size     96 .
3141 212416 d---------  3 size    128 ..
3142 205760 ----------  1 size  16384 test1
3143 RedBoot>
3144 </screen>
3145     </para>
3146   </refsect1>
3147 </refentry>
3148
3149 <!-- ******** fs mkdir ************************************************ -->
3150
3151 <refentry id="fs-mkdir-command">
3152   <refnamediv>
3153     <refname>fs mkdir</refname>
3154     <refpurpose>Create filesystem directory</refpurpose>
3155   </refnamediv>
3156   <refsynopsisdiv>
3157     <cmdsynopsis>
3158       <command>fs mkdir</command>
3159       <arg choice="req"><replaceable>directory</replaceable></arg>
3160     </cmdsynopsis>
3161   </refsynopsisdiv>
3162   <refsect1>
3163     <title>Arguments</title>
3164     <informaltable frame="all">
3165       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3166         <colspec colname="c1">
3167         <colspec colname="c2">
3168         <colspec colname="c3">
3169         <colspec colname="c4">
3170         <thead>
3171           <row>
3172             <entry>Name</entry>
3173             <entry>Type</entry>
3174             <entry>Description</entry>
3175             <entry>Default</entry>
3176           </row>
3177         </thead>
3178         <tbody>
3179             <row>
3180               <entry><replaceable>directory</replaceable></entry>
3181               <entry>String</entry>
3182               <entry>Pathname to directory to delete.</entry>
3183               <entry></entry>
3184             </row>
3185         </tbody>
3186       </tgroup>
3187     </informaltable>
3188   </refsect1>
3189   <refsect1>
3190     <title>Description</title>
3191 <para>This command creates (makes) a directory in the filesystem.
3192 </para>
3193 </refsect1>
3194
3195   <refsect1>
3196     <title>Examples</title>
3197     <para>Create directory:
3198 <screen>
3199 RedBoot> <userinput>fs list</userinput>
3200 212416 d---------  2 size    128 .
3201 212416 d---------  2 size    128 ..
3202 210368 ----------  1 size   4096 image
3203 RedBoot> <userinput>fs mkdir tests</userinput>
3204 RedBoot> <userinput>fs list</userinput>
3205 212416 d---------  3 size    128 .
3206 212416 d---------  3 size    128 ..
3207 211392 d---------  2 size     64 tests
3208 210368 ----------  1 size   4096 image
3209 RedBoot>
3210 </screen>
3211     </para>
3212   </refsect1>
3213 </refentry>
3214
3215 <!-- ******** fs deldir ************************************************ -->
3216
3217 <refentry id="fs-deldir-command">
3218   <refnamediv>
3219     <refname>fs deldir</refname>
3220     <refpurpose>Delete filesystem directory</refpurpose>
3221   </refnamediv>
3222   <refsynopsisdiv>
3223     <cmdsynopsis>
3224       <command>fs deldir</command>
3225       <arg choice="req"><replaceable>directory</replaceable></arg>
3226     </cmdsynopsis>
3227   </refsynopsisdiv>
3228   <refsect1>
3229     <title>Arguments</title>
3230     <informaltable frame="all">
3231       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3232         <colspec colname="c1">
3233         <colspec colname="c2">
3234         <colspec colname="c3">
3235         <colspec colname="c4">
3236         <thead>
3237           <row>
3238             <entry>Name</entry>
3239             <entry>Type</entry>
3240             <entry>Description</entry>
3241             <entry>Default</entry>
3242           </row>
3243         </thead>
3244         <tbody>
3245             <row>
3246               <entry><replaceable>directory</replaceable></entry>
3247               <entry>String</entry>
3248               <entry>Pathname to directory to delete.</entry>
3249               <entry></entry>
3250             </row>
3251         </tbody>
3252       </tgroup>
3253     </informaltable>
3254   </refsect1>
3255   <refsect1>
3256     <title>Description</title>
3257 <para>This command deletes a directory from the filesystem. If the
3258 directory contains files or other directories then this command will
3259 fail.
3260 </para>
3261 </refsect1>
3262
3263   <refsect1>
3264     <title>Examples</title>
3265     <para>Delete directory:
3266 <screen>
3267 RedBoot> <userinput>fs list</userinput>
3268 212416 d---------  3 size    128 .
3269 212416 d---------  3 size    128 ..
3270 211392 d---------  2 size     96 tests
3271 210368 ----------  1 size   4096 image
3272 RedBoot> <userinput>fs deldir tests</userinput>
3273 RedBoot> <userinput>fs list</userinput>
3274 212416 d---------  2 size    128 .
3275 212416 d---------  2 size    128 ..
3276 210368 ----------  1 size   4096 image
3277 RedBoot>
3278 </screen>
3279     </para>
3280   </refsect1>
3281 </refentry>
3282
3283 <!-- ******** fs del ************************************************ -->
3284
3285 <refentry id="fs-del-command">
3286   <refnamediv>
3287     <refname>fs del</refname>
3288     <refpurpose>Delete file</refpurpose>
3289   </refnamediv>
3290   <refsynopsisdiv>
3291     <cmdsynopsis>
3292       <command>fs del</command>
3293       <arg choice="req"><replaceable>file</replaceable></arg>
3294     </cmdsynopsis>
3295   </refsynopsisdiv>
3296   <refsect1>
3297     <title>Arguments</title>
3298     <informaltable frame="all">
3299       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3300         <colspec colname="c1">
3301         <colspec colname="c2">
3302         <colspec colname="c3">
3303         <colspec colname="c4">
3304         <thead>
3305           <row>
3306             <entry>Name</entry>
3307             <entry>Type</entry>
3308             <entry>Description</entry>
3309             <entry>Default</entry>
3310           </row>
3311         </thead>
3312         <tbody>
3313             <row>
3314               <entry><replaceable>file</replaceable></entry>
3315               <entry>String</entry>
3316               <entry>Pathname of file to delete.</entry>
3317               <entry></entry>
3318             </row>
3319         </tbody>
3320       </tgroup>
3321     </informaltable>
3322   </refsect1>
3323   <refsect1>
3324     <title>Description</title>
3325 <para>This command deletes a file from the filesystem.
3326 </para>
3327 </refsect1>
3328
3329   <refsect1>
3330     <title>Examples</title>
3331     <para>Change current directory:
3332 <screen>
3333 RedBoot> <userinput>fs list tests</userinput>
3334 211392 d---------  2 size     96 .
3335 212416 d---------  3 size    128 ..
3336 205760 ----------  1 size  16384 test1
3337 RedBoot> <userinput>fs del tests/test1</userinput>
3338 RedBoot> <userinput>fs list tests</userinput>
3339 211392 d---------  2 size     96 .
3340 212416 d---------  3 size    128 ..
3341 RedBoot>
3342 </screen>
3343     </para>
3344   </refsect1>
3345 </refentry>
3346
3347 <!-- ******** fs move ************************************************ -->
3348
3349 <refentry id="fs-move-command">
3350   <refnamediv>
3351     <refname>fs move</refname>
3352     <refpurpose>Move file</refpurpose>
3353   </refnamediv>
3354   <refsynopsisdiv>
3355     <cmdsynopsis>
3356       <command>fs move</command>
3357       <arg choice="req"><replaceable>source</replaceable></arg>
3358       <arg choice="req"><replaceable>dest</replaceable></arg>
3359     </cmdsynopsis>
3360   </refsynopsisdiv>
3361   <refsect1>
3362     <title>Arguments</title>
3363     <informaltable frame="all">
3364       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3365         <colspec colname="c1">
3366         <colspec colname="c2">
3367         <colspec colname="c3">
3368         <colspec colname="c4">
3369         <thead>
3370           <row>
3371             <entry>Name</entry>
3372             <entry>Type</entry>
3373             <entry>Description</entry>
3374             <entry>Default</entry>
3375           </row>
3376         </thead>
3377         <tbody>
3378             <row>
3379               <entry><replaceable>source</replaceable></entry>
3380               <entry>String</entry>
3381               <entry>Pathname of file to move.</entry>
3382               <entry></entry>
3383             </row>
3384             <row>
3385               <entry><replaceable>dest</replaceable></entry>
3386               <entry>String</entry>
3387               <entry>Pathname to new file location.</entry>
3388               <entry></entry>
3389             </row>
3390         </tbody>
3391       </tgroup>
3392     </informaltable>
3393   </refsect1>
3394   <refsect1>
3395     <title>Description</title>
3396 <para>This command moves a file within a filesystem. This command will
3397 fail if the destination file already exists, or is in a different
3398 filesystem.
3399 </para>
3400 </refsect1>
3401
3402   <refsect1>
3403     <title>Examples</title>
3404     <para>Rename a file:
3405 <screen>
3406 RedBoot> <userinput>fs list tests</userinput>
3407 211392 d---------  2 size     96 .
3408 212416 d---------  3 size    128 ..
3409 205760 ----------  1 size  12288 test1
3410 RedBoot> <userinput>fs move tests/test1 tests/test2</userinput>
3411 RedBoot> <userinput>fs list tests</userinput>
3412 211392 d---------  2 size    128 .
3413 212416 d---------  3 size    128 ..
3414 205760 ----------  1 size  12288 test2
3415 RedBoot>
3416 </screen>
3417     </para>
3418   </refsect1>
3419 </refentry>
3420
3421 <!-- ******** fs list ************************************************ -->
3422
3423 <refentry id="fs-list-command">
3424   <refnamediv>
3425     <refname>fs list</refname>
3426     <refpurpose>List filesystem directory</refpurpose>
3427   </refnamediv>
3428   <refsynopsisdiv>
3429     <cmdsynopsis>
3430       <command>fs list</command>
3431       <arg choice="opt"><replaceable>directory</replaceable></arg>
3432     </cmdsynopsis>
3433   </refsynopsisdiv>
3434   <refsect1>
3435     <title>Arguments</title>
3436     <informaltable frame="all">
3437       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3438         <colspec colname="c1">
3439         <colspec colname="c2">
3440         <colspec colname="c3">
3441         <colspec colname="c4">
3442         <thead>
3443           <row>
3444             <entry>Name</entry>
3445             <entry>Type</entry>
3446             <entry>Description</entry>
3447             <entry>Default</entry>
3448           </row>
3449         </thead>
3450         <tbody>
3451             <row>
3452               <entry><replaceable>directory</replaceable></entry>
3453               <entry>String</entry>
3454               <entry>Pathname to directory to list.</entry>
3455               <entry>Current directory</entry>
3456             </row>
3457         </tbody>
3458       </tgroup>
3459     </informaltable>
3460   </refsect1>
3461   <refsect1>
3462     <title>Description</title>
3463 <para>This command prints a list of the contents of the named
3464 directory. Each line of the listing starts with the file's inode
3465 number, which is its address in the filesystem. Following is a set of
3466 UNIX-like access flags, the first character of this will be a
3467 &rdquo;d&ldquo; if this entry is a directory. The third item indicates
3468 the number of links to the file. Following this is the size of the
3469 file in bytes and the last item is its name.
3470 </para>
3471 </refsect1>
3472
3473   <refsect1>
3474     <title>Examples</title>
3475     <para>List the current directory:
3476 <screen>
3477 RedBoot> <userinput>fs list</userinput>
3478 212416 d---------  3 size    128 .
3479 212416 d---------  3 size    128 ..
3480 211392 ----------  1 size   4096 image
3481 206784 d---------  2 size     96 tests
3482 RedBoot>
3483 </screen>
3484     </para>
3485 <para>
3486 List a subdirectory:
3487 <screen>
3488 RedBoot> fs list tests
3489 206784 d---------  2 size     96 .
3490 212416 d---------  3 size    128 ..
3491 205760 ----------  1 size  16384 test1
3492 RedBoot>
3493 </screen>
3494 </para>
3495   </refsect1>
3496 </refentry>
3497
3498 <!-- ******** fs write ************************************************ -->
3499
3500 <refentry id="fs-write-command">
3501   <refnamediv>
3502     <refname>fs write</refname>
3503     <refpurpose>Write to filesystem</refpurpose>
3504   </refnamediv>
3505   <refsynopsisdiv>
3506     <cmdsynopsis>
3507       <command>fs write</command>
3508       <arg choice="opt">-b <replaceable>mem_address</replaceable></arg>
3509       <arg choice="opt">-l <replaceable>length</replaceable></arg>
3510       <arg choice="req">name</arg>
3511     </cmdsynopsis>
3512   </refsynopsisdiv>
3513   <refsect1>
3514     <title>Arguments</title>
3515     <informaltable frame="all">
3516       <tgroup cols="4" colsep="1" rowsep="1" align="left">
3517         <colspec colname="c1">
3518         <colspec colname="c2">
3519         <colspec colname="c3">
3520         <colspec colname="c4">
3521         <thead>
3522           <row>
3523             <entry>Name</entry>
3524             <entry>Type</entry>
3525             <entry>Description</entry>
3526             <entry>Default</entry>
3527           </row>
3528         </thead>
3529         <tbody>
3530           <row>
3531             <entry><replaceable>mem_address</replaceable></entry>
3532             <entry>Number</entry>
3533             <entry>Address of data to be written to flash.</entry>
3534             <entry>Address of last loaded file. If not set by a load
3535             operation it must be specified.</entry>
3536           </row>
3537           <row>
3538             <entry><replaceable>length</replaceable></entry>
3539             <entry>Number</entry>
3540             <entry>Length of data to be written.</entry>
3541             <entry>Length of last loaded file.</entry>
3542           </row>
3543             <row>
3544               <entry><replaceable>name</replaceable></entry>
3545               <entry>String</entry>
3546               <entry>Name of file to create.</entry>
3547               <entry></entry>
3548             </row>
3549         </tbody>
3550       </tgroup>
3551     </informaltable>
3552   </refsect1>
3553   <refsect1>
3554     <title>Description</title>
3555 <para>This command is used to write data from memory to a file. If the
3556 file does not exist it will be created. If it does exist, then it will
3557 be overwritten with the new contents.</para>
3558 </refsect1>
3559
3560   <refsect1>
3561     <title>Examples</title>
3562 <para>Write an area of data to a file
3563 <screen>
3564 RedBoot> <userinput>fs write -b 0x0606f000 -l 0x1000 image</userinput>
3565 RedBoot> <userinput>fs list</userinput>
3566 212416 d---------  3 size    128 .
3567 212416 d---------  3 size    128 ..
3568 211392 ----------  1 size   4096 image
3569 206784 d---------  2 size     96 tests
3570 RedBoot>
3571 </screen>
3572     </para>
3573   </refsect1>
3574 </refentry>
3575
3576
3577
3578 </sect1>
3579
3580
3581 <sect1 id="Persistent-State-Flash">
3582 <title>Persistent State Flash-based Configuration and Control</title>
3583 <para><indexterm><primary>persistent state flash-based configuration and control
3584 </primary></indexterm><indexterm><primary>flash-based configuration and control
3585 </primary></indexterm><indexterm><primary>configuration and control</primary>
3586 <secondary>flash-based</secondary></indexterm></para>
3587 <para>RedBoot provides flash management support for storage in the flash memory
3588 of multiple executable images and of non-volatile information such as IP addresses
3589 and other network information.</para>
3590 <para>RedBoot on platforms that support flash based configuration information
3591 will report the following message the first time that RedBoot is booted on
3592 the target:</para>
3593 <screen>flash configuration checksum error or invalid key</screen>
3594 <para>This error can be ignored if no flash based configuration is desired,
3595 or can be silenced by running the <command>fconfig</command>
3596 command as described below. At this point you may also wish to run the <command>
3597 fis init</command> command. See other fis commands in <xref linkend="Flash-Image-System">.
3598 </para>
3599 <para>Certain control and configuration information used by RedBoot can be
3600 stored in flash. </para>
3601 <para>The details of what information is maintained in flash differ, based
3602 on the platform and the configuration. However, the basic operation used to
3603 maintain this information is the same. Using the <command>fconfig -l
3604 </command> command, the information may be displayed and/or changed.
3605 </para>
3606 <para>If the optional flag <computeroutput>-i</computeroutput> is specified,
3607 then the configuration database will be reset to its default
3608 state. This is also needed the first time RedBoot is installed on the
3609 target, or when updating to a newer RedBoot with different
3610 configuration keys.
3611 </para>
3612 <para>If the optional flag <computeroutput>-l</computeroutput> is specified,
3613 the configuration data is simply listed. Otherwise, each configuration parameter
3614 will be displayed and you are given a chance to change it. The entire value
3615 must be typed - typing just carriage return will leave a value unchanged.
3616 Boolean values may be entered using the first letter (<computeroutput>t</computeroutput>
3617 for true, <computeroutput>f</computeroutput> for false). At any time the editing
3618 process may be stopped simply by entering a period (.) on the line. Entering
3619 the caret (^) moves the editing back to the previous item. See &ldquo;RedBoot
3620 Editing Commands&rdquo;, <xref linkend="RedBoot-Editing-Commands">. </para>
3621 <para>If any changes are made in the configuration, then the updated data
3622 will be written back to flash after getting acknowledgment from the user.
3623 </para>
3624 <para>
3625 If the optional flag <computeroutput>-n</computeroutput> is specified
3626 (with or without <computeroutput>-l</computeroutput>) then &ldquo;nicknames&rdquo;
3627 of the entries are used.  These are shorter and less descriptive than
3628 &ldquo;full&rdquo; names.  The full name may also be displayed by adding the
3629 <computeroutput>-f</computeroutput> flag.</para>
3630 <para>The reason for telling you nicknames is that a quick way to set a single
3631 entry is provided, using the format
3632 <screen>
3633   RedBoot> <userinput>fconfig <replaceable>nickname</replaceable> <replaceable>value
3634 </replaceable></userinput></screen>
3635 If no
3636 value is supplied, the command will list and prompt for only that entry.
3637 If a value is supplied, then the entry will be set to that value.  You will
3638 be prompted whether to write the new information into flash if any change
3639 was made.  For example
3640 <screen>
3641   RedBoot> <userinput>fconfig -l -n</userinput>
3642   boot_script: false
3643   bootp: false
3644   bootp_my_ip: 10.16.19.176
3645   bootp_server_ip: 10.16.19.66
3646   dns_ip: 10.16.19.1
3647   gdb_port: 9000
3648   net_debug: false
3649   RedBoot> <userinput>fconfig bootp_my_ip 10.16.19.177</userinput>
3650   bootp_my_ip: 10.16.19.176 Setting to 10.16.19.177
3651   Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
3652   ... Unlock from 0x507c0000-0x507e0000: .
3653   ... Erase from 0x507c0000-0x507e0000: .
3654   ... Program from 0x0000a8d0-0x0000acd0 at 0x507c0000: .
3655   ... Lock from 0x507c0000-0x507e0000: .
3656   RedBoot>
3657 </screen>
3658 </para><para>
3659 Additionally, nicknames can be used like aliases via the format %{nickname}.
3660 This allows the values stored by <userinput>fconfig</userinput> to be used
3661 directly by scripts and commands.
3662 </para>
3663 <para>Depending on how your terminal program is connected and its
3664 capabilities, you might find that you are unable to use line-editing to
3665 delete the &lsquo;old&rsquo; value when using the default behaviour of
3666 <command>fconfig <replaceable>nickname</replaceable></command> or just
3667 plain <command>fconfig</command>, as shown in this example:
3668 <screen>
3669 RedBoot> <userinput>fco bootp</userinput>
3670 bootp: false&lowbar;
3671 </screen>
3672 The user deletes the word &ldquo;false;&rdquo and enters &ldquo;true&rdquo;
3673 so the display looks like this:
3674 <screen>
3675 RedBoot> <userinput>fco bootp</userinput>
3676 bootp: <userinput>true</userinput>
3677 Update RedBoot non-volatile configuration - continue (y/n)? y
3678 ... Unlock from ...
3679 RedBoot> &lowbar;
3680 </screen>
3681 </para>
3682 <para>To edit when you cannot backspace, use the optional flag
3683 <computeroutput>-d</computeroutput> (for &ldquo;dumb terminal&rdquo;)
3684 to provide a simpler interface thus:
3685 <screen>
3686 RedBoot> <userinput>fco -d bootp</userinput>
3687 bootp: false ? &lowbar;
3688 </screen>
3689 and you enter the value in the obvious manner thus:
3690 <screen>
3691 RedBoot> <userinput>fco -d bootp</userinput>
3692 bootp: false ? <userinput>true</userinput>
3693 Update RedBoot non-volatile configuration - continue (y/n)? y
3694 ... Unlock from ...
3695 RedBoot> &lowbar;
3696 </screen>
3697 </para>
3698 <para>One item which is always present in the configuration data is the ability
3699 to execute a script at boot time. A sequence of RedBoot commands can be entered
3700 which will be executed when the system starts up. Optionally, a time-out period
3701 can be provided which allows the user to abort the startup script and proceed
3702 with normal command processing from the console.     </para>
3703 <para><screen>
3704 RedBoot> <userinput>fconfig -l</userinput>
3705 Run script at boot: false
3706 Use BOOTP for network configuration: false
3707 Local IP address: 192.168.1.29
3708 Default server IP address: 192.168.1.101
3709 DNS server IP address: 192.168.1.1
3710 DNS domain name: example.com
3711 GDB connection port: 9000
3712 Network debug at boot time: false
3713 </screen></para>
3714 <para>The following example sets a boot script and then shows it running.
3715     </para>
3716 <para>
3717 <screen>
3718 RedBoot> <userinput>fconfig</userinput>
3719 Run script at boot: false <userinput>t</userinput>
3720       Boot script:
3721 Enter script, terminate with empty line
3722 >> <userinput>fi li</userinput>
3723     Boot script timeout: 0 <userinput>10</userinput>
3724 Use BOOTP for network configuration: false .
3725 Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
3726 ... Erase from 0xa0fc0000-0xa0fe0000: .
3727 ... Program from 0x8c021f60-0x8c022360 at 0xa0fc0000: .
3728 RedBoot>
3729 RedBoot(tm) debug environment - built 08:22:24, Aug 23 2000
3730 Copyright (C) 2000, Red Hat, Inc.
3731
3732
3733 RAM: 0x8c000000-0x8c800000
3734 flash: 0xa0000000 - 0xa1000000, 128 blocks of 0x00020000 bytes ea.
3735 Socket Communications, Inc: Low Power Ethernet CF Revision C \
3736 5V/3.3V 08/27/98 IP: 192.168.1.29, Default server: 192.168.1.101 \
3737 == Executing boot script in 10 seconds - enter ^C to abort
3738 RedBoot> <userinput>fi li</userinput>
3739 Name              flash addr   Mem addr    Length    Entry point
3740 RedBoot          0xA0000000   0xA0000000  0x020000  0x80000000
3741 RedBoot config   0xA0FC0000   0xA0FC0000  0x020000  0x00000000
3742 FIS directory    0xA0FE0000   0xA0FE0000  0x020000  0x00000000
3743 RedBoot>
3744 </screen>
3745 </para>
3746 <note><title>NOTE</title>
3747 <para>The bold characters above indicate where something was entered on the
3748 console. As you can see, the <command>fi li</command> command
3749 at the end came from the script,
3750 not the console. Once the script is executed, command processing reverts to
3751 the console. </para>
3752 </note>
3753 <para>
3754 <note><title>NOTE</title>
3755 <para>
3756 RedBoot supports the notion of a boot script timeout, i.e. a period of
3757 time that RedBoot waits before executing the boot time script.  This period
3758 is primarily to allow the possibility of canceling the script.  Since
3759 a timeout value of zero (0) seconds would never allow the script to
3760 be aborted or canceled, this value is not allowed.  If the timeout
3761 value is zero, then RedBoot will abort the script execution immediately.
3762 </para>
3763 </note>
3764 On many targets, RedBoot may be configured to run from ROM or it may be
3765 configured to run from RAM. Other configurations are also possible. All
3766 RedBoot configurations will execute the boot script, but in certain cases
3767 it may be desirable to limit the execution of certain script commands to
3768 one RedBoot configuration or the other. This can be accomplished by
3769 prepending <computeroutput>{&lt;startup type>}</computeroutput> to the
3770 commands which should be executed only by the RedBoot configured for the
3771 specified startup type. The following boot script illustrates this concept
3772 by having the ROM based RedBoot load and run the RAM based RedBoot. The RAM
3773 based RedBoot will then list flash images.</para>
3774 <para><screen>
3775 RedBoot> <userinput>fco</userinput>
3776 Run script at boot: false <userinput>t</userinput>
3777 Boot script:
3778 Enter script, terminate with empty line
3779 >> <userinput>{ROM}fis load RedBoot[RAM]</userinput>
3780 >> <userinput>{ROM}go</userinput>
3781 >> <userinput>{RAM}fis li</userinput>
3782 >>
3783 Boot script timeout (1000ms resolution): <userinput>2</userinput>
3784 Use BOOTP for network configuration: <userinput>false</userinput>
3785  ...
3786 Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
3787 ... Unlock from 0x007c0000-0x007e0000: .
3788 ... Erase from 0x007c0000-0x007e0000: .
3789 ... Program from 0xa0015030-0xa0016030 at 0x007df000: .
3790 ... Lock from 0x007c0000-0x007e0000: .
3791 RedBoot> <userinput>reset</userinput>
3792 ... Resetting.
3793 +Ethernet eth0: MAC address 00:80:4d:46:01:05
3794 IP: 192.168.1.153, Default server: 192.168.1.10
3795
3796 RedBoot(tm) bootstrap and debug environment [ROM]
3797 Red Hat certified release, version R1.xx - built 17:37:36, Aug 14 2001
3798
3799 Platform: IQ80310 (XScale)
3800 Copyright (C) 2000, 2001, Red Hat, Inc.
3801
3802 RAM: 0xa0000000-0xa2000000, 0xa001b088-0xa1fdf000 available
3803 FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
3804 == Executing boot script in 2.000 seconds - enter ^C to abort
3805 RedBoot> <userinput>fis load RedBoot[RAM]</userinput>
3806 RedBoot> <userinput>go</userinput>
3807 +Ethernet eth0: MAC address 00:80:4d:46:01:05
3808 IP: 192.168.1.153, Default server: 192.168.1.10
3809
3810 RedBoot(tm) bootstrap and debug environment [RAM]
3811 Red Hat certified release, version R1.xx - built 13:03:47, Aug 14 2001
3812
3813 Platform: IQ80310 (XScale)
3814 Copyright (C) 2000, 2001, Red Hat, Inc.
3815
3816 RAM: 0xa0000000-0xa2000000, 0xa0057fe8-0xa1fdf000 available
3817 FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
3818 == Executing boot script in 2.000 seconds - enter ^C to abort
3819 RedBoot> <userinput>fis li</userinput>
3820 Name              FLASH addr  Mem addr    Length      Entry point
3821 RedBoot           0x00000000  0x00000000  0x00040000  0x00002000
3822 RedBoot config    0x007DF000  0x007DF000  0x00001000  0x00000000
3823 FIS directory     0x007E0000  0x007E0000  0x00020000  0x00000000
3824 RedBoot>
3825 </screen></para>
3826 </sect1>
3827 <sect1 id="executing-programs">
3828 <title>Executing Programs from RedBoot</title>
3829 <para><indexterm><primary>executing programs</primary></indexterm><indexterm>
3830 <primary>RedBoot</primary><secondary>executing programs</secondary></indexterm>Once
3831 an image has been loaded into memory, either via the <command>load
3832 </command> command or the <command>fis load</command>
3833 command, execution may be transfered to that image.</para>
3834 <para>  <note><title>NOTE</title>
3835 <para>The image is assumed to be a stand-alone entity, as RedBoot gives the
3836 entire platform over to it. Typical examples would be an eCos application
3837 or a Linux kernel.</para>
3838 </note></para>
3839
3840
3841 <!-- ******** go *************************************************** -->
3842   <refentry id="go-command">
3843     <refnamediv>
3844       <refname>go</refname>
3845       <refpurpose>Execute a program</refpurpose>
3846     </refnamediv>
3847     <refsynopsisdiv>
3848       <cmdsynopsis>
3849         <command>go</command>
3850         <arg>-w <replaceable> timeout</replaceable></arg>
3851         <arg>-c</arg>
3852         <arg>-n</arg>
3853         <arg><replaceable> start_address</replaceable></arg>
3854       </cmdsynopsis>
3855     </refsynopsisdiv>
3856     <refsect1>
3857       <title>Arguments</title>
3858       <informaltable frame="all">
3859         <tgroup cols="4" colsep="1" rowsep="1" align="left">
3860           <colspec colname="c1">
3861           <colspec colname="c2">
3862           <colspec colname="c3">
3863           <colspec colname="c4">
3864           <thead>
3865             <row>
3866               <entry>Name</entry>
3867               <entry>Type</entry>
3868               <entry>Description</entry>
3869               <entry>Default</entry>
3870             </row>
3871           </thead>
3872           <tbody>
3873             <row>
3874               <entry>-w <replaceable>timeout</replaceable></entry>
3875               <entry>Number</entry>
3876               <entry>How long to wait before starting execution.</entry>
3877               <entry>0</entry>
3878             </row>
3879             <row>
3880               <entry>-c</entry>
3881               <entry>Boolean</entry>
3882               <entry>Go with caches enabled.</entry>
3883               <entry>caches off</entry>
3884             </row>
3885             <row>
3886               <entry>-n</entry>
3887               <entry>Boolean</entry>
3888               <entry>Go with network interface stopped.</entry>
3889               <entry>network enabled</entry>
3890             </row>
3891             <row>
3892               <entry><replaceable>start_address</replaceable></entry>
3893               <entry>Number</entry>
3894               <entry>Address in memory to begin execution.</entry>
3895               <entry>Value set by last <command>load</command> or <command>fis load</command> command.</entry>
3896             </row>
3897           </tbody>
3898         </tgroup>
3899       </informaltable>
3900     </refsect1>
3901     <refsect1>
3902       <title>Description</title>
3903       <para>
3904 The <command>go</command> command causes RedBoot to give control of the target platform to
3905 another program.  This program must execute stand alone, e.g. an eCos
3906 application or a Linux kernel.
3907       </para>
3908       <para>
3909 If the -w option is used, RedBoot will print a message and then
3910 wait for a period of time before starting the execution.  This is
3911 most useful in a script, giving the user a chance to abort executing
3912 a program and move on in the script.
3913       </para>
3914     </refsect1>
3915     <refsect1>
3916       <title>Examples</title>
3917       <para>
3918 Execute a program - <emphasis>no explicit output from RedBoot</emphasis>.
3919 <screen>
3920 RedBoot> <userinput>go 0x40040</userinput>
3921 </screen>
3922       </para>
3923       <para>
3924 Execute a program with a timeout.
3925 <screen>
3926 RedBoot> <userinput>go -w 10</userinput>
3927 About to start execution at 0x00000000 - abort with ^C within 10 seconds
3928 ^C
3929 RedBoot>
3930 </screen>
3931 Note that the starting address was implied (0x00000000 in this example).
3932 The user is prompted that execution will commence in 10 seconds.  At
3933 anytime within that 10 seconds the user may type  <guibutton>Ctrl+C</guibutton>
3934 on the console and RedBoot will abort execution and return for the next
3935 command, either from a script or the console.
3936       </para>
3937     </refsect1>
3938   </refentry>
3939
3940 <!-- ******** exec *************************************************** -->
3941   <refentry id="exec-command">
3942     <refnamediv>
3943       <refname>exec</refname>
3944       <refpurpose>Execute a Linux kernel</refpurpose>
3945     </refnamediv>
3946     <refsynopsisdiv>
3947       <cmdsynopsis>
3948         <command>exec</command>
3949         <arg>-w <replaceable> timeout</replaceable></arg>
3950         <arg>-r <replaceable> ramdisk_address</replaceable></arg>
3951         <arg>-s <replaceable> ramdisk_length</replaceable></arg>
3952         <arg>-b <replaceable> load_address</replaceable>
3953            <arg choice="req">-l <replaceable> load_length</replaceable></arg>
3954         </arg>
3955         <arg>-c <replaceable> kernel_command_line</replaceable></arg>
3956         <arg><replaceable> entry_point</replaceable></arg>
3957       </cmdsynopsis>
3958     </refsynopsisdiv>
3959     <refsect1>
3960       <title>Arguments</title>
3961       <informaltable frame="all">
3962         <tgroup cols="4" colsep="1" rowsep="1" align="left">
3963           <colspec colname="c1">
3964           <colspec colname="c2">
3965           <colspec colname="c3">
3966           <colspec colname="c4">
3967           <thead>
3968             <row>
3969               <entry>Name</entry>
3970               <entry>Type</entry>
3971               <entry>Description</entry>
3972               <entry>Default</entry>
3973             </row>
3974           </thead>
3975           <tbody>
3976             <row>
3977               <entry>-w <replaceable>timeout</replaceable></entry>
3978               <entry>Number</entry>
3979               <entry>Time to wait before starting execution.</entry>
3980               <entry>0</entry>
3981             </row>
3982             <row>
3983               <entry>-r <replaceable>ramdisk_address</replaceable></entry>
3984               <entry>Number</entry>
3985               <entry>Address in memory of "initrd"-style ramdisk - passed to Linux kernel.</entry>
3986               <entry><emphasis>None</emphasis></entry>
3987             </row>
3988             <row>
3989               <entry>-s <replaceable>ramdisk_length</replaceable></entry>
3990               <entry>Number</entry>
3991               <entry>Length of ramdisk image - passed to Linux kernel.</entry>
3992               <entry><emphasis>None</emphasis></entry>
3993             </row>
3994             <row>
3995               <entry>-b <replaceable>load_address</replaceable></entry>
3996               <entry>Number</entry>
3997               <entry>Address in memory of the Linux kernel image.</entry>
3998               <entry>Value set by <command>load</command> or <command>fis load</command></entry>
3999             </row>
4000             <row>
4001               <entry>-l <replaceable>load_length</replaceable></entry>
4002               <entry>Number</entry>
4003               <entry>Length of Linux kernel image.</entry>
4004               <entry><emphasis>none</emphasis></entry>
4005             </row>
4006             <row>
4007               <entry>-c <replaceable>kernel_command_line</replaceable></entry>
4008               <entry>String</entry>
4009               <entry>Command line to pass to the Linux kernel.</entry>
4010               <entry><emphasis>None</emphasis></entry>
4011             </row>
4012             <row>
4013               <entry>-x</entry>
4014               <entry></entry>
4015               <entry>Boot kernel with endianess opposite of RedBoot endianess.</entry>
4016               <entry>Boot kernel with same endianess as RedBoot</entry>
4017               </row>
4018             <row>
4019               <entry><replaceable>entry_address</replaceable></entry>
4020               <entry>Number</entry>
4021               <entry>Starting address for Linux kernel execution</entry>
4022               <entry>Implied by architecture</entry>
4023             </row>
4024           </tbody>
4025         </tgroup>
4026       </informaltable>
4027     </refsect1>
4028     <refsect1>
4029       <title>Description</title>
4030       <para>
4031 The <command>exec</command> command is used to execute a non-eCos application, typically a
4032 Linux kernel. Additional information may be passed to the kernel at startup
4033 time. This command is quite special (and unique from the <command>go</command> command) in
4034 that the program being executed may expect certain environmental setups, for
4035 example that the MMU is turned off, etc. </para>
4036 <para>The Linux kernel expects to have been loaded to a particular memory
4037 location which is architecture dependent(0xC0008000 in the case of the SA1110).
4038 Since this memory is  used
4039 by RedBoot internally, it is not possible to load the kernel to that location
4040 directly. Thus the requirement for the "-b" option which tells the command
4041 where the kernel has been loaded. When the <command>exec</command> command runs, the image will
4042 be relocated to the appropriate location before being started. The "-r" and
4043 "-s" options are used to pass information to the kernel about where a statically
4044 loaded ramdisk (initrd) is located.</para>
4045 <para>The "-c" option can be used to pass textual "command line" information
4046 to the kernel.  If the command line data contains any punctuation (spaces,
4047 etc), then it must be quoted using the double-quote character '"'. If the
4048 quote character is required, it should be written as '\"'.
4049       </para>
4050 <para>The "-x" option is optionally available on some bi-endian platforms. It is used to boot
4051 a kernel built with an endianess opposite of RedBoot.</para>
4052     </refsect1>
4053     <refsect1>
4054       <title>Examples</title>
4055       <para>
4056 Execute a Linux kernel, passing a command line, which needs relocation.
4057 The result from RedBoot is normally quiet, with the target platform being
4058 passed over to Linux immediately.
4059 <screen>
4060 RedBoot> <userinput>exec -b 0x100000 -l 0x80000 -c "noinitrd root=/dev/mtdblock3 console=ttySA0"</userinput>
4061 </screen>
4062       </para>
4063       <para>
4064 Execute a Linux kernel, default entry address and no relocation required, with a timeout.
4065 The <emphasis> emphasized lines</emphasis> are output from the loaded kernel.
4066 <screen>
4067 RedBoot> exec <userinput>-c "console=ttyS0,38400 ip=dhcp nfsroot=/export/elfs-sh" -w 5</userinput>
4068 Now booting linux kernel:
4069 Base address 0x8c001000 Entry 0x8c210000
4070 Cmdline : console=ttyS0,38400 ip=dhcp nfsroot=/export/elfs-sh
4071 About to start execution at 0x8x210000 - abort with ^C within 5 seconds
4072 <emphasis>
4073 Linux version 2.4.10-pre6 (...) (gcc version 3.1-stdsh-010931) #3 Thu Sep 27 11:04:23 BST 2001
4074 </emphasis>
4075 </screen>
4076       </para>
4077     </refsect1>
4078   </refentry>
4079
4080 </sect1>
4081 </chapter>