IBM
Contents Index Previous Next



A Simple Example


This section describes an example system named Simple. The annexes show how to integrate the example with different operating systems.

The example demonstrates the following techniques:

The Simple System

Figure 573 : System Simple

The SDL representation of Simple consists of a single block Bl1. Seen from the outside, the system accepts the signal Go and responds after about five seconds by sending the signal Ok. The signal Go may be sent twice to the system.

Block Bl1

Figure 574 : Block Bl1

Block Bl1 has two processes. The static process Pr1 and the dynamic process DynPr1. DynPr1 is created by Pr1 and can send the signal Terminating back to its parent. Pr1 handles all the interaction with the environment, through the signals Go and Ok.

Process Pr1

Figure 575 : Process Pr1

Process Pr1 is a static process with two instances. It has two states, Idle and Wait. In the Idle state the process waits for the signal Go with an integer parameter representing the instance number of this instance. It then prints the instance number to the standard output, creates one instance of DynPr1 and enters the Wait state. In the Wait state it waits for the signal Terminating from the created instance of DynPr1, sends Ok back to the environment and goes back into the Wait state. Since the Terminating signal will only be received once, the process is going to remain in the Wait state forever.

Process DynPr1

Figure 576 : Process DynPr1

The dynamic process DynPr1 has no instances at system start and a maximum of two instances. Each instance of Pr1 creates one instance of DynPr1. DynPr1 sets the timer t1 to five seconds, waits for a timeout, sends the signal Terminating to its creator and finally terminates.

Connection to the Environment

The environment is handled in different ways depending on the integration model. See below for details.

Building and Running a Light Integration

This section will take you through the general steps required to build a Light Integration for the Simple example. The procedure works the same for most operating systems. Please also check the annexes for important information about your operating system.

Note:

The source file and examples for RTOS Integrations are not included in the standard delivery. They are available as free downloads from IBM Rational Support web site.

General Steps for a Light Integration

  1. Use the Simple example from <installationdir>/sdt/examples/simple or .../RTOS/TightIntegrations/Examples/Simple.
  2. Create a working directory target and an include directory below it.
  3. Copy all files from .../RTOS/TightIntegrations/Examples/Simple/<selected OS>/LightIntegration to the working directory target (sctenv.c and Makefile).
  4. Copy the following files to the target/include directory:
    $(sdtdir)/INCLUDE/sctlocal.h
    $(sdtdir)/INCLUDE/sctpred.c
    $(sdtdir)/INCLUDE/sctsdl.c
    $(sdtdir)/INCLUDE/sctos.c
    $(sdtdir)/INCLUDE/sctpred.h
    $(sdtdir)/INCLUDE/scttypes.h
  5. Open the system file simple.sdt
  6. Select Set Directories from the File menu and change the target directory to target.
  7. If you used the names of folders mentioned above, you do not need to edit the Makefile supplied with the example (for example, MicrosoftMakefile).
  8. Select the system in the Organizer view, open the Make dialog by choosing Generate -> Make... , select the Cadvanced code generator, set options Lower Case and Generate environment header file, set Analyze & generate code, set Makefile, choose Use makefile and point to the makefile corresponding to your environment (for example, MicrosoftMakefile), set Compile & link and Use standard Application kernel (for example, Microsoft Application).
  9. Click Full make to build an executable.
  10. Download the executable to target or run it under a kernel simulator ("soft kernel").

Result From Running the System

The output when running the example should be:

Signal Go received in Pr1:Instance1
Signal Go received in Pr1:Instance2
Signal Ok received with the following parameter:1
Signal Ok received with the following parameter:2

The xInEnv Function

This is where the start-up signal Go is sent. In a real system xInEnv may be used for polling hardware devices for data, it should be updated manually according to the system communications. For the Simple example, the xInEnv implementation looks like this:

xSignalNode S;
static int SendGo = 0;

if(SendGo<=1) {
  if(SendGo==0) {
    S = xGetSignal(go,  pr1[1],   xEnv );
    ((yPDef_go *)(S))->Param1 = startinstance1;
  }
  else {
    S = xGetSignal(go,  pr1[2],   xEnv );
    ((yPDef_go *)(S))->Param1 = startinstance2;
  }
  SDL_Output( S, xSigPrioPar(xDefaultPrioSignal)
                (xIdNode *)0 );
  SendGo++;
}

The signal Go is sent the first and the second time xInEnv is called. The parameters startinstance1 and startinstance2 are integer constants defined in the SDL system, as integer SYNONYM's. They are made available by generating and including the file simple.ifc.

The xOutEnv Function

xOutEnv may be used to send signals to hardware devices. It should be updated manually according to the system communications. For the Simple example, the xOutEnv implementation for receiving signal Ok looks like this:

if ( ((*S)->NameNode) == ok ) {
  printf("Signal Ok received with the following
          parameter:%lu\n",
          ((yPDef_ok *)(*S))->Param1);
  xReleaseSignal( S );
  return;
}

The signal Ok also has an integer parameter, the value of this should be 1 if it is sent by Pr1 instance one and 2 if it is sent by instance two.

Building and Running a Tight Integration

This section will take you through the general steps required to build a Tight Integration for the Simple example. The procedure works the same for most operating systems. Please also check the annexes for important information about your operating system.

Note:

The source file and examples for RTOS Integrations are not included in the standard delivery. They are available as free downloads from IBM Rational Support web site.

General Steps for a Tight Integration

  1. Create a working directory and an INCLUDE directory below it.
  2. Copy all files from .../RTOS/TightIntegrations/Examples/Simple/<selected RTOS>/TightIntegration to the working directory.
  3. Copy all files from .../RTOS/TightIntegrations/INCLUDE to the INCLUDE directory.
  4. Open the system file .../RTOS/TightIntegrations/Examples/Simple/simple.sdt
  5. Change the destination directory to your working directory.
  6. Set the options Lower Case, Generate environment header file and Generate signal number file.
  7. Select the Cadvanced SDL to C Compiler and generate an application.
  8. Edit the makefile supplied with the example to fit your environment. Normally you will only have to point out the directory where the RTOS is installed.
  9. Use the makefile to build an executable.
  10. Download the executable to target or run it under a kernel simulator ("soft kernel").

Result From Running the System

The output when running the example depends on what kind of trace has been enabled. If you set XMSC_TRACE it should be similar to the following:

System_Init_Proc: instancehead process Environment;
msc RTOS_Trace;
Pr11: instancehead process Pr1;
Pr12: instancehead process Pr1;
Pr11: condition Idle;
Pr12: condition Idle;
Pr11: in Go,0 from MyExtTask3;
Signal Go received in Pr1:Instance1
dynpr14: instancehead process dynpr1;
Pr11 : create dynpr14;
Pr11: condition Wait;
Pr12: in Go,1 from MyExtTask3;
Signal Go received in Pr1:Instance2
dynpr15: instancehead process dynpr1;
Pr12 : create dynpr15;
Pr12: condition Wait;
dynpr14: set T1,2 (5000); /* #SDTNOW(269) */
dynpr14: condition wait;
dynpr15: set T1,3 (5000); /* #SDTNOW(276) */
dynpr15: condition wait;
dynpr14: timeout  T1,2; /* #SDTNOW(5284) */
dynpr14: out Terminating,4 to Pr11;
dynpr14: endinstance;
Pr11: in Terminating,4 from dynpr14;
Pr11: out Ok,5 to MyExtTask3;
Ok received in MyExtTask with paramer = 1
dynpr15: timeout  T1,3; /* #SDTNOW(5463) */
dynpr15: out Terminating,6 to Pr12;
dynpr15: endinstance;
Pr12: in Terminating,6 from dynpr15;
Pr12: out Ok,7 to MyExtTask3;
Ok received in MyExtTask with paramer = 2

Setting the XOS_TRACE flag should result in the following output:

** Process Pr1:9901455 created **

** Process Pr1:9901456 created **

** Process instance 9901455 **
Pr1: nextstate Idle

** Process instance 9901456 **
Pr1: nextstate Idle

** Process instance 9901455 **
Pr1: input signal Go
Signal Go received in Pr1:Instance1
Pr1: process dynpr1:9901458 created
Pr1: nextstate Wait

** Process instance 9901456 **
Pr1: input signal Go
Signal Go received in Pr1:Instance2

** Process instance 9901458 **

DynPr1: Set timer T1
Process instance 9901459
DynPr1: nextstate wait

** Process instance 9901458 **
DynPr1: input signal T1
DynPr1: signal Terminating sent
DynPr1: stopped

** Process instance 9901455 **
Pr1: input signal Terminating
Pr1: signal Ok sent
Pr1: dash nextstate
Ok received in MyExtTask with parameter = 1

** Process instance 99014516 **
DynPr1: input signal T1
DynPr1: signal Terminating sent
DynPr1: stopped

** Process instance 99014513 **
Pr1: input signal Terminating
Pr1: signal Ok sent
Pr1: dash nextstate
Ok received in MyExtTask with parameter = 2

Standard Model

In the standard model each instance of the Pr1 and the DynPr1 processes will be represented by an OS task (in all four tasks). The environment is represented by a task called MyExtTask. This task is external to the SDL system.

Instance Set Model

In the instance set model there will be two OS tasks, one each for Pr1 and DynPr1. The environment is represented by a task called MyExTask, just as in the standard model. This task is external to the SDL system.

How Signals are Sent to and from the Environment

There is an external task called MyExtTask which is written in C. It sends the signal Go into the SDL system and receives the signal Ok back by using services in the operating system.

The HOOK_MAIN_AFTER_PROCESS_RELEASE macro in scttypes.h is used to create MyExtTask as soon as the SDL system allowed to run.

The source code for the external task is placed in the file MyExtTask.c. This file is specific to the selected operating system because it calls the operating system directly.


http://www.ibm.com/rational
Contents Index Previous Next