Add NSH README file

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@873 42af7a65-404d-4744-a932-0658087f49c3

1 files changed, 460 insertions, 0 deletions

diff --git a/nuttx/examples/nsh/README.txt b/nuttx/examples/nsh/README.txt
new file mode 100644
index 000000000..837b8038a
--- /dev/null
+++ b/nuttx/examples/nsh/README.txt
@@ -0,0 +1,460 @@
+examples/nsh
+^^^^^^^^^^^^
+
+  This directory contains the NuttShell (NSH).  This is a simple
+  shell application for NuttX.
+
+  - Console/NSH Front End
+  - Command Overview
+  - Conditional Command Execution
+  - Built-In Variables
+  - Current Working Directory
+    Environment Variables:
+  - Simple Commands
+  - NSH Configuration Settings
+    Command Dependencies on Configuration Settings
+    NSH-Specific Configuration Settings
+
+Console/NSH Front End
+^^^^^^^^^^^^^^^^^^^^^
+
+  Using settings in the configuration file, NSH may be configured to
+  use either the serial stdin/out or a telnet connection as the console
+  or BOTH.  When NSH is started, you will see the following welcome on
+  either console:
+
+    NuttShell (NSH)
+    nsh>
+
+  'nsh>' is the NSH prompt and indicates that you may enter a command
+   from the console.
+
+Command Overview
+^^^^^^^^^^^^^^^^
+
+  This directory contains the NuttShell (NSH).  This is a simple
+  shell-like application.  At present, NSH supports the following commands
+  forms:
+
+    Simple command:                  <cmd>
+    Command with re-directed output: <cmd> > <file>
+                                     <cmd> >> <file>
+    Background command:              <cmd> &
+    Re-directed background command:  <cmd> > <file> &
+                                     <cmd> >> <file> &
+
+  Where:
+
+    <cmd>  is any one of the simple commands listed later.
+    <file> is the full or relative path to any writable object
+           in the filesystem name space (file or character driver).
+           Such objects will be referred to simply as files throughout
+           this README.
+
+  NSH executes at the mid-priority (128).  Backgrounded commands can
+  be made to execute at higher or lower priorities using nice:
+
+    [nice [-d <niceness>>]] <cmd> [> <file>|>> <file>] [&]
+
+  Where <niceness> is any value between -20 and 19 where lower
+  (more negative values) correspond to higher priorities.  The
+  default niceness is 10.
+
+Conditional Command Execution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  An if-then[-else]-fi construct is also supported in order to
+  support conditional execution of commands.  This works from the
+  command line but is primarily intended for use within NSH scripts
+  (see the sh commnd).  The syntax is as follows:
+
+    if <cmd>
+    then
+      [sequence of <cmd>]
+    else
+      [sequence of <cmd>]
+    fi
+
+Built-In Variables
+^^^^^^^^^^^^^^^^^^
+
+  $? - The result of the last simple command execution
+
+Current Working Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  All path arguments to commands may be either an absolute path or a
+  path relative to the current working directory.  The current working
+  directory is set using the 'cd' command and can be queried either
+  by using the 'pwd' command or by using the 'echo $PWD' command.
+
+  Environment Variables:
+  ----------------------
+
+    PWD    - The current working directory
+    OLDPWD - The previous working directory
+
+
+Simple Commands
+^^^^^^^^^^^^^^^
+
+o  [ <expression> ]
+o  test <expression>
+
+   These are two alternative forms of the same command.  They support
+   evaluation of a boolean expression which sets $?.  This command
+   is used most frequently as the conditional command following the
+   'if' in the if-then[-else]-fi construct.
+
+   Expression Syntax:
+   ------------------
+
+     expression = simple-expression | !expression |
+                  expression -o expression | expression -a expression
+
+     simple-expression = unary-expression | binary-expression
+
+     unary-expression = string-unary | file-unary
+
+     string-unary = -n string | -z string
+
+     file-unary = -b file | -c file | -d file | -e file | -f file |
+                  -r file | -s file | -w file
+
+     binary-expression = string-binary | numeric-binary
+
+     string-binary = string = string | string == string | string != string
+
+     numeric-binary = integer -eq integer | integer -ge integer |
+                      integer -gt integer | integer -le integer |
+                      integer -lt integer | integer -ne integer
+
+o  cat <path> [<path> [<path> ...]]
+
+  This command copies and concatentates all of the files at <path>
+  to the console (or to another file if the output is redirected).
+
+o cd [<dir-path>|-|~|..]
+
+  Changes the current working directory (PWD).  Also sets the
+  previous working directory environment variable (OLDPWD).
+
+  FORMS:
+  ------
+
+    'cd <dir-path>' sets the current working directory to <dir-path>.
+    'cd -' sets the current working directory to the previous
+       working directory ($OLDPWD).  Equivalent to 'cd $OLDPWD'.
+    'cd' or 'cd ~' set the current working directory to the 'home'
+       directory.  The 'home' directory can be configured by setting
+       CONFIG_LIB_HOMEDIR in the configuration file.  The default
+       'home' directory is '/'.
+    'cd ..' sets the current working directory to the parent directory.
+
+o cp <source-path> <dest-path>
+
+  Copy of the contents of the file at <source-path> to the location
+  in the filesystem indicated by <path-path>
+
+o echo [<string|$name> [<string|$name>...]]
+
+  Copy the sequence of strings and expanded environment variables to
+  console out (or to a file if the output is re-directed).
+
+o exec <hex-address>
+
+  Execute the user logic at address <hex-address>.  NSH will pause
+  until the execution unless the user logic is executed in background
+  via 'exec <hex-address> &'
+
+o exit
+
+  Exit NSH.  Only useful if you have started some other tasks (perhaps
+  using the 'exec' command') and you would like to have NSH out of the
+  way.
+
+o help
+
+  Presents summary information about each command to console.
+
+o ifconfig
+
+  Show the current configuration of the network, for example:
+
+    nsh> ifconfig
+    eth0    HWaddr 00:18:11:80:10:06
+            IPaddr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0
+
+  if uIP statistics are enabled (CONFIG_NET_STATISTICS), then
+  this command will also show the detailed state of uIP.
+
+o ls [-lRs] <dir-path>
+
+  Show the contents of the directory at <dir-path>.  NOTE:
+  <dir-path> must refer to a directory and no other filesystem
+  object.
+
+  Options:
+  --------
+
+     -R Show the constents of specified directory and all of its
+        sub-directories.
+     -s Show the size of the files along with the filenames in the
+        listing
+     -l Show size and mode information along with the filenames
+        in the listing.
+
+o mb <hex-address>[=<hex-value>][ <hex-byte-count>]
+o mh <hex-address>[=<hex-value>][ <hex-byte-count>]
+o mw <hex-address>[=<hex-value>][ <hex-byte-count>]
+
+  Access memory using byte size access (mb), 16-bit accesses (mh),
+  or 32-bit access (mw).  In each case,
+
+    <hex-address>. Specifies the address to be accessed.  The current
+      value at that address will always be read and displayed.
+    <hex-address>=<hex-value>.  Read the value, then write <hex-value>
+      to the location.
+    <hex-byte-count>.  Perform the mb, mh, or mw operation on a total
+      of <hex-byte-count> bytes, increment the <hex-address> appropriately
+      after each access
+
+  Example
+
+    nsh> mh 0 16
+      0 = 0x0c1e
+      2 = 0x0100
+      4 = 0x0c1e
+      6 = 0x0110
+      8 = 0x0c1e
+      a = 0x0120
+      c = 0x0c1e
+      e = 0x0130
+      10 = 0x0c1e
+      12 = 0x0140
+      14 = 0x0c1e
+    nsh>
+
+o mem
+
+  Show the current state of the memory allocator.  For example,
+
+    nsh> mem
+      arena:      fe2560
+      ordblks:         1
+      mxordblk:   fdc3e0
+      uordblks:     6180
+      fordblks:   fdc3e0
+    nsh>
+
+  Where:
+    arena - This is the total size of memory allocated for use
+      by malloc in bytes.
+    ordblks - This is the number of free (not in use) chunks.
+    mxordblk - Size of the largest free (not in use) chunk
+    uordblks - This is the total size of memory occupied by
+      chunks handed out by malloc.
+    fordblks - This is the total size of memory occupied by
+      free (not in use) chunks.
+o ps
+
+  Show the currently active threads and tasks.  For example,
+
+    nsh> ps
+    PID   PRI SCHD TYPE   NP STATE    NAME
+        0   0 FIFO TASK      READY    Idle Task()
+        1 128 RR   TASK      RUNNING  init()
+        2 128 FIFO TASK      WAITSEM  nsh_telnetmain()
+        3 100 RR   PTHREAD   WAITSEM  <pthread>(21)
+    nsh>
+
+o ping [-c <count>] [-i <interval>] <ip-address>
+
+  Test the network communication with a remote peer.  Example,
+
+    nsh> 10.0.0.1
+    PING 10.0.0.1 56 bytes of data
+    56 bytes from 10.0.0.1: icmp_seq=1 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=2 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=3 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=4 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=5 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=6 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=7 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=8 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=9 time=0 ms
+    56 bytes from 10.0.0.1: icmp_seq=10 time=0 ms
+    10 packets transmitted, 10 received, 0% packet loss, time 10190 ms
+    nsh>
+
+o pwd
+
+  Show the current working directory.
+
+    nsh> cd /dev
+    nsh> pwd
+    /dev
+    nsh>
+
+  Same as 'echo $PWD'
+
+    nsh> echo $PWD
+    /dev
+    nsh>
+
+o set <name> <value>
+
+  Set the environment variable <name> to the sting <value>.
+  For example,
+
+    nsh> echo $foobar
+
+    nsh> set foobar foovalue
+    nsh> echo $foobar
+    foovalue
+    nsh>
+
+o sh <script-path>
+
+  Execute the sequence of NSH commands in the file referred
+  to by <script-path>.
+
+o sleep <sec>
+
+  Pause execution (sleep) of <sec> seconds.
+
+o unset <name>
+
+  Remove the value associated with the environment variable
+  <name>.  Example:
+
+    nsh> echo $foobar
+    foovalue
+    nsh> unset foobar
+    nsh> echo $foobar
+
+    nsh>
+
+o usleep <usec>
+
+  Pause execution (sleep) of <usec> microseconds.
+
+NSH Configuration Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The availability of the above commands depends upon features that
+may or may not be enabled in the NuttX configuration file.  The 
+following table indicates the dependency of each command on NuttX
+configuration settings.  General configuration settings are discussed
+in the NuttX Porting Guide.  Configuration settings specific to NSH
+as discussed at the bottom of this README file.
+
+Command Dependencies on Configuration Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  Command    Depends on Configuration
+  ---------- --------------------------
+  [          !CONFIG_EXAMPLES_NSH_DISABLESCRIPT
+  cat        CONFIG_NFILE_DESCRIPTORS > 0
+  cd         !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0
+  cp         CONFIG_NFILE_DESCRIPTORS > 0
+  echo       --
+  exec       --
+  exit       --
+  help       --
+  ifconfig   CONFIG_NET
+  ls         CONFIG_NFILE_DESCRIPTORS > 0
+  mb,mh,mw   ---
+  mem        ---
+  mkdir      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0
+  mkfatfs    !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT
+  mkfifo     !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0
+  mount      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT
+  ping       CONFIG_NET && CONFIG_NET_ICMP && CONFIG_NET_ICMP_PING  && !CONFIG_DISABLE_CLOCK && !CONFIG_DISABLE_SIGNALS
+  ps         --
+  pwd        !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0
+  rm         !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0
+  rmdir      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0
+  set        !CONFIG_DISABLE_ENVIRON
+  sh         CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NFILE_STREAMS > 0 && !CONFIG_EXAMPLES_NSH_DISABLESCRIPT
+  sleep      !CONFIG_DISABLE_SIGNALS
+  test       !CONFIG_EXAMPLES_NSH_DISABLESCRIPT
+  umount     !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT
+  unset      !CONFIG_DISABLE_ENVIRON
+  usleep     !CONFIG_DISABLE_SIGNALS
+
+NSH-Specific Configuration Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  The behavior of NSH can be modified with the following settings in
+  the configs/<board-name>/defconfig file:
+
+  * CONFIG_EXAMPLES_NSH_FILEIOSIZE
+      Size of a static I/O buffer used for file access (ignored if
+      there is no filesystem).
+
+  * CONFIG_EXAMPLES_NSH_STRERROR
+      strerror(errno) makes more readable output but strerror() is
+      very large and will not be used unless this setting is 'y'
+
+  * CONFIG_EXAMPLES_NSH_LINELEN
+      The maximum length of one command line and of one output line.
+      Default: 80
+
+  * CONFIG_EXAMPLES_NSH_STACKSIZE
+      The stack size to use when spawning new threads or tasks.  Such
+      new threads are generated when a command is executed in background
+      or as new TELNET connections are established.
+
+  * CONFIG_EXAMPLES_NSH_NESTDEPTH
+      The maximum number of nested if-then[-else]-fi sequences that
+      are permissable.  Default: 3
+
+  * CONFIG_EXAMPLES_NSH_DISABLESCRIPT
+      This can be set to 'y' to suppress support for scripting.  This
+      setting disables the 'sh', 'test', and '[' commands and the
+      if-then[-else]-fi construct.  This would only be set on systems
+      where a minimal footprint is a necessity and scripting is not.
+
+  * CONFIG_EXAMPLES_NSH_DISABLEBG
+      This can be set to 'y' to suppress support for background
+      commands.  This setting disables the 'nice' command prefix and
+      the '&' command suffix.  This would only be set on systems
+      where a minimal footprint is a necessity and background command
+      execution is not.
+
+  * CONFIG_EXAMPLES_NSH_CONSOLE
+      If CONFIG_EXAMPLES_NSH_CONSOLE is set to 'y', then a serial
+      console front-end is selected.
+
+  * CONFIG_EXAMPLES_NSH_TELNET
+      If CONFIG_EXAMPLES_NSH_TELNET is set to 'y', then a TELENET
+      server front-end is selected.  When this option is provided,
+      you may log into NuttX remotely using telnet in order to
+      access NSH.
+
+  One or both of CONFIG_EXAMPLES_NSH_CONSOLE and CONFIG_EXAMPLES_NSH_TELNET
+  must be defined.  If CONFIG_EXAMPLES_NSH_TELNET is selected, then there some
+  other configuration settings that apply:
+
+  * CONFIG_EXAMPLES_NSH_IOBUFFER_SIZE
+      Determines the size of the I/O buffer to use for sending/
+      receiving TELNET commands/reponses
+
+  * CONFIG_EXAMPLES_NSH_DHCPC
+      Obtain the the IP address via DHCP.
+
+  * CONFIG_EXAMPLES_NSH_IPADDR
+      If CONFIG_EXAMPLES_NSH_DHCPC is NOT set, then the static IP
+      address must be provided.
+
+  * CONFIG_EXAMPLES_NSH_DRIPADDR
+      Default router IP address
+
+  * CONFIG_EXAMPLES_NSH_NETMASK
+      Network mask
+
+  * CONFIG_EXAMPLES_NSH_NOMAC
+      Set if your ethernet hardware has no built-in MAC address.
+      If set, a bogus MAC will be assigned.
+