RTP Applications
3 RTP Applications .6 Executing RTP Applications
3.6 Executing RTP Applications
3.6.2 Running Applications Automatically
Running applications automatically—without user intervention—is required for many deployed systems. VxWorks applications can be started automatically in a variety of ways. In addition, application executables can be stored either on a host system—which can be useful during development even when a startup facility is in use—or they can be stored on the target itself.
The VxWorks application startup facility is designed to serve the needs of both the development environment and deployed systems.
NOTE: For Windows hosts must use forward slashes (or double backslashes) as path delimiters. This is the case even when the executable is stored on the host system.
For the development environment, the startup facility can be used interactively to specify a variety of applications to be started at boot time. The operating system does not need to be rebuilt to run different sets of applications, or to run the same applications with different arguments or process-spawn parameters (such as the priority of the initial task). That is, as long as VxWorks has been configured with the appropriate startup components, and with the components required by the applications themselves, the operating system can be completely independent and ignorant of the applications that it will run until the moment it boots and starts them. One might call this a blind-date scenario.
For deployed systems, VxWorks can be configured and built with statically defined sets of applications to run at boot time (including their arguments and process-spawn parameters). The applications can also be built into the system image using the ROMFS file system. And this scenario might be characterized as most matrimonial.
In this section, use of the startup facility is illustrated with applications that reside on the host system. For information about using ROMFS to bundle applications with the operating system, and for examples illustrating how applications in the ROMFS file system are identified for the startup facility, see 3.7 Bundling RTP Applications in a System using ROMFS, p.59.
Startup Facility Options
Various means can be used to identify applications to be started, as well as to provide their arguments and process-spawn parameters for the initial application task. Applications can be identified and started automatically at boot time using any of the following:
■ an application startup configuration parameter
■ a boot loader parameter
■ a VxWorks shell script
■ the usrRtpAppInit( ) routine
The components that support this functionality are, respectively:
■ INCLUDE_RTP_APPL_INIT_STRING
■ INCLUDE_RTP_APPL_BOOTLINE
■ INCLUDE_RTP_APPL_INIT_CMD_SHELL_SCRIPT (for the command interpreter; the C interpreter can also be used with other components)
■ INCLUDE_RTP_APPL_USER
The boot loader parameter and the shell script methods can be used both
interactively (without modifying the operating system) and statically. Therefore, they are equally useful for application development, and for deployed systems.
The startup configuration parameter and the usrRtpAppInit( ) routine methods require that the operating system be re-configured and rebuilt if the developer wants to change the set of applications, application arguments, or process-spawn parameters.
There are no speed or initialization-order differences between the various means of automatic application startup. All of the startup facility components provide much the same performance.
3 RTP Applications 3.6 Executing RTP Applications
Application Startup String Syntax
A common string syntax is used with both the startup facility configuration parameter and the boot loader parameter for identifying applications. The basic syntax is as follows:
#progPathName^arg1^arg2^arg3#progPathName...
This syntax involves only two special characters:
#
A pound sign identifies what immediately follows as the path and name of an application executable.
^
A caret delimits individual arguments (if any) to the application. A caret is not required after the final argument.
The carets are not required—spaces can be used instead—with the startup configuration parameter, but carets must be used with the boot loader parameter.
The following examples illustrate basic syntax usage:
#c:/apps/myVxApp.vxe
Starts c:\apps\myVxApp.vxe
#c:/apps/myVxApp.vxe^one^two^three
Starts c:\apps\myVxApp.vxe with the arguments one, two, three.
#c:/apps/myOtherVxApp.vxe
Starts c:\apps\myOtherVxApp.vxe without any arguments.
#c:/apps/myVxApp.vxe^one^two^three#c:/apps/myOtherVxApp.vxe
Starts both applications, the first one with its three arguments.
The startup facility also allows for specification of rtpSpawn( ) routine parameters with additional syntax elements:
%p=value
Sets the priority of the initial task of the process. Priorities can be in the range of 0-255.
%s=value
Sets the stack size for the initial task of the process (an integer parameter).
%o=value
Sets the process options parameter.
%t=value
Sets task options for the initial task of the process.
When using the boot loader parameter, the option values must be either decimal or hexadecimal numbers. When using the startup facility configuration parameter, the code is preprocessed before compilation, so symbolic constants may be used as well (for example, VX_FP_TASK).
The following string, for example, specifies starting c:\apps\myVxApp.vxe with the arguments one, two, three, and an initial task priority of 125; and also starting c:\apps\myOtherVxApp.vxe with the options value 0x10 (which is to stop the process before running in user mode):
#c:/apps/myVxApp.vxe p=125^one^two^three#c:/apps/myOtherVxApp.vxe %o=0x10
If the rtpSpawn( ) options are not set, the following defaults apply: the initial task priority is 220; the initial task stack size is 64 Kb; the options value is zero; and the initial task option is VX_FP_TASK.
The maximum size of the string used in the assignment is 160 bytes, inclusive of names, parameters, and delimiters. No spaces can be used in the assignment, so application files should not be put in host directories for which the path includes spaces.
Specifying Applications with a Startup Configuration Parameter
Applications can be specified with the RTP_APPL_INIT_STRING parameter of the INCLUDE_RTP_APPL_INIT_STRING component.
The identification string must use the syntax described in Application Startup String Syntax, p.55. And the operating system must be rebuilt thereafter.
Specifying Applications with a Boot Loader Parameter
The VxWorks boot loader includes a parameter—the s parameter—that can be used to identify applications that should be started automatically at boot time, as well as to identify shell scripts to be executed.1 (For information about the boot loader, see the VxWorks Kernel Programmer’s Guide: Boot Loader.)
Applications can be specified both interactively and statically with the s
parameter. In either case, the parameter is set to the path and name of one or more executables and their arguments (if any), as well as to the applications’
process-spawn parameters (optionally). The special syntax described above is used to describe the applications (see Application Startup String Syntax, p.55).
This functionality is provided with the INCLUDE_RTP_APPL_BOOTLINE component.
Note that the boot loader s parameter serves a dual purpose: to dispatch script file names to the shell, and to dispatch application startup strings to the startup facility. Script files used with the s parameter can only contain C interpreter commands; they cannot include startup facility syntax (also see Specifying Applications with a VxWorks Shell Script, p.57).
If the boot parameter is used to identify a startup script to be run at boot time as well as applications, it must be listed before any applications. For example, to run the startup script file myScript and myVxApp.vxe (with three arguments), the following sequence would be required:
myScript#c:/apps/myVxApp.vxe^one^two^three
The assignment in the boot console window would look like this:
startup script (s) : myScript#c:/apps/myVxApp.vxe^one^two^three
The interactively-defined boot-loader parameters are saved in the target’s boot media, so that the application is started automatically with each reboot.
For the VxWorks simulator, the boot parameter assignments are saved in a special file on the host system, in the same directory as the image that was booted, for 1. In versions of VxWorks 5.x, the boot loader s parameter was used solely to specify a shell
script.
3 RTP Applications 3.6 Executing RTP Applications
example,
installDir/vxworks-6.x/target/proj/simpc_diab/default/nvram.vxWorks0. The number appended to the file name is processor ID number—the default for the first instance of the simulator is zero.
For a hardware target, applications can be identified statically. The DEFAULT_BOOT_LINE parameter of the INCLUDE_RTP_APPL_BOOTLINE component can be set to an identification string using the same syntax as the interactive method. Of course, the operating system must be rebuilt thereafter.
Specifying Applications with a VxWorks Shell Script
Applications can be started automatically with a VxWorks shell script. Different methods must be used, however, depending on whether the shell script uses command interpreter or C interpreter commands.
If the shell script is written for the command interpreter, applications can be identified statically.
The RTP_APPL_CMD_SCRIPT_FILE parameter of the
INCLUDE_RTP_APPL_INIT_CMD_SHELL_SCRIPT component can be set to the location of the shell script file.
A startup shell script for the command interpreter might, for example, contain the following line:
rtp exec c:/apps/myVxApp.vxe first second third
Note that for Windows hosts you must use either forward-slashes or double back-slashes instead of single back-slashes as path delimiters with the shell.
If a shell script is written for the C interpreter, it can be identified interactively using the boot loader s parameter— in a manner similar to applications—using a sub-set of the same string syntax. A shell script for the C interpreter can also be identified statically with the DEFAULT_BOOT_LINE parameter of the
INCLUDE_RTP_APPL_BOOTLINE component. (See Specifying Applications with a Boot Loader Parameter, p.56 and Application Startup String Syntax, p.55.)
The operating system must be configured with the kernel shell and the C interpreter components for use with C interpreter shell scripts (see the VxWorks Kernel Programmer’s Guide: Target Tools).
A startup shell script file for the C interpreter could contain the following line:
rtpSp "c:/apps/myVxApp.vxe first second third"
With the shell script file c:\scripts\myVxScript, the boot loader s parameter would be set interactively at the boot console as follows:
startup script (s) : c:/scripts/myVxScript
Note that shell scripts can be stored in ROMFS for use in deployed systems (see 3.7 Bundling RTP Applications in a System using ROMFS, p.59).
Specifying Applications with usrRtpAppInit( )
The VxWorks application startup facility can be used in conjunction with the usrRtpAppInit( ) initialization routine to start applications automatically when
VxWorks boots. In order to use this method, VxWorks must be configured with the INCLUDE_RTP_APPL_USER component.
For each application you wish to start, add an rtpSpawn( ) call and associated code to the usrRtpAppInit( ) routine stub, which is located in
installDir/vxworks-6.x/target/proj/projDir/usrRtpAppInit.c.
The following example starts an application called myVxApp, with three arguments:
void usrRtpAppInit (void) {
char * vxeName = "c:/vxApps/myVxApp/PPC32diab/myVxApp.vxe";
char * argv[5];
RTP_ID rtpId = NULL;
/* set the application's arguments */
argv[0] = vxeName;
argv[1] = "first";
argv[2] = "second";
argv[3] = "third";
argv[4] = NULL;
/* Spawn the RTP. No environment variables are passed */
if ((rtpId = rtpSpawn (vxeName, argv, NULL, 220, 0x10000, 0, 0)) == NULL) {
printErr ("Impossible to start myVxApp application (errno = %#x)", errno);
} }
Note that in this example, the myVxApp.vxe application executable is stored on the host system in c:\vxApps\myVxApp\PPC32diab.
The executable could also be stored in ROMFS on the target system, in which case the assignment statement that identifies the executable would look like this:
char * vxeName = "/romfs/myVxApp.vxe";
For information about bundling applications with the system image in ROMFS, see 3.7 Bundling RTP Applications in a System using ROMFS, p.59.