From c2153cfd292dbb771bcbff034284c30edff55f28 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 29 Feb 2008 00:23:04 +0000 Subject: 2008-02-28 Joel Sherrill * 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. --- doc/ChangeLog | 8 ++ doc/shell/.cvsignore | 1 + doc/shell/Makefile.am | 28 +++--- doc/shell/confinit.t | 253 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/shell/memory.t | 2 +- doc/shell/preface.texi | 103 +++++++++++++++++++- doc/shell/shell.texi | 4 +- 7 files changed, 382 insertions(+), 17 deletions(-) create mode 100644 doc/shell/confinit.t (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index 233bf4f19f..4189e2cd37 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2008-02-28 Joel Sherrill + + * 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. + 2008-02-28 Joel Sherrill * shell/file.t, shell/network.t: Document more commands and provide diff --git a/doc/shell/.cvsignore b/doc/shell/.cvsignore index f408039f93..1eaad1cf42 100644 --- a/doc/shell/.cvsignore +++ b/doc/shell/.cvsignore @@ -1,3 +1,4 @@ +confinit.texi file.texi general.texi index.html diff --git a/doc/shell/Makefile.am b/doc/shell/Makefile.am index 506fd6b4e5..8e13f23383 100644 --- a/doc/shell/Makefile.am +++ b/doc/shell/Makefile.am @@ -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 diff --git a/doc/shell/confinit.t b/doc/shell/confinit.t new file mode 100644 index 0000000000..bb94b608a3 --- /dev/null +++ b/doc/shell/confinit.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 +@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 +@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 + +int main_usercmd(int argc, char **argv) +@{ + int i; + printf( "UserCommand: argc=%d\n", argc ); + for (i=0 ; i +@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 + +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. + diff --git a/doc/shell/memory.t b/doc/shell/memory.t index c18e462c72..cb78277b20 100644 --- a/doc/shell/memory.t +++ b/doc/shell/memory.t @@ -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 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. + diff --git a/doc/shell/shell.texi b/doc/shell/shell.texi index 5a44678d36..085283c7e8 100644 --- a/doc/shell/shell.texi +++ b/doc/shell/shell.texi @@ -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 -- cgit v1.2.3