diff options
Diffstat (limited to 'doc/shell/preface.texi')
-rw-r--r-- | doc/shell/preface.texi | 103 |
1 files changed, 99 insertions, 4 deletions
diff --git a/doc/shell/preface.texi b/doc/shell/preface.texi index c3dfafc299..5868a10201 100644 --- a/doc/shell/preface.texi +++ b/doc/shell/preface.texi @@ -7,11 +7,106 @@ @c @ifinfo -@node Preface, General Commands, Top, Top +@node Preface, Configuration and Initialization, Top, Top @end ifinfo @unnumbered Preface Real-time embedded systems vary widely based upon their -operational and maintenance requirements. Many of these -systems now include a command line interface which can -be used to diagnostic +operational and maintenance requirements. Some of these +systems provide ways for the user or developer to interact +with them. This interaction could be used for operational, +diagnostic, or configuration purposes. The capabilities +described in this manual are those provided with RTEMS to +provide a command line interface for user access. Some +of these commands will be familiar as standard POSIX utilities +while others are RTEMS specific or helpful in debugging +and analyzing an embedded system. As a simple example of +the powerful and very familiar capabilities that the RTEMS +Shell provides to an application, consider the following +example which hints at some of the capabilities available: + +@smallexample +Welcome to rtems-4.8.99.0(SPARC/w/FPU/sis) +COPYRIGHT (c) 1989-2008. +On-Line Applications Research Corporation (OAR). + +Login into RTEMS + +login: rtems +Password: + +RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands. +SHLL [/] $ cat /etc/passwd +root:*:0:0:root::/:/bin/sh +rtems:*:1:1:RTEMS Application::/:/bin/sh +tty:!:2:2:tty owner::/:/bin/false +SHLL [/] $ ls /dev +-rwxr-xr-x 1 rtems root 0 Jan 01 00:00 console +-rwxr-xr-x 1 root root 0 Jan 01 00:00 console_b +2 files 0 bytes occupied +SHLL [/] $ stackuse +Stack usage by thread + ID NAME LOW HIGH CURRENT AVAILABLE USED +0x09010001 IDLE 0x023d89a0 - 0x023d99af 0x023d9760 4096 608 +0x0a010001 UI1 0x023d9f30 - 0x023daf3f 0x023dad18 4096 1804 +0x0a010002 SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0 16384 6204 +0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 +SHLL [/] $ mount -L +File systems: msdos +SHLL [/] $ +@end smallexample + +In the above example, the user @i{rtems} logs into a +SPARC based RTEMS system. The first command is +@code{cat /etc/passwd}. This simple command lets us +know that this application is running the In Memory +File System (IMFS) and that the infrastructure has +provided dummy entries for @i{/etc/passwd} and a few +other files. The contents of @i{/etc/passwd} let +us know that the user could have logged in as @code{root}. +In fact, the @code{root} user has more permissions +than @code{rtems} who is not allowed to write into the +filesystem. + +The second command is @code{ls /dev} which lets us +know that RTEMS has POSIX-style device nodes which +can be accesses through standard I/O function calls. + +The third command executed is the RTEMS specific +@code{stackuse} which gives a report on the stack +usage of each thread in the system. Since stack +overflows are a common error in deeply embedded systems, +this is a surprising simple, yet powerful debugging aid. + +Finally, the last command, @code{mount -L} hints that +RTEMS supports a variety of mountable filesystems. With +support for MS-DOS FAT on IDE/ATA and Flash devices as +well as network-based filesystens such as NFS and TFTP, +the standard free RTEMS provides a robuse infrastructure +for embedded applications. + +This manual describes the RTEMS Shell and its command set. +In our terminology, the Shell is just a loop reading user +input and turning that input into commands with argument. +The Shell provided with RTEMS is a simple command reading +loop with limited scripting capabilities. It can be connected +to via a standard serial port or connected to the RTEMS +@code{telnetd} server for use across a network. + +Each command in the command set is implemented as a single +subroutine which has a @i{main-style} prototype. The commands +interpret their arguments and operate upon stdin, stdout, and +stderr by default. This allows each command to be invoked +independent of the shell. + +The described separation of shell from commands from communications +mechanism was an important design goal. At one level, the RTEMS +Shell is a complete shell environment providing access to multiple +POSIX compliant filesystems and TCP/IP stack. The subset of +capabilities available is easy to configure and the standard +Shell can be logged into from either a serial port or via telnet. +But at another level, the Shell is a large set of components which +can be integrated into the user's developed command interpreter. +In either case, it is trivial to add custom commands to the command +set available. + |