Porting the TargetRTS for C workbook

1.0 Simple model execution phase

This chapter leads you through the steps required to create a simple, single-threaded, executable. Source code will most likely not need modification as this process primarily focuses on setting up compiler flags, link options, and creating your first C TargetRTS library. Print this chapter so that you capture the information you will need to reference.

1.1 Environment setup

1.1.1 Create target-specific environment variables

1. Confirm that basic environment variables specific to your target platform already exist on your host platform. If not, create them.

   ex: Use the Windows NT Control Panel to create an environment variable called USR_MRI.

1.1.2 Note the values of existing environment variables

Note that %RTS_HOME% is a conceptual and internal environment variable that is used in this document. It does not need to be formally created as an operating system environment variable.

To find the value of %OBJECTIME_HOME% on Windows NT, open an ObjecTime Developer command prompt and type "set OB".

1.1.3 Install all required target OS software on the host and target

Install and configure the target OS software on both the host and target platforms.

1.1.4 Compile and run hello.c for your target

For more information see "Simple non-ObjecTime program on target" on page 27.

1.2 Choose names

1.2.1 Choose a target name and target base name

For more information, see "Target name" on page 32.

Note: By ObjecTime convention, `S' denotes a single-threaded executable while `T' denotes a multi-threaded executable. For more information about multi-threaded run-time systems see "Threaded phase" on page 15.

1.2.2 Choose a libset name

For more information, see "Libset name" on page 33.

1.2.3 Determine the platform name

For more information, see "Choose a platform name" on page 31.

1.3 Create directories

1.4 Create and edit Perl scripts

1.4.1 Create an environment variable setup script

For more information, see "Create a setup script" on page 33.

1.4.2 Make copies of Perl scripts

If the compiler does not have options that correspond to the regular -L and -l options, it will probably be necessary to copy and then modify ld.pl from %RTS_HOME%\libset\x86-VisualC++-5.0 to %RTS_HOME%\libset\<LibsetName>.

In addition, if your system does not provide a suitable ar command copy ar.pl from %RTS_HOME%\tools to %RTS_HOME%\libset\<LibsetName> and modify as necessary.

1.5 Create and edit makefiles

For more information, see "TargetRTS makefiles" on page 34.

1.5.1 Create the config makefile

For more information, see "Config makefile" on page 39.

1.5.2 Create the libset makefile

For more information, see "Libset makefile" on page 39.

1.5.3 Create the target makefile

For more information, see "Target makefile" on page 38.

1.6 Create and edit C source and header files

1.6.1 Create RTTarget.h

For the simple model execution phase, disable Multi-threading (RSLMULTITHREADED), Target Observability (RSLTO) and Debugging (RSLDEBUG).

1.6.2 Creating platform-specific source files

If there is a need to override a portion of the standard code for the port, contained in the $RTS_HOME/src directory, copy the file that you want to override to the corresponding directory in $RTS_HOME/src/target.

For example:

On Unix:

$RTS_HOME/src/target/<TargetBaseName>/MAIN/main.c

overrides

$RTS_HOME/src/MAIN/main.c

Then when the compilation of the libraries is performed, the Perl scripts will choose the target specific source file rather than the standard source file.

1.6.3 Creating platform-specific include files

To override include files, such as RT_Time.h, contained in the $RTS_HOME/src/include directory, copy them to $RTS_HOME/src/target/<TargetBaseName> and then modify them.

1.7 Compile the TargetRTS for your target

1.8 Compile and run the C_HelloWorld model for your target

1.8.1 Activate C_HelloWorld within ObjecTime

1. Start an ObjecTime session. Do NOT Enable Target Observability.
2. Open the Workspace Browser.
3. Open a Directory Browser on %OBJECTIME_HOME%\ModelExamples\C.
4. Drag C_HelloWorld.update from the Directory Browser to the Workspace Browser.
5. Open a Model Browser on C_HelloWorld.

1.8.2 Create a new configuration

1.8.3 Edit the threads configuration

1. Right-click on the Update menu in the Model Browser. Select Open Threads Browser.
2. Activate the SingleThread threads configuration.
3. Close the Threads Browser.

1.8.4 Compile and run

1. Compile the HelloST actor. This will create an executable %PWD%\C_HelloWorld\build\<TargetName>_config\HelloST.exe.
2. Run the model on the target using the same approach that you used in step 1.1.4 when you compiled and ran hello.c on the target.
3. Confirm that it ran correctly by observing the output in the target console window. The output should look like:

   C_HelloWorld-v1.0-OT5.2x-started:

   Hello World

   C_HelloWorld v1.0-OT5.2x-finished!

   Compilation of the update is usually performed by compiling an actor in the ObjecTime toolset; however, an update can also be compiled from the $UPDATE_DIR by issuing the make command.

   The sections that follow provide detail on additional procedures to create threaded executables, as well as more complex areas such as debugging, target observability, compiler/linker error parsing and timers.

   Note: Perl needs to be installed or the use of Perl disabled to avoid compilation failure in this simple model execution phase. For more information, please refer to section "If the compilation platform does not have Perl" on page 165.

2.0 Debug phase

2.1 Modify $RTS_HOME\target\<TargetName>\RTTarget.h

2.2 Debug run-time testing

3.0 Target Observability phase

3.1 Modify $RTS_HOME\target\<TargetName>\RTTarget.h

3.2 Target Observability run-time testing

4.0 Threaded phase

4.1 Creating the multi-threaded libraries

Essentially, you will be completing most of the steps from the "Simple model execution phase" on page 3; however, you will be choosing a multi-threaded target. To save time, the steps you need to redo are included below.

4.2 Threaded phase run-time testing

5.0 Porting the error parser phase

The majority of the concepts involved in this section are explained in detail in "Modifying the error parser" on page 91. Using the concepts from that section, you should do the following:

5.1 If the compilation platform does not have Perl

If the compilation platform does not have Perl, the following solutions are available:

5.1.1 Short-term solutions

(Both the following solutions disable the use of Perl for the compilation phase, and consequently, error parsing. You will, however, be able to compile without getting a fatal error indicating Perl is not present.)

Solution 1: Make use of a make overrides file, as described in the chapter "Makefiles" in the C Language Guide. Set the following variables to nil within that file:

• OTCOMPILE_CMD =
• OTLINK_CMD =

  Solution 2: Modify the $RTS_HOME/target/<TargetName>/target.mk file to set the following variables to nil:

• OTCOMPILE_CMD =
• OTLINK_CMD =

5.1.2 Long Term Solution

Download and compile Perl for the compilation platform.

6.0 Porting timers phase

The majority of the concepts involved in this section are explained in "Implementing timer services in the C TargetRTS" on page 77.

Using the concepts from this section, you should decide what type of timers you want to implement— local timers or actor timers. It is suggested that for RTOS applications, local timers be used; otherwise, actor timers can be used.

6.1 Local timers

6.1.1 Integrated timers

6.1.2 Integrated IPC and timers

6.2 Actor timers