source: rtems-docs/shell/preface.rst

Last change on this file was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

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