IBM
Contents Index Previous Next



More Technical Descriptions


The File Formats of Sdtmt

General

This section deals with the general file format of the different files which are written to or read by the SDL Target Tester's tool chain. The section is not of general interest, and need be read only when implementing and connecting other tools to the host. The format of the file containing symbols is described in the subsection The Symbol Tables.

<infile> and <outfile>

Physically, there is the same file format behind the input files and output files written by sdtmt. These files store the information as received via the communications interface in a 1:1 format. The trace of the SDL execution flow and the information from the record mode is simply copied into the file on the hard disk. The same header information is used as on the communications link. This has some advantages.

Without exception the format of the information stored in <infile> or <outfile> is exactly the same as the format of the Cmicro Protocol. Therefore these files are using the memory layout of the target system.

The reason for this is that binary files are always more compact than readable ASCII files.

The message decoder of the host must be active only when information is to be converted, for example if they are to be displayed. This can decrease the performance a little.

The Symbol Tables

The symbol tables which are used by the SDL Target Tester are automatically generated by the Cmicro SDL to C Compiler. Most of the intelligence to interpret SDL traces and recorded events is implemented on the host system. Normally, the host system has enough memory and performance to do the interpretation, whereas the target has not. This is the reason, why the symbol tables used by the Cmicro Package mainly reside on the host. However, some parts of the symbol table reside where the Cmicro Kernel physically is executed, i.e. within the target system.

The Target Symbol Table

The following table is generated by the Cmicro SDL to C Compiler. For each SDL process, there is one entry in the table representing a pointer to the different trace options for that process.

/******************************************************
**  Symbol trace table
******************************************************/
#ifdef XMK_ADD_TEST_OPTIONS
XSYMTRACETBL *xSYMTRACETBL[MAX_SDL_PROCESS_TYPES+1] =
{
  (XSYMTRACETBL_ENTRY *)  NULL,
...........
..........
  (XSYMTRACETBL_ENTRY *)  NULL,
  X_END_SYMTRACE_TABLE
};
#endif

The Host Symbol Table

Generated File <systemname>.sym

The host symbol table is generated by the Cmicro SDL to C Compiler into a file called <systemname>.sym. This file is to be specified when the host site is invoked (see subsection Invoking the SDL Target Tester's Host).

In the following, the file format is described with EBNF like syntax:

SymbolFile         ::= Header SymbolDescriptions
Header             ::= HeaderComment Timestamp
HeaderComment      ::= "Cmicro .sym file, version x.y"
Timestamp          ::= "TIMESTAMP <GenerationTime>"
SymbolDescriptions ::= ( DescriptionLine ) ...
DescriptionLine    ::= Depth Subject SDTReference
Depth              ::= [0-9]+
Subject            ::=  SYSTEM IDs
                      | BLOCK IDs
                      | SIGNAL IDs
                      | PROCESS IDs
                      | START IDs
                      | INPUT IDs
                      | OUTPUT IDs
                      | NEXTSTATE IDs
                      | <to be continued>
SDTReference       ::= "#SDTREF(<sdt-reference>)" LF
LF                 ::= "\n"

In the following an example is given that was produced with a simple "ping pong" SDL system:

Example 630

Cmicro .sym file, version 2.0
TIMESTAMP <GenerationTime>

1 SYSTEM <SystemName>  #SDTREF(sdtref)
2 BLOCK <BlockName>  #SDTREF(sdtref)
3 PROCESS <ProcessName> 0 1  #SDTREF(sdtref)
4 START 0  #SDTREF(sdtref)
4 INPUT 1  #SDTREF(sdtref)
4 INPUT 2  #SDTREF(sdtref)
4 OUTPUT 3  #SDTREF(sdtref)
4 NEXTSTATE State1 1 4  #SDTREF(sdtref)
4 OUTPUT 5  #SDTREF(sdtref)
4 NEXTSTATE - 0 6  #SDTREF(sdtref)
4 TASK 7  #SDTREF(sdtref)
4 STOP 8  #SDTREF(sdtref)
3 PROCESS <ProcessName> 1 1  #SDTREF(sdtref)
4 START 9  #SDTREF(sdtref)
4 INPUT 10  #SDTREF(sdtref)
4 ASSIGNMENT 11  #SDTREF(sdtref)
4 NEXTSTATE State1 1 12  #SDTREF(sdtref)
4 ASSIGNMENT 13  #SDTREF(sdtref)
4 DECISION 14  #SDTREF(sdtref)
4 OUTPUT 15  #SDTREF(sdtref)
4 STOP 16  #SDTREF(sdtref)
4 OUTPUT 17  #SDTREF(sdtref)
4 NEXTSTATE - 0 18  #SDTREF(sdtref)
4 DCL counter Integer  #SDTREF(sdtref)
3 SIGNAL PING 1  #SDTREF(sdtref)
3 SIGNAL PONG 2  #SDTREF(sdtref)
3 SIGNAL PONG_SAY_BYE_BYE 3  #SDTREF(sdtref)
3 SIGNALROUTE SR1  #SDTREF(sdtref)
3 SIGNALROUTE SR2  #SDTREF(sdtref)

The first line, Cmicro .sym file, version x.y, gives some comment about the Cmicro symbol file version.

The TIMESTAMP <GenerationTime> value is used internally for consistency checks with the SDL Target Tester. With this time-stamp, a rough consistency check for the generated files is performed and warning messages are printed out in the case of an inconsistency.

The lines following the time-stamp information, contain in the first position an integer value indicating the depth of the structuring level in which the information is found in SDL. For example, the SDL system is in level 1, a block in the SDL system level is in level 2, and so on.

The next column in these lines describe the subject, e.g. if it is a system, block, channel, signal route, process, procedure, signal, start, input or output, or whatever.

For each subject there are IDs generated, these are used in the target executable program for generating trace information. The IDs begin with 0 (in the case above it is the start symbol of the first process) and end with the number of the last SDL symbol in the system.

The last column in the lines contains a #SDTREF reference, which points to the location of the subject in either SDL/GR or SDL/PR.

Internal Symbol Table Structure

The symbols of a trace can be found during the conversion of internal information into a displayable format.

The following three SDL objects are treated:

They are handled in the same way. Namely by building a linked list of symbols for processes, a linked list for signals and a linked list for states.

Cmicro Recorder

The information given in the following sections are valid both for host and target and there is no differentiation made between these.

Note:

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

Type and Amount of Stored Information

As already mentioned in earlier sections, using the Cmicro Recorder makes more sense in those cases where an SDL system is executed in real-time in the target.

That's why the amount of stored information is to be kept very small. Of course, this leads to the problem that not all types of errors can be found with the Cmicro Recorder but there is a good chance to find most of them. The information which the Cmicro Recorder produces at target site and which the Cmicro Recorder uses at host site cannot be configured in their dimension. The packets which are to be transmitted via the communications link are always the same. A technical description follows in the next section.

Record Mode

First, the SDL system executes the start transitions of all statically created processes. At the occurrence of a "counted" symbol, an internal counter variable is incremented (which was set to zero before going into the SDL start-up phase). The counter will simply be incremented until the first environment signal is sent from the environment to a process in the SDL system, or until the first timer expires within the SDL system.

These are special events for the Cmicro Recorder.

In that case, the Cmicro Recorder on the target site sends the following messages to the host:

Host <-------- <Counter value> ------------ Target
Host <-------- <Event> -------------------- Target

Both messages are stored in the <outfile> on the host.

The counter is reset to zero again and the procedure restarts by counting the "counted" symbols and sending the above messages to the host, either when an environment signal is sent from the environment to a process in the SDL system, or when the first timer expires within the SDL system.

The <outfile> is closed when the user terminates the record mode on the host site, i.e. it is not possible to close the file by ending the record mode on the target site. The record mode can be finished at any time.

After the record mode has been switched off, it is not allowed to switch the record mode or the play mode on again.

The <outfile> on the host now contains messages like this:

<trace event 1>
....
<trace event N>
<Counter value>
<Event>
<trace event N+1>
....
<trace event N+1+M>
<Counter value>
<Event>

As can be seen, the following sections are stored in the file whereas each section is optional:

For all events in the target
           [Store trace section]
           [Store Counter value section]
           [Store Event section]
Counted Symbols

The occurrence of the following SDL symbols will be "counted" by an internal counter (a C integer variable):

STATE

The SDL nextstate operation

INPUT

The SDL input operation

SAVE

The SDL save operation

CREATE

The SDL create operation

STOP

The SDL stop operation

STATIC CREATE

Used at system start, appears for each statically created process

DYNAMIC CREATE

Used at start of a dynamically created process

DECISION

SDL decision

TASK

SDL task (not C Code)

OUTPUT

The SDL output operation (see remarks below)

PROCEDURE

SDL procedure call

SET

SDL action: Set timer

RESET

SDL action: Reset timer

DISCARD

SDL Discard

IMPLICIT CONSUMPTION -

SDL implicit transition

A special case is the SDL output operation:

If the output is from one process in the SDL system to another process in the SDL system or if the output is from one SDL process in the SDL system to the environment, the occurrence of this symbol is counted.

Otherwise if the output is from the environment to a process within the SDL system, the event is relevant for the Cmicro Recorder (as the timer expiry is).

C code in an SDL task is normally not counted when recording. The users are free to count C code by calling:

xmk_Record (CMD_TTASK) for the record mode and

C code written into an SDL Task (i.e. by using the #CODE directive)

xmk_Play (CMD_TTASK) for the play mode.

Play Mode

In play mode, the target accepts signals coming from the SDL environment only from the Cmicro Recorder. These signals are read from the file which was previously written to in record mode.

Caution!

No environment signals may be handled by the user in the C function xInEnv! At the beginning of xInEnv, there should be a statement like

if (xmk_RecorderMode == XMK_RECORDER_PLAY) 
   return (XMK_OKAY));

In addition, no signal may be sent by any other environment function (like ISRs) to the SDL system.

At the beginning of the play mode, the host reads the first <counter value> from the <infile> and sends it to the target.

Host -------- <Counter value> --------------> Target

The meaning of this is: Please execute the amount of "counted" symbols as indicated in the <counter value>. The target executes the start transitions of all statically created processes (start-up-phase). When preemption is used, it is possible that a transition which is not a start transition is executed. Each "counted" symbol increments a counter value which is compared against the debit, which was indicated by <counter value>.

If the current counter value reaches the debit counter value, then an environment signal (or timer expiry) plus the next <counter value> is requested by the Cmicro Recorder.

Host <------- <Request> --------------------- Target
Host ---------------- <Event> --------------> Target
Host -------- <Counter value> --------------> Target

If the target has requested the next <Event> and <Counter value>, the target is waiting for these messages only and is not able to handle other messages. This is not a restriction because the environment is disabled in play mode in the target.

If the end of file of <infile> has been reached, the host indicates the end of the play mode to the target. <Counter value> and <event> are always stored together in record mode. Therefore the end of file can only be reached after reading an EnvSig or Timer expiry.

Host -------- <Play mode off> --------------> Target

Note:

After the play mode has been switched off, it is not allowed to switch the record mode or the play mode on again.

General Restrictions on Record and Play

Of course, there are restrictions in the use of the Cmicro Recorder, especially for the play mode. However, there may be situations where the Cmicro Recorder does not help in finding the source of the problem. The user must decide when the Cmicro Recorder can be properly utilized.

Firstly, the user has to ensure the same configurations are used for hardware and software, in order to allow comparison between the results of a recorded session with the ones of the replayed session. This is only a general recommendation. It is possible that he even would like to compare two different hardware configurations, and the Cmicro Recorder should help him finding the differences between these. As a more general recommendation we would say: Compare only those configurations that are definitely comparable.

Secondly, starting and ending the record and the play mode must be as follows. Host and target are to be synchronized.

Restrictions when Starting Record

The target may not transfer information to the host until the host has become active.

Therefore, the SDL Target Tester's host site should be started first and the file to write in should be opened.

If the target is started (e.g. reset-button), it has to wait on sdtmt before transmitting information (see XMK_WAIT_ON_HOST).

Restrictions when Ending Record

Ending the record session is to be done from the GUI (sdtmtui) by closing the <outfile>. The user can enter any exit commands at any time. He should pay attention to the exact time when he exits. If exit is performed in the middle of a running SDL transition in the target, then the traces following will not be stored! The last information may then be unpredictable.

Restrictions when Starting Replay

The target may not transfer information to the host, until the host has become active. The host may not transfer information to the target, before the target has become active.

Therefore the SDL Target Tester's host site should be started first and the file containing the recorded session should be opened.

If the target is started (e.g. reset-button) it has to wait for the host before transmitting information.

Restrictions when Terminating Replay

In principle, the play mode reaches the end when the last stimuli stored in the recorded file was read and sent to the target. Actually, the play mode should end when all the transitions which follow that stimuli have ended. This is a discrepancy which is solved as follows:

When the target has received the last stimuli from the recorded session, it enters the "recorder off" mode. The problem with this is, that timers are simulated during the play mode but are no longer simulated if changing to "recorder off" mode. Timers will expire as they have been set and it is the real-time that will be used to allow them expire instead of the simulated timer expiry in the Cmicro Recorder.

Real-time Play Mode

The host tries to replay the SDL environment events at the same absolute time values as they occurred during the record session, if so required by the user (real-time-play is switched on).

Internally, a time stamp is stored for each environment signal, which is compared within the target with the current value of SDL now. SDL now and the time stamps in the signals are calculated with the value 0 from system reset on. The target generates the SDL now values in any case.

Of course, the processing power of host and target together must be large enough to handle this. As a rule of thumb, the recorded environment signals may not be sent to the SDL system more often than one every few hundred microseconds. But that - of course - also depends on the communications link in use.

Restrictions when Using Preemption

There are some restrictions when the Cmicro Recorder is used in combination with preemption. The problem is that in a real-time execution, signals coming from the environment (this may be a hardware interface) can cause a preemption of a running SDL process by a new process with a higher priority. The preemption may occur at any time, which means at any machine instruction (see notes below). On the other hand, only SDL symbols are registered by the Cmicro Recorder.

This means that the play mode may produce a different system behavior other than the recorded one.

The only alternative to implement an exact reproduction of the recorded session would be the use of special debugger hardware (not a general solution).

Some Additional Comments

Real-time behavior cannot be expected in play mode. When considering the other direction, from SDL to the environment, it is not absolutely necessary to cut this connection off (C function xOutEnv). It may be a good idea to let this connection be as it is in record mode. For example, if there is a display driver in the environment, which is controlled by SDL, it would then be possible to see the reactions on the display in the same way as they have been observed in record mode.


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