Bridges

Each product has a number of interfaces, see the image below:

We have defined interfaces for the following components and bridges:

the OO RTX. The Object Oriented RealTime eXecution system comes in C or C++ form, and replaces the standard OXF Framework by IBM Rational.
one or more PMF's which extend the product with a shared library form of the OO RTX, an extention for a particular RTOS or Debugger (for runtime- and offline- target animation).
the Deployer (where available) which deploys Rhapsody generated source files, some configuration files, the OO RTX, optional PMF components and the bridges to your IDE environment.
interface / configuration details for use with Rhapsody, like a property file and profile(s)
interface with your compiler
interface with your target
interface with your IDE
interface with your RTOS. This interface must be implemented even if no RTOS extention is used.
interface with your debugger (when using a PMF for runtime- and offline- target animation)..

To make the adaption to your hardware future proof, we show you how to isolate hardware details from your UML model by defining an interface for a Board Support Package.

For maximum flexibility, we added the include files WSTProlog.h and WSTEpilog.h which allows you to hook details in:

the file WSTProlog.h is always included immediately after the include file WSTProduct.h in RXF source files. WSTProduct.h defines constants for your product so should not conflict in any way with something which comes afterwards.
You can use the file WSTProlog.h to add constants, typedefinitions, macros which must modify existing function prototypes, etc.
the file WSTEpilog.h which is always included as last include file in RXF source files. You can use this file to add constants, typedefinitions, macros which are the counterpart of those used in WSTProlog.h etc.

Some of the RXF source files use constants for dimensioning, like the files RxfConstants.h and RxfDimensions.h. Because not all RXF files need constants from one or both include files, these are not always included.

Example:

#include "RxfConstants.h"
#include "WSTProduct.h"
#include "WSTProlog.h"
#include "WSTCompiler.h"
#include "WSTTarget.h"
#include "WSTRTOS.h"
#include "WSTPMF.h"
#include "RxfDimensions.h"

.. (include files for ANSI-C like stddef.h, include files for RXF)

#include "WSTEpilog.h"

Interface Compiler

Files

Description

WSTCompiler.h

This file must define the following types:

RiCBoolean	to use a RiCTRUE and RiCFALSE based on TRUE and FALSE
RhpBoolean	to use a RiCTRUE and RiCFALSE based on TRUE and FALSE
timeUnit	a timer counter unit, usually an unsigned 32 bit quantity, see limits of the RXF.
RiCHandle	a signed 8 bit quantity
gen_ptr	a generic pointer, usually a void *
eventID_t	the type of en event identifier, sint16 is usually sufficient, see limits of the RXF.

This file must define the following macros:

TRUE	Sometimes the compiler defines this macro. If not, you must provide it.
FALSE	Ibed.
WST_NEARD	This macro defines the compiler keyword, if any, for near data
WST_FARD	This macro defines the compiler keyword, if any, for far data
WST_NEARC	This macro defines the compiler keyword, if any, for near code
WST_FARC	This macro defines the compiler keyword, if any, for far code
WST_NEARD_ADDRESS_SIZE¹	This macro defines the size of a near data address
WST_FARD_ADDRESS_SIZE¹	This macro defines the size of a far data address
WST_NEARC_ADDRESS_SIZE¹	This macro defines the size of a near code address
WST_FARC_ADDRESS_SIZE¹	This macro defines the size of a far data address
WST_TIMEUNIT_ADDRESS_SIZE¹	This macro defines the size of a timeUnit data address

MALLOC_ARGUMENT_TYPE

the argument type of malloc

MALLOC_RETURN_TYPE

this type may vary depending on memory model, if any.

FREE_ARGUMENT_TYPE

this type may vary depending on memory model, if any.

FREE_RETURN_TYPE

void

WST_xxx_IS_MAPPED

in some cases a function must be mapped, depending on a memory model, if any.
In that case, a corresponding macro must be set.

This file may define the following macros:

RIC_OS_TOLOWER_DEFINED_IN_CTYPE

This macro is defined when tolower() is available in <ctype.h>

OMitoa( val, string, radix )

It may be mapped on itoa() (non-ANSI) or sprintf()

This file must implement the following function or define the macro:

WSTCompiler_Init

Initialize the compiler. Some compilers need for example a heap (function) to be initialized

WST_COMPILER_INIT_AS_EMPTY_MACRO

When this macro is set, no WSTCompiler_Init() needs to be implemented.

If your product comes with Container Classes by IBM Rational, the file WSTCompiler.h must also define:

RiC_UINT64

a type which is used in address calculations

RiC_INT32_MIN

the minimum value of a signed 32 bits quantity

RiC_INT32_MAX

the maximum value of a signed 32 bits quantity

RhpPositive_MAX

the maximum value of an unsigned 32 bits quantity

1 ANSI-C does not allow for use of the sizeof operator in preprocessor statements, which is why we use these _ADDRESS_SIZE macros. These macros are used for Memory Section Management.

WSTCompiler.c

This file must exist - it is used in the GettingStarted example.

In most compiler bridges, this file remains empty but this is a good place to add variables or functions which are needed by the C library of your toolchain, but the toolchain requires you to implement them. An example is storage for a heap.

This file must implement the following function when the macro WST_COMPILER_INIT_AS_EMPTY_MACRO is not set in WSTCompiler.h:

WSTCompiler_Init

Initialize the compiler. Some compilers need for example a heap (function) to be initialized.
This function is called by main() unless you have specified WST_COMPILER_INIT_AS_EMPTY_MACRO .

WSTCompilerTypes.h

This file may be part of a Board Support Package installation, and its types may be visible inside a Rhapsody project.

This file must define the following types:

int8	a signed 8 bit field, capable to hold a range from -128 to +127
uint8	an unsigned 8 bit field, capable to hold a range from 0 to 255
sint16	a signed 16 bit field, capable to hold a range from -32768 to +32767
uint16	an unsigned 16 bit field, capable to hold a range from 0 to 65535
sint32	a signed 32 bit field, capable to hold a range from -2147483648 .to +2147483647
uint32	an unsigned 16 bit field, capable to hold a range from 0 to 4294967295
boolean	for use with TRUE/FALSE
char_t	type for character data
int_t	used to align memory pool blocks, see RiCDimMemoryAllocationPkg.h
struct_t	used to calculate buffer sizes, see RiCMemoryPool.c

Please refer to the exact implementation for your compiler bridge.

Interface Target

Files

Description

WSTTarget.h

This file must define the following constant when the constant WST_RTOS_NONE is set:

RIC_MS_PER_TICK

The constant RIC_MS_PER_TICK is used to match the timing in your Rhapsody model with your hardware.
It can be set in the Target interface bridge, or via a Board Support Package, if any.

This file must define the following functions:

WSTTarget_Init	This function is called in main(). The function can be used to initialize your hardware including a timer interrupt for a regular heartbeat of the OO RTX. Its prototype is: void WSTTarget_Init( void );
WSTTarget_Cleanup	This function is not called by the RXF. You must implement it and call it in your <Rhapsody component>__Cleanup() if you need it. Its prototype is: void WSTTarget_Cleanup( void );

This file must also define the following functions when the constant WST_RTOS_NONE is set:

WSTTarget_enterCriticalRegion	This function is called by the RXF on entering a critical region and should prevent any interrupts which can come thru in your application to disturb housekeeping in the OO RTX. Its prototype is: void WSTTarget_enterCriticalRegion( void ); In some cases an interrupt mask must be stored. In that case, you must set the constant WST_TARGET_SAVEISRMASK, in which case the prototype of the function is: isrmask_t WSTTarget_enterCriticalRegion( void );
WSTTarget_exitCriticalRegion	Its prototype is: void WSTTarget_exitCriticalRegion( void );
WSTTarget_timerInterrupt	This function can be added as wrapper to WSTRTOS_incrementRxfTicks() and used in your timer ISR if any. Its prototype is: void WSTTarget_timerInterrupt( void );

WSTTarget.c

This file must implement the following functions:

WSTTarget_Init	See its description for WSTTarget.h.
WSTTarget_Cleanup	Optional, see its description for WSTTarget.h.

This file must also define the following functions when the constant WST_RTOS_NONE is set:

WSTTarget_enterCriticalRegion	See its description for WSTTarget.h.
WSTTarget_exitCriticalRegion	See its description for WSTTarget.h.
WSTTarget_timerInterrupt	See its description for WSTTarget.h.

Please refer to the exact implementation for your target bridge.

Interface IDE

Please refer to the exact implementation for your IDE bridge to learn how this interface is implemented for the Deployer. Note: Please note that the IDE integration is not part of all products or adaptations.

Files

Description

WSTDeployer.bat

This file can be executed with the following arguments:

configure Displays a configuration dialog to see and change the configured paths.
deploy Copies files from the Rhapsody model to the configured paths.
version Displays the tool's version string.
debug Generates a more detailed log file, should be first argument.
setRoot(path) Sets the root path to the specified argument within the brackets and switches custom paths off without displaying a dialog. If the path contains spaces it has to be quoted, e.g. setRoot("C:\Program Files\Dest").
quitRpy Quits Rhapsody after having executed commands which came first. This can be useful for batch processing and regression tests.
quitRpySave Quits Rhapsody and saves all changes after having executed commands which came first. This can be useful for batch processing and regression tests.

If the tool is started with the deploy command but paths are not yet configured, the configuration dialog will be displayed once. Correct paths can be configured and saved, afterwards the deploy command is executed.

Please note if you start the WSTDeployer with the commands "configure deploy" and cancel the configuration dialog, the deployment will still be started, as the cancel button only cancels the current configuration command.

Running WSTDeployer always requires access to the Rhapsody COM API, no matter what command is used.
Please make sure Rhapsody is running with a project opened and a correctly stereotyped component.

Running the WSTDeployer requires the Java Runtime Environment (JRE) 6 or Java SE Development Kit (JDK) 6 or higher to be installed on your system. You can download the software from Sun Microsystems, Inc.

WSTDeployer.properties

Configuration file for the WSTDeployer, which is read every time the WSTDeployer is started. The possible properties are documented via comments within the file. They are grouped following the topics:

Directories and Files
Tag names
Stereotype names
GUI Settings
ToolchainGateway Strings
List of supported destinations

Deployment.java

This class must implement the following methods:

void deploy(WSTDeployer commonDeployer, DeployConfiguration dc)

Prepares and starts the actual deployment.
This consists of different steps:

Use the RpyConnector class, which is part of the WSTDeployer, to connect to the Rhapsody API
If no paths are configured automatically ask for the configuration (using makeSurePathsAreConfigured())
Set up a FileCopySet list including all RXF, Generated, and environment specific files retrieved using RpyConnector and known directories
FileCopy's copy() method is used to actually copy the files

Parameters:

commonDeployer: Reference to the WSTDeployer class which is common for all environments
dc: DeployConfiguration reference

Usually methods like void logFiles(List<File> files, String descr), void logDeployInfos(DeployConfiguration dc) and List<File> filterImplFiles(List<File> files) etc. are also implemented in that class, but they are private methods used via deploy() and not part of the interface.

ToolchainGateway.java

This class must implement the following methods:

boolean addFilesToProject(List<File> files, File project, String type)

Adds a list of files to the specified project or workspace file of a toolchain.
Files that already exist in the project will not be added a second time, but new files will be added. In most implementations this function never removes files from the project.

Parameters:

files: List of files to add to the toolchain project
project: Path to the toolchain project file
type: Type of files to be added (e.g. RXF files). Please see toolchain specific implementation for supported values.

The method must return true, if files could be added successfully or if it was not necessary to add files. False will be returned, if the project file can not be opened or seems to be corrupted.

Constants.java

This class has to contain:

static String constants for all properties that should be read from the WSTDeployer.properties file. This means just the property names like DeployEnvName, which will be looked up, but not the property value itself. These Strings all use a "PRP_" prefix.
static String constant PRPFILE defining the properties file to use, usually WSTDeployer.properties.
static String constant LOGFILE defining the log file to use, usually WSTDeployerLog.txt.

the methods:

String getDest( String key, int destNumber )	Returns the value of a destination property, read from the properties file. Destination properties have property names like "Dest2Name", which coule be queried using getDest( PRP_DEST_NAME, 2 ).
int getNumberOfDestinations()
String get(String prpName)	Returns the value, read from the properties file, which is assigned to the property name.
int getInt(String prpName)	Returns the Integer value, read from the properties file, which is assigned to the property name.
public static Constants getInstance()	Constants is a Singleton class which makes sure there will only be one instance. Using this function it is easily possible to access the one instance of Constants. The first getInstance() call will read theWSTDeployer.properties file using the constructor.

build_WSTDeployer.bat

This file can be executed to recompile the WSTDeployer, if one of the bridge files Constants.java, Deployment.java or ToolchainGateway.java has been changed. To rebuild the sources, the Java SE Development Kit (JDK) 6 or higher needs to be installed on your system.

Interface RTOS

Your product may use the OO RTX with an RTOS extention. The interface for the RTOS bridge is defined as:

Files

Description

WSTRTOS.h

This file must define the following functions:

WSTRTOS_Init	This function is called in main(). If you need to initialize a timer, you could also use RIC_MS_PER_TICK in here. Its prototype is: void WSTRTOS_Init( void ); Most implementations do not need the function WSTRTOS_Init, which is by default it is implemented as an empty macro when WST_RTOS_NONE is set.
WSTRTOS_Cleanup	This function is not called by the RXF. You must implement it and call it in your <Rhapsody component>_Cleanup() if you need it. Its prototype is: void WSTRTOS_Cleanup( void ); Most implementations do not need the function WSTRTOS_Cleanup, which is by default it is implemented as an empty macro when WST_RTOS_NONE is set.

This file must also define the following functions when the constant WST_RTOS_NONE is set:

WSTRTOS_incrementRxfTicks	This function is not called by the RXF. You must implement it and call it as the heartbeat of your RXF, typically from within an Interrupt Service Routine. Its prototype is: void WSTTarget_incrementRxfTicks( void );
WSTRTOS_getRxfTicks	This function is called by the RXF. Its prototype is: timeUnit WSTRTOS_getRxfTicks( void );
WSTRTOS_sleep	This function is called by the RXF when no events are found in an event queue (timeouts also result in a event). Its prototype is: void WSTRTOS_sleep( timeUnit aTime );

WSTRTOS.c

This file must implement the following functions:

WSTRTOS_Init	See its description for WSTRTOS.h.
WSTRTOS_Cleanup	See its description for WSTRTOS.h.

This file must also implement the following functions when the constant WST_RTOS_NONE is set:

WSTRTOS_incrementRxfTicks	See its description for WSTRTOS.h. If you provide the heartbeat via a ISR, it is good practice to name this ISR WSTTarget_timerInterrupt
WSTRTOS_getRxfTicks	See its description for WSTRTOS.h.
WSTRTOS_sleep	See its description for WSTRTOS.h.

Interface PMF

A PMF is an extention of an existing product, and merely a way to easily add or supersede files which exist in a product. The PMF interface is not fixed and differs per PMF.