Move NSH to apps/ as library

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

1 files changed, 1016 insertions, 0 deletions

diff --git a/apps/nshlib/README.txt b/apps/nshlib/README.txt
new file mode 100644
index 000000000..10bb202df
--- /dev/null
+++ b/apps/nshlib/README.txt
@@ -0,0 +1,1016 @@
+apps/nshlib
+^^^^^^^^^^^
+
+  This directory contains the NuttShell (NSH) library.  This library can be
+  linked with other logic to provide a simple shell application for NuttX.
+
+  - Console/NSH Front End
+  - Command Overview
+  - Conditional Command Execution
+  - Built-In Variables
+  - Current Working Directory
+    Environment Variables
+  - NSH Start-Up Script
+  - Simple Commands
+  - NSH Configuration Settings
+    Command Dependencies on Configuration Settings
+    NSH-Specific Configuration Settings
+  - Common Problems
+
+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
+
+NSH Start-Up Script
+^^^^^^^^^^^^^^^^^^^
+
+NSH supports options to provide a start up script for NSH.  In general
+this capability is enabled with CONFIG_EXAMPLES_NSH_ROMFSETC, but has
+several other related configuration options as described in the final
+section of this README.  This capability also depends on:
+
+  - CONFIG_DISABLE_MOUNTPOINT not set
+  - CONFIG_NFILE_DESCRIPTORS < 4
+  - CONFIG_FS_ROMFS
+
+Default Start-Up Behavior
+-------------------------
+
+The implementation that is provided is intended to provide great flexibility
+for the use of Start-Up files.  This paragraph will discuss the general
+behavior when all of the configuration options are set to the default
+values.
+
+In this default case, enabling CONFIG_EXAMPLES_NSH_ROMFSETC will cause
+NSH to behave as follows at NSH startup time:
+
+- NSH will create a read-only RAM disk (a ROM disk), containing a tiny
+  ROMFS filesystem containing the following:
+
+    |--init.d/
+         `-- rcS
+
+   Where rcS is the NSH start-up script
+
+- NSH will then mount the ROMFS filesystem at /etc, resulting in:
+
+   |--dev/
+   |   `-- ram0
+   `--etc/
+       `--init.d/
+           `-- rcS
+
+- By default, the contents of rcS script are:
+
+    # Create a RAMDISK and mount it at XXXRDMOUNTPOUNTXXX
+
+    mkrd -m 1 -s 512 1024
+    mkfatfs /dev/ram1
+    mount -t vfat /dev/ram1 /tmp
+
+- NSH will execute the script at /etc/init.d/rcS at start-up (before the
+  first NSH prompt.  After execution of the script, the root FS will look
+  like:
+
+   |--dev/
+   |   |-- ram0
+   |   `-- ram1
+   |--etc/
+   |   `--init.d/
+   |       `-- rcS
+   `--tmp/
+
+Modifying the ROMFS Image
+-------------------------
+
+The contents of the /etc directory are retained in the file
+apps/nshlib/nsh_romfsimg.h (OR, if CONFIG_EXAMPLES_NSH_ARCHROMFS
+is defined, include/arch/board/rcs.template).  In order to modify
+the start-up behavior, there are three things to study:
+
+1. Configuration Options.
+   The additional CONFIG_EXAMPLES_NSH_ROMFSETC configuration options
+   discussed in the final section of this README.
+
+2. tools/mkromfsimg.sh Script.
+   The script tools/mkromfsimg.sh creates nsh_romfsimg.h.
+   It is not automatically executed.  If you want to change the
+   configuration settings associated with creating and mounting
+   the /tmp directory, then it will be necessary to re-generate
+   this header file using the mkromfsimg.sh script.
+
+   The behavior of this script depends upon three things:
+
+   - The configuration settings of the installed NuttX configuration.
+   - The genromfs tool (available from http://romfs.sourceforge.net).
+   - The file apps/nshlib/rcS.template (OR, if
+     CONFIG_EXAMPLES_NSH_ARCHROMFS is defined, include/arch/board/rcs.template)
+
+3. rcS.template.
+   The file apps/nshlib/rcS.template contains the general form
+   of the rcS file; configured values are plugged into this
+   template file to produce the final rcS file.
+
+NOTE:
+
+   apps/nshlib/rcS.template generates the standard, default
+   nsh_romfsimg.h file.  If CONFIG_EXAMPLES_NSH_ARCHROMFS is defined
+   in the NuttX configuration file, then a custom, board-specific
+   nsh_romfsimg.h file residing in configs/<board>/include will be
+   used.  NOTE when the OS is configured, include/arch/board will
+   be linked to configs/<board>/include.
+
+All of the startup-behavior is contained in rcS.template.  The
+role of mkromfsimg.sh is to (1) apply the specific configuration
+settings to rcS.template to create the final rcS, and (2) to
+generate the header file nsh_romfsimg.h containg the ROMFS
+file system image.
+
+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 dd if=<infile> of=<outfile> [bs=<sectsize>] [count=<sectors>] [skip=<sectors>]
+
+  Copy blocks from <infile> to <outfile>.  <nfile> or <outfile> may
+  be the path to a standard file, a character device, or a block device.
+
+  Examples:
+
+    1. Read from character device, write to regular file.  This will
+       create a new file of the specified size filled with zero.
+
+    nsh> dd if=/dev/zero of=/tmp/zeros bs=64 count=16
+    nsh> ls -l /tmp
+    /tmp:
+     -rw-rw-rw-    1024 ZEROS
+
+    2. Read from character device, write to block device.  This will
+       fill the entire block device with zeros.
+
+    nsh> ls -l /dev
+    /dev:
+     brw-rw-rw-       0 ram0
+     crw-rw-rw-       0 zero
+    nsh> dd if=/dev/zero of=/dev/ram0
+
+    3. Read from a block devic, write to a character device.  This
+       will read the entire block device and dump the contents in
+       the bit bucket.
+
+    nsh> ls -l /dev
+    /dev:
+     crw-rw-rw-       0 null
+     brw-rw-rw-       0 ram0
+    nsh> dd if=/dev/ram0 of=/dev/null
+
+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 free
+
+  Show the current state of the memory allocator.  For example,
+
+  nsh> free
+  free
+               total       used       free    largest
+  Mem:       4194288    1591552    2602736    2601584
+
+  Where:
+    total - This is the total size of memory allocated for use
+      by malloc in bytes.
+    used - This is the total size of memory occupied by
+      chunks handed out by malloc.
+    free - This is the total size of memory occupied by
+      free (not in use) chunks.
+    largest - Size of the largest free (not in use) chunk
+
+o get [-b|-n] [-f <local-path>] -h <ip-address> <remote-path>
+
+  Use TFTP to copy the file at <remote-address> from the host whose IP
+  address is identified by <ip-address>.  Other options:
+
+  -f <local-path>
+     The file will be saved relative to the current working directory
+      unless <local-path> is provided.
+  -b|-n
+      Selects either binary ("octect") or test ("netascii") transfer
+      mode.  Default: text.
+
+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 kill -<signal> <pid>
+
+  Send the <signal> to the task identified by <pid>.
+
+o losetup [-d <dev-path>] | [[-o <offset>] [-r] <ldev-path> <file-path>]
+
+  Setup or teardown the loop device:
+
+  1. Teardown the setup for the loop device at <dev-path>:
+
+    losetup d <dev-path>
+
+  2. Setup the loop device at <dev-path> to access the file at <file-path>
+     as a block device:
+
+    losetup [-o <offset>] [-r] <dev-path> <file-path>
+
+  Example:
+
+    nsh> dd if=/dev/zero of=/tmp/image bs=512 count=512
+    nsh> ls -l /tmp
+    /tmp:
+     -rw-rw-rw-   262144 IMAGE
+    nsh> losetup /dev/loop0 /tmp/image
+    nsh> ls -l /dev
+    /dev:
+     brw-rw-rw-       0 loop0
+    nsh> mkfatfs /dev/loop0
+    nsh> mount -t vfat /dev/loop0 /mnt/example
+    nsh> ls -l /mnt
+    ls -l /mnt
+    /mnt:
+     drw-rw-rw-       0 example/
+    nsh> echo "This is a test" >/mnt/example/atest.txt
+    nsh> ls -l /mnt/example
+    /mnt/example:
+     -rw-rw-rw-      16 ATEST.TXT
+    nsh> cat /mnt/example/atest.txt
+    This is a test
+    nsh>
+
+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 mkdir <path>
+
+  Create the directory at <path>.  All components of of <path>
+  except the final directory name must exist on a mounted file
+  system; the final directory must not.
+
+  Recall that NuttX uses a pseudo filesystem for its root file system.
+  The mkdir command can only be used to create directories in volumes
+  set up with the mount command; it cannot be used to create directories
+  in the pseudo filesystem.
+
+  Example:
+  ^^^^^^^^
+
+    nsh> mkdir /mnt/fs/tmp
+    nsh> ls -l /mnt/fs
+    /mnt/fs:
+     drw-rw-rw-       0 TESTDIR/
+     drw-rw-rw-       0 TMP/
+    nsh>
+
+o mkfatfs <path>
+
+  Format a fat file system on the block device specified by path.
+  NSH provides this command to access the mkfatfs() NuttX API.
+  This block device must reside in the NuttX psuedo filesystem and
+  must have been created by some call to register_blockdriver() (see
+  include/nuttx/fs.h).
+
+o mkfifo <path>
+
+  Creates a FIFO character device anywhere in the pseudo file system,
+  creating whatever psuedo directories that may be needed to complete
+  the full path.  By convention, however, device drivers are place in
+  the standard /dev directory. After it is created, the FIFO device
+  may be used as any other device driver. NSH provides this command
+  to access the mkfifo() NuttX API.
+
+  Example:
+  ^^^^^^^^
+
+    nsh> ls -l /dev
+    /dev:
+     crw-rw-rw-       0 console
+     crw-rw-rw-       0 null
+     brw-rw-rw-       0 ram0
+    nsh> mkfifo /dev/fifo
+    nsh> ls -l /dev
+    ls -l /dev
+    /dev:
+     crw-rw-rw-       0 console
+     crw-rw-rw-       0 fifo
+     crw-rw-rw-       0 null
+     brw-rw-rw-       0 ram0
+    nsh>
+
+o mkrd [-m <minor>] [-s <sector-size>] <nsectors>
+
+  Create a ramdisk consisting of <nsectors>, each of size
+  <sector-size> (or 512 bytes if <sector-size> is not specified.
+  The ramdisk will be registered as /dev/ram<n> (if <n> is not
+  specified, mkrd will attempt to register the ramdisk as
+  /dev/ram0.
+
+  Example:
+  ^^^^^^^^
+
+    nsh> ls /dev
+    /dev:
+     console
+     null
+     ttyS0
+     ttyS1
+    nsh> mkrd 1024
+    nsh> ls /dev
+    /dev:
+     console
+     null
+     ram0
+     ttyS0
+     ttyS1
+    nsh>
+
+  Once the ramdisk has been created, it may be formatted using
+  the mkfatfs command and mounted using the mount command.
+
+  Example:
+  ^^^^^^^^
+    nsh> mkrd 1024
+    nsh> mkfatfs /dev/ram0
+    nsh> mount -t vfat /dev/ram0 /tmp
+    nsh> ls /tmp
+    /tmp:
+    nsh>
+
+o mount -t <fstype> <block-device> <dir-path>
+
+  The 'mount' command mounts a file system in the NuttX psuedo
+  filesystem.  'mount' performs a three way associating, binding
+
+    File system.  The '-t <fstype>' option identifies the type of
+      file system that has been formatted on the <block-device>.  As
+      of this writing, vfat is the only supported value for <fstype>
+
+    Block Device.  The <block-device> argument is the full or relative
+      path to a block driver inode in the psuedo filesystem.  By convention,
+      this is a name under the /dev sub-directory.  This <block-device>
+      must have been previously formatted with the same file system
+      type as specified by <fstype>
+
+    Mount Point.  The mount point is the location in the psuedo file
+      system where the mounted volume will appear.  This mount point
+      can only reside in the NuttX psuedo filesystem.  By convention, this
+      mount point is a subdirectory under /mnt.  The mount command will
+      create whatever psuedo directories that may be needed to complete
+      the full path but the full path must not already exist.
+
+  After the volume has been mounted in the NuttX psuedo file
+  system, it may be access in the same way as other objects in the
+  file system.
+
+  Example:
+  ^^^^^^^^
+
+    nsh> ls -l /dev
+    /dev:
+     crw-rw-rw-       0 console
+     crw-rw-rw-       0 null
+     brw-rw-rw-       0 ram0
+    nsh> ls /mnt
+    nsh: ls: no such directory: /mnt
+    nsh> mount -t vfat /dev/ram0 /mnt/fs
+    nsh> ls -l /mnt/fs/testdir
+    /mnt/fs/testdir:
+     -rw-rw-rw-      15 TESTFILE.TXT
+    nsh> echo "This is a test" >/mnt/fs/testdir/example.txt
+    nsh> ls -l /mnt/fs/testdir
+    /mnt/fs/testdir:
+    -rw-rw-rw-      15 TESTFILE.TXT
+     -rw-rw-rw-      16 EXAMPLE.TXT
+    nsh> cat /mnt/fs/testdir/example.txt
+    This is a test
+    nsh>
+
+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 put [-b|-n] [-f <remote-path>] -h <ip-address> <local-path>
+
+  Copy the file at <local-address> to the host whose IP address is
+  identified by <ip-address>.  Other options:
+
+  -f <remote-path>
+     The file will be saved with the same name on the host unless
+      unless <local-path> is provided.
+  -b|-n
+      Selects either binary ("octect") or test ("netascii") transfer
+      mode.  Default: text.
+
+o pwd
+
+  Show the current working directory.
+
+    nsh> cd /dev
+    nsh> pwd
+    /dev
+    nsh>
+
+  Same as 'echo $PWD'
+
+    nsh> echo $PWD
+    /dev
+    nsh>
+
+o rm <file-path>
+
+  Remove the specified <file-path> name from the mounted file system.
+  Recall that NuttX uses a pseudo filesystem for its root file system.
+  The rm command can only be used to remove (unlink) files in volumes
+  set up with the mount command; it cannot be used to remove names from
+  the pseudo filesystem.
+
+  Example:
+  ^^^^^^^^
+
+    nsh> ls /mnt/fs/testdir
+    /mnt/fs/testdir:
+     TESTFILE.TXT
+     EXAMPLE.TXT
+    nsh> rm /mnt/fs/testdir/example.txt
+    nsh> ls /mnt/fs/testdir
+    /mnt/fs/testdir:
+     TESTFILE.TXT
+    nsh>
+
+o rmdir <dir-path>
+
+  Remove the specified <dir-path> directory from the mounted file system.
+  Recall that NuttX uses a pseudo filesystem for its root file system. The
+  rmdir command can only be used to remove directories from volumes set up
+  with the mount command; it cannot be used to remove directories from the
+  pseudo filesystem. 
+
+  Example:
+  ^^^^^^^^
+
+    nsh> mkdir /mnt/fs/tmp
+    nsh> ls -l /mnt/fs
+    /mnt/fs:
+     drw-rw-rw-       0 TESTDIR/
+     drw-rw-rw-       0 TMP/
+    nsh> rmdir /mnt/fs/tmp
+    nsh> ls -l /mnt/fs
+    ls -l /mnt/fs
+    /mnt/fs:
+     drw-rw-rw-       0 TESTDIR/
+    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.
+
+o wget [-o <local-path>] <url>
+
+  Use HTTP to copy the file at <url> to the current directory.
+  Options:
+
+  -o <local-path>
+     The file will be saved relative to the current working directory
+     and with the same name as on the HTTP server unless <local-path>
+     is provided.
+
+o xd <hex-address> <byte-count>
+
+  Dump <byte-count> bytes of data from address <hex-address>
+
+  Example:
+  ^^^^^^^^
+
+    nsh> xd 410e0 512
+    Hex dump:
+    0000: 00 00 00 00 9c 9d 03 00 00 00 00 01 11 01 10 06 ................
+    0010: 12 01 11 01 25 08 13 0b 03 08 1b 08 00 00 02 24 ....%..........$
+    ...
+    01f0: 08 3a 0b 3b 0b 49 13 00 00 04 13 01 01 13 03 08 .:.;.I..........
+    nsh>
+
+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
+  dd         CONFIG_NFILE_DESCRIPTORS > 0
+  echo       --
+  exec       --
+  exit       --
+  free       --
+  get        CONFIG_NET && CONFIG_NET_UDP && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET_BUFSIZE >= 558  (see note 1)
+  help       --
+  ifconfig   CONFIG_NET
+  kill       !CONFIG_DISABLE_SIGNALS
+  losetup    !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0
+  ls         CONFIG_NFILE_DESCRIPTORS > 0
+  mb,mh,mw   ---
+  mkdir      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE (see note 4)
+  mkfatfs    !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_FAT
+  mkfifo     CONFIG_NFILE_DESCRIPTORS > 0
+  mkrd       !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE (see note 4)
+  mount      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_READABLE (see note 3)
+  ping       CONFIG_NET && CONFIG_NET_ICMP && CONFIG_NET_ICMP_PING  && !CONFIG_DISABLE_CLOCK && !CONFIG_DISABLE_SIGNALS
+  ps         --
+  put        CONFIG_NET && CONFIG_NET_UDP && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_NET_BUFSIZE >= 558 (see note 1,2)
+  pwd        !CONFIG_DISABLE_ENVIRON && CONFIG_NFILE_DESCRIPTORS > 0
+  rm         !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE (see note 4)
+  rmdir      !CONFIG_DISABLE_MOUNTPOINT && CONFIG_NFILE_DESCRIPTORS > 0 && CONFIG_FS_WRITABLE (see note 4)
+  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_READABLE
+  unset      !CONFIG_DISABLE_ENVIRON
+  usleep     !CONFIG_DISABLE_SIGNALS
+  get        CONFIG_NET && CONFIG_NET_TCP && CONFIG_NFILE_DESCRIPTORS > 0
+  xd         ---
+
+* NOTES:
+  1. Because of hardware padding, the actual buffersize required for put and get
+     operations size may be larger.
+  2. Special TFTP server start-up optionss will probably be required to permit
+     creation of file for the correct operation of the put command.
+  3. CONFIG_FS_READABLE is not a user configuration but is set automatically
+     if any readable filesystem is selected.  At present, this is either CONFIG_FS_FAT
+     and CONFIG_FS_ROMFS.
+  4. CONFIG_FS_WRITABLE is not a user configuration but is set automatically
+     if any writable filesystem is selected.  At present, this is only CONFIG_FS_FAT.
+
+In addition, each NSH command can be individually disabled via one of the following
+settings.  All of these settings make the configuration of NSH potentially complex but
+also allow it to squeeze into very small memory footprints.
+
+  CONFIG_EXAMPLES_NSH_DISABLE_CAT,      CONFIG_EXAMPLES_NSH_DISABLE_CD,       CONFIG_EXAMPLES_NSH_DISABLE_CP,
+  CONFIG_EXAMPLES_NSH_DISABLE_DD,       CONFIG_EXAMPLES_NSH_DISABLE_ECHO,     CONFIG_EXAMPLES_NSH_DISABLE_EXEC,
+  CONFIG_EXAMPLES_NSH_DISABLE_EXIT,     CONFIG_EXAMPLES_NSH_DISABLE_FREE,     CONFIG_EXAMPLES_NSH_DISABLE_GET,
+  CONFIG_EXAMPLES_NSH_DISABLE_HELP,     CONFIG_EXAMPLES_NSH_DISABLE_IFCONFIG, CONFIG_EXAMPLES_NSH_DISABLE_KILL,
+  CONFIG_EXAMPLES_NSH_DISABLE_LOSETUP,  CONFIG_EXAMPLES_NSH_DISABLE_LS,       CONFIG_EXAMPLES_NSH_DISABLE_MB,
+  CONFIG_EXAMPLES_NSH_DISABLE_MKDIR,    CONFIG_EXAMPLES_NSH_DISABLE_MKFATFS,  CONFIG_EXAMPLES_NSH_DISABLE_MKFIFO,
+  CONFIG_EXAMPLES_NSH_DISABLE_MKRD,     CONFIG_EXAMPLES_NSH_DISABLE_MH,       CONFIG_EXAMPLES_NSH_DISABLE_MOUNT,
+  CONFIG_EXAMPLES_NSH_DISABLE_MW,       CONFIG_EXAMPLES_NSH_DISABLE_PS,       CONFIG_EXAMPLES_NSH_DISABLE_PING,
+  CONFIG_EXAMPLES_NSH_DISABLE_PUT,      CONFIG_EXAMPLES_NSH_DISABLE_PWD,      CONFIG_EXAMPLES_NSH_DISABLE_RM,
+  CONFIG_EXAMPLES_NSH_DISABLE_RMDIR,    CONFIG_EXAMPLES_NSH_DISABLE_SET,      CONFIG_EXAMPLES_NSH_DISABLE_SH,
+  CONFIG_EXAMPLES_NSH_DISABLE_SLEEP,    CONFIG_EXAMPLES_NSH_DISABLE_TEST,     CONFIG_EXAMPLES_NSH_DISABLE_UMOUNT,
+  CONFIG_EXAMPLES_NSH_DISABLE_UNSET,    CONFIG_EXAMPLES_NSH_DISABLE_USLEEP,   CONFIG_EXAMPLES_NSH_DISABLE_WGET,
+  CONFIG_EXAMPLES_NSH_DISABLE_XD
+
+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). Default is 1024.
+
+  * 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_MMCSDMINOR
+      If the architecture supports an MMC/SD slot and if the NSH
+      architecture specific logic is present, this option will provide
+      the MMC/SD minor number, i.e., the MMC/SD block driver will
+      be registered as /dev/mmcsdN where N is the minor number.
+      Default is zero.
+
+  * CONFIG_EXAMPLES_NSH_ROMFSETC
+      Mount a ROMFS filesystem at /etc and provide a startup script
+      at /etc/init.d/rcS.  The default startup script will mount
+      a FAT FS RAMDISK at /tmp but the logic is easily extensible.
+
+  * 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.
+
+  * CONFIG_EXAMPLES_NSH_ARCHINIT
+      Set if your board provides architecture specific initialization
+      via the board-specific function nsh_archinitialize().  This
+      function will be called early in NSH initialization to allow
+      board logic to do such things as configure MMC/SD slots.
+
+  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_NET=y
+      Of course, networking must be enabled
+ 
+  * CONFIG_NSOCKET_DESCRIPTORS
+      And, of course, you must allocate some socket descriptors.
+
+  * CONFIG_NET_TCP=y
+      TCP/IP support is required for telnet (as well as various other TCP-related
+      configuration settings).
+
+  * 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 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.
+
+  If you use DHCPC, then some special configuration network options are
+  required.  These include:
+
+  * CONFIG_NET=y
+      Of course, networking must be enabled
+ 
+  * CONFIG_NSOCKET_DESCRIPTORS
+      And, of course, you must allocate some socket descriptors.
+
+  * CONFIG_NET_UDP=y
+      UDP support is required for DHCP (as well as various other UDP-related
+      configuration settings)
+
+  * CONFIG_NET_BROADCAST=y
+      UDP broadcast support is needed.
+ 
+  * CONFIG_NET_BUFSIZE=650 (or larger)
+      Per RFC2131 (p. 9), the DHCP client must be prepared to receive DHCP
+      messages of up to 576 bytes (excluding Ethernet, IP, or UDP headers and FCS).
+
+  If CONFIG_EXAMPLES_NSH_ROMFSETC is selected, then the following additional
+  configuration setting apply:
+
+  * CONFIG_EXAMPLES_NSH_ROMFSMOUNTPT
+      The default mountpoint for the ROMFS volume is /etc, but that
+      can be changed with this setting.  This must be a absolute path
+      beginning with '/'.
+
+  * CONFIG_EXAMPLES_NSH_INITSCRIPT
+      This is the relative path to the startup script within the mountpoint.
+      The default is init.d/rcS.  This is a relative path and must not
+      start with '/'.
+
+  * CONFIG_EXAMPLES_NSH_ROMFSDEVNO
+      This is the minor number of the ROMFS block device.  The default is 
+      '0' corresponding to /dev/ram0.
+
+  * CONFIG_EXAMPLES_NSH_ROMFSSECTSIZE
+      This is the sector size to use with the ROMFS volume.  Since the
+      default volume is very small, this defaults to 64 but should be
+      increased if the ROMFS volume were to be become large.  Any value
+      selected must be a power of 2.
+
+  When the default rcS file used when CONFIG_EXAMPLES_NSH_ROMFSETC is
+  selected, it will mount a FAT FS under /tmp.  The following selections
+  describe that FAT FS.
+
+  * CONFIG_EXAMPLES_NSH_FATDEVNO
+      This is the minor number of the FAT FS block device.  The default is 
+      '1' corresponding to /dev/ram1.
+
+  * CONFIG_EXAMPLES_NSH_FATSECTSIZE
+      This is the sector size use with the FAT FS. Default is 512.
+
+  * CONFIG_EXAMPLES_NSH_FATNSECTORS
+      This is the number of sectors to use with the FAT FS.  Defalt is
+      1024.  The amount of memory used by the FAT FS will be
+      CONFIG_EXAMPLES_NSH_FATSECTSIZE * CONFIG_EXAMPLES_NSH_FATNSECTORS
+      bytes.
+
+  * CONFIG_EXAMPLES_NSH_FATMOUNTPT
+      This is the location where the FAT FS will be mounted.  Default
+      is /tmp.
+
+Common Problems
+^^^^^^^^^^^^^^^
+
+  Problem:
+    Using NSH over serial, the "nsh>" prompt repeats over and over again
+    with no serial input.
+  Usual Cause:
+    NSH over serial needs to use the interrupt driven serial driver
+    (drivers/serial/serial.c) not the polled serial driver (drivers/serial/lowconsole.c).
+    Make sure that the polled console is disabled in the OS configuration
+    file, .config.  That file should have CONFIG_DEV_LOWCONSOLE=n for
+    NSH over serial.