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. See the C++ Target Guide for a customization example. 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 4.5T for Motorola 68040 microprocessors. This is a currently supported platform, but 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 68040 (m68040). The compiler is the Microtec Research C++ Compiler Version 4.5T. 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> = m68040-Microtec-4.5T

<OS>.<LIBSET> = VRTX4T.m68040-Microtec-4.5T

Create setup script

The setup script is in the file $(RTS_HOME)/config/VRTX4T.m68040-Microtec-4.5T/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_HOME = $ENV{`OS_HOME`};

$USR_MRI = "$OS_HOME/spectra/solaris-68k-4.AAA";

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

$ENV{`SPECTRA'} = "$USR_MRI/spa68k";

$ENV{`MRI_68K_BIN'} = "$USR_MRI/bin";

$ENV{`MRI_68K_LIB`} = "$USR_MRI/lib";

$ENV{`MRI_68K_INC`} = "$USR_MRI/include/mcc68k";

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

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

$include_opt = `-J`;

$target_base = `VRTX3`;

$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 VRTX3. This means the VRTX4T target uses the same code base for the TargetRTS classes as the VRTX3T target. 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 8 illustrates these required commands, the Unix equivalent, and the Microtec variant.

Compiler tool chain requirements

Command	Unix	Microtec
library archive	ar	microtec_ar (script)
C++ Compiler	CC	ccc68k
Linker	ld -r	lnk68k -r
Pre-linker	ld -r -o	lnk68k -r -o
Shared library builder	CC -G -z text -o	ccc68k -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 script file, microtec_ar 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. 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 9 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 -Gf
LIBSETCCEXTRA		-p68040 -c -Qms0401 -Qs -Xp -Mca -Mda1
LIBSETCCFLAGS	-O	-O -Ob -Oe -Ot -Qfs -NM$(@F:.o=)2
INCLUDE_TAG	-I	-J
DIR_TAG	-l	-l
LIB_EXT	.a	.lib

1 The -Qms0401 option suppresses the 0401 error message "destructor for base class is not virtual". The -Qs option suppresses the summary message. The -Xp allocates space for global variables that have not been explicitly initialized. 2 The -Qfs option suppresses the display of the source file line number for diagnostic messages. The -NM options sets the module name.

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/m68040-Microtec-4.5T/libset.mk , for Microtec compiler is as follows:

  AR_CMD = $(RTS_HOME)/targets/microtec_ar lib68k

  CC = ccc68k

  LD = lnk68k -r

  PRELINK = cat >

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

  #VENDOR is used in definition of OTCOMPILE and OTLINK in default.mk

  VENDOR = Microtec

  #override the extension for executables

  EXEC_EXT = .x

  LIBSETCCFLAGS = -p68040 -c -Qms0401 -Qs -Xp -Mca -Mda

  LIBSETCCEXTRA = -O -Ob -Oe -Ot -Qfs -NM$(@F:.o=)

  SHLIBS =

  LIB_EXT = .lib

  DEBUG_TAG = -g -Gf

  DIR_TAG =

  INCLUDE_TAG = -J

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 definitions for libraries are made here since they are specific to the compiler and operating system combination. Therefore these definitions are not appropriate in the target makefile. The content of the configuration makefile, $(RTS_HOME)/config/VRTX4T.m68040-Microtec-4.5T/config.mk, is as follows:

EXEC_EXT = .x

SYSTEM_LIBS = $(RTS_LIBRARY)/libObjecTime$(LIB_EXT) \

$(RTS_LIBRARY)/libObjecTimeTransport$(LIB_EXT) \

$(RTS_LIBRARY)/libObjecTimeTypes$(LIB_EXT)

TARGETLIBS = $(USR_MRI)/lib/ccc68kab040.lib

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 and possibly $(RTS_HOME)/libset/m68040-Microtec-4.5T/RTLibSet.h. These definitions are used to enable and disable various features in the TargetRTS. By default all of the TargetRTS features are enabled (for example, target observability). The porting effort may be made easier if these features are disabled. See section "TargetRTS Customization Example" in the C++ Target Guide for instructions on how to build a minimized TargetRTS. The content of the file $(RTS_HOME)/target/VRTX4T/RTTarget.h is as follows:

#ifndef __RTTarget_h__

#define __RTTarget_h__ included

#define TARGET_VRTX 4

#define TARGET platVRTX

#define USE_THREADS 1

#define EXTERNAL_LAYER 1

#define DEFAULT_MAIN_PRIORITY 75

#define DEFAULT_LAYER_PRIORITY 73

#define DEFAULT_TIMER_PRIORITY 70

#define DEFAULT_IOMON_PRIORITY 72

#define DEFAULT_DEBUG_PRIORITY 60

#define CLOCK_TICKS_PER_SEC 100

#define NSECS_PER_TICK 10000000

#define __READY_EXTENSIONS__

#ifdef _SIZE_T

#ifndef __size_t

#define __size_t

#endif

typedef _SIZE_T size_t;

#endif

#endif // __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. A description of TargetRTS classes that may require changes is already given in Table 5, "TargetRTS constants/macros and their default values," on page 46.

The required changes to the TargetRTS source for VRTX 4 and the Microtec compiler are located in the $(RTS_HOME)/src/target/VRTX3 directory. These files override the versions in $(RTS_HOME)/src. To override a definition from the source directory a new subdirectory is created in $(RTS_HOME)/src/target/VRTX3 (that is, a new definition for RTTimespec::getclock requires a subdirectory $(RTS_HOME)/src/target/VRTX3/RTTimespec). The new file containing RTTimespec::getclock would be $(RTS_HOME)/src/target/VRTX3/RTTimespec/getclock.cc.

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

Required changes to TargetRTS source

Class	File	Change
main function	main.cc	This change was required due to a bug in the Microtec compiler with respect to static constructors. Normally changes are required for operating systems that already provide a main function.
RTDebuggerInput	nextChar.cc
RTDiagStream	flush.cc	if fflush is not supported, implement a flush empty method
	ls_string	<< operator overridden with code to output string (fputs not supported)
RTIOMonitor	min_size.cc	min_size method changed to use FD_SETSIZE.
RTMain	targetStartup.cc	targetStartup method overridden with code to perform VRTX specific startup code.
	installOneHandler.cc	installOneHandler empty method
	installHandlers.cc	installHandlers empty method
RTMutex	ct.cc	constructor for RTMutex defined for VRTX mutex creation (sc_mcreate)
	dt.cc	destructor for RTMutex defined for VRTX mutex destruction (sc_mdelete)
	enter.cc	enter method created to use VRTX sc_mpend function
	leave.cc	leave method created to use VRTX sc_mpost function
RTSyncObject	ct.cc	constructor for RTSyncObject
	dt.cc	destructor for RTSyncObject
	signal.cc	signal method for RTSyncObject created to use VRTX sc_post function.
	wait.cc	wait method defined to use VRTX sc_pend function with no time-out.
	timedwait.cc	timedwait method defined to use VRTX sc_pend function with time-out specified. NOTE: In VRTX the mailbox feature is used — it behaves much like a binary semaphore and provides a time-out on the sc_pend function — this greatly simplifies the implementation of the RTSyncObject
RTTcpSocket	getPrimary.cc	getPrimary method overridden to support different method of establishing host name.
	lookup.cc	lookup method overridden due to differences in gethostbyname function
	set_nonblocking.cc	set_nonblocking method overridden due to differences in ioctl function.
RTThread	ct.cc	constructor for RTThread overridden to use VRTX-specific thread creation function (sc_tecreate)
RTTimespec	getclock.cc	getclock method overridden to use VRTX-specific clock function (sc_gclock).

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.m68040-Microtec-4.5T

This will create a directory $(RTS_HOME)/build-VRTX4T.m68040-Microtec-4.5T 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 directory.