source: rtems-docs/shell/preface.rst @ 735de5f

Last change on this file since 735de5f was 735de5f, checked in by Amar Takhar <amar@…>, on 01/17/16 at 00:10:06

Move preface/intro one level up so the section is unnumbered.

  • Property mode set to 100644
File size: 5.8 KB
5Real-time embedded systems vary widely based upon their operational and
6maintenance requirements. Some of these systems provide ways for the user or
7developer to interact with them.  This interaction could be used for
8operational, diagnostic, or configuration purposes.  The capabilities described
9in this manual are those provided with RTEMS to provide a command line
10interface for user access.  Some of these commands will be familiar as standard
11POSIX utilities while others are RTEMS specific or helpful in debugging and
12analyzing an embedded system. As a simple example of the powerful and very
13familiar capabilities that the RTEMS Shell provides to an application, consider
14the following example which hints at some of the capabilities available:
16.. code-block:: shell
18    Welcome to rtems-
19    COPYRIGHT (c) 1989-2011.
20    On-Line Applications Research Corporation (OAR).
21    Login into RTEMS
22    login: rtems
23    Password:
24    RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands.
25    SHLL [/] $ cat /etc/passwd
26    root:*:0:0:root::/:/bin/sh
27    rtems:*:1:1:RTEMS Application::/:/bin/sh
28    tty:!:2:2:tty owner::/:/bin/false
29    SHLL [/] $ ls /dev
30    -rwxr-xr-x   1  rtems   root           0 Jan 01 00:00 console
31    -rwxr-xr-x   1   root   root           0 Jan 01 00:00 console_b
32    2 files 0 bytes occupied
33    SHLL [/] $ stackuse
34    Stack usage by thread
35    ID      NAME    LOW          HIGH     CURRENT     AVAILABLE     USED
36    0x09010001  IDLE 0x023d89a0 - 0x023d99af 0x023d9760      4096        608
37    0x0a010001  UI1  0x023d9f30 - 0x023daf3f 0x023dad18      4096       1804
38    0x0a010002  SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0     16384       6204
39    0xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
40    SHLL [/] $ mount -L
41    File systems: msdos
42    SHLL [/] $
44In the above example, the user *rtems* logs into a SPARC based RTEMS system.
45The first command is ``cat /etc/passwd``.  This simple command lets us know
46that this application is running the In Memory File System (IMFS) and that the
47infrastructure has provided dummy entries for */etc/passwd* and a few other
48files.  The contents of */etc/passwd* let us know that the user could have
49logged in as ``root``.  In fact, the ``root`` user has more permissions than
50``rtems`` who is not allowed to write into the filesystem.
52The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style
53device nodes which can be accesses through standard I/O function calls.
55The third command executed is the RTEMS specific ``stackuse`` which gives a
56report on the stack usage of each thread in the system.  Since stack overflows
57are a common error in deeply embedded systems, this is a surprising simple, yet
58powerful debugging aid.
60Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of
61mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices
62as well as network-based filesystens such as NFS and TFTP, the standard free
63RTEMS provides a robuse infrastructure for embedded applications.
65This manual describes the RTEMS Shell and its command set.  In our terminology,
66the Shell is just a loop reading user input and turning that input into
67commands with argument.  The Shell provided with RTEMS is a simple command
68reading loop with limited scripting capabilities.  It can be connected to via a
69standard serial port or connected to the RTEMS ``telnetd`` server for use across
70a network.
72Each command in the command set is implemented as a single subroutine which has
73a *main-style* prototype.  The commands interpret their arguments and operate
74upon stdin, stdout, and stderr by default.  This allows each command to be
75invoked independent of the shell.
77The described separation of shell from commands from communications mechanism
78was an important design goal.  At one level, the RTEMS Shell is a complete
79shell environment providing access to multiple POSIX compliant filesystems and
80TCP/IP stack.  The subset of capabilities available is easy to configure and
81the standard Shell can be logged into from either a serial port or via telnet.
82But at another level, the Shell is a large set of components which can be
83integrated into the user’s developed command interpreter.  In either case, it
84is trivial to add custom commands to the command set available.
89.. COMMENT: The RTEMS Project has been granted permission from The Open Group
90.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
91.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
92.. COMMENT: We have to include a specific acknowledgement paragraph in these
93.. COMMENT: documents (e.g. preface or copyright page) and another slightly
94.. COMMENT: different paragraph for each manual page that excerpts and uses
95.. COMMENT: text from the standards.
96.. COMMENT: This file should help ensure that the paragraphs are consistent
97.. COMMENT: and not duplicated
99The Institute of Electrical and Electronics Engineers, Inc and The Open Group,
100have given us permission to reprint portions of their documentation.
102.. pull-quote::
104    Portions of this text are reprinted and reproduced in electronic form from
105    IEEE Std 1003.1, 2004 Edition, Standard for Information Technology â
106    Operating System Interface (POSIX), The Open Group Base Specifications
107    Issue 6, Copyright © 2001-2004 by the Institute of Electrical and
108    Electronics Engineers, Inc and The Open Group. In the event of any
109    discrepancy between this version and the original IEEE and The Open Group
110    Standard, the original IEEE and The Open Group Standard is the referee
111    document. The original Standard can be obtained online at
112  This notice shall appear on any
113    product containing this material.
Note: See TracBrowser for help on using the repository browser.