redboot_cmds.sgml

eCos/RedBoot for勤研ARM AnywhereII(4510) 含全部源代码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     redboot_cmds.sgml                                           -->
<!--                                                                 -->
<!--     Documentation for RedBoot Commands                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<chapter id="RedBoot-Commands-and-Examples">
<title>RedBoot Commands and Examples</title>
<sect1>
<title>Introduction</title>
<para><indexterm><primary>RedBoot</primary><secondary>commands and examples
</secondary></indexterm><indexterm><primary>commands and examples</primary>
</indexterm>RedBoot provides three basic classes of commands:    <itemizedlist>
<listitem><para>Program loading and execution</para>
</listitem>
<listitem><para>Flash image and configuration management</para>
</listitem>
<listitem><para>Miscellaneous commands</para>
</listitem>
</itemizedlist>Given the extensible and configurable nature of eCos and RedBoot,
there may be extended or enhanced sets of commands available.</para>
<para>The basic format for commands is:    <programlisting>RedBoot> COMMAND [-S]... [-s val]... operand
</programlisting>
</para>
<para>
Commands may require additional information beyond the basic
command name. In most cases this additional information is optional, with
suitable default values provided if they are not present. 

      <informaltable frame="all">
	<tgroup cols="3" colsep="1" rowsep="1" align="left">
	  <colspec colname="c1">
	  <colspec colname="c2">
	  <colspec colname="c3">
	  <thead>
	    <row>
	      <entry>Format</entry>
	      <entry>Description</entry>
	      <entry>Example</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>-S</entry>	     
	      <entry>A boolean switch; the behavior of the command will differ, depending
on the presence of the switch.  In this example, the <userinput>-f</userinput> switch
indicates that a complete initialization of the FIS data should be performed.
There may be many such switches available for any given command and any or all of
them may be present, in any order.</entry>
	      <entry>
                <computeroutput> RedBoot> <userinput>fis init -f</userinput></computeroutput>
              </entry>	     
	    </row>
	    <row>
	      <entry>-s<replaceable> val</replaceable></entry>	     
	      <entry>A qualified value; the letter "s" introduces the value, qualifying it's meaning.  In the
example, <userinput>-b 0x100000</userinput> specifies where the memory dump should begin.
There may be many such switches available for any given command and any or all of
them may be present, in any order.
</entry>
	      <entry>
                <computeroutput> RedBoot> <userinput>dump -b 0x100000 -l 0x20</userinput></computeroutput>
              </entry>	     
	    </row>
	    <row>
	      <entry><replaceable> operand</replaceable></entry>	     
	      <entry>A simple value; some commands require a single parameter for which an additional
<userinput>-X</userinput> switch would be redundant.  In the example, <userinput>JFFS2</userinput>
is the name of a flash image.  The image name is always required, thus is no need to qualify it with 
a switch.
Note that any un-qualified operand must always appear at the end of the command.</entry>
	      <entry>
                <computeroutput> RedBoot> <userinput>fis delete JFFS2</userinput></computeroutput>
              </entry>	     
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

</para>
<para>The list of available commands, and their syntax, can be obtained by
typing <command>help</command> at the command line:    
<screen>
RedBoot> <userinput>help</userinput>
Manage aliases kept in FLASH memory
      alias name [value]
Set/Query the system console baud rate
      baudrate [-b &lt;rate>]
Manage machine caches
      cache [ON | OFF]
Display/switch console channel
      channel [-1|&lt;channel number>]
Display disk partitions
      disks
Display (hex dump) a range of memory
      dump -b &lt;location> [-l &lt;length>] [-s]
Manage flash images
      fis {cmds}
Manage configuration kept in FLASH memory
      fconfig [-i] [-l] [-n] [-f] [-d] | [-d] nickname [value]
Execute code at a location
      go [-w &lt;timeout>] [-c] [-n] [entry]
Help about help?
      help [&lt;topic>]
Set/change IP addresses
      ip_address [-l &lt;local_ip_address>[/&lt;mask_length>]] [-h &lt;server_address>]
Load a file
      load [-r] [-v] [-d] [-c &lt;channel>] [-h &lt;host>] [-m {TFTP | HTTP | {x|y}MODEM | disk}]
      [-b &lt;base_address>] &lt;file_name>
Network connectivity test
      ping [-v] [-n &lt;count>] [-t &lt;timeout>] [-i &lt;IP_addr]
      -h &lt;host>
Reset the system
      reset
Display RedBoot version information
      version
Display (hex dump) a range of memory
      x -b &lt;location> [-l &lt;length>] [-s]
</screen>
</para>
<para>
Commands can be abbreviated to their shortest
unique string. Thus in the list above, <command>d,du,dum</command>
and dump are all valid for the <command>dump</command> command. The <command>fconfig</command>
command can be abbreviated <command>fc</command>, but 
<command>f</command> would be ambiguous with <command>fis</command>.
</para>
<para>There is one additional, special command. When RedBoot detects '$' or '+'
(unless escaped via '\') in a command, it switches to GDB protocol mode. At this
point, the eCos GDB stubs take over, allowing connections from a GDB host.
The only way to get back to RedBoot from GDB mode is to restart the platform.
</para>
<note><title>NOTE</title>
<para>
Multiple commands may be entered on a single line, separated by the semi-colon &ldquo;;&rdquo; character.
</para>
</note>
<para>The standard RedBoot command set is structured around the bootstrap
environment. These commands are designed to be simple to use and remember,
while still providing sufficient power and flexibility to be useful. No attempt
has been made to render RedBoot as the end-all product. As such, things such
as the debug environment are left to other modules, such as GDB stubs, which
are typically included in RedBoot. </para>
<para>The command set may be also be extended on a platform basis. </para>
</sect1>

<sect1 id="common-commands">
<title>Common Commands</title>
<para>
  <indexterm><primary>commands</primary><secondary>common</secondary>
  </indexterm>
</para>

<!-- ******** alias *************************************************** -->
  <refentry id="alias-command">
    <refnamediv>
      <refname>alias</refname>
      <refpurpose>Manipulate command line aliases</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <cmdsynopsis>
	<command>alias</command>
	<arg choice="req"><replaceable> name</replaceable></arg>
	<arg><replaceable> value</replaceable></arg>
      </cmdsynopsis>
    </refsynopsisdiv>
    <refsect1>
      <title>Arguments</title>
      <informaltable frame="all">
	<tgroup cols="4" colsep="1" rowsep="1" align="left">
	  <colspec colname="c1">
	  <colspec colname="c2">
	  <colspec colname="c3">
	  <colspec colname="c4">
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Type</entry>
	      <entry>Description</entry>
	      <entry>Default</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry><replaceable>name</replaceable></entry>	     
	      <entry>Name</entry>
	      <entry>The name for this alias.</entry>	     
	      <entry><emphasis>none</emphasis></entry>	     
	    </row>
	    <row>
	      <entry><replaceable>value</replaceable></entry>	     
	      <entry>String</entry>
	      <entry>Replacement value for the alias.</entry>	     
	      <entry><emphasis>none</emphasis></entry>	     
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </refsect1>
    <refsect1>
      <title>Description</title>
      <para>The <command>alias</command> command is used to maintain simple command
line aliases.  These aliases are shorthand for longer expressions.
When the pattern %{name} appears in a command line, including in a script,
the corresponding value will be substituted.  Aliases may be nested.
      </para>
      <para>
If no value is provided, then the current value of the alias is displayed.
      </para>
      <para>
If the system supports non-volatile configuration data via the 
<command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
then the value will be saved and used when the system is reset.
      </para>
    </refsect1>
    <refsect1>
      <title>Examples</title>
      <para>
Set an alias.
<screen> 
RedBoot> <userinput>alias joe "This is Joe"</userinput>
Update RedBoot non-volatile configuration - continue (y/n)? n
</screen> 
</para>
<para>
Display an alias.
<screen> 
RedBoot> <userinput>alias joe</userinput>
'joe' = 'This is Joe'
</screen> 
</para>
<para>
Use an alias.  Note: the <command>"="</command> command simply echoes the command to to console.
<screen> 
RedBoot> <userinput>= %{joe}</userinput>
This is Joe
</screen>
</para>
<para>
Aliases can be nested.
<screen>
RedBoot> <userinput>alias frank "Who are you? %{joe}"</userinput>
Update RedBoot non-volatile configuration - continue (y/n)? n
RedBoot> <userinput>= %{frank}</userinput>
Who are you? This is Joe
</screen>
</para>
<para>
Notice how the value of %{frank} changes when %{joe} is changed since
the value of %{joe} is not evaluated until %{frank} is evaluated.
<screen>
RedBoot> <userinput>alias joe "This is now Josephine"</userinput>
Update RedBoot non-volatile configuration - continue (y/n)? n
RedBoot> <userinput>= %{frank}</userinput>
Who are you? This is now Josephine
</screen>
      </para>
    </refsect1>
  </refentry>

<!-- ******** baudrate *************************************************** -->
  <refentry id="baudrate-command">
    <refnamediv>
      <refname>baudrate</refname>
      <refpurpose>Set the baud rate for the system serial console</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <cmdsynopsis>
	<command>baudrate</command>
	<arg>-b<replaceable> rate</replaceable></arg>
      </cmdsynopsis>
    </refsynopsisdiv>
    <refsect1>
      <title>Arguments</title>
      <informaltable frame="all">
	<tgroup cols="4" colsep="1" rowsep="1" align="left">
	  <colspec colname="c1">
	  <colspec colname="c2">
	  <colspec colname="c3">
	  <colspec colname="c4">
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Type</entry>
	      <entry>Description</entry>
	      <entry>Default</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>-b <replaceable>rate</replaceable></entry>	     
	      <entry>Number</entry>
	      <entry>The baud rate to use for the serial console.</entry>	     
	      <entry><emphasis>none</emphasis></entry>	     
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </refsect1>
    <refsect1>
      <title>Description</title>
      <para>The <command>baudrate</command> command sets the baud rate for the system serial console.
      </para>
      <para>
If no value is provided, then the current value of the console baud rate is displayed.
      </para>
      <para>
If the system supports non-volatile configuration data via the 
<command>fconfig</command> command (see <xref linkend="Persistent-State-Flash">),
then the value will be saved and used when the system is reset.
      </para>
    </refsect1>
    <refsect1>
      <title>Examples</title>
      <para>
Show the current baud rate.
<screen> 
RedBoot> <userinput>baudrate</userinput>
Baud rate = 38400
</screen> 
</para>
<para>
Change the console baud rate.  In order to make this operation safer,
there will be a slight pause after the
first message to give you time to change to the new baud rate.
If it doesn't work, or a less than affirmative answer is given to the 
"continue" prompt, then the baud rate will revert to the current value.
Only after the baud rate has been firmly established will <emphasis>RedBoot</emphasis>
give you an opportunity to save the value in persistent storage.
<screen> 
RedBoot> <userinput>baudrate -b 57600</userinput>
Baud rate will be changed to 57600 - update your settings
<emphasis>Device baud rate changed at this point</emphasis>
Baud rate changed to 57600 - continue (y/n)? y
Update RedBoot non-volatile configuration - continue (y/n)? n
</screen> 
      </para>
    </refsect1>
  </refentry>

<!-- ******** cache *************************************************** -->
  <refentry id="cache-command">
    <refnamediv>
      <refname>cache</refname>
      <refpurpose>Control hardware caches</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
      <cmdsynopsis>
	<command>cache</command>
	<group>
	  <arg>on</arg>
	  <arg>off</arg>
	</group>