diff --git a/ChangeLog b/ChangeLog index e0af7c0af96..84cf98a9b5b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -448,4 +448,5 @@ ping request logic. * NSH: Add ping command * Correct IP checksum calculation in ICMP and UDP message send logic. + * NSH: Created a more detailed README file for NSH. diff --git a/Documentation/NuttX.html b/Documentation/NuttX.html index 06169e4ea0c..560107afda3 100644 --- a/Documentation/NuttX.html +++ b/Documentation/NuttX.html @@ -1075,6 +1075,7 @@ nuttx-0.3.14 2008-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> ping request logic. * NSH: Add ping command * Correct IP checksum calculation in ICMP and UDP message send logic. + * NSH: Created a more detailed README file for NSH. pascal-0.1.3 2008-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> diff --git a/examples/README.txt b/examples/README.txt index 469a84b9265..13865365347 100644 --- a/examples/README.txt +++ b/examples/README.txt @@ -31,134 +31,9 @@ examples/nsh ^^^^^^^^^^^^ This directory contains the NuttShell (NSH). This is a simple - shell-like application. With some additional development, NSH will - someday be a great NuttX application debugger. At present, NSH - supports the following commands: - - 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 - - Test 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 - - Other behavior of NSH can be modified with the following settings in - the configs//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. + shell application. With some additional development, NSH will + someday be a great NuttX application debugger. NSH is described + in its own README located at examples/nsh/README.txt examples/mount ^^^^^^^^^^^^^^ diff --git a/examples/nsh/README.txt b/examples/nsh/README.txt new file mode 100644 index 00000000000..837b8038aa5 --- /dev/null +++ b/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: + Command with re-directed output: > + >> + Background command: & + Re-directed background command: > & + >> & + + Where: + + is any one of the simple commands listed later. + 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 >]] [> |>> ] [&] + + Where 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 + then + [sequence of ] + else + [sequence of ] + 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 [ ] +o test + + 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 [ [ ...]] + + This command copies and concatentates all of the files at + to the console (or to another file if the output is redirected). + +o cd [|-|~|..] + + Changes the current working directory (PWD). Also sets the + previous working directory environment variable (OLDPWD). + + FORMS: + ------ + + 'cd ' sets the current working directory to . + '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 + + Copy of the contents of the file at to the location + in the filesystem indicated by + +o echo [ [...]] + + Copy the sequence of strings and expanded environment variables to + console out (or to a file if the output is re-directed). + +o exec + + Execute the user logic at address . NSH will pause + until the execution unless the user logic is executed in background + via 'exec &' + +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] + + Show the contents of the directory at . NOTE: + 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 [=][ ] +o mh [=][ ] +o mw [=][ ] + + Access memory using byte size access (mb), 16-bit accesses (mh), + or 32-bit access (mw). In each case, + + . Specifies the address to be accessed. The current + value at that address will always be read and displayed. + =. Read the value, then write + to the location. + . Perform the mb, mh, or mw operation on a total + of bytes, increment the 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 (21) + nsh> + +o ping [-c ] [-i ] + + 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 + + Set the environment variable to the sting . + For example, + + nsh> echo $foobar + + nsh> set foobar foovalue + nsh> echo $foobar + foovalue + nsh> + +o sh + + Execute the sequence of NSH commands in the file referred + to by . + +o sleep + + Pause execution (sleep) of seconds. + +o unset + + Remove the value associated with the environment variable + . Example: + + nsh> echo $foobar + foovalue + nsh> unset foobar + nsh> echo $foobar + + nsh> + +o usleep + + Pause execution (sleep) of 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//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. +