source: SVN/cambria/redboot/packages/redboot/current/doc/redboot_cmds.sgml @ 1

Last change on this file since 1 was 1, checked in by Tim Harvey, 2 years ago

restored latest version of files from server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 102.9 KB
Line 
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,
46there 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>
51Commands may require additional information beyond the basic
52command name. In most cases this additional information is optional, with
53suitable 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
71on the presence of the switch.  In this example, the <userinput>-f</userinput> switch
72indicates that a complete initialization of the FIS data should be performed.
73There may be many such switches available for any given command and any or all of
74them 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
82example, <userinput>-b 0x100000</userinput> specifies where the memory dump should begin.
83There may be many such switches available for any given command and any or all of
84them 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>
94is the name of a flash image.  The image name is always required, thus is no need to qualify it with
95a switch.
96Note 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
107typing <command>help</command> at the command line:   
108<screen>
109RedBoot> <userinput>help</userinput>
110Manage aliases kept in FLASH memory
111      alias name [value]
112Set/Query the system console baud rate
113      baudrate [-b &lt;rate>]
114Manage machine caches
115      cache [ON | OFF]
116Display/switch console channel
117      channel [-1|&lt;channel number>]
118Display disk partitions
119      disks
120Display (hex dump) a range of memory
121      dump -b &lt;location> [-l &lt;length>] [-s]
122Manage flash images
123      fis {cmds}
124Manage configuration kept in FLASH memory
125      fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
126Execute code at a location
127      go [-w &lt;timeout>] [-c] [-n] [entry]
128Help about help?
129      help [&lt;topic>]
130Set/change IP addresses
131      ip_address [-l &lt;local_ip_address>[/&lt;mask_length>]] [-h &lt;server_address>]
132Load 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>
135Network connectivity test
136      ping [-v] [-n &lt;count>] [-t &lt;timeout>] [-i &lt;IP_addr]
137      -h &lt;host>
138Reset the system
139      reset
140Display RedBoot version information
141      version
142Display (hex dump) a range of memory
143      x -b &lt;location> [-l &lt;length>] [-s]
144</screen>
145</para>
146<para>
147Commands can be abbreviated to their shortest
148unique string. Thus in the list above, <command>d,du,dum</command>
149and dump are all valid for the <command>dump</command> command. The <command>fconfig</command>
150command 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
155point, the eCos GDB stubs take over, allowing connections from a GDB host.
156The only way to get back to RedBoot from GDB mode is to restart the platform.
157</para>
158<note><title>NOTE</title>
159<para>
160Multiple 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
164environment. These commands are designed to be simple to use and remember,
165while still providing sufficient power and flexibility to be useful. No attempt
166has been made to render RedBoot as the end-all product. As such, things such
167as the debug environment are left to other modules, such as GDB stubs, which
168are 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
228line aliases.  These aliases are shorthand for longer expressions.
229When the pattern %{name} appears in a command line, including in a script,
230the corresponding value will be substituted.  Aliases may be nested.
231      </para>
232      <para>
233If no value is provided, then the current value of the alias is displayed.
234      </para>
235      <para>
236If the system supports non-volatile configuration data via the
237<command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
238then the value will be saved and used when the system is reset.
239      </para>
240    </refsect1>
241    <refsect1>
242      <title>Examples</title>
243      <para>
244Set an alias.
245<screen> 
246RedBoot> <userinput>alias joe "This is Joe"</userinput>
247Update RedBoot non-volatile configuration - continue (y/n)? n
248</screen>
249</para>
250<para>
251Display an alias.
252<screen> 
253RedBoot> <userinput>alias joe</userinput>
254'joe' = 'This is Joe'
255</screen>
256</para>
257<para>
258Use an alias.  Note: the <command>"="</command> command simply echoes the command to to console.
259<screen> 
260RedBoot> <userinput>= %{joe}</userinput>
261This is Joe
262</screen>
263</para>
264<para>
265Aliases can be nested.
266<screen>
267RedBoot> <userinput>alias frank "Who are you? %{joe}"</userinput>
268Update RedBoot non-volatile configuration - continue (y/n)? n
269RedBoot> <userinput>= %{frank}</userinput>
270Who are you? This is Joe
271</screen>
272</para>
273<para>
274Notice how the value of %{frank} changes when %{joe} is changed since
275the value of %{joe} is not evaluated until %{frank} is evaluated.
276<screen>
277RedBoot> <userinput>alias joe "This is now Josephine"</userinput>
278Update RedBoot non-volatile configuration - continue (y/n)? n
279RedBoot> <userinput>= %{frank}</userinput>
280Who 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>
330If no value is provided, then the current value of the console baud rate is displayed.
331      </para>
332      <para>
333If the system supports non-volatile configuration data via the
334<command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
335then the value will be saved and used when the system is reset.
336      </para>
337    </refsect1>
338    <refsect1>
339      <title>Examples</title>
340      <para>
341Show the current baud rate.
342<screen> 
343RedBoot> <userinput>baudrate</userinput>
344Baud rate = 38400
345</screen>
346</para>
347<para>
348Change the console baud rate.  In order to make this operation safer,
349there will be a slight pause after the
350first message to give you time to change to the new baud rate.
351If 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.
353Only after the baud rate has been firmly established will <emphasis>RedBoot</emphasis>
354give you an opportunity to save the value in persistent storage.
355<screen> 
356RedBoot> <userinput>baudrate -b 57600</userinput>
357Baud rate will be changed to 57600 - update your settings
358<emphasis>Device baud rate changed at this point</emphasis>
359Baud rate changed to 57600 - continue (y/n)? y
360Update 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>
423Show the current cache state.
424<screen> 
425RedBoot> <userinput>cache</userinput>
426Data cache: On, Instruction cache: On
427</screen>
428</para>
429<para>
430Disable the caches.
431<screen> 
432RedBoot> <userinput>cache off</userinput>
433RedBoot> <userinput>cache</userinput>
434Data cache: Off, Instruction cache: Off
435</screen>
436</para>
437<para>
438Enable the caches.
439<screen> 
440RedBoot> <userinput>cache on</userinput>
441RedBoot> <userinput>cache</userinput>
442Data 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>
499With no arguments, the <command>channel</command> command displays the current console channel number.
500</para><para>
501When passed an argument of 0 upward, this command switches the console
502channel to that channel number. The mapping between channel numbers and
503physical channels is platform specific but will typically be something like
504channel 0 is the first serial port, channel 1 is the second, etc.
505</para><para>
506When passed an argument of -1, this command reverts RedBoot to responding
507to whatever channel receives input first, as happens when RedBoot initially
508starts execution.
509</para>
510    </refsect1>
511    <refsect1>
512      <title>Examples</title>
513      <para>
514Show the current channel.
515<screen> 
516RedBoot> <userinput>channel</userinput>
517Current console channel id: 0
518</screen>
519</para>
520<para>
521Change to an invalid channel.
522<screen> 
523RedBoot> <userinput>channel 99</userinput>
524**Error: bad channel number '99'
525</screen>
526</para>
527<para>
528Revert to the default channel setting (any console mode).
529<screen> 
530RedBoot> <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).
585The 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>
592Checksum a buffer.
593<screen> 
594RedBoot> <userinput>cksum -b 0x100000 -l 0x100</userinput>
595POSIX cksum = 3286483632 256 (0xc3e3c2b0 0x00000100)
596</screen>
597      </para>
598      <para>
599Checksum an area of memory after loading a file. Note that the base
600address and length parameters are provided by the preceding
601load command.
602<screen> 
603RedBoot> <userinput>load -r -b %{FREEMEMLO} redboot.bin</userinput>
604Raw file loaded 0x06012800-0x0602f0a8
605RedBoot> <userinput>cksum</userinput>
606Computing cksum for area 0x06012800-0x0602f0a8
607POSIX 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>
635Show what disk partitions are available.
636<screen> 
637RedBoot> <userinput>disks</userinput>
638hda1     Linux Swap
639hda2     Linux
64000100000: 00 3E 00 06 00 06 00 06  00 00 00 00 00 00 00 00  |.>..............|
64100100010: 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. 
705Only 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. 
712Only 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
730be detrimental if used on memory mapped hardware registers. </para>
731        <para>The memory is displayed at most sixteen bytes per line, first as the
732raw hex value, followed by an ASCII interpretation of the data. </para>
733    </refsect1>
734    <refsect1>
735      <title>Examples</title>
736      <para>
737Display a buffer, one byte at a time.
738<screen> 
739RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
740RedBoot> <userinput>x -b 0x100000</userinput>
74100100000: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
74200100010: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
743</screen>
744</para>
745<para>
746Display a buffer, one short (16 bit) word at a time.  Note in this case that
747the ASCII interpretation is suppressed.
748<screen> 
749RedBoot> <userinput>dump -b 0x100000 -2</userinput>
75000100000: FACE DEAD FACE DEAD  FACE DEAD FACE DEAD
75100100010: FACE DEAD FACE DEAD  FACE DEAD FACE DEAD
752</screen>
753</para>
754<para>
755Display a buffer, one word (32 bit) word at a time.  Note in this case that
756the ASCII interpretation is suppressed.
757<screen> 
758RedBoot> <userinput>dump -b 0x100000 -4</userinput>
75900100000: DEADFACE DEADFACE DEADFACE DEADFACE
76000100010: DEADFACE DEADFACE DEADFACE DEADFACE
761</screen>
762</para>
763<para>
764Display the same buffer, using Motorola S-record format.
765<screen> 
766RedBoot> <userinput>dump -b 0x100000 -s</userinput>
767S31500100000CEFAADDECEFAADDECEFAADDECEFAADDE8E
768S31500100010CEFAADDECEFAADDECEFAADDECEFAADDE7E
769</screen>
770</para>
771<para>
772Display a buffer, with visible ASCII strings.
773<screen> 
774RedBoot> <userinput>d -b 0xfe00b000 -l 0x80</userinput>
7750xFE00B000: 20 25 70 0A 00 00 00 00  41 74 74 65 6D 70 74 20 | %p.....Attempt |
7760xFE00B010: 74 6F 20 6C 6F 61 64 20  53 2D 72 65 63 6F 72 64 |to load S-record|
7770xFE00B020: 20 64 61 74 61 20 74 6F  20 61 64 64 72 65 73 73 | data to address|
7780xFE00B030: 3A 20 25 70 20 5B 6E 6F  74 20 69 6E 20 52 41 4D |: %p [not in RAM|
7790xFE00B040: 5D 0A 00 00 2A 2A 2A 20  57 61 72 6E 69 6E 67 21 |]...*** Warning!|
7800xFE00B050: 20 43 68 65 63 6B 73 75  6D 20 66 61 69 6C 75 72 | Checksum failur|
7810xFE00B060: 65 20 2D 20 41 64 64 72  3A 20 25 6C 78 2C 20 25 |e - Addr: %lx, %|
7820xFE00B070: 30 32 6C 58 20 3C 3E 20  25 30 32 6C 58 0A 00 00 |02lX &lt;> %02lX...|
7830xFE00B080: 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>
831The <command>help</command> command displays information about the available
832RedBoot commands.  If a <emphasis>topic</emphasis> is given, then the display
833is restricted to information about that specific command.
834      </para>
835      <para>
836If the command has sub-commands, e.g. <command>fis</command>, then the topic
837specific display will print additional information about the available sub-commands.
838special (ICMP) packets to a specific host. These packets should be automatically
839returned by that host. The command will indicate how many of these round-trips
840were successfully completed.
841      </para>
842    </refsect1>
843    <refsect1>
844      <title>Examples</title>
845      <para>
846Show generic help.  Note that the contents of this display will depend on the various configuration
847options for RedBoot when it was built.
848<screen>
849RedBoot> <userinput>help</userinput>
850Manage aliases kept in FLASH memory
851   alias name [value]
852Manage machine caches
853   cache [ON | OFF]
854Display/switch console channel
855   channel [-1|&lt;channel number&gt;]
856Compute a 32bit checksum [POSIX algorithm] for a range of memory
857   cksum -b &lt;location&gt; -l &lt;length&gt;
858Display (hex dump) a range of memory
859   dump -b &lt;location&gt; [-l &lt;length&gt;] [-s] [-1|2|4]
860Manage FLASH images
861   fis {cmds}
862Manage configuration kept in FLASH memory
863   fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
864Execute code at a location
865   go [-w &lt;timeout&gt;] [entry]
866Help about help?
867   help [&lt;topic&gt;]
868Set/change IP addresses
869   ip_address [-l &lt;local_ip_address&gt;[/&lt;mask_length&gt;]] [-h &lt;server_address&gt;]
870Load a file
871   load [-r] [-v] [-d] [-h &lt;host&gt;] [-m {TFTP | HTTP | {x|y}MODEM -c &lt;channel_number&gt;}]
872        [-b &lt;base_address&gt;] &lt;file_name&gt;
873Compare two blocks of memory
874   mcmp -s &lt;location&gt; -d &lt;location&gt; -l &lt;length&gt; [-1|-2|-4]
875Fill a block of memory with a pattern
876   mfill -b &lt;location&gt; -l &lt;length&gt; -p &lt;pattern&gt; [-1|-2|-4]
877Network connectivity test
878   ping [-v] [-n &lt;count&gt;] [-l &lt;length&gt;] [-t &lt;timeout&gt;] [-r &lt;rate&gt;]
879        [-i &lt;IP_addr&gt;] -h &lt;IP_addr&gt;
880Reset the system
881   reset
882Display RedBoot version information
883   version
884Display (hex dump) a range of memory
885   x -b &lt;location&gt; [-l &lt;length&gt;] [-s] [-1|2|4]
886</screen>
887      </para>
888      <para>
889Help about a command with sub-commands.
890<screen>
891RedBoot> <userinput>help fis</userinput>
892Manage FLASH images
893   fis {cmds}
894Create an image
895  fis create -b &lt;mem_base&gt; -l &lt;image_length&gt; [-s &lt;data_length&gt;]
896      [-f &lt;flash_addr&gt;] [-e &lt;entry_point&gt;] [-r &lt;ram_addr&gt;] [-n] &lt;name&gt;
897Display an image from FLASH Image System [FIS]
898  fis delete name
899Erase FLASH contents
900  fis erase -f &lt;flash_addr&gt; -l &lt;length&gt;
901Display free [available] locations within FLASH Image System [FIS]
902  fis free
903Initialize FLASH Image System [FIS]
904  fis init [-f]
905Display contents of FLASH Image System [FIS]
906  fis list [-c] [-d]
907Load image from FLASH Image System [FIS] into RAM
908  fis load [-d] [-b &lt;memory_load_address&gt;] [-c] name
909Write raw data directly to FLASH
910  fis write -f &lt;flash_addr&gt; -b &lt;mem_base&gt; -l &lt;image_length&gt;
911</screen>
912      </para>
913    </refsect1>
914  </refentry>
915
916<!-- ******** ip_address *************************************************** -->
917  <refentry id="ip-address-command">
918    <refnamediv>
919      <refname>ip_address</refname>
920      <refpurpose>Set IP addresses</refpurpose>
921    </refnamediv>
922    <refsynopsisdiv>
923      <cmdsynopsis>
924        <command>ip_address</command>
925        <arg>-l <replaceable> local_IP_address</replaceable>
926        <arg choice=opt>/<replaceable>netmask_length</replaceable></arg> </arg>
927        <arg>-h <replaceable> server_IP_address</replaceable></arg>
928        <arg>-d <replaceable>
929DNS_server_IP_address</replaceable></arg>
930      </cmdsynopsis>
931    </refsynopsisdiv>
932    <refsect1>
933      <title>Arguments</title>
934      <informaltable frame="all">
935        <tgroup cols="4" colsep="1" rowsep="1" align="left">
936          <colspec colname="c1">
937          <colspec colname="c2">
938          <colspec colname="c3">
939          <colspec colname="c4">
940          <thead>
941            <row>
942              <entry>Name</entry>
943              <entry>Type</entry>
944              <entry>Description</entry>
945              <entry>Default</entry>
946            </row>
947          </thead>
948          <tbody>
949            <row>
950              <entry>-l <replaceable>
951local_IP_address</replaceable><option>[<replaceable>/netmask_length</replaceable>]</option></entry>         
952              <entry>Numeric IP or DNS name</entry>
953              <entry>The IP address RedBoot should use, optionally
954with the network mask length.</entry>       
955              <entry><emphasis>none</emphasis></entry>       
956            </row>
957            <row>
958              <entry>-h <replaceable>
959server_IP_address</replaceable></entry>     
960              <entry>Numeric IP or DNS name</entry>
961              <entry>The IP address of the default server. Use of this
962address is implied by other commands, such as
963<command>load</command>.</entry>            
964              <entry><emphasis>none</emphasis></entry>       
965            </row>
966            <row>
967              <entry>-d <replaceable>
968DNS_server_IP_address</replaceable></entry>         
969              <entry>Numeric IP or DNS name</entry>
970              <entry>The IP address of the DNS server.</entry>       
971              <entry><emphasis>none</emphasis></entry>       
972            </row>
973          </tbody>
974        </tgroup>
975      </informaltable>
976    </refsect1>
977    <refsect1>
978      <title>Description</title>
979      <para>The <command>ip_address</command> command is used to show and/or change the basic IP
980addresses used by RedBoot. IP addresses may be given as numeric
981values, e.g. 192.168.1.67, or as symbolic names such as www.redhat.com
982if DNS support is enabled.
983      </para>
984      <para>
985The <option>-l</option> option is used to set the IP address used by
986the target device. The network mask length can also be specified
987      </para>
988      <para>
989The <option>-h</option> option is used to set the default server
990address, such as is used by the <command>load</command> command.
991      </para>
992      <para>
993The <option>-d</option> option is used to set the default DNS server
994address which is used for resolving symbolic network addresses. Note
995that an address of 0.0.0.0 will disable DNS lookups.
996      </para>
997    </refsect1>
998    <refsect1>
999      <title>Examples</title>
1000      <para>
1001Display the current network settings.
1002<screen> 
1003RedBoot> <userinput>ip_address</userinput>
1004IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 0.0.0.0
1005</screen>
1006</para>
1007<para>
1008Change the DNS server address.
1009<screen> 
1010RedBoot> <userinput>ip_address -d 192.168.1.101</userinput>
1011IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 192.168.1.101
1012</screen>
1013</para>
1014<para>
1015Change the default server address.
1016<screen> 
1017RedBoot> <userinput>ip_address -h 192.168.1.104</userinput>
1018IP: 192.168.1.31, Default server: 192.168.1.104, DNS server IP: 192.168.1.101
1019</screen>
1020</para>
1021<para>
1022Set the IP address to something new, with a 255.255.255.0 netmask
1023<screen> 
1024RedBoot> <userinput>ip_address -l 192.168.1.32/24</userinput>
1025IP: 192.168.1.32, Default server: 192.168.1.104, DNS server IP: 192.168.1.101
1026</screen>
1027      </para>
1028    </refsect1>
1029  </refentry>
1030
1031<!-- ******** load *************************************************** -->
1032  <refentry id="download-command">
1033    <refnamediv>
1034      <refname>load</refname>
1035      <refpurpose>Download programs or data to the RedBoot platform</refpurpose>
1036    </refnamediv>
1037    <refsynopsisdiv>
1038      <cmdsynopsis>
1039        <command>load</command>
1040        <arg>-v </arg>
1041        <arg>-d </arg>
1042        <arg>-r </arg>
1043        <arg>-m
1044          <group>
1045            <arg choice="req"><group>
1046              <arg>xmodem</arg>
1047              <arg>ymodem</arg>
1048            </group></arg>
1049            <arg>tftp</arg>
1050            <arg>disk</arg>
1051          </group>
1052        </arg> 
1053        <arg>-h <replaceable> server_IP_address</replaceable></arg>
1054        <arg>-b <replaceable> location</replaceable></arg>
1055        <arg>-c <replaceable> channel</replaceable></arg>
1056        <arg><replaceable>file_name</replaceable></arg>
1057      </cmdsynopsis>
1058    </refsynopsisdiv>
1059    <refsect1>
1060      <title>Arguments</title>
1061      <informaltable frame="all">
1062        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1063          <colspec colname="c1">
1064          <colspec colname="c2">
1065          <colspec colname="c3">
1066          <colspec colname="c4">
1067          <thead>
1068            <row>
1069              <entry>Name</entry>
1070              <entry>Type</entry>
1071              <entry>Description</entry>
1072              <entry>Default</entry>
1073            </row>
1074          </thead>
1075          <tbody>
1076            <row>
1077              <entry>-v</entry>     
1078              <entry>Boolean</entry>
1079              <entry>Display a small spinner (indicator)
1080while the download is in  progress. This is just for feedback, especially
1081during long loads. Note that the option has no effect when using a
1082serial download method since it would interfere with the protocol.</entry>           
1083              <entry><emphasis>quiet</emphasis></entry>     
1084            </row>
1085            <row>
1086              <entry>-d</entry>     
1087              <entry>Boolean</entry>
1088              <entry>Decompress data stream (gzip data)</entry>     
1089              <entry><emphasis>non-compressed data</emphasis></entry>       
1090            </row>
1091            <row>
1092              <entry>-r</entry>     
1093              <entry>Boolean</entry>
1094              <entry>Raw (or binary) data</entry>           
1095              <entry><emphasis>formatted (S-records, ELF image, etc)</emphasis></entry>     
1096            </row>
1097            <row>
1098              <entry>-m tftp</entry>         
1099              <entry></entry>
1100              <entry>Transfer data via the network using <acronym>TFTP</acronym> protocol.</entry>           
1101              <entry><acronym>TFTP</acronym></entry>         
1102            </row>
1103            <row>
1104              <entry>-m http</entry>         
1105              <entry></entry>
1106              <entry>Transfer data via the network using <acronym>HTTP</acronym> protocol.</entry>           
1107              <entry><acronym>TFTP</acronym></entry>         
1108            </row>
1109            <row>
1110              <entry>-m xmodem</entry>       
1111              <entry></entry>
1112              <entry>Transfer data using <emphasis>X-modem</emphasis> protocol.</entry>     
1113              <entry><acronym>TFTP</acronym></entry>         
1114            </row>
1115            <row>
1116              <entry>-m ymodem</entry>       
1117              <entry></entry>
1118              <entry>Transfer data using <emphasis>Y-modem</emphasis> protocol.</entry>     
1119              <entry><acronym>TFTP</acronym></entry>         
1120            </row>
1121            <row>
1122              <entry>-m disk</entry>         
1123              <entry></entry>
1124              <entry>Transfer data from a local disk.</entry>       
1125              <entry><acronym>TFTP</acronym></entry>         
1126            </row>
1127            <row>
1128              <entry>-h <replaceable>server_IP_address</replaceable></entry>         
1129              <entry>Numeric IP or DNS name</entry>
1130              <entry>The IP address of the <acronym>TFTP</acronym> or <acronym>HTTP</acronym> server.</entry>       
1131              <entry>Value set by <command>ip_address</command></entry>     
1132            </row>
1133            <row>
1134              <entry>-b <replaceable>location</replaceable></entry>         
1135              <entry>Number</entry>
1136              <entry>Address in memory to load the data.  Formatted data streams will have
1137an implied load address which this option may override.</entry>     
1138              <entry><emphasis>Depends on data format</emphasis></entry>             
1139            </row>
1140            <row>
1141              <entry>-c <replaceable>channel</replaceable></entry>           
1142              <entry>Number</entry>
1143              <entry>Specify which I/O channel to
1144use for download.  This option is only supported when using either
1145xmodem or ymodem protocol.</entry>           
1146              <entry><emphasis>Depends on data format</emphasis></entry>             
1147            </row>
1148            <row>
1149              <entry><replaceable>file_name</replaceable></entry>           
1150              <entry>String</entry>
1151              <entry>The name of the file on the <acronym>TFTP</acronym> or <acronym>HTTP</acronym>
1152server or the local disk. Details of how this is specified for <acronym>TFTP</acronym> are
1153host-specific. For local disk files, the name must be in <emphasis>disk</emphasis>:
1154<emphasis>filename</emphasis> format. The disk portion must match one of the disk
1155names listed by the <command>disks</command> command.</entry>       
1156              <entry><emphasis>None</emphasis></entry>       
1157            </row>
1158          </tbody>
1159        </tgroup>
1160      </informaltable>
1161    </refsect1>
1162    <refsect1>
1163      <title>Description</title>
1164      <para>
1165The <command>load</command> command is used to download
1166data into the target system. Data can be loaded via a network connection,
1167using either the <acronym>TFTP</acronym> or <acronym>HTTP</acronym> protocols, or the console serial connection using the
1168X/Y modem protocol. Files may also be loaded directly from local filesystems
1169on disk. Files to be downloaded may either be executable images in
1170ELF executable program format,
1171Motorola S-record (SREC)
1172format or raw data.
1173      </para>
1174    </refsect1>
1175    <refsect1>
1176      <title>Examples</title>
1177      <para>
1178Download a Motorola S-record (or ELF) image, using <acronym>TFTP</acronym>, specifying the
1179base memory address.
1180<screen>
1181RedBoot> <userinput>load redboot.ROM -b 0x8c400000</userinput>
1182Address offset = 0x0c400000
1183Entry point: 0x80000000, address range: 0x80000000-0x8000fe80
1184</screen>
1185      </para>
1186      <para>
1187Download a Motorola S-record (or ELF) image, using <acronym>HTTP</acronym>, specifying the
1188host [server] address.
1189<screen>
1190RedBoot> <userinput>load /redboot.ROM -m HTTP -h 192.168.1.104</userinput>
1191Address offset = 0x0c400000
1192Entry point: 0x80000000, address range: 0x80000000-0x8000fe80
1193</screen>
1194      </para>
1195      <para>
1196Load an ELF file from /dev/hda1 which should be an EXT2 partition:
1197<screen>
1198RedBoot> <userinput>load -mode disk hda1:hello.elf</userinput>
1199Entry point: 0x00020000, address range: 0x00020000-0x0002fd70
1200</screen>
1201      </para>
1202    </refsect1>
1203  </refentry>
1204
1205<!-- ******** mcmp *************************************************** -->
1206  <refentry id="mcmp-command">
1207    <refnamediv>
1208      <refname>mcmp</refname>
1209      <refpurpose>Compare two segments of memory</refpurpose>
1210    </refnamediv>
1211    <refsynopsisdiv>
1212      <cmdsynopsis>
1213        <command>mcmp</command>
1214            <arg choice="req">-s <replaceable>location1</replaceable></arg>
1215            <arg choice="req">-d <replaceable>location1</replaceable></arg>
1216            <arg choice="req">-l <replaceable>length</replaceable></arg>
1217          <group>
1218            <arg>-1</arg>
1219            <arg>-2</arg>
1220            <arg>-4</arg>
1221          </group>
1222      </cmdsynopsis>
1223    </refsynopsisdiv>
1224    <refsect1>
1225      <title>Arguments</title>
1226      <informaltable frame="all">
1227        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1228          <colspec colname="c1">
1229          <colspec colname="c2">
1230          <colspec colname="c3">
1231          <colspec colname="c4">
1232          <thead>
1233            <row>
1234              <entry>Name</entry>
1235              <entry>Type</entry>
1236              <entry>Description</entry>
1237              <entry>Default</entry>
1238            </row>
1239          </thead>
1240          <tbody>
1241            <row>
1242              <entry>-s <replaceable>location1</replaceable></entry>         
1243              <entry>Memory address</entry>
1244              <entry>Location for start of data.</entry>             
1245              <entry><emphasis>none</emphasis></entry>       
1246            </row>
1247            <row>
1248              <entry>-d <replaceable>location2</replaceable></entry>         
1249              <entry>Memory address</entry>
1250              <entry>Location for start of data.</entry>             
1251              <entry><emphasis>none</emphasis></entry>       
1252            </row>
1253            <row>
1254              <entry>-l <replaceable>length</replaceable></entry>           
1255              <entry>Number</entry>
1256              <entry>Length of data</entry>         
1257              <entry><emphasis>none</emphasis></entry>       
1258            </row>
1259            <row>
1260              <entry>-1</entry>     
1261              <entry></entry>
1262              <entry>Access one byte (8 bits) at a time. 
1263Only the least significant 8 bits of the pattern will be used.</entry>       
1264              <entry>-4</entry>     
1265            </row>
1266            <row>
1267              <entry>-2</entry>     
1268              <entry></entry>
1269              <entry>Access two bytes (16 bits) at a time. 
1270Only the least significant 16 bits of the pattern will be used.</entry>     
1271              <entry>-4</entry>     
1272            </row>
1273            <row>
1274              <entry>-4</entry>     
1275              <entry></entry>
1276              <entry>Access one word (32 bits) at a time.</entry>           
1277              <entry>-4</entry>     
1278            </row>
1279          </tbody>
1280        </tgroup>
1281      </informaltable>
1282    </refsect1>
1283    <refsect1>
1284      <title>Description</title>
1285        <para>Compares the contents of two ranges of memory (RAM, ROM, FLASH, etc).</para>
1286    </refsect1>
1287    <refsect1>
1288      <title>Examples</title>
1289      <para>
1290Compare two buffers which match (result is <emphasis>quiet</emphasis>).
1291<screen> 
1292RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
1293RedBoot> <userinput>mfill -b 0x200000 -l 0x20 -p 0xDEADFACE</userinput>
1294RedBoot> <userinput>mcmp -s 0x100000 -d 0x200000 -l 0x20</userinput>
1295</screen>
1296</para>
1297<para>
1298Compare two buffers which don't match. 
1299Only the first non-matching element is displayed.
1300<screen> 
1301RedBoot> <userinput>mcmp -s 0x100000 -d 0x200000 -l 0x30 -2</userinput>
1302Buffers don't match - 0x00100020=0x6000, 0x00200020=0x0000
1303</screen>
1304      </para>
1305    </refsect1>
1306  </refentry>
1307
1308<!-- ******** mcopy *************************************************** -->
1309  <refentry id="mcopy-command">
1310    <refnamediv>
1311      <refname>mcopy</refname>
1312      <refpurpose>Copy memory</refpurpose>
1313    </refnamediv>
1314    <refsynopsisdiv>
1315      <cmdsynopsis>
1316        <command>mcopy</command>
1317            <arg choice="req">-s <replaceable>source</replaceable></arg>
1318            <arg choice="req">-d <replaceable>destination</replaceable></arg>
1319            <arg choice="req">-l <replaceable>length</replaceable></arg>
1320          <group>
1321            <arg>-1</arg>
1322            <arg>-2</arg>
1323            <arg>-4</arg>
1324          </group>
1325      </cmdsynopsis>
1326    </refsynopsisdiv>
1327    <refsect1>
1328      <title>Arguments</title>
1329      <informaltable frame="all">
1330        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1331          <colspec colname="c1">
1332          <colspec colname="c2">
1333          <colspec colname="c3">
1334          <colspec colname="c4">
1335          <thead>
1336            <row>
1337              <entry>Name</entry>
1338              <entry>Type</entry>
1339              <entry>Description</entry>
1340              <entry>Default</entry>
1341            </row>
1342          </thead>
1343          <tbody>
1344            <row>
1345              <entry>-s <replaceable>location1</replaceable></entry>         
1346              <entry>Memory address</entry>
1347              <entry>Location of data to copy.</entry>       
1348              <entry><emphasis>none</emphasis></entry>       
1349            </row>
1350            <row>
1351              <entry>-d <replaceable>location2</replaceable></entry>         
1352              <entry>Memory address</entry>
1353              <entry>Destination for copied data.</entry>           
1354              <entry><emphasis>none</emphasis></entry>       
1355            </row>
1356            <row>
1357              <entry>-l <replaceable>length</replaceable></entry>           
1358              <entry>Number</entry>
1359              <entry>Length of data</entry>         
1360              <entry><emphasis>none</emphasis></entry>       
1361            </row>
1362            <row>
1363              <entry>-1</entry>     
1364              <entry></entry>
1365              <entry>Copy one byte (8 bits) at a time.</entry>
1366              <entry>-4</entry>     
1367            </row>
1368            <row>
1369              <entry>-2</entry>     
1370              <entry></entry>
1371              <entry>Copy two bytes (16 bits) at a time.</entry>
1372              <entry>-4</entry>     
1373            </row>
1374            <row>
1375              <entry>-4</entry>     
1376              <entry></entry>
1377              <entry>Copy one word (32 bits) at a time.</entry>     
1378              <entry>-4</entry>     
1379            </row>
1380          </tbody>
1381        </tgroup>
1382      </informaltable>
1383    </refsect1>
1384    <refsect1>
1385      <title>Description</title>
1386        <para>Copies memory (RAM, ROM, FLASH, etc) from one area to another.</para>
1387    </refsect1>
1388    <refsect1>
1389      <title>Examples</title>
1390      <para>
1391Copy 16 bits at a time.
1392<screen> 
1393RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -2 -p 0xDEAD</userinput>
1394RedBoot> <userinput>mfill -b 0x200000 -l 0x20 -2 -p 0x0</userinput>
1395RedBoot> <userinput>dump  -b 0x200000 -l 0x20 -2</userinput>
139600200000: 0000 0000 0000 0000  0000 0000 0000 0000
139700200010: 0000 0000 0000 0000  0000 0000 0000 0000
1398RedBoot> <userinput>mcopy -s 0x100000 -d 0x200000 -2 -l 0x20</userinput>
1399RedBoot> <userinput>dump  -b 0x200000 -l 0x20 -2</userinput>
140000200000: DEAD DEAD DEAD DEAD  DEAD DEAD DEAD DEAD
140100200010: DEAD DEAD DEAD DEAD  DEAD DEAD DEAD DEAD
1402</screen>
1403</para>
1404    </refsect1>
1405  </refentry>
1406
1407<!-- ******** mfill *************************************************** -->
1408  <refentry id="mfill-command">
1409    <refnamediv>
1410      <refname>mfill</refname>
1411      <refpurpose>Fill RAM with a specified pattern</refpurpose>
1412    </refnamediv>
1413    <refsynopsisdiv>
1414      <cmdsynopsis>
1415        <command>mfill</command>
1416            <arg choice="req">-b <replaceable>location</replaceable></arg>
1417            <arg choice="req">-l <replaceable>length</replaceable></arg>
1418            <arg choice="req">-p <replaceable>value</replaceable></arg>
1419          <group>
1420            <arg>-1</arg>
1421            <arg>-2</arg>
1422            <arg>-4</arg>
1423          </group>
1424      </cmdsynopsis>
1425    </refsynopsisdiv>
1426    <refsect1>
1427      <title>Arguments</title>
1428      <informaltable frame="all">
1429        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1430          <colspec colname="c1">
1431          <colspec colname="c2">
1432          <colspec colname="c3">
1433          <colspec colname="c4">
1434          <thead>
1435            <row>
1436              <entry>Name</entry>
1437              <entry>Type</entry>
1438              <entry>Description</entry>
1439              <entry>Default</entry>
1440            </row>
1441          </thead>
1442          <tbody>
1443            <row>
1444              <entry>-b <replaceable>location</replaceable></entry>         
1445              <entry>Memory address</entry>
1446              <entry>Location in memory for start of data.</entry>           
1447              <entry><emphasis>none</emphasis></entry>       
1448            </row>
1449            <row>
1450              <entry>-l <replaceable>length</replaceable></entry>           
1451              <entry>Number</entry>
1452              <entry>Length of data</entry>         
1453              <entry><emphasis>none</emphasis></entry>       
1454            </row>
1455            <row>
1456              <entry>-p <replaceable>pattern</replaceable></entry>           
1457              <entry>Number</entry>
1458              <entry>Data value to fill with</entry>         
1459              <entry>0</entry>       
1460            </row>
1461            <row>
1462              <entry>-1</entry>     
1463              <entry></entry>
1464              <entry>Access one byte (8 bits) at a time. 
1465Only the least significant 8 bits of the pattern will be used.</entry>       
1466              <entry>-4</entry>     
1467            </row>
1468            <row>
1469              <entry>-2</entry>     
1470              <entry></entry>
1471              <entry>Access two bytes (16 bits) at a time. 
1472Only the least significant 16 bits of the pattern will be used.</entry>     
1473              <entry>-4</entry>     
1474            </row>
1475            <row>
1476              <entry>-4</entry>     
1477              <entry></entry>
1478              <entry>Access one word (32 bits) at a time.</entry>           
1479              <entry>-4</entry>     
1480            </row>
1481          </tbody>
1482        </tgroup>
1483      </informaltable>
1484    </refsect1>
1485    <refsect1>
1486      <title>Description</title>
1487        <para>Fills a range of memory with the given pattern.</para>
1488    </refsect1>
1489    <refsect1>
1490      <title>Examples</title>
1491      <para>
1492Fill a buffer with zeros.
1493<screen> 
1494RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
149500100000: 00 3E 00 06 00 06 00 06  00 00 00 00 00 00 00 00  |.>..............|
149600100010: 00 00 00 78 00 70 00 60  00 60 00 60 00 60 00 60  |...x.p.`.`.`.`.`|
1497RedBoot> <userinput>mfill -b 0x100000 -l 0x20</userinput>
1498RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
149900100000: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
150000100010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
1501</screen>
1502</para>
1503<para>
1504Fill a buffer with a pattern.
1505<screen> 
1506RedBoot> <userinput>mfill -b 0x100000 -l 0x20 -p 0xDEADFACE</userinput>
1507RedBoot> <userinput>x -b 0x100000 -l 0x20</userinput>
150800100000: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
150900100010: CE FA AD DE CE FA AD DE  CE FA AD DE CE FA AD DE  |................|
1510</screen>
1511      </para>
1512    </refsect1>
1513  </refentry>
1514
1515<!-- ******** ping *************************************************** -->
1516  <refentry id="ping-command">
1517    <refnamediv>
1518      <refname>ping</refname>
1519      <refpurpose>Verify network connectivity</refpurpose>
1520    </refnamediv>
1521    <refsynopsisdiv>
1522      <cmdsynopsis>
1523        <command>ping</command>
1524        <arg>-v </arg>
1525        <arg>-i <replaceable> local_IP_address</replaceable></arg>
1526        <arg>-l <replaceable> length</replaceable></arg>
1527        <arg>-n <replaceable> count</replaceable></arg>
1528        <arg>-t <replaceable> timeout</replaceable></arg>
1529        <arg>-r <replaceable> rate</replaceable></arg>
1530        <arg choice="req">-h <replaceable> server_IP_address</replaceable></arg>
1531      </cmdsynopsis>
1532    </refsynopsisdiv>
1533    <refsect1>
1534      <title>Arguments</title>
1535      <informaltable frame="all">
1536        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1537          <colspec colname="c1">
1538          <colspec colname="c2">
1539          <colspec colname="c3">
1540          <colspec colname="c4">
1541          <thead>
1542            <row>
1543              <entry>Name</entry>
1544              <entry>Type</entry>
1545              <entry>Description</entry>
1546              <entry>Default</entry>
1547            </row>
1548          </thead>
1549          <tbody>
1550            <row>
1551              <entry>-v</entry>     
1552              <entry>Boolean</entry>
1553              <entry>Be verbose, displaying information about each packet sent.</entry>     
1554              <entry><emphasis>quiet</emphasis></entry>     
1555            </row>
1556            <row>
1557              <entry>-n <replaceable>local_IP_address</replaceable></entry>         
1558              <entry>Number</entry>
1559              <entry>Controls the number of packets to be sent.</entry>     
1560              <entry>10</entry>     
1561            </row>
1562            <row>
1563              <entry>-i <replaceable>local_IP_address</replaceable></entry>         
1564              <entry>Numeric IP or DNS name</entry>
1565              <entry>The IP address RedBoot should use.</entry>     
1566              <entry>Value set by <command>ip_address</command></entry>     
1567            </row>
1568            <row>
1569              <entry>-h <replaceable>server_IP_address</replaceable></entry>         
1570              <entry>Numeric IP or DNS name</entry>
1571              <entry>The IP address of the host to contact.</entry>
1572              <entry><emphasis>none</emphasis></entry>       
1573            </row>
1574            <row>
1575              <entry>-l <replaceable>length</replaceable></entry>           
1576              <entry>Number</entry>
1577              <entry>The length of the ICMP data payload.</entry>           
1578              <entry>64</entry>     
1579            </row>
1580            <row>
1581              <entry>-r <replaceable>length</replaceable></entry>           
1582              <entry>Number</entry>
1583              <entry>How fast to deliver packets, i.e. time between successive sends.
1584A value of 0 sends packets as quickly as possible.</entry>           
1585              <entry>1000ms (1 second)</entry>       
1586            </row>
1587            <row>
1588              <entry>-t <replaceable>length</replaceable></entry>           
1589              <entry>Number</entry>
1590              <entry>How long to wait for the round-trip to complete, specified in milliseconds.</entry>             
1591              <entry>1000ms (1 second)</entry>       
1592            </row>
1593          </tbody>
1594        </tgroup>
1595      </informaltable>
1596    </refsect1>
1597    <refsect1>
1598      <title>Description</title>
1599      <para>
1600The <command>ping</command> command checks the connectivity of the local network by sending
1601special (ICMP) packets to a specific host. These packets should be automatically
1602returned by that host. The command will indicate how many of these round-trips
1603were successfully completed.
1604      </para>
1605    </refsect1>
1606    <refsect1>
1607      <title>Examples</title>
1608      <para>
1609Test connectivity to host 192.168.1.101.
1610<screen>
1611RedBoot> <userinput>ping -h 192.168.1.101</userinput>
1612Network PING - from 192.168.1.31 to 192.168.1.101
1613PING - received 10 of 10 expected
1614</screen>
1615</para>
1616<para>
1617Test connectivity to host 192.168.1.101, with verbose reporting.
1618<screen>
1619RedBoot> <userinput>ping -h 192.168.1.101 -v -n 4</userinput>
1620Network PING - from 192.168.1.31 to 192.168.1.101
1621 seq: 1, time: 1 (ticks)
1622 seq: 2, time: 1 (ticks)
1623 seq: 3, time: 1 (ticks)
1624 seq: 4, time: 1 (ticks)
1625PING - received 10 of 10 expected
1626</screen>
1627</para>
1628<para>
1629<screen>
1630Test connectivity to a non-existent host (192.168.1.109).
1631RedBoot> <userinput>ping -h 192.168.1.109 -v -n 4</userinput>
1632PING: Cannot reach server '192.168.1.109' (192.168.1.109)
1633</screen>
1634      </para>
1635    </refsect1>
1636  </refentry>
1637
1638<!-- ******** reset *************************************************** -->
1639  <refentry id="reset-command">
1640    <refnamediv>
1641      <refname>reset</refname>
1642      <refpurpose>Reset the device</refpurpose>
1643    </refnamediv>
1644    <refsynopsisdiv>
1645      <cmdsynopsis>
1646        <command>reset</command>
1647      </cmdsynopsis>
1648    </refsynopsisdiv>
1649    <refsect1>
1650      <title>Arguments</title>
1651<para><emphasis>None</emphasis></para>
1652    </refsect1>
1653    <refsect1>
1654      <title>Description</title>
1655      <para>
1656The <command>reset</command> command causes the target platform to be reset.
1657Where possible (hardware support permitting), this will be
1658equivalent to a power-on reset condition.
1659      </para>
1660    </refsect1>
1661    <refsect1>
1662      <title>Examples</title>
1663      <para>
1664Reset the platform.
1665<screen>
1666RedBoot> <userinput>reset</userinput>
1667... Resetting.+... Waiting for network card: .
1668Socket Communications, Inc: Low Power Ethernet CF Revision C 5V/3.3V 08/27/98
1669Ethernet eth0: MAC address 00:c0:1b:00:ba:28
1670IP: 192.168.1.29, Default server: 192.168.1.101
1671
1672RedBoot(tm) bootstrap and debug environment [ROM]
1673Non-certified release, version UNKNOWN - built 10:41:41, May 14 2002
1674
1675Platform: Compaq iPAQ Pocket PC (StrongARM 1110)
1676Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
1677
1678RAM: 0x00000000-0x01fc0000, 0x00014748-0x01f71000 available
1679FLASH: 0x50000000 - 0x51000000, 64 blocks of 0x00040000 bytes each.
1680RedBoot>
1681</screen>
1682      </para>
1683    </refsect1>
1684  </refentry>
1685
1686
1687<!-- ******** version *************************************************** -->
1688  <refentry id="version-command">
1689    <refnamediv>
1690      <refname>version</refname>
1691      <refpurpose>Display RedBoot version information</refpurpose>
1692    </refnamediv>
1693    <refsynopsisdiv>
1694      <cmdsynopsis>
1695        <command>version</command>
1696      </cmdsynopsis>
1697    </refsynopsisdiv>
1698    <refsect1>
1699      <title>Arguments</title>
1700      <para><emphasis>None</emphasis></para>
1701    </refsect1>
1702    <refsect1>
1703      <title>Description</title>
1704      <para>The <command>version</command> command simply displays version information about RedBoot.
1705      </para>
1706    </refsect1>
1707    <refsect1>
1708      <title>Examples</title>
1709      <para>
1710Display RedBoot's version.
1711<screen>
1712RedBoot> <userinput>version</userinput>
1713RedBoot(tm) debug environment - built 09:12:03, Feb 12 2001
1714Platform: XYZ (PowerPC 860)
1715Copyright (C) 2000, 2001, Red Hat, Inc.
1716RAM: 0x00000000-0x00400000
1717</screen>
1718      </para>
1719    </refsect1>
1720  </refentry>
1721
1722</sect1>
1723 
1724<sect1 id="Flash-Image-System">
1725<title>Flash Image System (FIS)</title>
1726<para><indexterm><primary>commands</primary><secondary>flash image system
1727</secondary></indexterm><indexterm><primary>flash image system commands</primary>
1728</indexterm><indexterm><primary>commands</primary><secondary>fis</secondary>
1729</indexterm><indexterm><primary>fis commands</primary></indexterm>If the platform
1730has flash memory, RedBoot can use this for image storage. Executable images,
1731as well as data, can be stored in flash in a simple file store. The <command>
1732fis</command> command (fis is short for Flash Image System) is used to
1733manipulate and maintain flash images.
1734</para>
1735
1736<!-- ******** fis init ************************************************ -->
1737
1738  <refentry id="fis-init-command">
1739    <refnamediv>
1740      <refname>fis init</refname>
1741      <refpurpose>Initialize Flash Image System (FIS)</refpurpose>
1742    </refnamediv>
1743    <refsynopsisdiv>
1744      <cmdsynopsis>
1745        <command>fis init</command>
1746        <arg><replaceable>-f</replaceable></arg>
1747      </cmdsynopsis>
1748    </refsynopsisdiv>
1749    <refsect1>
1750      <title>Arguments</title>
1751      <informaltable frame="all">
1752        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1753          <colspec colname="c1">
1754          <colspec colname="c2">
1755          <colspec colname="c3">
1756          <colspec colname="c4">
1757          <thead>
1758            <row>
1759              <entry>Name</entry>
1760              <entry>Type</entry>
1761              <entry>Description</entry>
1762              <entry>Default</entry>
1763            </row>
1764          </thead>
1765          <tbody>
1766            <row>
1767              <entry>-f</entry>     
1768              <entry></entry>
1769              <entry>All blocks of flash memory (except for the boot
1770              blocks) will be erased as part of the initialization
1771              procedure.</entry>
1772              <entry></entry>       
1773            </row>
1774          </tbody>
1775        </tgroup>
1776      </informaltable>
1777    </refsect1>
1778    <refsect1>
1779      <title>Description</title>
1780
1781       <para>This command is used to initialize the Flash Image System
1782       (FIS). It should normally only be executed once, when RedBoot
1783       is first installed on the hardware. If the reserved images or
1784       their sizes in the FIS change, due to a different configuration
1785       of RedBoot being used, it may be necessary to issue the command
1786       again though.
1787
1788        <note><para>Subsequent executions will cause loss of
1789       previously stored information in the FIS.</para></note>
1790     </para>
1791    </refsect1>
1792    <refsect1>
1793      <title>Examples</title>
1794      <para>
1795Initialize the FIS directory.
1796<screen> 
1797RedBoot> <userinput>fis init</userinput>
1798About to initialize [format] flash image system - continue (y/n)? <userinput>y</userinput>
1799*** Initialize FLASH Image System
1800    Warning: device contents not erased, some blocks may not be usable
1801... Erase from 0x00070000-0x00080000: .
1802... Program from 0x0606f000-0x0607f000 at 0x00070000: .
1803</screen>
1804</para>
1805
1806      <para>
1807Initialize the FIS directory and all of flash memory, except for first
1808blocks of the flash where the boot monitor resides.
1809<screen> 
1810RedBoot> <userinput>fis init -f</userinput>
1811About to initialize [format] flash image system - continue (y/n)? <userinput>y</userinput>
1812*** Initialize FLASH Image System                                               
1813... Erase from 0x00020000-0x00070000: .....                                     
1814... Erase from 0x00080000-0x00080000:                                           
1815... Erase from 0x00070000-0x00080000: .                                         
1816... Program from 0x0606f000-0x0607f000 at 0x00070000: .                         
1817</screen>
1818</para>
1819</refsect1>
1820</refentry>
1821
1822<!-- ******** fis list ************************************************ -->
1823  <refentry id="fis-list-command">
1824    <refnamediv>
1825      <refname>fis list</refname>
1826      <refpurpose>List Flash Image System directory</refpurpose>
1827    </refnamediv>
1828    <refsynopsisdiv>
1829      <cmdsynopsis>
1830        <command>fis list</command>
1831        <arg><replaceable>-f</replaceable></arg>
1832      </cmdsynopsis>
1833    </refsynopsisdiv>
1834    <refsect1>
1835      <title>Arguments</title>
1836      <informaltable frame="all">
1837        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1838          <colspec colname="c1">
1839          <colspec colname="c2">
1840          <colspec colname="c3">
1841          <colspec colname="c4">
1842          <thead>
1843            <row>
1844              <entry>Name</entry>
1845              <entry>Type</entry>
1846              <entry>Description</entry>
1847              <entry>Default</entry>
1848            </row>
1849          </thead>
1850          <tbody>
1851            <row>
1852              <entry>-c</entry>
1853              <entry></entry>
1854              <entry>Show image checksum instead of memory address
1855              (column <computeroutput>Mem addr</computeroutput> is
1856              replaced by
1857              <computeroutput>Checksum</computeroutput>).</entry>
1858              <entry></entry>
1859            </row>
1860            <row>
1861              <entry>-d</entry>
1862              <entry></entry>
1863              <entry>Show image data length instead of amount of flash
1864              occupied by image (column
1865              <computeroutput>Length</computeroutput> is replaced by
1866              <computeroutput>Datalen</computeroutput>).</entry>
1867              <entry></entry>
1868            </row>
1869          </tbody>
1870        </tgroup>
1871      </informaltable>
1872    </refsect1>
1873    <refsect1>
1874      <title>Description</title>
1875<para>This command lists the images currently available in the FIS. Certain
1876images used by RedBoot have fixed names and have reserved slots in the
1877FIS (these can be seen after using the <command>fis init</command>
1878command). Other images can be manipulated by the user.</para>
1879<note><para>The images are listed in the order they appear in the FIS
1880directory, not by name or creation time.</para></note>
1881    </refsect1>
1882
1883    <refsect1>
1884      <title>Examples</title>
1885      <para>
1886List the FIS directory.
1887<screen> 
1888RedBoot> <userinput>fis list</userinput>
1889Name              FLASH addr  Mem addr    Length      Entry point               
1890RedBoot           0x00000000  0x00000000  0x00020000  0x00000000               
1891RedBoot config    0x0007F000  0x0007F000  0x00001000  0x00000000               
1892FIS directory     0x00070000  0x00070000  0x0000F000  0x00000000               
1893</screen>
1894</para>
1895
1896      <para>
1897List the FIS directory, with image checksums substituted for
1898memory addresses.
1899<screen> 
1900RedBoot> <userinput>fis list -c</userinput>
1901Name              FLASH addr  Checksum    Length      Entry point               
1902RedBoot           0x00000000  0x00000000  0x00020000  0x00000000               
1903RedBoot config    0x0007F000  0x00000000  0x00001000  0x00000000               
1904FIS directory     0x00070000  0x00000000  0x0000F000  0x00000000               
1905</screen>
1906</para>
1907
1908      <para>
1909List the FIS directory with image data lengths substituted for flash
1910block reservation lengths.
1911<screen> 
1912RedBoot> <userinput>fis list -d</userinput>
1913Name              FLASH addr  Mem addr    Datalen     Entry point               
1914RedBoot           0x00000000  0x00000000  0x00000000  0x00000000               
1915RedBoot config    0x0007F000  0x0007F000  0x00000000  0x00000000               
1916FIS directory     0x00070000  0x00070000  0x00000000  0x00000000               
1917</screen>
1918</para>
1919</refsect1>
1920</refentry>
1921
1922<!-- ******** fis free ************************************************ -->
1923
1924  <refentry id="fis-free-command">
1925    <refnamediv>
1926      <refname>fis free</refname>
1927      <refpurpose>Free flash image</refpurpose>
1928    </refnamediv>
1929    <refsynopsisdiv>
1930      <cmdsynopsis>
1931        <command>fis free</command>
1932      </cmdsynopsis>
1933    </refsynopsisdiv>
1934    <refsect1>
1935      <title>Description</title>
1936
1937
1938<para>This command shows which areas of the flash memory are currently
1939not in use. When a block contains non-erased contents it is considered
1940in use. Since it is possible to force an image to be loaded at a
1941particular flash location, this command can be used to check whether
1942that location is in use by any other image.</para>
1943
1944<note><para>There is currently no cross-checking between actual flash
1945contents and the FIS directory, which mans that there could be a
1946segment of flash which is not erased that does not correspond to a
1947named image, or vice-versa.</para></note>
1948    </refsect1>
1949
1950    <refsect1>
1951      <title>Examples</title>
1952      <para>
1953Show free flash areas.
1954<screen>
1955RedBoot> <userinput>fis free</userinput>
1956        0xA0040000 .. 0xA07C0000
1957        0xA0840000 .. 0xA0FC0000
1958</screen></para>
1959</refsect1>
1960</refentry>
1961
1962<!-- ******** fis create ************************************************ -->
1963
1964  <refentry id="fis-create-command">
1965    <refnamediv>
1966      <refname>fis create</refname>
1967      <refpurpose>Create flash image</refpurpose>
1968    </refnamediv>
1969    <refsynopsisdiv>
1970      <cmdsynopsis>
1971        <command>fis create</command>
1972        <arg choice="req">-b <replaceable> data address</replaceable></arg>
1973        <arg choice="req">-l <replaceable> length</replaceable></arg>
1974        <arg>-f <replaceable> flash address</replaceable></arg>
1975        <arg>-e <replaceable> entry</replaceable></arg>
1976        <arg>-r <replaceable> relocation address</replaceable></arg>
1977        <arg>-s <replaceable> data length</replaceable></arg>
1978        <arg>-n </arg>
1979        <arg><replaceable>name</replaceable></arg>
1980      </cmdsynopsis>
1981    </refsynopsisdiv>
1982    <refsect1>
1983      <title>Arguments</title>
1984      <informaltable frame="all">
1985        <tgroup cols="4" colsep="1" rowsep="1" align="left">
1986          <colspec colname="c1">
1987          <colspec colname="c2">
1988          <colspec colname="c3">
1989          <colspec colname="c4">
1990          <thead>
1991            <row>
1992              <entry>Name</entry>
1993              <entry>Type</entry>
1994              <entry>Description</entry>
1995              <entry>Default</entry>
1996            </row>
1997          </thead>
1998          <tbody>
1999            <row>
2000              <entry>-b</entry>
2001              <entry>Number</entry>
2002              <entry>Address of data to be written to the flash.</entry>
2003              <entry>Address of last loaded file. If not set in a load
2004              operation, it must be specified.</entry>
2005            </row>
2006            <row>
2007              <entry>-l</entry>
2008              <entry>Number</entry>
2009              <entry>Length of flash area to occopy. If specified, and
2010              the named image already exists, the length must match
2011              the value in the FIS directory.</entry>
2012              <entry>Length of area reserved in FIS directory if the
2013              image already exists, or the length of the last loaded
2014              file. If neither are set, it must be specified.</entry>
2015            </row>
2016            <row>
2017              <entry>-f</entry>
2018              <entry>Number</entry>
2019              <entry>Address of flash area to occopy.</entry>
2020              <entry>The address of an area reserved in the FIS
2021              directory for extant images. Otherwise the first free block
2022              which is large enough will be used.</entry>
2023            </row>
2024            <row>
2025              <entry>-e</entry>
2026              <entry>Number</entry>
2027              <entry>Entry address for an executable image, used by
2028              the <command>fis load</command> command.</entry>
2029              <entry>The entry address of last loaded file.</entry>
2030            </row>
2031            <row>
2032              <entry>-r</entry>
2033              <entry>Number</entry>
2034              <entry>Address where the image should be relocated to by
2035              the <command>fis load</command> command. This is only
2036              relevant for images that will be loaded with the
2037              <command>fis load</command> command.</entry>
2038              <entry>The load address of the last loaded file.</entry>
2039            </row>
2040            <row>
2041              <entry>-s</entry>
2042              <entry>Number</entry>
2043              <entry>Actual length of data written to image. This is
2044              used to control the range over which the checksum is
2045              made.</entry>
2046              <entry>It defaults to the length of the last loaded
2047              file.</entry>
2048            </row>
2049            <row>
2050              <entry>-n</entry>
2051              <entry></entry>
2052              <entry>When set, no image data will be written to the
2053              flash. Only the FIS directory will be updated.</entry>
2054              <entry></entry>
2055            </row>
2056            <row>
2057              <entry><replaceable>name</replaceable></entry>
2058              <entry>String</entry>
2059              <entry>Name of flash image.</entry>
2060              <entry></entry>
2061            </row>
2062          </tbody>
2063        </tgroup>
2064      </informaltable>
2065    </refsect1>
2066    <refsect1>
2067      <title>Description</title>
2068<para>This command creates an image in the FIS directory. The data for the
2069image must exist in RAM memory before the copy. Typically, you would use the
2070RedBoot <command>load</command> command to load file into
2071RAM and then the <command>fis create</command> command to write
2072it to a flash image.</para>
2073</refsect1>
2074
2075    <refsect1>
2076      <title>Examples</title>
2077      <para>Trying to create an extant image, will require the action
2078      to be verified.
2079<screen>
2080RedBoot> <userinput>fis create RedBoot -f 0xa0000000 -b 0x8c400000 -l 0x20000</userinput>
2081An image named &lsquo;RedBoot&rsquo; exists - continue (y/n)? <userinput>n</userinput>
2082</screen>
2083</para>
2084
2085<para>Create a new test image, let the command find a suitable place.
2086<screen>
2087RedBoot> <userinput>fis create junk -b 0x8c400000 -l 0x20000</userinput>
2088... Erase from 0xa0040000-0xa0060000: .
2089... Program from 0x8c400000-0x8c420000 at 0xa0040000: .
2090... Erase from 0xa0fe0000-0xa1000000: .
2091... Program from 0x8c7d0000-0x8c7f0000 at 0xa0fe0000: .
2092</screen>
2093</para>
2094
2095<para>Update the RedBoot[RAM] image.
2096<screen>
2097RedBoot> <userinput>load redboot_RAM.img</userinput>
2098Entry point: 0x060213c0, address range: 0x06020000-0x06036cc0                   
2099RedBoot> <userinput>fis create RedBoot[RAM]</userinput>
2100No memory address set.
2101An image named 'RedBoot[RAM]' exists - continue (y/n)? <userinput>y</userinput>
2102* CAUTION * about to program 'RedBoot[RAM]'
2103            at 0x00020000..0x00036cbf from 0x06020000 - continue (y/n)? <userinput>y</userinput>
2104... Erase from 0x00020000-0x00040000: ..
2105... Program from 0x06020000-0x06036cc0 at 0x00020000: ..
2106... Erase from 0x00070000-0x00080000: .
2107... Program from 0x0606f000-0x0607f000 at 0x00070000: .
2108</screen>
2109</para>
2110</refsect1>
2111</refentry>
2112
2113<!-- ******** fis load ************************************************ -->
2114
2115  <refentry id="fis-load-command">
2116    <refnamediv>
2117      <refname>fis load</refname>
2118      <refpurpose>Load flash image</refpurpose>
2119    </refnamediv>
2120    <refsynopsisdiv>
2121      <cmdsynopsis>
2122        <command>fis load</command>
2123        <arg>-b <replaceable> load address</replaceable></arg>
2124        <arg>-c </arg>
2125        <arg>-d </arg>
2126        <arg><replaceable>name</replaceable></arg>
2127      </cmdsynopsis>
2128    </refsynopsisdiv>
2129    <refsect1>
2130      <title>Arguments</title>
2131      <informaltable frame="all">
2132        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2133          <colspec colname="c1">
2134          <colspec colname="c2">
2135          <colspec colname="c3">
2136          <colspec colname="c4">
2137          <thead>
2138            <row>
2139              <entry>Name</entry>
2140              <entry>Type</entry>
2141              <entry>Description</entry>
2142              <entry>Default</entry>
2143            </row>
2144          </thead>
2145          <tbody>
2146            <row>
2147              <entry>-b</entry>
2148              <entry>Number</entry>
2149              <entry>Address the image should be loaded to. Executable
2150              images normally load at the location to which the file
2151              was linked. This option allows the image to be loaded to
2152              a specific memory location, possibly overriding any
2153              assumed location.</entry>
2154              <entry>If not specified, the address associated with the
2155              image in the FIS directory will be used.</entry>
2156            </row>
2157            <row>
2158              <entry>-c</entry>
2159              <entry></entry>
2160              <entry>Compute and print the checksum of the image data
2161              after it has been loaded into memory.</entry>
2162            </row>
2163            <row>
2164              <entry>-d</entry>
2165              <entry></entry>
2166              <entry>Decompress gzipped image while copying it from
2167              flash to RAM.</entry>
2168            </row>
2169            <row>
2170              <entry><replaceable>name</replaceable></entry>
2171              <entry>String</entry>
2172              <entry>The name of the file, as shown in the FIS
2173              directory.</entry>
2174            </row>
2175          </tbody>
2176        </tgroup>
2177      </informaltable>
2178    </refsect1>
2179    <refsect1>
2180      <title>Description</title>
2181<para>This command is used to transfer an image from flash memory to RAM.
2182</para>
2183<para>Once the image has been loaded, it may be executed using the
2184<command>go</command> command.</para>
2185</refsect1>
2186
2187    <refsect1>
2188      <title>Examples</title>
2189<para>Load and run RedBoot[RAM] image.
2190<screen>
2191RedBoot> <userinput>fis load RedBoot[RAM]</userinput>
2192RedBoot> <userinput>go</userinput>
2193</screen>
2194</para>
2195</refsect1>
2196</refentry>
2197
2198<!-- ******** fis delete ************************************************ -->
2199
2200  <refentry id="fis-delete-command">
2201    <refnamediv>
2202      <refname>fis delete</refname>
2203      <refpurpose>Delete flash image</refpurpose>
2204    </refnamediv>
2205    <refsynopsisdiv>
2206      <cmdsynopsis>
2207        <command>fis delete</command>
2208        <arg choice="req"><replaceable>name</replaceable></arg>
2209      </cmdsynopsis>
2210    </refsynopsisdiv>
2211    <refsect1>
2212      <title>Arguments</title>
2213      <informaltable frame="all">
2214        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2215          <colspec colname="c1">
2216          <colspec colname="c2">
2217          <colspec colname="c3">
2218          <colspec colname="c4">
2219          <thead>
2220            <row>
2221              <entry>Name</entry>
2222              <entry>Type</entry>
2223              <entry>Description</entry>
2224              <entry>Default</entry>
2225            </row>
2226          </thead>
2227          <tbody>
2228            <row>
2229              <entry><replaceable>name</replaceable></entry>
2230              <entry>Number</entry>
2231              <entry>Name of image that should be deleted.</entry>
2232              <entry></entry>
2233            </row>
2234          </tbody>
2235        </tgroup>
2236      </informaltable>
2237    </refsect1>
2238    <refsect1>
2239      <title>Description</title>
2240<para>This command removes an image from the FIS. The flash memory will be
2241erased as part of the execution of this command, as well as removal of the
2242name from the FIS directory.</para>
2243
2244<note><para>Certain images are reserved by RedBoot and cannot be deleted.
2245RedBoot will issue a warning if this is attempted.</para></note>
2246</refsect1>
2247    <refsect1>
2248      <title>Examples</title>
2249<para>
2250<screen>
2251RedBoot> <userinput>fis list</userinput>
2252Name              flash addr   Mem addr    Length    Entry point
2253RedBoot          0xA0000000   0xA0000000  0x020000  0x80000000
2254RedBoot config   0xA0FC0000   0xA0FC0000  0x020000  0x00000000
2255FIS directory    0xA0FE0000   0xA0FE0000  0x020000  0x00000000
2256junk             0xA0040000   0x8C400000  0x020000  0x80000000
2257RedBoot> <userinput>fis delete junk</userinput>
2258Delete image &lsquo;junk&rsquo; - continue (y/n)? <userinput>y</userinput>
2259... Erase from 0xa0040000-0xa0060000: .
2260... Erase from 0xa0fe0000-0xa1000000: .
2261... Program from 0x8c7d0000-0x8c7f0000 at 0xa0fe0000: .
2262</screen>
2263</para>
2264</refsect1>
2265</refentry>
2266
2267<!-- ******** fis lock ************************************************ -->
2268
2269  <refentry id="fis-lock-command">
2270    <refnamediv>
2271      <refname>fis lock</refname>
2272      <refpurpose>Lock flash area</refpurpose>
2273    </refnamediv>
2274    <refsynopsisdiv>
2275      <cmdsynopsis>
2276        <command>fis lock</command>
2277        <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2278        <arg choice="req">-l <replaceable>length</replaceable></arg>
2279      </cmdsynopsis>
2280    </refsynopsisdiv>
2281    <refsect1>
2282      <title>Arguments</title>
2283      <informaltable frame="all">
2284        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2285          <colspec colname="c1">
2286          <colspec colname="c2">
2287          <colspec colname="c3">
2288          <colspec colname="c4">
2289          <thead>
2290            <row>
2291              <entry>Name</entry>
2292              <entry>Type</entry>
2293              <entry>Description</entry>
2294              <entry>Default</entry>
2295            </row>
2296          </thead>
2297          <tbody>
2298            <row>
2299              <entry><replaceable>flash_address</replaceable></entry>
2300              <entry>Number</entry>
2301              <entry>Address of area to be locked.</entry>
2302              <entry></entry>
2303            </row>
2304            <row>
2305              <entry><replaceable>length</replaceable></entry>
2306              <entry>Number</entry>
2307              <entry>Length of area to be locked.</entry>
2308              <entry></entry>
2309            </row>
2310          </tbody>
2311        </tgroup>
2312      </informaltable>
2313    </refsect1>
2314    <refsect1>
2315      <title>Description</title>
2316<para>This command is used to write-protect (lock) a portion of flash memory,
2317to prevent accidental overwriting of images. In order to make make any modifications
2318to the flash, a matching <command>fis unlock</command> command must be
2319issued. This command is optional and will only be provided on hardware
2320which can support write-protection of the flash space.</para>
2321<note>
2322<para>Depending on the system, attempting to write to write-protected flash
2323may generate errors or warnings, or be benignly quiet.  </para>
2324</note>
2325</refsect1>
2326
2327    <refsect1>
2328      <title>Examples</title>
2329<para>Lock an area of the flash
2330<screen>
2331RedBoot> <userinput>fis lock -f 0xa0040000 -l 0x20000</userinput>
2332... Lock from 0xa0040000-0xa0060000: .
2333</screen>
2334</para>
2335</refsect1>
2336</refentry>
2337
2338<!-- ******** fis unlock ************************************************ -->
2339
2340  <refentry id="fis-unlock-command">
2341    <refnamediv>
2342      <refname>fis unlock</refname>
2343      <refpurpose>Unlock flash area</refpurpose>
2344    </refnamediv>
2345    <refsynopsisdiv>
2346      <cmdsynopsis>
2347        <command>fis unlock</command>
2348        <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2349        <arg choice="req">-l <replaceable>length</replaceable></arg>
2350      </cmdsynopsis>
2351    </refsynopsisdiv>
2352    <refsect1>
2353      <title>Arguments</title>
2354      <informaltable frame="all">
2355        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2356          <colspec colname="c1">
2357          <colspec colname="c2">
2358          <colspec colname="c3">
2359          <colspec colname="c4">
2360          <thead>
2361            <row>
2362              <entry>Name</entry>
2363              <entry>Type</entry>
2364              <entry>Description</entry>
2365              <entry>Default</entry>
2366            </row>
2367          </thead>
2368          <tbody>
2369            <row>
2370              <entry><replaceable>flash_address</replaceable></entry>
2371              <entry>Number</entry>
2372              <entry>Address of area to be unlocked.</entry>
2373              <entry></entry>
2374            </row>
2375            <row>
2376              <entry><replaceable>length</replaceable></entry>
2377              <entry>Number</entry>
2378              <entry>Length of area to be unlocked.</entry>
2379              <entry></entry>
2380            </row>
2381          </tbody>
2382        </tgroup>
2383      </informaltable>
2384    </refsect1>
2385    <refsect1>
2386      <title>Description</title>
2387<para>This command is used to unlock a portion of flash memory forcibly, allowing
2388it to be updated. It must be issued for regions which have been locked before
2389the FIS can reuse those portions of flash.</para>
2390<note>
2391<para>Some flash devices power up in locked state and always need to
2392be manually unlocked before they can be written to.</para></note>
2393</refsect1>
2394
2395    <refsect1>
2396      <title>Examples</title>
2397<para>Unlock an area of the flash
2398<screen>
2399RedBoot> <userinput>fis unlock -f 0xa0040000 -l 0x20000</userinput>
2400... Unlock from 0xa0040000-0xa0060000: .
2401</screen>
2402</para>
2403</refsect1>
2404</refentry>
2405
2406<!-- ******** fis erase ************************************************ -->
2407
2408  <refentry id="fis-erase-command">
2409    <refnamediv>
2410      <refname>fis erase</refname>
2411      <refpurpose>Erase flash area</refpurpose>
2412    </refnamediv>
2413    <refsynopsisdiv>
2414      <cmdsynopsis>
2415        <command>fis erase</command>
2416        <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2417        <arg choice="req">-l <replaceable>length</replaceable></arg>
2418      </cmdsynopsis>
2419    </refsynopsisdiv>
2420    <refsect1>
2421      <title>Arguments</title>
2422      <informaltable frame="all">
2423        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2424          <colspec colname="c1">
2425          <colspec colname="c2">
2426          <colspec colname="c3">
2427          <colspec colname="c4">
2428          <thead>
2429            <row>
2430              <entry>Name</entry>
2431              <entry>Type</entry>
2432              <entry>Description</entry>
2433              <entry>Default</entry>
2434            </row>
2435          </thead>
2436          <tbody>
2437            <row>
2438              <entry><replaceable>flash_address</replaceable></entry>
2439              <entry>Number</entry>
2440              <entry>Address of area to be erased.</entry>
2441              <entry></entry>
2442            </row>
2443            <row>
2444              <entry><replaceable>length</replaceable></entry>
2445              <entry>Number</entry>
2446              <entry>Length of area to be erased.</entry>
2447              <entry></entry>
2448            </row>
2449          </tbody>
2450        </tgroup>
2451      </informaltable>
2452    </refsect1>
2453    <refsect1>
2454      <title>Description</title>
2455<para>This command is used to erase a portion of flash memory forcibly. There
2456is no cross-checking to ensure that the area being erased does not correspond
2457to an existing image.</para>
2458</refsect1>
2459
2460    <refsect1>
2461      <title>Examples</title>
2462<para>Erase an area of the flash
2463<screen>
2464RedBoot> <userinput>fis erase -f 0xa0040000 -l 0x20000</userinput>
2465... Erase from 0xa0040000-0xa0060000: .
2466</screen>
2467</para>
2468</refsect1>
2469</refentry>
2470
2471<!-- ******** fis write ************************************************ -->
2472
2473  <refentry id="fis-write-command">
2474    <refnamediv>
2475      <refname>fis write</refname>
2476      <refpurpose>Write flash area</refpurpose>
2477    </refnamediv>
2478    <refsynopsisdiv>
2479      <cmdsynopsis>
2480        <command>fis write</command>
2481        <arg choice="req">-b <replaceable>mem_address</replaceable></arg>
2482        <arg choice="req">-l <replaceable>length</replaceable></arg>
2483        <arg choice="req">-f <replaceable>flash_address</replaceable></arg>
2484      </cmdsynopsis>
2485    </refsynopsisdiv>
2486    <refsect1>
2487      <title>Arguments</title>
2488      <informaltable frame="all">
2489        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2490          <colspec colname="c1">
2491          <colspec colname="c2">
2492          <colspec colname="c3">
2493          <colspec colname="c4">
2494          <thead>
2495            <row>
2496              <entry>Name</entry>
2497              <entry>Type</entry>
2498              <entry>Description</entry>
2499              <entry>Default</entry>
2500            </row>
2501          </thead>
2502          <tbody>
2503            <row>
2504              <entry><replaceable>mem_address</replaceable></entry>
2505              <entry>Number</entry>
2506              <entry>Address of data to be written to flash.</entry>
2507              <entry></entry>
2508            </row>
2509            <row>
2510              <entry><replaceable>length</replaceable></entry>
2511              <entry>Number</entry>
2512              <entry>Length of data to be writtem.</entry>
2513              <entry></entry>
2514            </row>
2515            <row>
2516              <entry><replaceable>flash_address</replaceable></entry>
2517              <entry>Number</entry>
2518              <entry>Address of flash to write to.</entry>
2519              <entry></entry>
2520            </row>
2521          </tbody>
2522        </tgroup>
2523      </informaltable>
2524    </refsect1>
2525    <refsect1>
2526      <title>Description</title>
2527<para>This command is used to write data from memory to flash. There
2528is no cross-checking to ensure that the area being written to does not
2529correspond to an existing image.</para>
2530</refsect1>
2531
2532    <refsect1>
2533      <title>Examples</title>
2534<para>Write an area of data to the flash
2535<screen>
2536RedBoot> <userinput>fis write -b 0x0606f000 -l 0x1000 -f 0x00020000</userinput>
2537* CAUTION * about to program FLASH
2538            at 0x00020000..0x0002ffff from 0x0606f000 - continue (y/n)? <userinput>y</userinput>
2539... Erase from 0x00020000-0x00030000: .
2540... Program from 0x0606f000-0x0607f000 at 0x00020000: .
2541</screen>
2542</para>
2543</refsect1>
2544</refentry>
2545
2546</sect1>
2547<sect1 id="Persistent-State-Flash">
2548<title>Persistent State Flash-based Configuration and Control</title>
2549<para><indexterm><primary>persistent state flash-based configuration and control
2550</primary></indexterm><indexterm><primary>flash-based configuration and control
2551</primary></indexterm><indexterm><primary>configuration and control</primary>
2552<secondary>flash-based</secondary></indexterm></para>
2553<para>RedBoot provides flash management support for storage in the flash memory
2554of multiple executable images and of non-volatile information such as IP addresses
2555and other network information.</para>
2556<para>RedBoot on platforms that support flash based configuration information
2557will report the following message the first time that RedBoot is booted on
2558the target:</para>
2559<screen>flash configuration checksum error or invalid key</screen>
2560<para>This error can be ignored if no flash based configuration is desired,
2561or can be silenced by running the <command>fconfig</command>
2562command as described below. At this point you may also wish to run the <command>
2563fis init</command> command. See other fis commands in <xref linkend="Flash-Image-System">.
2564</para>
2565<para>Certain control and configuration information used by RedBoot can be
2566stored in flash. </para>
2567<para>The details of what information is maintained in flash differ, based
2568on the platform and the configuration. However, the basic operation used to
2569maintain this information is the same. Using the <command>fconfig -l
2570</command> command, the information may be displayed and/or changed.
2571</para>
2572<para>If the optional flag <computeroutput>-i</computeroutput> is specified,
2573then the configuration database will be reset to its default
2574state. This is also needed the first time RedBoot is installed on the
2575target, or when updating to a newer RedBoot with different
2576configuration keys.
2577</para>
2578<para>If the optional flag <computeroutput>-l</computeroutput> is specified,
2579the configuration data is simply listed. Otherwise, each configuration parameter
2580will be displayed and you are given a chance to change it. The entire value
2581must be typed - typing just carriage return will leave a value unchanged.
2582Boolean values may be entered using the first letter (<computeroutput>t</computeroutput>
2583for true, <computeroutput>f</computeroutput> for false). At any time the editing
2584process may be stopped simply by entering a period (.) on the line. Entering
2585the caret (^) moves the editing back to the previous item. See &ldquo;RedBoot
2586Editing Commands&rdquo;, <xref linkend="RedBoot-Editing-Commands">. </para>
2587<para>If any changes are made in the configuration, then the updated data
2588will be written back to flash after getting acknowledgment from the user.
2589</para>
2590<para>
2591If the optional flag <computeroutput>-n</computeroutput> is specified
2592(with or without <computeroutput>-l</computeroutput>) then &ldquo;nicknames&rdquo;
2593of the entries are used.  These are shorter and less descriptive than
2594&ldquo;full&rdquo; names.  The full name may also be displayed by adding the
2595<computeroutput>-f</computeroutput> flag.</para>
2596<para>The reason for telling you nicknames is that a quick way to set a single
2597entry is provided, using the format
2598<screen>
2599  RedBoot> <userinput>fconfig <replaceable>nickname</replaceable> <replaceable>value
2600</replaceable></userinput></screen>
2601If no
2602value is supplied, the command will list and prompt for only that entry.
2603If a value is supplied, then the entry will be set to that value.  You will
2604be prompted whether to write the new information into flash if any change
2605was made.  For example
2606<screen>
2607  RedBoot> <userinput>fconfig -l -n</userinput>
2608  boot_script: false
2609  bootp: false
2610  bootp_my_ip: 10.16.19.176
2611  bootp_server_ip: 10.16.19.66
2612  dns_ip: 10.16.19.1
2613  gdb_port: 9000
2614  net_debug: false
2615  RedBoot> <userinput>fconfig bootp_my_ip 10.16.19.177</userinput>
2616  bootp_my_ip: 10.16.19.176 Setting to 10.16.19.177
2617  Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
2618  ... Unlock from 0x507c0000-0x507e0000: .
2619  ... Erase from 0x507c0000-0x507e0000: .
2620  ... Program from 0x0000a8d0-0x0000acd0 at 0x507c0000: .
2621  ... Lock from 0x507c0000-0x507e0000: .
2622  RedBoot>
2623</screen>
2624</para><para>
2625Additionally, nicknames can be used like aliases via the format %{nickname}.
2626This allows the values stored by <userinput>fconfig</userinput> to be used
2627directly by scripts and commands.
2628</para>
2629<para>Depending on how your terminal program is connected and its
2630capabilities, you might find that you are unable to use line-editing to
2631delete the &lsquo;old&rsquo; value when using the default behaviour of
2632<command>fconfig <replaceable>nickname</replaceable></command> or just
2633plain <command>fconfig</command>, as shown in this example:
2634<screen>
2635RedBoot> <userinput>fco bootp</userinput>
2636bootp: false&lowbar;
2637</screen>
2638The user deletes the word &ldquo;false;&rdquo and enters &ldquo;true&rdquo;
2639so the display looks like this:
2640<screen>
2641RedBoot> <userinput>fco bootp</userinput>
2642bootp: <userinput>true</userinput>
2643Update RedBoot non-volatile configuration - continue (y/n)? y
2644... Unlock from ...
2645RedBoot> &lowbar;
2646</screen>
2647</para>
2648<para>To edit when you cannot backspace, use the optional flag
2649<computeroutput>-d</computeroutput> (for &ldquo;dumb terminal&rdquo;)
2650to provide a simpler interface thus:
2651<screen>
2652RedBoot> <userinput>fco -d bootp</userinput>
2653bootp: false ? &lowbar;
2654</screen>
2655and you enter the value in the obvious manner thus:
2656<screen>
2657RedBoot> <userinput>fco -d bootp</userinput>
2658bootp: false ? <userinput>true</userinput>
2659Update RedBoot non-volatile configuration - continue (y/n)? y
2660... Unlock from ...
2661RedBoot> &lowbar;
2662</screen>
2663</para>
2664<para>One item which is always present in the configuration data is the ability
2665to execute a script at boot time. A sequence of RedBoot commands can be entered
2666which will be executed when the system starts up. Optionally, a time-out period
2667can be provided which allows the user to abort the startup script and proceed
2668with normal command processing from the console.     </para>
2669<para><screen>
2670RedBoot> <userinput>fconfig -l</userinput>
2671Run script at boot: false
2672Use BOOTP for network configuration: false
2673Local IP address: 192.168.1.29
2674Default server IP address: 192.168.1.101
2675DNS server IP address: 192.168.1.1
2676GDB connection port: 9000
2677Network debug at boot time: false
2678</screen></para>
2679<para>The following example sets a boot script and then shows it running.
2680    </para>
2681<para>
2682<screen>
2683RedBoot> <userinput>fconfig</userinput>
2684Run script at boot: false <userinput>t</userinput>
2685      Boot script:
2686Enter script, terminate with empty line
2687>> <userinput>fi li</userinput>
2688    Boot script timeout: 0 <userinput>10</userinput>
2689Use BOOTP for network configuration: false .
2690Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
2691... Erase from 0xa0fc0000-0xa0fe0000: .
2692... Program from 0x8c021f60-0x8c022360 at 0xa0fc0000: .
2693RedBoot>
2694RedBoot(tm) debug environment - built 08:22:24, Aug 23 2000
2695Copyright (C) 2000, Red Hat, Inc.
2696
2697
2698RAM: 0x8c000000-0x8c800000
2699flash: 0xa0000000 - 0xa1000000, 128 blocks of 0x00020000 bytes ea.
2700Socket Communications, Inc: Low Power Ethernet CF Revision C \
27015V/3.3V 08/27/98 IP: 192.168.1.29, Default server: 192.168.1.101 \
2702== Executing boot script in 10 seconds - enter ^C to abort
2703RedBoot> <userinput>fi li</userinput>
2704Name              flash addr   Mem addr    Length    Entry point
2705RedBoot          0xA0000000   0xA0000000  0x020000  0x80000000
2706RedBoot config   0xA0FC0000   0xA0FC0000  0x020000  0x00000000
2707FIS directory    0xA0FE0000   0xA0FE0000  0x020000  0x00000000
2708RedBoot>
2709</screen>
2710</para>
2711<note><title>NOTE</title>
2712<para>The bold characters above indicate where something was entered on the
2713console. As you can see, the <command>fi li</command> command
2714at the end came from the script,
2715not the console. Once the script is executed, command processing reverts to
2716the console. </para>
2717</note>
2718<para>
2719<note><title>NOTE</title>
2720<para>
2721RedBoot supports the notion of a boot script timeout, i.e. a period of
2722time that RedBoot waits before executing the boot time script.  This period
2723is primarily to allow the possibility of canceling the script.  Since
2724a timeout value of zero (0) seconds would never allow the script to
2725be aborted or canceled, this value is not allowed.  If the timeout
2726value is zero, then RedBoot will abort the script execution immediately.
2727</para>
2728</note>
2729On many targets, RedBoot may be configured to run from ROM or it may be
2730configured to run from RAM. Other configurations are also possible. All
2731RedBoot configurations will execute the boot script, but in certain cases
2732it may be desirable to limit the execution of certain script commands to
2733one RedBoot configuration or the other. This can be accomplished by
2734prepending <computeroutput>{&lt;startup type>}</computeroutput> to the
2735commands which should be executed only by the RedBoot configured for the
2736specified startup type. The following boot script illustrates this concept
2737by having the ROM based RedBoot load and run the RAM based RedBoot. The RAM
2738based RedBoot will then list flash images.</para>
2739<para><screen>
2740RedBoot> <userinput>fco</userinput>
2741Run script at boot: false <userinput>t</userinput>
2742Boot script:
2743Enter script, terminate with empty line
2744>> <userinput>{ROM}fis load RedBoot[RAM]</userinput>
2745>> <userinput>{ROM}go</userinput>
2746>> <userinput>{RAM}fis li</userinput>
2747>>
2748Boot script timeout (1000ms resolution): <userinput>2</userinput>
2749Use BOOTP for network configuration: <userinput>false</userinput>
2750 ...
2751Update RedBoot non-volatile configuration - continue (y/n)? <userinput>y</userinput>
2752... Unlock from 0x007c0000-0x007e0000: .
2753... Erase from 0x007c0000-0x007e0000: .
2754... Program from 0xa0015030-0xa0016030 at 0x007df000: .
2755... Lock from 0x007c0000-0x007e0000: .
2756RedBoot> <userinput>reset</userinput>
2757... Resetting.
2758+Ethernet eth0: MAC address 00:80:4d:46:01:05
2759IP: 192.168.1.153, Default server: 192.168.1.10
2760
2761RedBoot(tm) bootstrap and debug environment [ROM]
2762Red Hat certified release, version R1.xx - built 17:37:36, Aug 14 2001
2763
2764Platform: IQ80310 (XScale)
2765Copyright (C) 2000, 2001, Red Hat, Inc.
2766
2767RAM: 0xa0000000-0xa2000000, 0xa001b088-0xa1fdf000 available
2768FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
2769== Executing boot script in 2.000 seconds - enter ^C to abort
2770RedBoot> <userinput>fis load RedBoot[RAM]</userinput>
2771RedBoot> <userinput>go</userinput>
2772+Ethernet eth0: MAC address 00:80:4d:46:01:05
2773IP: 192.168.1.153, Default server: 192.168.1.10
2774
2775RedBoot(tm) bootstrap and debug environment [RAM]
2776Red Hat certified release, version R1.xx - built 13:03:47, Aug 14 2001
2777
2778Platform: IQ80310 (XScale)
2779Copyright (C) 2000, 2001, Red Hat, Inc.
2780
2781RAM: 0xa0000000-0xa2000000, 0xa0057fe8-0xa1fdf000 available
2782FLASH: 0x00000000 - 0x00800000, 64 blocks of 0x00020000 bytes each.
2783== Executing boot script in 2.000 seconds - enter ^C to abort
2784RedBoot> <userinput>fis li</userinput>
2785Name              FLASH addr  Mem addr    Length      Entry point
2786RedBoot           0x00000000  0x00000000  0x00040000  0x00002000
2787RedBoot config    0x007DF000  0x007DF000  0x00001000  0x00000000
2788FIS directory     0x007E0000  0x007E0000  0x00020000  0x00000000
2789RedBoot>
2790</screen></para>
2791</sect1>
2792<sect1 id="executing-programs">
2793<title>Executing Programs from RedBoot</title>
2794<para><indexterm><primary>executing programs</primary></indexterm><indexterm>
2795<primary>RedBoot</primary><secondary>executing programs</secondary></indexterm>Once
2796an image has been loaded into memory, either via the <command>load
2797</command> command or the <command>fis load</command>
2798command, execution may be transfered to that image.</para>
2799<para>  <note><title>NOTE</title>
2800<para>The image is assumed to be a stand-alone entity, as RedBoot gives the
2801entire platform over to it. Typical examples would be an eCos application
2802or a Linux kernel.</para>
2803</note></para>
2804
2805
2806<!-- ******** go *************************************************** -->
2807  <refentry id="go-command">
2808    <refnamediv>
2809      <refname>go</refname>
2810      <refpurpose>Execute a program</refpurpose>
2811    </refnamediv>
2812    <refsynopsisdiv>
2813      <cmdsynopsis>
2814        <command>go</command>
2815        <arg>-w <replaceable> timeout</replaceable></arg>
2816        <arg>-c</arg>
2817        <arg>-n</arg>
2818        <arg><replaceable> start_address</replaceable></arg>
2819      </cmdsynopsis>
2820    </refsynopsisdiv>
2821    <refsect1>
2822      <title>Arguments</title>
2823      <informaltable frame="all">
2824        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2825          <colspec colname="c1">
2826          <colspec colname="c2">
2827          <colspec colname="c3">
2828          <colspec colname="c4">
2829          <thead>
2830            <row>
2831              <entry>Name</entry>
2832              <entry>Type</entry>
2833              <entry>Description</entry>
2834              <entry>Default</entry>
2835            </row>
2836          </thead>
2837          <tbody>
2838            <row>
2839              <entry>-w <replaceable>timeout</replaceable></entry>           
2840              <entry>Number</entry>
2841              <entry>How long to wait before starting execution.</entry>             
2842              <entry>0</entry>       
2843            </row>
2844            <row>
2845              <entry>-c</entry>     
2846              <entry>Boolean</entry>
2847              <entry>Go with caches enabled.</entry>         
2848              <entry>caches off</entry>     
2849            </row>
2850            <row>
2851              <entry>-n</entry>     
2852              <entry>Boolean</entry>
2853              <entry>Go with network interface stopped.</entry>     
2854              <entry>network enabled</entry>         
2855            </row>
2856            <row>
2857              <entry><replaceable>start_address</replaceable></entry>       
2858              <entry>Number</entry>
2859              <entry>Address in memory to begin execution.</entry>           
2860              <entry>Value set by last <command>load</command> or <command>fis load</command> command.</entry>       
2861            </row>
2862          </tbody>
2863        </tgroup>
2864      </informaltable>
2865    </refsect1>
2866    <refsect1>
2867      <title>Description</title>
2868      <para>
2869The <command>go</command> command causes RedBoot to give control of the target platform to
2870another program.  This program must execute stand alone, e.g. an eCos
2871application or a Linux kernel.
2872      </para>
2873      <para>
2874If the -w option is used, RedBoot will print a message and then
2875wait for a period of time before starting the execution.  This is
2876most useful in a script, giving the user a chance to abort executing
2877a program and move on in the script.
2878      </para>
2879    </refsect1>
2880    <refsect1>
2881      <title>Examples</title>
2882      <para>
2883Execute a program - <emphasis>no explicit output from RedBoot</emphasis>.
2884<screen>
2885RedBoot> <userinput>go 0x40040</userinput>
2886</screen>
2887      </para>
2888      <para>
2889Execute a program with a timeout.
2890<screen>
2891RedBoot> <userinput>go -w 10</userinput>
2892About to start execution at 0x00000000 - abort with ^C within 10 seconds
2893^C
2894RedBoot>
2895</screen>
2896Note that the starting address was implied (0x00000000 in this example).
2897The user is prompted that execution will commence in 10 seconds.  At
2898anytime within that 10 seconds the user may type  <guibutton>Ctrl+C</guibutton>
2899on the console and RedBoot will abort execution and return for the next
2900command, either from a script or the console.
2901      </para>
2902    </refsect1>
2903  </refentry>
2904
2905<!-- ******** exec *************************************************** -->
2906  <refentry id="exec-command">
2907    <refnamediv>
2908      <refname>exec</refname>
2909      <refpurpose>Execute a Linux kernel</refpurpose>
2910    </refnamediv>
2911    <refsynopsisdiv>
2912      <cmdsynopsis>
2913        <command>exec</command>
2914        <arg>-w <replaceable> timeout</replaceable></arg>
2915        <arg>-r <replaceable> ramdisk_address</replaceable></arg>
2916        <arg>-s <replaceable> ramdisk_length</replaceable></arg>
2917        <arg>-b <replaceable> load_address</replaceable>
2918           <arg choice="req">-l <replaceable> load_length</replaceable></arg>
2919        </arg>
2920        <arg>-c <replaceable> kernel_command_line</replaceable></arg>
2921        <arg><replaceable> entry_point</replaceable></arg>
2922      </cmdsynopsis>
2923    </refsynopsisdiv>
2924    <refsect1>
2925      <title>Arguments</title>
2926      <informaltable frame="all">
2927        <tgroup cols="4" colsep="1" rowsep="1" align="left">
2928          <colspec colname="c1">
2929          <colspec colname="c2">
2930          <colspec colname="c3">
2931          <colspec colname="c4">
2932          <thead>
2933            <row>
2934              <entry>Name</entry>
2935              <entry>Type</entry>
2936              <entry>Description</entry>
2937              <entry>Default</entry>
2938            </row>
2939          </thead>
2940          <tbody>
2941            <row>
2942              <entry>-w <replaceable>timeout</replaceable></entry>           
2943              <entry>Number</entry>
2944              <entry>Time to wait before starting execution.</entry>         
2945              <entry>0</entry>       
2946            </row>
2947            <row>
2948              <entry>-r <replaceable>ramdisk_address</replaceable></entry>           
2949              <entry>Number</entry>
2950              <entry>Address in memory of "initrd"-style ramdisk - passed to Linux kernel.</entry>           
2951              <entry><emphasis>None</emphasis></entry>       
2952            </row>
2953            <row>
2954              <entry>-s <replaceable>ramdisk_length</replaceable></entry>           
2955              <entry>Number</entry>
2956              <entry>Length of ramdisk image - passed to Linux kernel.</entry>       
2957              <entry><emphasis>None</emphasis></entry>       
2958            </row>
2959            <row>
2960              <entry>-b <replaceable>load_address</replaceable></entry>     
2961              <entry>Number</entry>
2962              <entry>Address in memory of the Linux kernel image.</entry>           
2963              <entry>Value set by <command>load</command> or <command>fis load</command></entry>             
2964            </row>
2965            <row>
2966              <entry>-l <replaceable>load_length</replaceable></entry>       
2967              <entry>Number</entry>
2968              <entry>Length of Linux kernel image.</entry>
2969              <entry><emphasis>none</emphasis></entry>       
2970            </row>
2971            <row>
2972              <entry>-c <replaceable>kernel_command_line</replaceable></entry>       
2973              <entry>String</entry>
2974              <entry>Command line to pass to the Linux kernel.</entry>       
2975              <entry><emphasis>None</emphasis></entry>       
2976            </row>
2977            <row>
2978              <entry>-x</entry>     
2979              <entry></entry>
2980              <entry>Boot kernel with endianess opposite of RedBoot endianess.</entry>       
2981              <entry>Boot kernel with same endianess as RedBoot</entry>     
2982              </row>
2983            <row>
2984              <entry><replaceable>entry_address</replaceable></entry>       
2985              <entry>Number</entry>
2986              <entry>Starting address for Linux kernel execution</entry>             
2987              <entry>Implied by architecture</entry>         
2988            </row>
2989          </tbody>
2990        </tgroup>
2991      </informaltable>
2992    </refsect1>
2993    <refsect1>
2994      <title>Description</title>
2995      <para>
2996The <command>exec</command> command is used to execute a non-eCos application, typically a
2997Linux kernel. Additional information may be passed to the kernel at startup
2998time. This command is quite special (and unique from the <command>go</command> command) in
2999that the program being executed may expect certain environmental setups, for
3000example that the MMU is turned off, etc. </para>
3001<para>The Linux kernel expects to have been loaded to a particular memory
3002location which is architecture dependent(0xC0008000 in the case of the SA1110).
3003Since this memory is  used
3004by RedBoot internally, it is not possible to load the kernel to that location
3005directly. Thus the requirement for the "-b" option which tells the command
3006where the kernel has been loaded. When the <command>exec</command> command runs, the image will
3007be relocated to the appropriate location before being started. The "-r" and
3008"-s" options are used to pass information to the kernel about where a statically
3009loaded ramdisk (initrd) is located.</para>
3010<para>The "-c" option can be used to pass textual "command line" information
3011to the kernel.  If the command line data contains any punctuation (spaces,
3012etc), then it must be quoted using the double-quote character '"'. If the
3013quote character is required, it should be written as '\"'.
3014      </para>
3015<para>The "-x" option is optionally available on some bi-endian platforms. It is used to boot
3016a kernel built with an endianess opposite of RedBoot.</para>
3017    </refsect1>
3018    <refsect1>
3019      <title>Examples</title>
3020      <para>
3021Execute a Linux kernel, passing a command line, which needs relocation.
3022The result from RedBoot is normally quiet, with the target platform being
3023passed over to Linux immediately.
3024<screen>
3025RedBoot> <userinput>exec -b 0x100000 -l 0x80000 -c "noinitrd root=/dev/mtdblock3 console=ttySA0"</userinput>
3026</screen>
3027      </para>
3028      <para>
3029Execute a Linux kernel, default entry address and no relocation required, with a timeout. 
3030The <emphasis> emphasized lines</emphasis> are output from the loaded kernel.
3031<screen> 
3032RedBoot> exec <userinput>-c "console=ttyS0,38400 ip=dhcp nfsroot=/export/elfs-sh" -w 5</userinput>
3033Now booting linux kernel:
3034Base address 0x8c001000 Entry 0x8c210000
3035Cmdline : console=ttyS0,38400 ip=dhcp nfsroot=/export/elfs-sh
3036About to start execution at 0x8x210000 - abort with ^C within 5 seconds
3037<emphasis>
3038Linux version 2.4.10-pre6 (...) (gcc version 3.1-stdsh-010931) #3 Thu Sep 27 11:04:23 BST 2001
3039</emphasis>
3040</screen>
3041      </para>
3042    </refsect1>
3043  </refentry>
3044
3045</sect1>
3046</chapter>
Note: See TracBrowser for help on using the repository browser.