Using pSOS+ with ObjecTime Developer for C++ 5.2.1

Building executable ObjecTime Developer for C++ applications for Integrated System Inc.'s pSOS+ operating system requires more steps than is typical for UNIX operating systems. This note was written to help get an ObjecTime Developer application running on a pSOS target.

Intended Audience:

Top

ObjecTime Developers.

This technical note assumes some familiarity with pSOS+ and the development tools that form the pRISM+ development environment.

Applicable to:

Top

ObjecTime 5.2.1 and up

Description:

Top

ObjecTime Developer for C++ Supported pSOS Platforms:

The following platforms are currently supported for ObjecTime Developer for C++ version 5.2.1 (N.B.: for development tools hosted on Sun Solaris only) :

PSOS2T.m68040-Green-1.8.7B (pRISM: Green Hills tools for pSOS 2.1.4 on 68K)
PSOS2T.ppc603-Green-1.8.7C (pRISM: Green Hills tools for pSOS 2.1.3 on PowerPC)
PSOS22T.m68040-Microtec-4.5G (Microtec tools for pSOS 2.2.0 on 68K)
PSOS2T.ppc603-Diab-4.0b (pRISM+: Diab/SDS tools for pSOS+ 2.1.3 for PowerPC)

This tech-note is written specifically for the Diab 4.0b toolchain although all of the steps are applicable to these other supported platforms.

Setting up your Environment:

The first step is to setup your environment for using pSOS+ and a compiler. In all cases the supported pSOS+ toolchains run on Solaris so from this point forward this technical note assumes you are logged into a Solaris workstation. The pSOS+ development environment requires three environment variables :

PSS_ROOT : points to the top level directory of your pSOS+ installation
PSS_BSP : points to the BSP directory for your target
PSS_HOST : type of host being used, in this case "sunos"

Other environment variables will need to be set in order to use the entire set of tools. Please refer to the documentation that comes with the tools to see what needs to be set. If this is the first time you have used this development environment you should make you have developed and tested some simple non-ObjecTime Developer applications before attempting run ObjecTime on the target hardware.

Building a pSOS+ TargetRTS:

By default ObjecTime Developer for C++ does not have the ObjecTime Developer for C++ TargetRTS libraries built for RTOS targets. You will have to build the appropriate TargetRTS for pSOS+ before being able to build your model on top of it. Assuming you have set up your environment as discussed in the previous section,it is a simple matter to build the TargetRTS. The file $OBJECTIME_HOME/C++/TargetRTS/config/PSOS2T.ppc603-Diab-4.0b/setup.pl has definitions that are specific to ObjecTime's internal development environment. If by default you have the necessary environment to build pSOS+ applications (as discussed in the previous section) then you should remove these environment variable settings in the setup.pl file. In the end your setup.pl file should only contain the following :

$preprocessor    = "dplus -t PPC603EH -P";
$supported       = 'Yes';

You can now build the TargetRTS for the PSOS2T.ppc603-Diab-4.0b platform :

cd $OBJECTIME_HOME/C++/TargetRTS/src
make PSOS2T.ppc603-Diab-4.0b

Once complete and you will have a new TargetRTS when finished. If an error occur during the dependency generation be sure to remove the build-PSOS2T.ppc603-Diab-4.0b directory in $OBJECTIME_HOME/C++/TargetRTS before proceeding. This will force the regeneration of the dependencies the next time you build the TargetRTS. An error during dependency generation is probably due to incorrect path settings for the tool chain executables.

Building a pSOS+ Executable:

Once your environment is setup you can start the ObjecTime Developer toolset. Start the ObjecTime Developer toolset from the same shell that you used to build the TargetRTS or at least in a shell with the correct settings needed to compile and link pSOS+ applications. Select the appropriate pSOS+ configuration for your model and compile it. When you compile an ObjecTime model using the pSOS+ target you have not completely finished. The "link" step when using pSOS+ is actually an archive command which adds the model code into a library file. This file has the same name as the top actor with a ".a" extension. In order to build an executable from this point the pSOS+ RTOS and board support package must be compiled and linked with the ObjecTime model library and the TargetRTS libraries. The simplest way to do this is to use a template makefile provided by the C++ example program provided with pSOS+. Please check your pSOS+ documentation for information on the C++ examples that come with pSOS+.
Create a subdirectory in which to build your pSOS+ application. Try to use a directory that is independent of the working directory for your models. For example, a good place is a subdirectory in your home directory called ~/pSOS_builds/model_name. Copy the following files to this new directory :

$PSS_ROOT/apps/cxx/sys_conf.h
$PSS_ROOT/apps/cxx/drv_conf.c
$PSS_ROOT/apps/cxx/makefile

The file makefile must be edited before you can build the executable. Make the following changes :

# add new make variable OTD_LIB_DIR and OTD_LIBS
OTD_LIB_DIR=$(OBJECTIME_HOME)/C++/TargetRTS/lib/PSOS2T.ppc603-Diab-4.0b
OTD_LIBS=	\
	-lObjecTime \
	-lObjecTimeTypes \
	-lObjecTimeTransport

#add new make variable OTD_UPDATE_LIB
OTD_UPDATE_LIB= *** complete path and filename of ".a" produced by ObjecTime Developer \
  (include full name including .a) ***

#change PSS_APPOBJS
PSS_APPOBJS=$(OTD_LIB_DIR)/main.o

#add following to PSS_COMPLIB - do not remove existing libraries already defined!
PSS_COMPLIB= $(OTD_UPDATE_LIB) -L$(OTD_LIB_DIR) $(OTD_LIBS)
#
#if using Microtec tool chain then use the following definition for PSS_COMPLIB
#the linker only does a single pass so circuler references must be resolved by the user
#PSS_COMPLIB= $(OTD_UPDATE_LIB) -L$(OTD_LIB_DIR) $(OTD_LIBS) $(OTD_UPDATE_LIB)
#
#remove target "demo.o" and all subsequent commands defined for demo.o target

The sys_conf.h file must be edited to enable features required by ObjecTime. Make the following changes to the sys_conf.h file :

#define SC_PROBE_DEBUG      YES      /* pROBE+ (debug interface executive) */
#define SC_PHILE_PHILE      YES      /* pHILE+ (pHILE+ real-time file sys) */
#define SC_PNA              YES      /* pNA+ TCP/IP networking manager     */
#define SD_LAN1             YES      /* Disable the LAN interface */
#define KC_SYSSTK           0x8000   /* pSOS+ system stack size (bytes)     */
#define KC_ROOTSSTK         0x8000   /* ROOT supervisor stack size          */
#define KC_ROOTUSTK         0x8000   /* ROOT user stack size                */
#define NC_NSOCKETS         20       /* Number of sockets in the system     */
#define NC_NDESCS           20       /* # of socket descriptors/task        */

To build the executable :

make all

The executable will be generated as three files, ram.map, ram.hex and ram.elf. The ram.map file is the map file showing the complete memory map of the executable. The ram.elf file the executable in ELF format (needed by SingleStep debugger) and the ram.hex file is in Motorola S-records which is need by the ppc-Bug DL command or with TFTP.

Running a pSOS+ Executable (Diab/SDS toolchain):

There are three ways to download and execute a ObjecTime Developer for C++ application on a pSOS+ target. The first is using the serial line and S-records. This is slow and error prone. The second is using the SingleStep debugger. The debugger is connected to the target via the Ethernet connection and allows for quick download and then source-level debugging on the target. Please refer to the documentation for SingleStep on how to download an ELF file to the target. Remember that by default all applications end up as ram.elf and ram.hex. The third technique is to use TFTP to download the executable (ram.hex). In either case you must configure the target board to startup with pROBE+ which is the resident low-level debugger used with pSOS+. You can configure pROBE+ to startup and be ready in stand-alone mode, SingleStep debugger mode or TFTP boot mode. Since you now have a "standard" pSOS+ executable you should be able to follow the steps documented for SingleStep and/or pROBE+.

Target Observability and pSOS+:

Enabling Target Observability (T.O.) in an ObjecTime application requires command line arguments. You cannot use command line arguments with pSOS+ as you would with UNIX therefore you must compile them into the executable. This is done using the "Default Arguments" list box which is located in Target Browser->Configuration Browser->Language Options->Targets. Add the following arguments :

	-connect='port'@'host IP'
	-name=RTS'number''updatename'

Where 'port' and host name are found in the External Access browser (from main Settings menu). 'Host IP' must be defined using an numeric IP address instead of a textual host name (i.e., 127.0.1.0 ). The RTS 'number' is the currently selected TargetRTS (e.g., RTS2) and 'update name' is the full name of the update (not the top actor!) If using port 1234 on host "mySun" with RTS3 enabled and update named MypSOSTestUpdate then the default arguments would be :

	-connect=1234@127.0.1.0
	-name=RTS3MypSOSTestUpdate

Note that you must recompile the application if any of these values change (rebuild the executable and download again as well.) Please see the ObjecTime Developer C++ Language Guide pages 114-116 for more information.

Additional Notes

By default, an ObjecTime Developer application will assume that it is the root task in the system. ObjecTime Developer defines the root task, initializes the C++ run time, initializes the system timer (DEV_TIMER) and the serial line (DEV_SERIAL). You must modify the main.cc file in $OBJECTIME_HOME/C++/TargetRTS/src/target/PSOS2/MAIN in order to modify this behaviour. If you already have a root task that does this same initialization then you can start the main thread for ObjecTime from your own root task. The name of the main thread function for ObjecTime is "main_thread_func". You can use the thread creation code from main.cc as an example. Your user-defined root task must initialize the C++ runtime, timer and serial line in order for ObjecTime Developer to function properly. If you modify main.cc you must rebuild the TargetRTS as described in the previous section "Building a pSOS+ TargetRTS".

All threads in ObjecTime Developer for C++ running on pSOS+ are created with the T_LOCAL and T_FPU flags set. In addition, each thread is started with the T_PREEMPT, T_TSLICE, T_NOASR and T_USER flags set. You will need to modify $OBJECTIME_HOME/C++/TargetRTS/src/target/PSOS2/RTThread/ct.cc in order to change these settings. If you modify this file you must rebuild the TargetRTS as described in the previous section "Building a pSOS+ TargetRTS".

The ObjecTime Developer for C++ TargetRTS uses two event numbers for internal signaling. These are, by default, 1 and 2.

Limitations:

Top

None