TargetRTS for C Porting example

Introduction

This section provides an example of porting the TargetRTS for C to a new platform. This is an example port rather than customization of an existing port. This porting example should help implement the information presented in previous sections. The target platform for this example is the VRTX 4.0 real-time operating system using the Microtec Research C Compiler Version 1.3C for Motorola PowerPC 603 microprocessors. It is assumed that no previous version of the TargetRTS for this platform exists.

Choosing the platform name

The platform name is an important identifier of the TargetRTS. It identifies the operating system, hardware architecture and (cross) compiler. In this example, the operating system is VRTX4. The hardware architecture is Motorola PowerPC 603 (ppc603). The compiler is the Microtec Research C Compiler Version 1.3C. For this example we will only consider the multi-threaded version of the TargetRTS since this provides the most interesting porting challenges. The resulting platform name is as follows:

<OS> = VRTX4T

<LIBSET> = ppc603-Microtec-1.3C

<OS>.<LIBSET> = VRTX4T.ppc603-Microtec-1.3C

Create setup script

The setup script is in the file $(RTS_HOME)/config/VRTX4T.ppc603-Microtec-1.3C /setup.pl. This file is a Perl script that defines environment variables for the compilation of the TargetRTS. The contents of the setup script are as follows:

$os = $ENV{'OS'};

$os = 'default' unless defined( $os );

if( $os eq 'Windows_NT' )

{

$usr_mri = $ENV{'USR_MRI'};

$ENV{'PATH'} = "$usr_mri/bin;$ENV{'PATH'}";

}

else

{

$os_name = \Quname -s\Q; ## get the flavor of unix

chomp( $os_name );

if( $os_name eq 'SunOS' ) ## if the flavor of unix is solaris

{

$usr_mri = "$ENV{'OS_HOME'}/spectra/solaris-ppc603-4.AB";

}

elsif( $os_name eq 'HP-UX' ) ## if the flavor of unix is HP-UX

{

$usr_mri = "$ENV{'OS_HOME'}/spectra/hp-ppc603-4.AB";

}

else ## this flavor of unix is not a supported flavor

{

printf "This\Q%s'is not a supported flavor of unix\n",

$os_name;

}

$ENV{'USR_MRI'} = "$usr_mri";

$ENV{'SPECTRA'} = "$usr_mri/spappc";

$ENV{'MRI_PPC_BIN'} = "$usr_mri/bin";

$ENV{'MRI_PPC_LIB'} = "$usr_mri/lib";

$ENV{'MRI_PPC_INC'} = "$usr_mri/include/mccppc";

$ENV{'PATH'} = "$usr_mri/bin:$ENV{'PATH'}";

}

$preprocessor = "mccppc -E >MANIFEST.i";

$include_opt = '-J';

$target_base = 'VRTX4';

$supported = 'Yes';

The setup script must contain the mandatory definitions for the preprocessor and supported flags. The tool chain environment variables are usually required for cross compiler tools such as Microtec, since it is not typically part of a user's command path and the environment variable definitions are probably not already defined in most users' environments. Note that the target_base variable is set to VRTX4. The value VRTX4 for target_base implies that the name of the directory for the VRTX code base is $(RTS_HOME)/src/target/VRTX4. In a TargetRTS port to a native compiler tool chain these definitions are probably not required.

Create makefiles

The next step in porting the TargetRTS is to create various makefiles needed to build the TargetRTS for the platform and to build ObjecTime models on this new TargetRTS and platform.

Libset makefile

The libset makefile is used to make specific definitions for the compiler. The command line interface for C compilers differs significantly, particularly for cross-compilers such as the Microtec C compiler. It is in this file that we make definitions for command line options for the compiler and linker and override other definitions made in $(RTS_HOME)/libset/default.mk. See "Default makefile" on page 36 for details. In any port of the TargetRTS there are certain commands required in the tool chain in order to support the building of the TargetRTS. Table 11 illustrates these required commands, the Unix equivalent, and the Microtec variant.

Compiler tool chain requirements

Command

Unix

Microtec

library archive

ar

ar.pl (a perl script)

C++ Compiler

CC

mccppc

Linker

ld -r

lnkppc -i

Pre-linker

ld -r -o

lnkppc -i -o

Shared library builder

CC -G -z text -o

mccppc -G -z text -o

VENDOR

n/a

Microtec

Compiler tool chain requirements
Command	Unix	Microtec
library archive	ar	ar.pl (a perl script)
C++ Compiler	CC	mccppc
Linker	ld -r	lnkppc -i
Pre-linker	ld -r -o	lnkppc -i -o
Shared library builder	CC -G -z text -o	mccppc -G -z text -o
VENDOR	n/a	Microtec

The library archive command (ar) for the Microtec tool chain requires the use of a script to work the way the TargetRTS build requires. The Microtec development environment does not supply an ar command. Instead it provides a lib command that behaves differently than the ar command. A Perl script file, ar.pl that resides in the directory $(RTS_HOME)/libset/ppc603-Microtec-1.3C, was written to provide a wrapper around the lib command. This is an exception to other supported TargetRTS platforms but illustrates a possible pitfall when moving to a new platform. Another Perl script file, ld.pl that resides in the directory $(RTS_HOME)/libset/ppc603-Microtec-1.3C, was written to provide a wrapper around the lnkppc -i command. This script takes lnkppc -i as arguments and is invoked to link an ObjecTime Developer update. The libset makefile must define the VENDOR variable that instructs the error parser which type of compiler is being used. The error parser uses this information to decode error messages returned by the compiler to a format compatible with the ObjecTime Developer toolset.

Another important role of the libset makefile is the definition of command line options. Table 12 illustrates the typical subset of command line options, the Unix equivalent, and the Microtec variant.

C++ Command line options

Option

Unix

Microtec

DEBUG_TAG

-g

-g -Gd -Gf -Gm -Gs

LIBSETCCFLAGS

-p603 -DPPC

LIBSETCCEXTRA

-O

-O -Qfs¹

INCLUDE_TAG

-I

-J

DIR_TAG

-l

-l

LIB_EXT

.a

.lib

¹
The -Qfs option suppresses the display of the source file line number for diagnostic messages.

C++ Command line options
Option	Unix	Microtec
DEBUG_TAG	-g	-g -Gd -Gf -Gm -Gs
LIBSETCCFLAGS		-p603 -DPPC
LIBSETCCEXTRA	-O	-O -Qfs¹
INCLUDE_TAG	-I	-J
DIR_TAG	-l	-l
LIB_EXT	.a	.lib

The compiler options may vary greatly from one platform to another, but must support some basic features. Read the compiler documentation carefully and review some of the libset.mk for other
TargetRTS platforms for guidance. A list of required features follows:

to compile source files into object files only (that is, not to the link phase), typically the `-c' option
to place the object file in a desired directory and file name, typically the `-o' option
to produce shared libraries, typically the `-G' option
to link and place the executable in a desired directory and file name, typically the `-o' option for the link phase
to turn on debugging instructions in the compiled code, typically the `-g' option
to specify the pathname of include files, typically the `-I' option
to specify the pathname of libraries, typically the `-L' option
to specify the libraries to link, typically the `-l' option
to turn on code optimization, typically `-O' option and sub-options
The contents of the libset makefile, $(RTS_HOME)/libset/ppc603-Microtec-1.3C/libset.mk , for Microtec compiler is as follows:

VENDOR = Microtec AR_CMD = $(PERL) $(RTS_HOME)/libset/$(LIBRARY_SET)/ar.pl CC = mccppc LD = $(PERL)$(RTS_HOME)/libset/$(LIBRARY_SET)/ld.pl \

lnkppc -i SHLIB_CMD = $(CC) -G -z text -o

LIBSETCCFLAGS = -p603 -DPPC LIBSETCCEXTRA = -O -Qfs SHLIBS =

OT_LIB_TAG = -llib LIB_EXT = .lib

INCLUDE_TAG = -J

ALL_OBJS_LIST = %$(ALL_OBJS_LISTFILE)

DEBUG_TAG = -g -Gd -Gf -Gm -Gs

Target makefile

The target makefile is used to make definitions specific to the target operating system and the
TargetRTS configuration. These are usually specific command line options for the compiler and linker to define such things as include directories for the target OS and libraries and their pathnames. These definitions must be common to all VRTX targets. The contents of the target makefile, $(RTS_HOME)/target/VRTX4T/target.mk, is as follows:

TARGETCCFLAGS = $(INCLUDE_TAG)$(SPECTRA)/target/include \

$(DEFINE_TAG)timeout=otTimeout

Configuration makefile

The configuration makefile is used to make definitions required by the operating system and compilation environment together. In the case of VRTX, the extension to be used at the end of the filename for the final executable is defined here. The content of the configuration makefile, $(RTS_HOME)/config/VRTX4T.ppc603-Microtec-1.3C/config.mk, is as follows:

EXEC_EXT = .x

TargetRTS configuration definitions

The configuration definitions for the TargetRTS are found in the include file $(RTS_HOME)/include/RTConfig.h. The definitions in this file are overridden by $(RTS_HOME)/target/VRTX4T/RTTarget.h. These definitions are used to enable and disable various features in the TargetRTS. The content of the file $(RTS_HOME)/target/VRTX4T/RTTarget.h is as follows:

#ifndef __RTTarget_h__

#define __RTTarget_h__ included

#define USE_THREADS 1

#define RSLMULTITHREADED RSLTRUE

/* Following definition is due to PR 7890 */

#ifdef RSLTHREAD_RETURNVAL

#undef RSLTHREAD_RETURNVAL

#endif

#define RSLTHREAD_RETURNVAL

#define RSLTO RSLTRUE

#define RSLDEBUG RSLTRUE

#define RSLTIMERS RSLTRUE

#define RSLACTOR_TIMERS RSLFALSE

#define DEFAULT_MAIN_PRIORITY 75

#define DEFAULT_LAYER_PRIORITY 73

#define DEFAULT_TIMER_PRIORITY 70

#define DEFAULT_DEBUG_PRIORITY 60

#define __READY_EXTENSIONS__

#define RSL_OVERRIDE_BASIC_SIZES

/*

*

* typically long

*

*/

typedef unsigned long RSLMemorySize;

typedef unsigned long RSLTimeoutSize;

/*

* typically short or int

* -- each actor may only have 64k-1 of local data

*/

typedef unsigned short RSLDataSize;

/*

typedef unsigned short RSLFieldOffset;

*/

typedef unsigned long RSLFieldOffset; /* for VRTX-MRI C compiler */

/*

* typically unsigned short

* -- there may only be 64k-2 ports

* -- there may only be 64k-2 actors

* -- there may only be 64k-2 threads

*/

/* override RSLPortIndex definition for VRTX - PR7804, PR7808 */

typedef short RSLPortIndex;

#define RSLMaxPort 32767

typedef unsigned short RSLActorIndex;

#define RSLMaxActor 65535

typedef unsigned short RSLThreadIndex;

#define RSLMaxThread 65535

typedef unsigned short RSLMessageIndex;

#define RSLMaxMessages 65535

typedef unsigned short RSLTCBIndex;

#define RSLMaxTCBs 65535

/*

* typically char

* -- there may only be 255 events per protocol

* -- there may only be 255 ports references per actor

* -- there may only be 255 Actor Classes

* -- there may only be 255 states in each actor

* -- there may only be 255 port classes

*/

typedef unsigned short RSLBool;

typedef unsigned short RSLFlags;

#define RSLMaxMessagePriority 65535

typedef unsigned short RSLMessagePriority;

#define RSLSignalEvent 65535

typedef unsigned short RSLSignalIndex;

#define RSLMaxActorClasses 65535

typedef unsigned short RSLActorType;

typedef unsigned short RSLStateIndex;

#define RSLMaxPortClasses 65535

typedef unsigned short RSLPortType;

#define RSLMaxFieldTypes 65535

typedef unsigned short RSLFieldType;

#endif /* #ifndef __RTTarget_h__ */

Code changes to TargetRTS classes

Most ports to new targets require some minor changes to the TargetRTS code. These changes typically apply to operating system features for thread (task) creation and destruction, mutual exclusion and synchronization and time services.

The required changes to the TargetRTS source for VRTX 4 and the Microtec compiler are located in the $(RTS_HOME)/src/target/VRTX4 directory. These files override the versions in various directories in $(RTS_HOME)/src. To override a definition from the source directory a new subdirectory is created in $(RTS_HOME)/src/target/VRTX4.

The required changes to the TargetRTS are too large to include in this document. Table 13 contains a summary of the required changes to each file.

Required changes to TargetRTS source

Class

File

Change and Description

MAIN

main.c

DEBUG

debugio.c

RSL_nextChar function is overridden to support getting the next character from Input stream

INITSTOP

TGTinit.c

RSL_Target_Startup function is overridden to support relevant initialization during startup

TCP

lookup.c

cRSL_lookup function is overridden due to differences in
gethostbyname function

THREAD

RTThread.c

The functions RSLmutex_init, RSLmutex_lock, RSLmutex_unlock, RSLsemaphore_init, RSLsemaphore_wait, RSLsemaphore_post, RSLthr_create are overridden.

Required changes to TargetRTS source
Class	File	Change and Description
MAIN	main.c
DEBUG	debugio.c	`RSL_nextChar` function is overridden to support getting the next character from Input stream
INITSTOP	TGTinit.c	`RSL_Target_Startup` function is overridden to support relevant initialization during startup
TCP	lookup.c	`cRSL_lookup` function is overridden due to differences in `gethostbyname` function
THREAD	RTThread.c	The functions `RSLmutex_init`, `RSLmutex_lock`, `RSLmutex_unlock`, `RSLsemaphore_init`, `RSLsemaphore_wait`, `RSLsemaphore_post`, `RSLthr_create` are overridden.

Building the new TargetRTS

Once the setup script, makefiles and source are complete the TargetRTS is ready to be built. To build the TargetRTS for the VRTX-Microtec target, type the following in the $(RTS_HOME)/src directory:

make VRTX4T.ppc603-Microtec-1.3C

This will create a directory $(RTS_HOME)/build-VRTX4T.ppc603-Microtec-1.3C which will contain the dependency file and object files for the TargetRTS. If the build completes successfully the resulting ObjecTime libraries will be placed in the $(RTS_HOME)/lib/VRTX4T.ppc603-Microtec-1.3C directory.

[Top] [Prev] [TOC] [Next] [Bottom]