Bridges

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

We have defined interfaces for the following components and bridges:

the RXF. The Realtime 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 RXF, 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 RXF, 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
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	reserved for future use

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

WST_TM_OVERFLOW	the maximum value of the timeUnit type, see limits of the RXF.
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 as unsigned 64 bit value, 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	reserved for future use
int_t	reserved for future use
struct_t	reserved for future use

Please refer to the exact implementation for your compiler bridge.

Interface Target

Files

Description

WSTTarget.h

This file must define the following functions:

WSTTarget_Init	This function is called in main(). WSTTarget_Init() is the place to hook code into when your target is not already initialized by your startup code, prior to calling main(). 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 );

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.

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. Plöease 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

This your product uses the RXF with an RTOS extention. The interface for the RXF is defined as:

Files

Description

WSTRTOS.h

The file WSTRTOS.h must define the following macros:

RIC_MS_PER_TICK	The number of ticks per milisecond. Usually this constant can be derived from your RTOS configuration.
RiCOSDefaultThreadPriority	This constant, type long, is part of the RiCOSOXFInitEpilog and RiCOSEndApplocation interface by IBM Rational, but needed in an RTX based on an RTOS only. You can define it as RTOS_PRIORITY_NORMAL
RiCOSDefaultStackSize	This constant, type long, is part of the RiCOSOXFInitEpilog and RiCOSEndApplocation interface by IBM Rational, but needed in an RXF based on an RTOS only. You can define it as RTOS_DEFAULT_STACK
RiCOSDefaultMessageQueueSize	This constant, type long, is part of the RiCOSOXFInitEpilog and RiCOSEndApplocation interface by IBM Rational, but needed in an RTX based on an RTOS only. You can define it as RTOS_MQ_DEFAULT_SIZE
RTOS_PRIORITY_NORMAL	The default priority of any task. This priority is used when the real time model is used.
RTOS_PRIORITY_HIGH	The priority of the Bridge task
RTOS_PRIORITY_LOW	The lowest priority of any task. This priority is used when the simulated time model is used.
RTOS_DEFAULT_STACK	This macro defines the default size of any task in bytes.
RTOS_MQ_DEFAULT_SIZE	This macro defines the maximum number of messages in a queue
RTOS_MAIN_STK_SIZE	This macro defines the size in bytes of the stack of the main task
RTOS_SMALL_STACK	This macro defines the size in bytes of the stack of the bridge task
RiC_RAW_MEMORY_ALIGNMENT
RiCOSMemoryAllocation_malloc	malloc must be mapped to this function
RiCOSMemoryAllocation_calloc	calloc must be mapped to this function
RiCOSMemoryAllocation_realloc	realloc must be mapped to this function
RiCOSMemoryAllocation_free	free must be mapped to this function

The constant RIC_OS_MUTEX_LOCK_AS_OPERATION may be used when the RTOS is capable of locking a mutex in a single operation.

This file must define the following functions:

WSTRTOS_Init	This function is called in main(). So this is the place to hook code into when your RTOS is not already initialized by your startup code, prior to calling main(). Its prototype is: void WSTRTOS_Init( void );
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 );

WSTRTOS.c

This file must implement the following functions:

WSTRTOS_Init	See its description for WSTRTOS.h.
WSTRTOS_Cleanup	Optional, 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.