![]() |
![]() |
![]() |
![]() |
![]() |
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.
- Trace of SDL and system events
- Symbols and processes can be selected and filtered in order to reduce the amount of information
- Record and replay of SDL executions (error reproduction)
- Execution trace into file, to screen and to MSC Editor
- Files can be read in later and displayed either on screen or on the MSC Editor
- Small SDL Debugger
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.
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.
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:
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:
- XON/XOFF protocol possible
- 8 Bit data
- One start bit
- One stop bit
- No parity
- All data is transmitted as binary.
- Control characters are masked and de-masked.
- Binary protocol: Cmicro 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:
- All data is transmitted as binary.
- Control characters are masked and de-masked.
- Binary protocol: Cmicro 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:
- Target timer's scale and unit.
These entries affect only the text trace.- Target data types' endian, alignment and size
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:
- USE_GATE:
- The path and the name of the used gate executable has to be specified here. In the delivered version of the SDL Target Tester, two executables called sdtgate and sockgate are included. They handle the V.24 and the socket interface on the host system.
In case of a host simulation, the name of the executable which contains the simulated SDL system is inserted instead of the gateway.- GATE_CHAR_PARAM_, GATE_INT_PARAM_
- When the gate is forked by sdtmt these values are handed over to the gateway to configure the interface.
- V.24
- Select the device: GATE_CHAR_PARAM_1 <devicename>
- On UNIX <devicename> might be /dev/ttya or /dev/ttyb (Please ask your system administrator).
- In Windows <devicename> might be COM1 or COM2
- Select the appropriate baud rate: GATE_INT_PARAM_1 19200
- All other GATE_... entries are not used with V.24 implementation.
- Socket
- UNIT-NAME, UNIT-SCALE
- USE_AUTO_MCOD
- Switch on or of the use of the automatic message coder configuration on the host. Valid values are "yes" and "no".
- If the value is "no" you have to use the values described in the following to configure the message coder.
- If the value is "yes" the message coder will be configured by the target itself. Therefore it sends its configuration in a message at startup.The following values will be ignored in that case.
The target has to be compiled with the flag XMK_USE_AUTO_MCOD defined
- LENGTH_
- ALIGN_
- The alignment for each C basic type must be given here.
- Alignment is the distance (counted in bits) from the first bit of a character to the named basic type. The Character is stored at an address dividable by four. See Figure 602.
- Allowed values are 8, 16, 32
- ENDIAN_
- The order of the C basic types within the target's memory must be given here. See the microcontroller data sheets and Figure 603 to get further information.
- Allowed values are: 1, 12, 21, 14, 41, 23, 32, 18, 81
USE_GATE $(sdtdir)/sdtgate (on UNIX)USE_GATE $(sdtdir)\sdtgate.exe (in Windows)GATE_CHAR_PARAM_1 COM2GATE_CHAR_PARAM_2 0GATE_CHAR_PARAM_3 0GATE_INT_PARAM_1 9600GATE_INT_PARAM_2 0GATE_INT_PARAM_3 0UNIT-NAME secUNIT-SCALE 0.001USE_AUTO_MCOD noLENGTH_CHAR 1LENGTH_SHORT 2LENGTH_INT 4LENGTH_LONG 4LENGTH_POINTER 4LENGTH_FLOAT 4LENGTH_DOUBLE 8ALIGN_CHAR 8ALIGN_SHORT 16ALIGN_INT 32ALIGN_LONG 32ALIGN_POINTER 32ALIGN_FLOAT 32ALIGN_DOUBLE 32ENDIAN_CHAR 1ENDIAN_SHORT 12ENDIAN_INT 14ENDIAN_LONG 14ENDIAN_POINTER 14ENDIAN_FLOAT 14ENDIAN_DOUBLE 18Invoking the SDL Target Tester's Host
Command Line Options of the SDL Target Tester
Show the version of the SDL Target Tester without opening it.
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=&TesterSeparator=0StatusbarText=Start Target TesterProprietaryKey=1AttributeKey=0Scope=ALWAYSConfirmText=ActionInterpretation=OS_COMMANDBlockCommand=0FormattedCommand=sdtmtui -t%v
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.
- Change the current directory to the project directory (assuming that this directory is ~/cmicro_project).
cd ~/cmicro_project- Now, type
sdtmtui
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:
- Target:
<instdir>\bin\wini386\sdtmtui.exe -t<targetdirectory> -- Entry Start in:
<instdir>\bin\wini386\
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:
In the text area of the UI the following is displayed at startup:
Welcome to SDL Target Tester Version 6.3.0Opening file: D:\...\sdtmt.optStarting "D:\...\component_sct_mdebcom.exe" ...Done.Starting in SCMADEBCOM mode.Reading symbols file ...doneThe 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 sumAmount of signals :19Amount of timers :4After 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 activeSignal Priorities are usedReceiver PId in signals are usedSender PId in signals are usedSending Signals the simple way is not usedPid addressing is possibleSDL System Stop can not be usedAdditional errorchecks are switched ONTimer handling is implementedTimers with parameters are not usedDynamic create is implementedSave is not implementedDynamic stop is not implementedOnly single instance processes NOCompiled SDL Target Tester Features:Host commands can be usedProfiling can be usedDebugging can be usedTrace is implementedSignalfilter can be setTime stamps are implementedRecorder can not be usedRealtime play can not be usedTrace is currently switched ONAuto MessageCoder is ONSelected TARGET Modes:Recorder is currently switched OFFPlayer is currently switched OFFMessage Coder configuration: (size in octetts)-------------------------------------------------------SDL process ID's (xPID) : 4SDL state ID's (xmk_T_STATE) : 1SDL signal ID's (xmk_T_SIGNAL) : 1SDL time values (xmk_T_TIME) : 4Message length (xmk_T_MESS_LENGTH ) : 1-------------------------------------------------------SDL Data Type sizes (octetts):-------------------------------------------------------Boolean : 1 | Bit : 1 | Character : 1Charstring :Ptr | Integer : 4 | Natural : 4Real : 8 | PId : 4 | Duration : 4Time : 4 | Null : 4 | Octet : 1Octetstring: 12 | ObjId : 16-------------------------------------------------------Target was generated at: Mon Jan 01 12:00:00 2001SDL System ready for configuration.Start with "Go-Forever".
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 IdleDebugging - 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 signalnameDoes a specific process instance (pid) go into a specific state (does it end any transition, which leads to that state)?
BPS processname nr statenameTrace 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 0Tr-Params 1The main interest may be lay on the work of one special process. This process can be explicitly defined with
Tr-Process processname nrThe 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 signalnameIf the trace of the whole SDL system should be reduced, e.g. the trace of TASKs and DECISIONs is of no interest
Tr-Detail 4switches 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
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
- Open an output file by using the command
Output-File filename- Switch the Cmicro Recorder on by using
Recorder-On- Start the SDL system with
Go-ForeverAs 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.
- To end the session the Cmicro Recorder should be stopped:
Recorder-Off- And the output file has to be closed:
Close-FileRe-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
- 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).- Switch the play mode on:
Recorder-Play- If desired switch the real-time play mode on:
Recorder-Realtime
Remember: the target has to be compiled using this feature.- Start the target:
Go-ForeverThe 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.
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:
- Only values of the following SDL data types are displayed in readable form: Bit, Boolean, Char, Charstring, Integer, Natural, Octet, Real, PId, Duration and Time.
Syntypes, Structures, Enumeration Types and Arrays which contain only SDL-data types can be decoded correctly.- Complex data types, e.g. Array of Structures indexed by syntype may be decoded wrong due to alignment.
- If the SDL Target Tester encounters a unknown data type, decoding is interrupted. The first unknown data type is printed to the screen and the rest of the parameters is displayed as a hexadecimal buffer.
- Record and play mode may not be entered together.
- During the play mode only certain commands are allowed. The available commands are marked with an asterisk.
- Any SDL sort that is implemented as pointer in C (like Charstring, Object_Identifier, Ref, Own, etc.), cannot be handled in trace, record or play mode. This comes as a result of the implementation of trace (explained in The Cmicro Library). The trace does not distinguish if there is a buffer containing a pointer to be traced or not, because there is no symbol information generated into the target system for efficiency.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |