diff options
author | patacongo <patacongo@42af7a65-404d-4744-a932-0658087f49c3> | 2008-09-03 17:29:17 +0000 |
---|---|---|
committer | patacongo <patacongo@42af7a65-404d-4744-a932-0658087f49c3> | 2008-09-03 17:29:17 +0000 |
commit | 842f404d2b07c21c80232a63384055d46386be0e (patch) | |
tree | 8d426f1aaba7679e9f200021c0ae3f95bd9d1226 /nuttx/examples/nsh | |
parent | 18c2739aa6486a0d6dd7f19a8ee36058f1d62674 (diff) | |
download | px4-nuttx-842f404d2b07c21c80232a63384055d46386be0e.tar.gz px4-nuttx-842f404d2b07c21c80232a63384055d46386be0e.tar.bz2 px4-nuttx-842f404d2b07c21c80232a63384055d46386be0e.zip |
Add NSH README file
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@873 42af7a65-404d-4744-a932-0658087f49c3
Diffstat (limited to 'nuttx/examples/nsh')
-rw-r--r-- | nuttx/examples/nsh/README.txt | 460 |
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. + |