Cmicro Targeting Tutorial

This Cmicro tutorial takes you through the first steps of targeting using Cmicro.

Currently this tutorial is designed for using a Borland C++ 5.02 or a Microsoft Visual C++ 5.0 compiler in Windows, and any C++ compiler available on UNIX.

Table of Contents 

• Prerequisites / Abbreviations Used
• Introduction
• Parts of This Tutorial
• The Kind of Integration Used in This Tutorial
• Prerequisites to the First Example
• The AccessControl System
• Delivered Files
• Generating the Executable
• Generating Files for the Bodybuilder
• Configuring the Cmicro Library and the Cmicro Tester
• Compiling and Linking the Program
• Use of the Cmicro Tester
• Differences between SDT Simulator and Cmicro Tester
• Restrictions in This Tutorial
• Restriction in the Use of Commands
• Testing the Access System with the Cmicro Tester
• Running the Cmicro Tester
• CmicroTester Commands
• Creating Your Own Target System
• Prerequisites
• The SDL System Calcul
• Template Files
• Configuring with the Bodybuilder
• Generated Files
• Environment Functions (env.c)
• Sending Signals into the SDL System
• Receiving Signals from the System
• Initializing and Closing the Environment
• The System Without Cmicro Tester
• Making of <systemname>.exe
• Execution of the System
• Debugging and Testing the System with the Cmicro Tester
• Prerequisites
• Configure the Target with the Bodybuilder
• Making <systemname>.exe with the Cmicro Tester Extension
• Execution with the Cmicro Tester
• Summary

Prerequisites / Abbreviations Used

It is assumed that Telelogic Tau is already installed on your PC running Windows 95/NT4.0, or on your UNIX workstation running SunOS 5.5 or HP-UX 10.20. This tutorial will not work on any other systems.

Before you run this tutorial, you should be familiar with the SDT tools, especially the Organizer, the Analyzer and the Simulator. If you have not already done so, you are recommended to go through the previous tutorials in this volume.

The following notations and directories concern the rest of this tutorial:

• <TAUinstallation> denotes the Telelogic Tau installation directory, which is called <systemdrive>:\tau35 in Windows and $telelogic on UNIX.
• In this tutorial there is a mixed use of the path separation characters `/' and `\', as several steps in Windows and on UNIX only differ in these.
• Although "directories" are called "folders" in Windows, this tutorial always uses the expression "directory".
• You will find this tutorial placed in the directories:
  <TAUinstallation>\sdt\examples\cmicrotutorial\wini386
<TAUinstallation>/sdt/examples/cmicrotutorial/sunos5
<TAUinstallation>/sdt/examples/cmicrotutorial/hppa
• The Cmicro Library can be found in the directories:
  <TAUinstallation>\sdt\sdtdir\wini386\cmicro
<TAUinstallation>/sdt/sdtdir/sunos5sdtdir/cmicro
<TAUinstallation>/sdt/sdtdir/hppasdtdir/cmicro

Introduction

Parts of This Tutorial

In the first part of this tutorial you will generate an already designed system. All configurations have already been done. This part starts with Generating the Executable.

In the second part, you will design a new system, generate it with the SDT Analyzer, configure it with the Cmicro Bodybuilder (including creation of environment functions) and run the target as an application in a command shell. This part starts with Creating Your Own Target System.

The Kind of Integration Used in This Tutorial

Targeting may be implemented using the following methods:

• Bare integration:

The SDL system is running on a bare target, scheduled by the Cmicro Kernel without any other operating system (OS).

• Light integration:

The SDL system (scheduled by the Cmicro Kernel) is running as one task in an OS, possibly using functions of the OS.

• Tight integration:

All the SDL processes (and other tasks) are scheduled by the OS of the target.

The Cmicro Package is mainly designed to work in bare integrations but can be simply adapted to OSs and executed as light integrations.

For tight integrations the effort depends on the operating system in use.

In this tutorial you will be doing a light integration as the target executable is executed as independent OS tasks, where the SDL processes are scheduled by the Cmicro Kernel.

Prerequisites to the First Example

The AccessControl System

The SDL system that will be used for the first part of this tutorial is an AccessControl System that controls four doors. An administrator has got a master card and uses this card to register cards along with an associated PIN (Personal Identity Number).

To register a card, the administrator inserts his card via the control panel and enters the PIN 0 0 0 0. Now the user can insert his own card and enter a private PIN. The users card and PIN are then registered and it is allowed to open one of the four doors.

The SDL Overview shows the access system divided into blocks and processes.

Figure 272 : An overview of the system Access

Process	Description
DoorMonitor	The DoorMonitor process starts the DoorController process instances when the controller wants to allocate a door.
DoorController	Any instance of the DoorController controls one door.
PanelControl	The PanelController is an interface between the access system and the user, who wants to open a door. It displays messages via a display and performs any message from the card reader and the keyboard.
Controller	The process Controller controls the doors and user interface and establishes a link to the database represented by the Central.
Central	The Central is the database of the system containing all card information. If a user inserts a card the card information will be registered by the database.

Delivered Files

The files needed for the first part of this tutorial can be found in the following directories:

• In Windows: <TAUinstallation>\sdt\examples\
cmicrotutorial\wini386\door_acc
• On UNIX: <TAUinstallation>/sdt/examples/
cmicrotutorial/sunos5/door_acc (for SunOS 5), or <TAUinstallation>/sdt/examples/cmicrotutorial/hppa/
door_acc (for HP-UX).

The project directory door_acc is divided into directories called system and target. The directory system contains the SDL-GR files of the Access Control system. The files located in the target directory are listed below.

Filename	Description
mk_stim.c	Timer implementation
mk_user.c	Errorhandler, watchdog
mk_cpu.c	Memory management, interface to an external environment
env.c	Environment functions
dl.c	Physical layer of the access.exe
mpm_con.c	Connection to the Cmicro Postmaster
sdtmt.btm	Button file for the Cmicro Tester

Special Files in Windows

To generate an executable in Windows you need following files, located in the make_bc and make_cl directory of the cmicrotutorial\wini386 directory, for the Borland C++ and the Microsoft Visual C++ compiler.

File	Description
make.opt	Configuration for the project (Cmicro path, compiler flags)
comp.opt	make template for the generator

Special Files on UNIX

File	Description
makeoptions	Configuration for the project (Cmicro path, compiler flags)

Generating the Executable

You will now generate an executable for the already designed Access Control system.

1. Make a new empty directory cmicrotutorial in your home directory or on your local hard disk. This directory will be denoted by <MyTutorial> in the following.
2. Copy the directory <TAUinstallation>/sdt/examples/
cmicrotutorial/<platform>/door_acc (including all files and subdirectories) to your new <MyTutorial> directory and remove any write protections.
3. In Windows, if you use the Borland C++ compiler, copy make.opt and comp.opt from the directory <TAUinstallation>\sdt\
examples\cmicrotutorial\wini386\make_bc into your target directory.

If you use the Microsoft C++ compiler, you have to copy these files from the <TAUinstallation>\sdt\examples\
cmicrotutorial\wini386\make_cl directory into your target directory.

4. In the Organizer, open the Access Control system found in<MyTutorial>/door_acc/system.

The following steps are necessary to ensure that the tutorial works properly.

Generating Files for the Bodybuilder

The Cmicro Bodybuilder needs the files access.sym, access.ifc and sdl_cfg.h (generated by the Cmicro Code Generator) to configure the Cmicro Library. To generate these files, do as follows:

1. Select Make in the Generate menu of the Organizer.

The Make dialog will be issued.

2. In the dialog, make the following settings:
• Code Generator: Cmicro. This is because you are doing Cmicro targeting
• Prefix: Full. This attaches the prefix to all the files of the SDT system.
• Separation: No. This will only generate one C file, access.c
• Capitalization: As defined. Whatever way you declared your variables is the way the compiler treats them.
• Make sure that the Target directory path is set to <MyTutorial>/door_acc/target.
• Select Generate makefile and Use kernel in directory.

You have to select the Use kernel in directory path <MyTutorial>/door_acc/target because you have to use the comp.opt file from the target directory of your example system.

• De-select the toggle buttons Makefile and Compile & link.
3. When this is all done, click on the Full Make button.

When the make process has finished, you will have the files necessary to configure the Cmicro Library and the Cmicro Tester.

Configuring the Cmicro Library and the Cmicro Tester

1. Start the Cmicro Bodybuilder from the Generate menu in the Organizer.
2. In the Bodybuilder, click on the Host box and then select Gate Selection. Modify the path to the following (you cannot use the Browse button, because no gateway has been built yet):
   <MyTutorial>\door_acc\target\access.exe (in Windows), or <MyTutorial>/door_acc/target/access (on UNIX).
3. Click on Message Coding and modify the values, which are described in Configuring the Host with the Bodybuilder. Follow the instructions in that section and then continue with the next step below.
4. Leave the Host box and go to the Compiler box. In the Compiler box you have to select the compiler (e.g. Microsoft C++).
5. Select Save from the File menu. You can now exit the Cmicro Bodybuilder. All other modifications are already done for this example.

Compiling and Linking the Program

Before you compile your system you have to modify the file make.opt (in Windows) or makeoptions (on UNIX).

1. Edit the file make.opt or makeoptions if not already done.

On UNIX, you have to select the sctLDFLAGS for your hosttype. Also modify the macro sctLINKKERNEL to use sctLINKTARGET_WITH_TESTER.

Note:  Make sure that you are using a C++ compiler because you are linking C++ objects from the Cmicro Postmaster Library.

In Windows, you have to modify the macros COMPILER_DIR and CMICRO_DIR in the file make.opt. Also modify the macro sctLINKKERNEL to use sctLINKTARGET_WITH_TESTER.

Note:  Make sure that you can use your compiler with an external tool like the Telelogic Tau package (binaries, include path, lib path, etc. of your compiler may need to be added to your environment).

2. Next you have to select Make again in the Organizer, and this time you will actually compile and link the program. All that you need to modify from the last time is to select the Makefile and Compile & Link toggle buttons. When this has completed, you will have created a file access.exe in Windows, or access on UNIX, respectively.

Figure 273 summarizes the settings to use in this step.

Figure 273  : The Telelogic SDL Make Dialog

Caution!  The executable you will get following the steps described above is a Cmicro target executable for use in combination with the SDT Cmicro Tester only. It cannot be started directly from the command line (see the following sections).

Use of the Cmicro Tester

Differences between SDT Simulator and Cmicro Tester

The difference compared to the SDT Simulator is that the generated SDL system is running on a target hardware and is sending messages to the host system on which the SDT Cmicro Tester's host part is running.

In this Cmicro tutorial, the SDT Cmicro Tester's host part is running on the host as well as the generated SDL system (target). Therefore, from the host's point of view, the target is running as a gateway (to be able to establish a communications link to the Cmicro Tester's host part via the Cmicro Postmaster).

Figure 274 : Communication links between the processes

Restrictions in This Tutorial

It is possible to use all the features supported by Cmicro (e.g. signal priorities, error checks, tester) except the preemptive Cmicro Kernel. This is due to the concept behind Cmicro which is designed for small targets on a stand-alone hardware (bare integration).

Restriction in the Use of Commands

There are a few Cmicro Tester commands which make no sense for a light integration:

• shutdown: This command simply exits the target. On small embedded systems this is used to exit and restart the target executable. There will be no reason to exit the target executable used here in this way.
• reinit: The first idea is to re-initialize the target systems. But to work correctly it is necessary to have a separation between RAM and ROM memory. This means that on small embedded systems the program code is stored in the ROM and copied into the RAM and not duplicated during start-up time.

Note:  The Cmicro Tester is intentionally designed for testing a hardware connected to a host machine.

Testing the Access System with the Cmicro Tester

Running the Cmicro Tester

The Cmicro Tester has a user interface similar to the SDT Simulator. You are assumed to be familiar with this user interface. For more information, see Tutorial: The SDT Simulator.

• On UNIX: Start the Cmicro Tester in your target directory with the command sdtmtui. You have to start the Cmicro Tester in a shell because your target sends and receives messages from this console.

In Windows: Start the Cmicro Tester from the Organizer menu choice SDL > Cmicro Tester in the Tools menu. A DOS window for your target will be opened.

The Cmicro Tester is forking the target access or access.exe in the directory you selected in the Bodybuilder's Host box. Now you can test the access system.

1. Start the communication with the access or access.exe by pushing the button Start-Com in the Access Control group or in the Communication group.
2. Now the system on the target is idle. The Cmicro Tester displays the message Start with "Go Forever". The appropriate button is located in the Execute group.
3. On UNIX, all messages from the target are displayed on the console from where your tester was started. In Windows, all messages are displayed in a DOS window. You can send the message card with the keys a, b, c, d and numbers with the keys 0 - 9.
4. The Access Control displays the message "Insert card". After starting the access system, the control system database is empty. The system only knows the administrator, who has the permission to deliver access codes. Insert a card by entering a letter and then the administrator PIN 0 0 0 0.
5. The access control displays the message "Register card". Now the user who wants to get the access puts his card in the card reader by typing a letter. Afterwards he can insert his own PIN and select a door. The user will then be registered in the system's database.

CmicroTester Commands

The Cmicro Tester has button groups. Each button represents a Tester command. You can use the buttons to enter a command or the command line at the bottom of the Tester. If you enter help in the command line you will see a list of Cmicro Tester commands.

In the following some Tester commands are explained briefly. For more information, see The Cmicro Tester.

Tracing the SDL System With the Cmicro Tester and MSC Editor

Similar to the SDT Simulator GUI it is possible to generate MSC traces while testing the system with the Cmicro Tester.

• In the Trace group you can select the Start MSC button, for example, to start the MSC trace.
• Now you can select between output via display or output to a file. If you select output via display the trace can slow down the target because it takes time to draw the MSC. A faster way is to write the MSC trace into a file. After the test phase you can load the file in the MSC Editor.

Tracing the SDL System With the Cmicro Tester and SDL Editor

It is possible to trace the target system with the SDL Editor.

• You can start the trace with the command line of the Cmicro Tester by typing start-sdle, or by using the button Start SDLE.

The MSC trace and SDL trace functions are powerful tools for understanding the system.

Target Information

To get more information about target configuration, you must open the Configuration Group in the button area of the Cmicro Tester. Now you can press Target to get the current target configuration.

To get information about the kernel, you have to open the View group. If you press Queue you will get information about the current state of the internal queue of your system. You will see the peek hold and the amount of signals of your current system. By pressing the other buttons in the View group, you will get more information of the running system.

Breakpoints

To debug the system you can use the Breakpoints button group. You can set a breakpoint on a signal input or a process state. If a breakpoint was reached you can continue the system with the button Continue.

Systemcontrol

In the Systemcontrol group it is possible to test the system with single steps. To switch into single step mode use Single-Step; to exit this mode use Exit-Single-Step.

Creating Your Own Target System

In the second part of this tutorial, you will now design a new system, generate it with the SDT Analyzer, configure it with the Cmicro Bodybuilder (inclusive creation of environment functions) and run the target as an application in a command shell.

Prerequisites

When you start a new project, it is recommended to keep the SDL files and the generated files in separate directories.

Thus the following scenario shows how a typical project might be partitioned.

Figure 275 : Directory structure

The SDL system should be stored in <My_SDL_System>, and the generated system in the directory <My_Cmicro_Target>.

Caution!  If you use DOS to compile your target program you should use file names which fit to the 8.3 convention, since only Windows 95/NT and UNIX are supporting long file names. Long file names can cause errors while compiling your program within a DOS environment.

Note:  For any Cmicro project you have to create a new directory, because some tools create files (e.g. sdl_cfg.h and env.c) which have the same name for all SDL systems.

Now you can design a new SDL system or take an already created and tested system.

In the following sections the way of targeting a delivered system is described, as it is sometimes necessary to have references to some signal names in the explanation. The directories <My_SDL_System> and <My_Cmicro_Target> will be named system and target, and <My_Cmicro_Project> will be named calcul.

The calculator example may be found in the following directories:

<TAUinstallation>\sdt\examples\cmicrotutorial\wini386
<TAUinstallation>/sdt/examples/cmicrotutorial/hppa
<TAUinstallation>/sdt/examples/cmicrotutorial/sunos5

Hint:  When using timers in Cmicro, timers are often realized as an interrupt service routine, i.e. one timer tick can take any value which is possible. So the SDL command "set(NOW+5,TIMER)" lets the timer TIMER expire after 5 ticks. Please view the timer implementation in mk_stim.c. In this tutorial one timer tick is one second.

Note:  Timers are differently realized within the SDT Simulator where timers always have ticks of one second.

The SDL System Calcul

This section uses the supplied SDL Calcul system to show you how to create your own target system.

Figure 276 : System view of Calcul

The simple calculator given receives two integer values (0, 1, 2,...9). The user can then apply common mathematical functions such as addition, subtraction, etc. to these integer values.

1. Copy the directory <TAUinstallation>/sdt/examples/
cmicrotutorial/<hosttype>/calcul (including all files and subdirectories) to your <MyTutorial> directory.
2. Using the Telelogic Tau Organizer, open the Calcul system found in <MyTutorial>/calcul/system, and take a little time to become familiar with it. When the design is finished the system can be simulated using the SDT Simulator to debug the system and ensure that all the logic is correct and does what it sets out to do.

When the debugging is done you can start the targeting with the Cmicro Package.

3. Open the Make dialog in the Organizer.

Figure 277  : Make dialog to generate a Cmicro system

To generate the system you must:

1. Select Analyze & generate code
• Code generator: Cmicro
• Prefix: Full
• Separation: No
• Capitalization: As defined
2. Select Generate makefile and Use kernel in directory.
3. Make sure that the Target directory path and the Use kernel in directory path are set to <MyTutorial>/calcul/target.
4. De-select the toggle buttons Makefile and Compile & link
5. Click Full Make.

The C Code Generator generates the system.

Note:  If the message "Max number of instances must be specified" is printed in the Organizer Log, you have to look into your blocks and correct your process names with <processname>(x,y). The maximum number of instances of a process must specified in Cmicro to generate an optimized code. Please view the section SDL Restrictions to get a feeling about the SDL restrictions concerning Cmicro.

The Cmicro Code Generator creates the files <systemname>.c, <systemname>.ifc and sdl_cfg.h for compiling the system. In this case, the <systemname> will be calcul.

Filename	Description
<systemname>.c	This file describes the SDL system with C functions.
<systemname>.ifc	This file is a header file for the environment functions
<systemname>.sym	The .sym file is a file for the Cmicro Tester to locate SDL symbols for tracing the SDL system.
sdl_cfg.h	This file is the automatic configuration for the Cmicro Kernel. For example, if you use timers the file will include a define, which turns the timer implementation on.

Template Files

• You now have to copy some template files from the directory



<TAUinstallation>\sdt\sdtdir\wini386\cmicro\template
<TAUinstallation>/sdt/sdtdir/sunos5sdtdir/cmicro/template
<TAUinstallation>/sdt/sdtdir/hppasdtdir/cmicro/template

(depending on your platform) into the <MyTutorial>\calcul\
target directory. The files that need to be copied are listed below.

Filename	Description
mk_cpu.c	This module is a template for functions, which are to be filled up by the user of the Cmicro Kernel in some cases. Character read / write on hardware / OS-level Functions for dynamic memory handling.
mk_stim.c	This module exports all necessary functions to represent the hardware layer of timers.
mk_user.c	This module includes Functions for central error handling Functions for the Cmicro Kernel (optional in order to optimize) Functions to trigger a hardware-Watchdog
dl.c	This module represents the data link of the communication interface (which is normally a serial interface like V.24).

Note:  The template of the environment functions (signals from and to the SDL system) will be created by the Cmicro Bodybuilder (please see Configuring with the Bodybuilder). If you are creating a new system running on a microcontroller you have also to copy the template file make.opt or makeoptions into your target directory. The file make.opt or makeoptions is already adapted as this tutorial is still based on a light integration.

Configuring with the Bodybuilder

After generating the C code you have to configure the Cmicro target. The best way is to use the Cmicro Bodybuilder. With the Bodybuilder you can scale your target, configure your communications link to your host and select your C-compiler.

1. Start the Bodybuilder.

(For more information, see Configuring the Cmicro Library and the Cmicro Tester.)

2. Open the log window of the Bodybuilder. Here the Bodybuilder reports errors and operations.
3. In the tool bar of the Bodybuilder you will see a button with a check mark. Click this button.
4. The Bodybuilder shows you a box, informing you about the configuration of your files.
5. Click on Target Kernel. Now you see the Kernel options and a help text.
6. Click on Cmicro Kernel > Kernel. Now you can scale your Cmicro Kernel.
7. In this tutorial, only the button Initialize Variables has to be selected, which leads to a



#define XMK_USE_KERNEL_INIT

in ml_mcf.h.

8. Open the environment configuration by clicking Environment > Target Environment
9. In this box you have to select Standard IO library, because all your signals are received from the stdin and sent to the stdout.
10. Click on the OK button.
11. The last step is to select the C Compiler. You need a C compiler to compile a program. There is no default compiler selected so you must select the compiler yourself. For this tutorial select an appropriate Windows or UNIX compiler.
12. Now you can save the options with File > Save.
13. You have to generate the environment file with File > Generate "env.c"
14. Exit the Bodybuilder with File > Exit.

Generated Files

The Bodybuilder generates three files which have different meanings.

File	Description
env.c	This module includes the environment functions. The environment functions must be filled up by the user.
ml_mcf.h	This header file includes the options for the Cmicro target. All option are set by #define XMK... directives. The ml_mcf.h file is the manual configuration file and the sdl_cfg.h the automatic configuration file for the Cmicro Kernel
sdtmt.opt	This is an option file for the Cmicro Tester. This settings are made in the host section of the Cmicro Bodybuilder.

Environment Functions (env.c)

In this section you will learn how to fill in the environment functions in env.c.

• Open the file env.c with an ASCII editor (e.g. the Borland Editor or vi), and edit according to the information in this section.

In the example system calcul you send the signals

signal plus,sub,mult,div;
signal value(natural);

to the system.

And you receive the signals

signal result(natural);
signal message(natural);

from the system.

Caution!  When using the file env.c it is allowed to edit only between the lines /* BEGIN User Code */ /* END User Code */ When the Bodybuilder is started for the second time, it will create a new file env.c (e.g. when creating new signals in the system or other changes), if you select Generate "env.c". Only the lines between these labels are unchanged by the Bodybuilder. Do not remove, modify or insert any lines with the text /* BEGIN User Code */ /* END User Code */

Sending Signals into the SDL System

The function xInEnv() will be polled by the Cmicro Kernel and asks the environment for events which causes the sending of environment signals.

Caution!  As the environment is polled with every cycle of the Cmicro Kernel it is not allowed to use blocking functions here.

Blocking and Unblocking Functions

/* BEGIN User Code (variable section)*/
  char my_inkey;
  int  my_value;
  getchar("%d",&my_inkey);
  /*
  ** getchar is a blocking read function for one character
  ** from the keyboard, a function of <stdio.h>
  */
  my_value = ((int)my_inkey)-((int)'0');

/* END User Code (variable section)*/

You can see that the getchar() function blocks the kernel because it waits until someone presses a key on the keyboard. The Kernel stops and cannot receive or send any other signals, and cannot process the SDL system.

The right way is to use non-blocking functions. Example 8 is fitted to UNIX and Windows compilers. _GCC_ is the switch for the UNIX compiler and BORLAND_Cor MICROSOFT_C for a Windows compiler.

 XMK_SEND_TMP_VARS
   /* BEGIN User Code (variable section)*/
   /* It is possible to define some variables here      */
   /* or to insert a functionality which must be polled */ 
   #define key_was_pressed 1
   #define key_not_pressed 0
   char my_inkey;
   int  my_value;
   int  key_pressed = key_not_pressed;
   #if defined(_GCC_)
     static char c;
   #endif
   #if defined(_GCC_)
     key_pressed = read ( STDIN_FILENO , (void *) &c, 1 );
     if (key_pressed>0)
     {

       my_inkey=((char) c);
       key_pressed=key_was_pressed;
     }
   #elif defined(BORLAND_C) || defined(MICROSOFT_C)
     if (kbhit())
     {
       my_inkey=_getch();
       key_pressed=key_was_pressed;
       printf("%c\n",my_inkey);
     }
   #endif
   my_value = ((int)my_inkey)-((int)'0');

Signals with Parameters

Now you have to define the receiving process and fill up the parameters of your signals.

You will find a part in your env.c listing like this:

01: /* BEGIN User Code */
02: if (i_have_to_send_signal_value)
03: /*   END User Code */
04: {
05:   yPDef_value var;
06: /* BEGIN User Code */
07:   /* It is possible to insert any user code here. */
08: /*   END User Code */
09:   XMK_SEND_ENV( ENV,
10:                 value,
11:                  xDefaultPrioSignal,
12:                  sizeof( yPDef_value ),
13:                  &var,
14:  /* BEGIN User Code */
15:                       GLOBALPID(Who_should_receive_signal_value,0));
16:  /*   END User Code */
17:    return;
18:  }

You have to change the text in the lines 02 and 15 and you have to insert code between line 06 and 08.

In the Calcul system you have to change (line 02)

if (i_have_to_send_signal_value)

into

if (('0'<=my_inkey)&&(my_inkey<='9'))

This is the condition when you have to send the specific signal. Here you send only a value so you have to filter only numeric characters.

After that you have to adapt the signal parameters. So you have to insert

var.Param1 = my_value;

between line 07 and 08.

For instance, if you have defined a signal in your SDL system like this:

Signal a(natural,natural,natural)

then you can reach the parameters via var.Param1, var.Param2 and var.Param3.

Hint:  If you want to see the structure of your signal parameters, please view the file <systemname>.ifc.

Finally you have to modify line 15:

GLOBALPID(Who_should_receive_signal_value,0));

In this line the receiver process PID must be inserted. The symbolic name of the PID can be found in the file sdl_cfg.h.

 /* "sdl_cfg.h" file generated for system Calcul */
#define XMK_CFG_TIME 874509481
#define XPTID_alu 0
#define MAX_SDL_PROCESS_TYPES 1
#define XMK_USED_ONLY_X_1
#define MAX_SDL_TIMER_TYPES 0
#define MAX_SDL_TIMER_INSTS 0
#define XMK_HIGHEST_SIGNAL_NR 7
/* NOT #define XMK_USED_TIMER */
/* NOT #define XMK_USED_DYNAMIC_CREATE */
/* NOT #define XMK_USED_DYNAMIC_STOP */
/* NOT #define XMK_USED_SAVE */
#define XMK_USED_SIGNAL_WITH_PARAMS
/* NOT #define XMK_USED_TIMER_WITH_PARAMS */
/* NOT #define XMK_USED_SENDER */
/* NOT #define XMK_USED_OFFSPRING */
/* NOT #define XMK_USED_PARENT */
/* NOT #define XMK_USED_SELF */
/* NOT #define XMK_USED_PWOS */
/* NOT #define XMK_USED_INITFUNC */

The PID of the process alu is now defined as XPTID_alu. So you can modify the line 15 as follows:

GLOBALPID(XPTID_alu,0));

Now the listing env.c is ready for sending the value message with parameters.

Sending Signals without Parameters

In this unit you have to modify a signal that does not include any parameters.

In the env.c file you will find code like this:

01:  /* BEGIN User Code */
02:  if (i_have_to_send_signal_plus)
03:  /*   END User Code */
04:  {
05:  /* BEGIN User Code */
06:    /* It is possible to insert any user code here. */
07:  /*   END User Code */
08:    XMK_SEND_ENV( ENV,
09:                  plus,
10:                  xDefaultPrioSignal,
11:                  0,
12:                  NULL,
13:  /* BEGIN User Code */
14:                  GLOBALPID(Who_should_receive_signal_plus,0));
15:  /*   END User Code */
16:    return;
17:  }

Here you have to modify only the line 02 into

if (my_inkey=='+')

and line 14 into

GLOBALPID(XPTID_alu,0));

The same steps must be done for the signals sub, mult and div, where sub, mul and div are represented by the symbols `-', `*' and `/', respectively.

Receiving Signals from the System

In this section you will learn how to describe the behavior of the environment when the SDL system sends a signal.

Let us look at the env.c listing again. Please locate the code looking like this:

   switch (xmk_TmpSignalID)
       {
        case message :
   [...]
01:     case result :
02:          {
03:           /* BEGIN User Code */
04:             /* Use (yPDef_result*)xmk_TmpDataPtr to access the signal's
                  parameters */
05:           /* ATTENTION: the data needs to be copied. Otherwise it */
06:           /*            will be lost when leaving xOutEnv */
07:           /* Do your environment actions here. */
08:            xmk_result = XMK_TRUE; /* to tell the caller that */
09:                                   /* signal is consumed      */
10:           /*   END User Code */
11:          }

Between line 03 and 08 the behavior of the environment when receiving the signal result can be described.

You can get the data from the signal's parameters by using

((yPDef_result*)xmk_TmpDataPtr)->Param1

This information can be found in line 04. Similar to when sending signals, other signal data can be reached by using Param2, Param3, and so on.

Now you can print the calculated result by inserting the following lines between lines 03 and 08:

int my_i;
my_i = (((yPDef_result*)xmk_TmpDataPtr)->Param1);
printf("\nResult           : = %d\n", my_i);

The next step is to implement the behavior for the signal message. Find the place where the first three lines of Example 13 below appear in the env.c file and insert the remaining code at that position.

case message :     
     {
       /* BEGIN User Code */
       switch (((yPDef_message*)xmk_TmpDataPtr)->Param1)
       {
         case command:
              {
                printf("\nCommand(+,-,*,/,): ");
                break;
              }
         case first_value:
              {
                printf("\nFirst_value      : ");
                break;
              }
         case second_value:
              {
                printf("\nSecond_value     : ");
                break;
              }
         case ui_ready:
              {
                printf("\nCalculator Ready\n");
                break;
              }
         case ui_error:
              {
                printf("\n\nCALCULATOR ERROR !\n\n");
                break;
              }
         default:
              {
                printf("\nUnknown Message !!!\n");
                break;
              }
            }
            xmk_result = XMK_TRUE; /*to tell the caller that*/
                                   /*signal is consumed     */
            /*   END User Code */
          }
          break ;

In Example 13 you can see your literals defined in the SDL system (e.g. the synonym command). These literals will be defined in the file <systemname>.ifc.

Initializing and Closing the Environment

In your target there is no need to initialize or to close the environment. In other cases, e.g. microprocessor set ports, timers and so on, you will be required to do so.

In the file env.c, find the part in the function xInitEnv() of the listing looking like this:

void xInitEnv(void)
{
  /* BEGIN User Code */
  /* Initialize your environment here */
  /*   END User Code */
}

You can modify this part as follows. You insert only a message and disable the assignment.

void xInitEnv(void)
{
  /* BEGIN User Code */
  /* Initialize your environment here */
  printf("Calculator Init\n");
  /*   END User Code */
}

The same procedure must be done when modifying the function xCloseEnv().

The System Without Cmicro Tester

In this section, all the things are described which have to be done when you are not using the Cmicro Tester.

Making of <systemname>.exe

You have to build your executable using a makefile.

Files Used in Windows

The following files are used (by different tools) while making the executable. It is assumed that you have copied the files from the make_bc or make_cl directory.

File	Description
comp.opt	Definition of how to generate the makefile.
make.opt	This file is for the Borland or Microsoft C++ compiler (light integration) and includes compiler options, include paths and dependencies.

These files exist only to generate an executable for Windows. In other cases you have to create your own files, i.e. for target compilers.

Note:  You have two versions of the make.opt file. One version still exist in the template directory and one is in the calcul example. You need the template make.opt from the calcul example when you create your target executable. This file is already fitted for your target. If you compile your system for a microcontroller, you have to modify the make.opt from the template directory. More information about make.opt can be found in The Cmicro Library.

• comp.opt will not be explained here. Please have a look in The Cmicro Library.
• The file make.opt in the target directory must be modified when adapting any other compiler. In this example the comp.opt file was fitted for the Borland C compiler and the Microsoft C compiler. You only have to modify the include paths for Cmicro files and your compiler.
• The Borland and Microsoft maketool are using temporary response files while compiling and linking the executable.

The first compile of the system will be done without the Cmicro Tester. Therefore the make tool must only include the files of the kernel directory of the Cmicro library.

Files Used on UNIX

The following file is used while making the executable on UNIX.

File	Description
makeoptions	This file is fitted for UNIX compilers and includes compiler options, include paths and dependencies.

You can use the default setting compile without tester in the makeoptions file. This means you must not select the sctLINKKERNEL. You have to select the sctLDFLAGS for your host.

Starting Make

1. Open the Organizer's Make dialog.
2. Select Analyze & generate code.
• Code generator: Cmicro
• Prefix: Full
• Separation: No
• Capitalization: As defined
3. Set the target directory to <My_Cmicro_Project>\target.
4. Select Generate Makefile and Compile & link.
5. Set the kernel directory to <My_Cmicro_Project>\target.
6. Start making with Full Make when all settings have been done.

In the calcul example the file calcul.m will be generated. Then the maketool of your compiler with the makefile below will be started.

# makefile for System: calcul

!include make.opt

default: calcul$(sctEXTENSION)

calcul$(sctEXTENSION): \
  calcul$(sctOEXTENSION) \
  $(sctLINKKERNEL)
      $(sctLD) @&&!
$t$(sctLD1FLAGS)  calcul$(sctOEXTENSION) $(sctLINKKERNEL)  $(sctLD2FLAGS) ,calcul$(sctEXTENSION)
!

calcul$(sctOEXTENSION): \
  calcul.c
      $(sctCC) @&&!
      $(sctCPPFLAGS) $(sctCCFLAGS) $(SCTDIR)\calcul.c
!

The make tool starts and generates an executable program. Now you can modify the system, compile and make the system again, and test the system without modifying make files or using other tools again.

Note:  If you are adding environment signals you have to start the Bodybuilder because you must generate a new env.c file. After that you have to modify the environment function in env.c.

Execution of the System

• After compiling the system it is possible to start your <systemname>.exe in Windows or<systemname> on UNIX. Do this directly from a command shell in your target folder.

You should see your created program waiting for an input of a value. Now you can test your system by simply sending signals via the keyboard (type values and the desired operator).

Debugging and Testing the System with the Cmicro Tester

You have the possibility to test and trace the target system with the Cmicro Tester. But before that, some things must be performed.

Prerequisites

The Cmicro Tester provides the option for a communications link via a V.24 interface. These options are available in the Bodybuilder.

However, the target is not running on a small embedded system (like an 8051); it runs on the host machine. Therefore, you have to create a gateway from your SDL system to the Cmicro Tester. All messages needed for debugging and tracing are sent to the Cmicro Postmaster who delivers the messages to the Cmicro Tester.

Therefore you have to compile the files dl.c and mpm_con.c

The file dl.c represents the physical layer. If you use another target system, you have to modify the file dl.c to include functions that are communicating with the serial interface or doing something else. The module mpm_con.c includes functions used by the module dl.c

Note:  The Cmicro Tester was built for testing SDL systems on small embedded systems and not for host systems.

Configure the Target with the Bodybuilder

1. Start the Bodybuilder.
2. Select Use the Cmicro Postmaster in the Communications Link section of the Bodybuilder.
3. Open Target > Tester in the Bodybuilder.

Here you have to configure the Tester options. First you have to configure the Initialization options. You can select all options except the option Add connection to external environment. In the section Target > Tester > Trace you can select all options.

Configuring the Host with the Bodybuilder

The next step is to configure the host which is represented by the Cmicro Tester.

1. Open Host > Gate Selection.
2. You have to define where your gateway is placed. In the example calcul system the gateway is represented by the file calcul.exe or calcul. Insert the path to the gate <My_Cmicro_Projekt>\target\<systemname>.exe or <My_Cmicro_Projekt>/target/<systemname>.

The Cmicro Tester does not know which target hardware your SDL system is running on. So you must describe in the host section of the Bodybuilder how the Cmicro Tester deals with the messages received from the target system.

3. Open the Host > Message Coding in the Bodybuilder menu. You have to configure three sections.
4. In the first section you must define the number of octets of each data type. For example, the host is a PC with an 80x86 processor. That means that the integer value needs 4 octets, or pointers needs 4 octets.
5. The second section is for to configuring the alignment. This means defining how the processor maps the data types in the memory.
6. The last section represents the endian configuration. This means for instance that a 4 byte integer (long)is mapped in the memory as low byte first, high byte last. Therefore you have to insert the integer 41 according to Example 17 below.

Hint:  More information about message coding can be found in the Cmicro Tester's help. See Configuration Possibilities of Sdtmt (sdtmt.opt) for more information.

Data type	Length	Alignment Microsoft (Borland)	Endian
Character	1	8 (8)	1
Short	2	16 (8)	21
Integer	4	32 (8)	41
Long	4	32 (8)	41
Pointer	4	32 (8)	41

This table above shows the complete configuration for this example for an 80x86 Intel processor. The alignment differs for the Borland and Microsoft Compiler.      

Data type	Length	Alignment	Endian
Character	1	8	1
Short	2	16	12
Integer	4	32	14
Long	4	32	14
Pointer	4	32	14

The table above shows the complete configuration for this example for a SPARC processor of a Sun workstation.

Making <systemname>.exe with the Cmicro Tester Extension

After configuring with the Bodybuilder you only have to modify the file make.opt (in Windows) or makeoptions (on UNIX) as follows.

1. You have to set the sctLINKKERNEL to sctLINKTARGET_WITH_TESTER.
2. Finally you use the Make dialog of the Organizer again to make an executable.

Execution with the Cmicro Tester

The Cmicro Tester requires an sdtmt.btn file. This file includes the configuration of the buttons.

1. Copy this file from the directory
• <TAUinstallation>\bin\wini386
• <TAUinstallation>/bin/sunos5bin
• <TAUinstallation>/bin/hppabin
(depending on your used platform) into your <My_Cmicro_Project>\target directory.

Hint:  You can modify the sdtmt.btn file with an ASCII editor or add, modify and remove buttons directly in the Cmicro Tester.

2. Start the Cmicro Tester. The Cmicro Tester tries to fork the gateway executable (calcul).

Figure 278 : Init phase of the Cmicro Tester

3. Now you can start the gateway in the Communication group with the button Start Gateway.
4. The target is ready for configuration and waits for the start signal from the Cmicro Tester. This can be done in the Execution group of the Cmicro Tester with Go Forever.

After this point the target is running and is ready to receive environment signals from the environment or the Cmicro Tester.

You can trace the target with the MSC or the SDL Editor to see your system at work (see also CmicroTester Commands).

Summary

Now you have learned how to build an executable using the tools of Telelogic Tau, Cmicro and your compiler.

Below are all the steps to build a system running on a target summarized.

1. The first step is to build an SDL system. There are some SDL restrictions when using Cmicro; please see SDL Restrictions.
2. Then you have to generate the system for Cmicro.

Note:  If your target compiler is not listed in the manual (see List of Available C Compilers in ml_typ.h), you have to make some adaptations for the Cmicro Library, e.g. timer handling, make, startup, etc.

3. Using the Cmicro Bodybuilder, you can scale the Cmicro Kernel to switch on features or to save memory.
4. Then you have to adapt the environment.

Note:  If you want to test your system without using the environment, you can turn it off with the Bodybuilder.

5. After adding the environment you can compile your system.
6. The last step is to test the system with or without the Cmicro Tester.

This is the way to get a running SDL system with the Cmicro Package.