IBM
Contents Index Previous Next



Using the SDL Target Tester's Host


Introduction

The SDL Target Tester on host site is a tool chain consisting of the parts: GUI (sdtmtui), the logical part (sdtmt), the communications link gateway (sdtgate or sockgate) and the glue between these components the Cmicro Postmaster (sdtmpm). Sometimes, e.g. when the SDL Target Tester uses the MSC Editor, a further tool is executed called Cmicro Link (sdtmlnk).

The SDL Target Tester's host site is the tool, which allows communication with the target via a communications interface (see The Communications Link's Host Site) to read or write to files (sdtmt), display information on the screen (sdtmtui) and/or the MSC Editor. It allows tracing of SDL and system events and has the ability to record and replay events to reproduce error situations.

Host features:

It is important to know that the host works independently from the target. The communication between both is built up automatically by the host if you start to communicate with the target. Thus, the host part of the SDL Target Tester remains the same executable when changing the target hardware! Only some adaptations in the configuration file sdtmt.opt have to be made, see Preparing the Host to Target Communication.

The graphical user interface is described in Graphical User Interface.

Different Ways of Using the SDL Target Tester

The standard method for using the SDL Target Tester is to connect a host with a target machine. A communications link implemented by the user must exist between host and target. The target can be seen as a remote system, where the SDL Target Tester running on the host machine can be considered a controlling unit. This is described in Figure 599.

Figure 599 : SDL Target Tester used for target control

The second way to use the SDL Target Tester is as a front-end for a host simulation. Therefore, a host simulation for the SDL System is built with the Targeting Expert. As described in Figure 600 the Gateway used for connection to the target is replaced by the host simulation.

Figure 600 : SDL Target Tester used for host simulation

Another way to use the host software is to use it purely as a conversion tool. This is of interest if a binary file has been written during earlier sessions with the target. The following picture shows the SDL Target Tester as a conversion tool:

Figure 601 : Sdtmt used for file conversion

Furthermore, by using the commands Output-NPAR and Output-PAR the SDL environment of the target or host simulation can be simulated with the host site.

Preparing the Host to Target Communication

After implementing the parts in the target, which are necessary to have a communication between host and target, the appropriate device on the host site is to be selected. This can be done in the file named

sdtmt.opt.

The Targeting Expert should be used to generate or modify sdtmt.opt (see Configure the Host (Cmicro only)).

The Default Communications Link of Sdtmt

There is a V.24 interface implementation to transfer data between target and host. This is delivered as an additional executable called sdtgate.

The sdtgate default implementation uses the following protocol:

There is also a socket interface implementation to transfer data between target and host. This is delivered as an additional executable called sockgate.

The sockgate default implementation uses the following protocol:

Communication Setup on the Host System

If sdtmt is invoked, it searches for the configuration file sdtmt.opt. This file is mandatory!

Each line beginning with a '#' is treated as a comment.

It contains information on target options such as:

Caution!

The file needs to be updated if another target system is connected, or if you change from a host simulation to your real target.

The file sdtmt.opt should have the following entries in order to configure the communications link:

Note:

The target has to be compiled with the flag XMK_USE_AUTO_MCOD defined

Figure 602 : Target's alignment types

Figure 603 : Definitions of the target's endian

Example 614 : sdtmt.opt

USE_GATE     $(sdtdir)/sdtgate  (on UNIX) 
USE_GATE     $(sdtdir)\sdtgate.exe (in Windows)
GATE_CHAR_PARAM_1    COM2
GATE_CHAR_PARAM_2    0
GATE_CHAR_PARAM_3    0
GATE_INT_PARAM_1     9600
GATE_INT_PARAM_2     0
GATE_INT_PARAM_3     0

UNIT-NAME            sec
UNIT-SCALE           0.001 

USE_AUTO_MCOD        no

LENGTH_CHAR          1
LENGTH_SHORT         2
LENGTH_INT           4
LENGTH_LONG          4
LENGTH_POINTER       4
LENGTH_FLOAT         4
LENGTH_DOUBLE        8
ALIGN_CHAR           8
ALIGN_SHORT         16
ALIGN_INT           32
ALIGN_LONG          32
ALIGN_POINTER       32
ALIGN_FLOAT         32
ALIGN_DOUBLE        32
ENDIAN_CHAR          1
ENDIAN_SHORT        12
ENDIAN_INT          14
ENDIAN_LONG         14
ENDIAN_POINTER      14
ENDIAN_FLOAT        14
ENDIAN_DOUBLE       18

Invoking the SDL Target Tester's Host

Command Line Options of the SDL Target Tester

Option Description

-h

Show a short help on the command line options.

-v

Show the version of the SDL Target Tester without opening it.

-t <targetdir>

Change the working directory to <targetdir>.

Invocation from the Organizer

There are two ways to invoke the SDL Target Tester from the Organizer with the actual project.
First you can use the menu Tools > SDL >Target Tester UI.
The other way is to add the following lines into the file
org-menus.ini. For more information, see The Public Interface.

[MENU]
Name=&Cmicro
[MENUITEM]
ItemName=&Tester
Separator=0
StatusbarText=Start Target Tester
ProprietaryKey=1
AttributeKey=0
Scope=ALWAYS
ConfirmText=
ActionInterpretation=OS_COMMAND
BlockCommand=0
FormattedCommand=sdtmtui -t%v

Note:

Since code generation and compilation for Cmicro is only possible with the Targeting Expert, and the Organizer does not know about the directory where the Targeting Expert generates all files, you will be prompted automatically to enter the right directory.

In host simulation mode, internally, the -s flag is used additionally. The output of the Tester then contains some more helpful information that cannot be given in target debug mode.

Invocation from the Command Line or Desktop

Before using the SDL Target Tester described in the sections below, it is assumed, that a communications link between host and target exists (see Connection of Host and Target), that the target executable has included the SDL Target Tester and that the trace is switched on within the target.

Several files have to be read from the user's current working directory.

On UNIX, the SDL Target Tester's host simply needs to be started from the working (project) directory.

  1. Change the current directory to the project directory (assuming that this directory is ~/cmicro_project).
    cd ~/cmicro_project
  2. Now, type
    sdtmtui

Note:

If the command sdtmtui is not found, the $path variable needs to be set up correctly. The user should ask his system administrator or the person that is responsible for the SDL Suite environment.

In Windows it is recommended that you create a new shortcut to the SDL Target Tester in the Window's Start menu or on the desktop. The shortcut must contain the following entries in its properties sheet:

Note:

The user should ask his system administrator about adding new links to the Start menu or the desktop.

The SDL Target Tester's host site is started when you double-click the SDL Target Tester icon.

The SDL Target Tester's host tool chain responds by showing the SDL Target Tester window:

Figure 604 : SDL Target Tester window

In the text area of the UI the following is displayed at startup:

Welcome to SDL Target Tester Version 6.3.0

Opening file: D:\...\sdtmt.opt
Starting "D:\...\component_sct_mdebcom.exe" ...
Done.

Starting in SCMADEBCOM mode.


Reading symbols file ...done

The SDL-System in D:\...\component.sym contains these processes:
DoorMonitor	  max. 1 instance(s)
DoorController	  max. 4 instance(s)
Controller	  max. 1 instance(s)
PanelController	  max. 1 instance(s)
Central	  max. 1 instance(s)

8 process instances in sum
Amount of signals :19
Amount of timers  :4

After the target is reset its whole configuration is shown:

Example 615 : Target's Start-up / Configuration Message

The current target configuration is:

Compiled Cmicro KERNEL Features:
  Preemption is                         not active
  Signal Priorities are                 used
  Receiver PId in signals are           used
  Sender PId in signals are             used
  Sending Signals the simple way is     not used
  Pid addressing is                     possible
  SDL System Stop can                   not be used
  Additional errorchecks are switched   ON
  Timer handling is                     implemented
  Timers with parameters are            not used
  Dynamic create is                     implemented
  Save is                               not implemented
  Dynamic stop is                       not implemented
  Only single instance processes        NO

Compiled SDL Target Tester Features:
  Host commands can                     be used
  Profiling can                         be used
  Debugging can                         be used
  Trace is                              implemented
  Signalfilter can                      be set
  Time stamps are                       implemented
  Recorder can                          not be used
  Realtime play can                     not be used
  Trace is currently switched           ON
  Auto MessageCoder is                  ON

Selected TARGET Modes:
  Recorder is currently switched        OFF
  Player is currently switched          OFF

Message Coder configuration: (size in octetts)
-------------------------------------------------------
  SDL process ID's (xPID)              :  4
  SDL state ID's   (xmk_T_STATE)       :  1
  SDL signal ID's  (xmk_T_SIGNAL)      :  1
  SDL time values  (xmk_T_TIME)        :  4
  Message length  (xmk_T_MESS_LENGTH ) :  1
-------------------------------------------------------

SDL Data Type sizes (octetts):
-------------------------------------------------------
  Boolean    :  1 | Bit        :  1 | Character  :  1
  Charstring :Ptr | Integer    :  4 | Natural    :  4
  Real       :  8 | PId        :  4 | Duration   :  4
  Time       :  4 | Null       :  4 | Octet      :  1
  Octetstring: 12 | ObjId      : 16
-------------------------------------------------------

  Target was generated at: Mon Jan 01 12:00:00 2001

SDL System ready for configuration.

Start with "Go-Forever".

Note:

Within the target's configuration message the timestamp (seconds since the 1st of January 1970) of the generated C file is sent to the host, too.

If this timestamp is not equal to the one in the symbols file (.sym) a message box is displayed giving hints as to what has to be done.

Getting a Target Trace

After the start-up message is received the target is ready to be traced.

The command Go-Forever starts the SDL system in the target and the static create trace messages will be sent.

When a process instance executes actions within a transition, trace information describing the different actions is either printed on the screen, on the MSC Editor or written into a file specified by the user. The amount of information printed can be selected using the trace commands in the monitor system. All trace information is self explanatory. This trace example was created from the AccessControl:

Example 616 : Trace for the AccessControl

*** STATIC CREATE
*     PId      : DoorMonitor:0
*   TASK  LastOffspring := 
*** NEXTSTATE Idle

*** STATIC CREATE
*     PId      : Controller:0
*   TASK  NextDoor := 
*   OUTPUT of  Allocate to DoorMonitor:0
*     Prio     : 100
*     Now      : 0.000000 sec
*     Param(s) : 1
*   SET  MyTimer
*     Time     : 10.000000 sec
*     Value    : 0
*** NEXTSTATE WaitAllocated

*** STATIC CREATE
*     PId      : PanelController:0
*   OUTPUT of  Display to ENVIRONMENT
*     Prio     : 100
*     Now      : 0.000000 sec
*     Param(s) : 1
*** NEXTSTATE Idle

*** STATIC CREATE
*     PId      : Central:0
*   TASK  NextFree := 
*** NEXTSTATE Idle

Debugging - A Few Guidelines

The following few guidelines may help to understand the different possibilities when searching for a specific command.

Breakpoints

A lot of error situations may occur when the system is downloaded for the first time. Possibly the basic functions needed to allow the SDL system to run the target do not work. Possibly the compiler adaptations are wrong. The initialization of the environment may be incomplete. The compiler may generate faulty object code. The memory of the target may be exceeded, i.e. either variables, constants, program code, stack or dynamic allocated memory. Also, real-time requirements may not be fulfilled.

Breakpoints can greatly help to discover such situations. The breakpoint logic is especially useful as it has only a negligible impact on the systems real-time performance.

Setting Breakpoints

Does a specific process instance (pid) receive a specific signal?

BPI processname nr signalname

Does a specific process instance (pid) go into a specific state (does it end any transition, which leads to that state)?

BPS processname nr statename

Trace Scaling

The target's trace can be scaled. Sometimes it is necessary to omit trace altogether.

This may be necessary to reduce the amount of trace messages via the communications link, but can also be used to expand the view of some details.

Switch off the trace of signal parameters

Tr-Params 0

or switch it on again.

Tr-Params 1

The main interest may be lay on the work of one special process. This process can be explicitly defined with

Tr-Process processname nr

The trace for all other processes will be switched off.

Corresponding to this command the scope view can be set to a specific signal

Tr-Signal signalname

If the trace of the whole SDL system should be reduced, e.g. the trace of TASKs and DECISIONs is of no interest

Tr-Detail 4

switches the trace of these symbols off.

The command Tr-Detail can be used with five levels, for further information see Tr-Detail.

Record a Session

Note:

The SDL Target Tester's Record and Play functions are only available if a Cmicro Recorder license is available.

See Invoking the SDL Target Tester's Host to start-up the SDL Target Tester. When the target's start-up message is displayed in the text area, the target must be configured to record a session, i.e. the Recorder must be switched on in the target.

If the user wants to replay a recorded session in real-time mode he must be sure that the target executable is compiled with signals including time stamps (see XMK_USE_SIGNAL_TIME_STAMP).

The user has to do several things

  1. Open an output file by using the command
    Output-File filename
  2. Switch the Cmicro Recorder on by using
    Recorder-On
  3. Start the SDL system with
    Go-Forever

As with a standard trace the target's messages are displayed in the text area. The user can now use the target as if the SDL Target Tester is not involved. All traces and recorded messages are stored into the output file.

  1. To end the session the Cmicro Recorder should be stopped:
    Recorder-Off
  2. And the output file has to be closed:
    Close-File

Re-Play a Recorded Session

Before replaying a session it is required to record a session by following the steps listed in Record a Session.

First the target has to be reset. The start-up message reappears.

Now the user can start the replay with the commands

  1. Input-File filename
    where filename is the name of the file written during a recording session (this file must contain Cmicro Tracer messages as well as Cmicro Recorder information).
  2. Switch the play mode on:
    Recorder-Play
  3. If desired switch the real-time play mode on:
    Recorder-Realtime
    Remember: the target has to be compiled using this feature.
  4. Start the target:
    Go-Forever

The target now starts by tracing the static creates and in accordance with the design of the SDL system the first transitions are executed and traced.

Now the SDL Target Tester's host inserts all the signals coming from the environment so that the recorded session will be replayed in the same order.

Note:

The real environment is not being polled during the replay session.

Restrictions of the SDL Target Tester

The SDL Target Tester has a few restrictions:


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