mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2026-09-20 20:54:18 +08:00
2008-02-28 Joel Sherrill <joel.sherrill@oarcorp.com>
* shell/.cvsignore, shell/Makefile.am, shell/memory.t, shell/preface.texi, shell/shell.texi: Added much information the Preface. Created initial version of Configuration and Intialization chapter. Links are now complete from start to end of manual. * shell/confinit.t: New file.
This commit is contained in:
Joel Sherrill
@@ -1,3 +1,4 @@
|
||||
confinit.texi
|
||||
file.texi
|
||||
general.texi
|
||||
index.html
|
||||
|
||||
+17
-11
@@ -14,37 +14,43 @@ include $(top_srcdir)/main.am
|
||||
|
||||
FILES = shell.texi preface.texi
|
||||
|
||||
GENERATED_FILES = general.texi file.texi memory.texi rtems.texi network.texi
|
||||
GENERATED_FILES = confinit.texi general.texi file.texi memory.texi \
|
||||
rtems.texi network.texi
|
||||
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
info_TEXINFOS = shell.texi
|
||||
shell_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
|
||||
|
||||
general.texi: general.t
|
||||
confinit.texi: confinit.t
|
||||
$(BMENU2) -p "Preface" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
-n "General Commands" < $< > $@
|
||||
|
||||
general.texi: general.t
|
||||
$(BMENU2) -p "Configuration and Initialization rtems_shell_init - initialize the shell" \
|
||||
-u "Top" \
|
||||
-n "File and Directory Commands" < $< > $@
|
||||
|
||||
file.texi: file.t
|
||||
$(BMENU2) -p "" \
|
||||
$(BMENU2) -p "General Commands exit - exit the shell" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
-n "Memory Commands" < $< > $@
|
||||
|
||||
memory.texi: memory.t
|
||||
$(BMENU2) -p "" \
|
||||
$(BMENU2) -p "File and Directory Commands cd - alias for chdir" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
-n "RTEMS Specific Commands" < $< > $@
|
||||
|
||||
rtems.texi: rtems.t
|
||||
$(BMENU2) -p "" \
|
||||
$(BMENU2) -p "Memory Commands malloc - obtain information on C program heap" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
-n "Network Commands" < $< > $@
|
||||
|
||||
network.texi: network.t
|
||||
$(BMENU2) -p "" \
|
||||
$(BMENU2) -p "RTEMS Specific Commands dname - displays information about named drivers" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
-n "Function and Variable Index" < $< > $@
|
||||
|
||||
EXTRA_DIST = general.t file.t memory.t rtems.t network.t
|
||||
|
||||
|
||||
@@ -0,0 +1,253 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2008.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Configuration and Initialization
|
||||
|
||||
@section Introduction
|
||||
|
||||
This chapter provides information on how the application
|
||||
configures and intializes the RTEMS shell.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Configuration
|
||||
|
||||
The command set available to the application is user configurable.
|
||||
It is configured using a mechanism similar to the @code{confdefs.h}
|
||||
mechanism used to specify application configuration.
|
||||
|
||||
In the simplest case, if the user wishes to configure a command
|
||||
set with all commands available that are neither filesystem
|
||||
management (e.g. mounting, formating, etc.) or network related,
|
||||
then the following is all that is required:
|
||||
|
||||
@smallexample
|
||||
#define CONFIGURE_SHELL_COMMANDS_INIT
|
||||
#define CONFIGURE_SHELL_COMMANDS_ALL
|
||||
|
||||
#include <rtems/shellconfig.h>
|
||||
@end smallexample
|
||||
|
||||
In a slightly more complex example, if the user wishes to include
|
||||
all networking commands as well as support for mounting MS-DOS and
|
||||
NFS filesystems, then the following is all that is required:
|
||||
|
||||
@smallexample
|
||||
#define CONFIGURE_SHELL_COMMANDS_INIT
|
||||
#define CONFIGURE_SHELL_COMMANDS_ALL
|
||||
#define CONFIGURE_SHELL_MOUNT_MSDOS
|
||||
#define CONFIGURE_SHELL_MOUNT_NFS
|
||||
|
||||
#include <rtems/shellconfig.h>
|
||||
@end smallexample
|
||||
|
||||
@subsection Customizing the Command Set
|
||||
|
||||
The user can configure specific command sets by either building
|
||||
up the set from individual commands or starting with a complete
|
||||
set and disabling individual commands. Each command has two
|
||||
configuration macros associated with it.
|
||||
|
||||
@table @b
|
||||
|
||||
@item @code{CONFIGURE_SHELL_COMMAND_XXX}
|
||||
Each command has a constant of this form which is defined when
|
||||
building a command set by individually enabling specific
|
||||
commands.
|
||||
|
||||
@item @code{CONFIGURE_SHELL_NO_COMMAND_XXX}
|
||||
In contrast, each command has a similar command which is
|
||||
defined when the application is configuring a command set
|
||||
by disabling specific commands in the set.
|
||||
|
||||
@end table
|
||||
|
||||
@subsection Adding Custom Commands
|
||||
|
||||
One of the design goals of the RTEMS Shell was to make it
|
||||
easy for a user to add custom commands specific to their
|
||||
application. We believe this design goal was accomplished.
|
||||
In order to add a custom command, the user is required to
|
||||
do the following:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Provide a @i{main-style} function which implements
|
||||
the command. If that command function uses a @code{getopt}
|
||||
related function to parse arguments, it @b{MUST} use the
|
||||
reentrant form.
|
||||
|
||||
@item Provide a command definition structure of type
|
||||
@code{rtems_shell_cmd_t}.
|
||||
|
||||
@item Configure that command using the
|
||||
@code{CONFIGURE_SHELL_USER_COMMANDS} macro.
|
||||
@end itemize
|
||||
|
||||
Custom aliases are configured similarly but the user
|
||||
only provides an alias definition structure of type
|
||||
@code{rtems_shell_alias_t} and configures the alias
|
||||
via the @code{CONFIGURE_SHELL_USER_ALIASES} macro.
|
||||
|
||||
In the following example, we have implemented a custom
|
||||
command named @code{usercmd} which simply prints the
|
||||
arguments it was passed. We have also provided an
|
||||
alias for @code{usercmd} named @code{userecho}.
|
||||
|
||||
@smallexample
|
||||
#include <rtems/shell.h>
|
||||
|
||||
int main_usercmd(int argc, char **argv)
|
||||
@{
|
||||
int i;
|
||||
printf( "UserCommand: argc=%d\n", argc );
|
||||
for (i=0 ; i<argc ; i++ )
|
||||
printf( "argv[%d]= %s\n", i, argv[i] );
|
||||
return 0;
|
||||
@}
|
||||
|
||||
rtems_shell_cmd_t Shell_USERCMD_Command = @{
|
||||
"usercmd", /* name */
|
||||
"usercmd n1 [n2 [n3...]]", /* usage */
|
||||
"user", /* topic */
|
||||
main_usercmd, /* command */
|
||||
NULL, /* alias */
|
||||
NULL /* next */
|
||||
@};
|
||||
|
||||
rtems_shell_alias_t Shell_USERECHO_Alias = @{
|
||||
"usercmd", /* command */
|
||||
"userecho" /* alias */
|
||||
@};
|
||||
|
||||
#define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command
|
||||
#define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias
|
||||
#define CONFIGURE_SHELL_COMMANDS_INIT
|
||||
#define CONFIGURE_SHELL_COMMANDS_ALL
|
||||
#define CONFIGURE_SHELL_MOUNT_MSDOS
|
||||
|
||||
#include <rtems/shellconfig.h>
|
||||
@end smallexample
|
||||
|
||||
Notice in the above example, that the user wrote the
|
||||
@i{main} for their command (e.g. @code{main_usercmd})
|
||||
which looks much like any other @code{main()}. They
|
||||
then defined a @code{rtems_shell_cmd_t} structure
|
||||
named @code{Shell_USERCMD_Command} which describes that
|
||||
command. This command definition structure is registered
|
||||
into the static command set by defining
|
||||
@code{CONFIGURE_SHELL_USER_COMMANDS} to
|
||||
@code{&Shell_USERCMD_Command}.
|
||||
|
||||
Similarly, to add the @code{userecho} alias, the user
|
||||
provides the alias definition structure named
|
||||
@code{Shell_USERECHO_Alias} and defines
|
||||
@code{CONFIGURE_SHELL_USER_ALIASES} to configure
|
||||
the alias.
|
||||
|
||||
The user can configure any number of commands
|
||||
and aliases in this manner.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Initialization
|
||||
|
||||
The shell may be easily attached to a serial port or
|
||||
to the @code{telnetd} server. This section describes
|
||||
how that is accomplished.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@subsection Attached to a Serial Port
|
||||
|
||||
Starting the shell attached to the console or a serial
|
||||
port is very simple. The user invokes @code{rtems_shell_init}
|
||||
with parameters to indicate the characteristics of the task
|
||||
that will be executing the shell including name, stack size,
|
||||
and priority. The user also specifies the device that the
|
||||
shell is to be attached to.
|
||||
|
||||
This example is taken from the @code{fileio} sample test.
|
||||
This shell portion of this test can be run on any target which
|
||||
provides a console with input and output capabilities. It does
|
||||
not include any commands which cannot be supported on all BSPs.
|
||||
The source code for this test is in @code{testsuites/samples/fileio}
|
||||
with the shell configuration in the @code{init.c} file.
|
||||
|
||||
@smallexample
|
||||
#include <rtems/shell.h>
|
||||
|
||||
void start_shell(void)
|
||||
@{
|
||||
printf(" =========================\n");
|
||||
printf(" starting shell\n");
|
||||
printf(" =========================\n");
|
||||
rtems_shell_init(
|
||||
"SHLL", /* task name */
|
||||
RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */
|
||||
100, /* task priority */
|
||||
"/dev/console", /* device name */
|
||||
0, /* initial termios cflag value */
|
||||
0 /* run forever */
|
||||
);
|
||||
rtems_task_suspend(RTEMS_SELF);
|
||||
@}
|
||||
@end smallexample
|
||||
|
||||
In the above example, the call to @code{rtems_shell_init}
|
||||
spawns a task to run the RTEMS Shell attached to @code{/dev/console}
|
||||
and executing at priority 100. The caller suspends itself and
|
||||
lets the shell take over the console device.
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@subsection Attached to a Socket
|
||||
|
||||
TBD
|
||||
|
||||
@section Functions
|
||||
|
||||
This section describes the Shell related C functions which are
|
||||
publicly available related to initialization and configuration.
|
||||
|
||||
@page
|
||||
@subsection rtems_shell_init - initialize the shell
|
||||
|
||||
@cindex initialization
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@findex rtems_shell_init
|
||||
@example
|
||||
rtems_status_code rtems_shell_init (
|
||||
char *task_name,
|
||||
uint32_t task_stacksize,
|
||||
rtems_task_priority task_priority,
|
||||
char *devname,
|
||||
tcflag_t tcflag,
|
||||
int forever
|
||||
);
|
||||
@end example
|
||||
|
||||
@subheading DIRECTIVE STATUS CODES:
|
||||
@code{RTEMS_SUCCESSFUL} - Shell task spawned successfully@*
|
||||
others - to indicate a failure condition
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
This service creates a task with the specified characteristics to
|
||||
run the RTEMS Shell attached to the specified @code{devname}.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
This method invokes the @code{rtems_task_create} and @code{rtems_task_start}
|
||||
directives and as such may return any status code that those directives
|
||||
may return.
|
||||
|
||||
+1
-1
@@ -438,7 +438,7 @@ extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
|
||||
@c
|
||||
@c
|
||||
@page
|
||||
@subsection malloc - obtain information on c program heap
|
||||
@subsection malloc - obtain information on C program heap
|
||||
|
||||
@pgindex malloc
|
||||
|
||||
|
||||
+99
-4
@@ -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.
|
||||
|
||||
|
||||
@@ -66,6 +66,7 @@
|
||||
@contents
|
||||
|
||||
@include preface.texi
|
||||
@include confinit.texi
|
||||
@include general.texi
|
||||
@include file.texi
|
||||
@include memory.texi
|
||||
@@ -79,6 +80,7 @@ This is the online version of the RTEMS Shell User's Guide.
|
||||
|
||||
@menu
|
||||
* Preface::
|
||||
* Configuration and Initialization::
|
||||
* General Commands::
|
||||
* File and Directory Commands::
|
||||
* Memory Commands::
|
||||
@@ -95,7 +97,7 @@ This is the online version of the RTEMS Shell User's Guide.
|
||||
@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
|
||||
@c
|
||||
|
||||
@node Function and Variable Index, Concept Index, , Top
|
||||
@node Function and Variable Index, Concept Index, Network Commands route - show or manipulate the ip routing table, Top
|
||||
@unnumbered Function and Variable Index
|
||||
@printindex fn
|
||||
|
||||
|
||||
Reference in New Issue
Block a user