[e52906b] | 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
[489740f] | 2 | |
---|
[4886d60] | 3 | .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
[e5afcaa] | 4 | |
---|
[8ca13ed] | 5 | Preface |
---|
[f15d607] | 6 | ******* |
---|
[8ca13ed] | 7 | |
---|
| 8 | Real-time embedded systems vary widely based upon their operational and |
---|
| 9 | maintenance requirements. Some of these systems provide ways for the user or |
---|
| 10 | developer to interact with them. This interaction could be used for |
---|
| 11 | operational, diagnostic, or configuration purposes. The capabilities described |
---|
| 12 | in this manual are those provided with RTEMS to provide a command line |
---|
| 13 | interface for user access. Some of these commands will be familiar as standard |
---|
| 14 | POSIX utilities while others are RTEMS specific or helpful in debugging and |
---|
| 15 | analyzing an embedded system. As a simple example of the powerful and very |
---|
| 16 | familiar capabilities that the RTEMS Shell provides to an application, consider |
---|
| 17 | the following example which hints at some of the capabilities available: |
---|
| 18 | |
---|
| 19 | .. code-block:: shell |
---|
| 20 | |
---|
| 21 | Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis) |
---|
| 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 [/] $ |
---|
| 46 | |
---|
| 47 | In the above example, the user *rtems* logs into a SPARC based RTEMS system. |
---|
| 48 | The first command is ``cat /etc/passwd``. This simple command lets us know |
---|
| 49 | that this application is running the In Memory File System (IMFS) and that the |
---|
| 50 | infrastructure has provided dummy entries for */etc/passwd* and a few other |
---|
| 51 | files. The contents of */etc/passwd* let us know that the user could have |
---|
| 52 | logged in as ``root``. In fact, the ``root`` user has more permissions than |
---|
| 53 | ``rtems`` who is not allowed to write into the filesystem. |
---|
| 54 | |
---|
| 55 | The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style |
---|
| 56 | device nodes which can be accesses through standard I/O function calls. |
---|
| 57 | |
---|
| 58 | The third command executed is the RTEMS specific ``stackuse`` which gives a |
---|
| 59 | report on the stack usage of each thread in the system. Since stack overflows |
---|
| 60 | are a common error in deeply embedded systems, this is a surprising simple, yet |
---|
| 61 | powerful debugging aid. |
---|
| 62 | |
---|
| 63 | Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of |
---|
| 64 | mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices |
---|
| 65 | as well as network-based filesystens such as NFS and TFTP, the standard free |
---|
| 66 | RTEMS provides a robuse infrastructure for embedded applications. |
---|
| 67 | |
---|
| 68 | This manual describes the RTEMS Shell and its command set. In our terminology, |
---|
| 69 | the Shell is just a loop reading user input and turning that input into |
---|
| 70 | commands with argument. The Shell provided with RTEMS is a simple command |
---|
| 71 | reading loop with limited scripting capabilities. It can be connected to via a |
---|
| 72 | standard serial port or connected to the RTEMS ``telnetd`` server for use across |
---|
| 73 | a network. |
---|
| 74 | |
---|
| 75 | Each command in the command set is implemented as a single subroutine which has |
---|
| 76 | a *main-style* prototype. The commands interpret their arguments and operate |
---|
| 77 | upon stdin, stdout, and stderr by default. This allows each command to be |
---|
| 78 | invoked independent of the shell. |
---|
| 79 | |
---|
| 80 | The described separation of shell from commands from communications mechanism |
---|
| 81 | was an important design goal. At one level, the RTEMS Shell is a complete |
---|
| 82 | shell environment providing access to multiple POSIX compliant filesystems and |
---|
| 83 | TCP/IP stack. The subset of capabilities available is easy to configure and |
---|
| 84 | the standard Shell can be logged into from either a serial port or via telnet. |
---|
| 85 | But at another level, the Shell is a large set of components which can be |
---|
[d389819] | 86 | integrated into the user's developed command interpreter. In either case, it |
---|
[8ca13ed] | 87 | is trivial to add custom commands to the command set available. |
---|
| 88 | |
---|
| 89 | Acknowledgements |
---|
| 90 | ================ |
---|
| 91 | |
---|
| 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 |
---|
| 101 | |
---|
| 102 | The Institute of Electrical and Electronics Engineers, Inc and The Open Group, |
---|
| 103 | have given us permission to reprint portions of their documentation. |
---|
| 104 | |
---|
| 105 | .. pull-quote:: |
---|
| 106 | |
---|
| 107 | Portions of this text are reprinted and reproduced in electronic form from |
---|
[e5afcaa] | 108 | IEEE Std 1003.1, 2004 Edition, Standard for Information Technology |
---|
[8ca13ed] | 109 | Operating System Interface (POSIX), The Open Group Base Specifications |
---|
[d389819] | 110 | Issue 6, Copyright (c) 2001-2004 by the Institute of Electrical and |
---|
[8ca13ed] | 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 | http://www.opengroup.org/unix/online.html. This notice shall appear on any |
---|
| 116 | product containing this material. |
---|