The Cmicro Tester is a help tool which can be used to find errors and illegal or unwanted behavior within a target system. It allows the programmer to follow and to reproduce the execution flow of the SDL system (running on the target) on the host.
The strength of the Cmicro Tester is the minimum amount of storage it occupies on the target. With the exception of certain traces, the Cmicro Tester's memory requirements do not increase proportionally with system size. That means, that the memory amount is a compiler specific constant. If the memory is scarce it is also possible to reduce the memory by reducing the functionality.
In order to use the Cmicro Tester, the system must be developed with the Cmicro Code Generator (see The Cmicro Code Generator) and the Cmicro Library (see The Cmicro Library).
The host and target systems can be connected by any type of communications link, as any kind of communications drivers can easily be connected to the Cmicro Tester system.
The Cmicro Tester offers the following features:
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
The Cmicro Tester will be executed in a distributed fashion, i.e. some parts of the Cmicro Tester run on a host machine, while other parts run together with the Cmicro Kernel and the SDL application on the target machine, for example a micro controller. A prerequisite is a communications link between the host and target systems.
The Cmicro Tester is an optional part of the Cmicro Package and is delivered when specifically ordered. It is an addition to the Cmicro Library and contains the following parts:
The Cmicro Tester's host executable is a tool chain which consists of sdtmt, sdtmtui and sdtgate. The sdtgate module contains the default configuration (V.24) for connecting host and target. All open interface functionality is utilized here.
The target library is mandatory when the Cmicro Tester is ordered. By using the open interface, it is possible to connect user specific tools to the Cmicro Testers target library. The Cmicro Tester's target library must be used together with the Cmicro Library on the target.
This diagram gives an overview of the Cmicro Tester functionality:
Figure 558 : Functionality of the Cmicro Tester
|
|
The following components, as seen from the user's point of view, represent the Cmicro Tester:
The Cmicro Tracer is introduced in the subsection Following the Execution Flow -- The Cmicro Tracer.
The Cmicro Recorder is introduced following the subsection Reproduction of Errors -- The Cmicro Recorder.
The command and debug interface is introduced in the subsection Commands for the Host and Debugging Facilities.
The following subsections give an overview of how to use the Cmicro Tester. A detailed description of the necessary preparations and adaptations will be given in the sections
These sections follow after the introduction subsections.
The Cmicro Tracer transmits information about the execution flow of the SDL system on the target. Information traced includes the signals sent and received by processes and the SDL states and symbols entered in execution flow. A filter can be defined so that only partial trace information is created for particular process instances or for particular SDL constructs. The tracer can be connected with the MSC Editor on the host, thus allowing observation of dynamic signal trace between processes on the target.
The following SDL events can be traced.
For each symbol in each process in the system the trace can be separately switched on or off.
Please consult the subsection The API on Target for information about how to set the different options.
The following system events can be traced.
Each system event can be separately switched on or off.
Please consult the subsection The API on Target for information about how to set the different options.
By using the Cmicro Tester it is possible to create traces on the MSC Editor. Two modes are of special interest:
The first case, however, only makes sense if the processor has enough time to handle and display all the traces created during the run-time of the SDL system. That may also be a question of buffer dimensioning. Alternatively there might be SDL systems which do not have these timing constraints, for example, the SDL system may wait until the MSC trace is completed.
The second possibility does not need that much processor power on the host site. In practice, this method is more useful.
The method with using the Cmicro Recorder is the one with the best real-time properties. In comparison to the trace, the Cmicro Recorder stores only a reduced subset of information in a compact format.
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
Using the Cmicro Recorder, the user can "record" the actions taken within an SDL system running on the target and save these to a file on the host machine. This file can later be "played" in order to run the system through the same state changes, so that the same actions are performed. In this way error situations, perhaps recorded by a client or a developer at another location, can be reproduced. In the following, a general description is given. A more detailed description of the internal procedures can be found in the subsection " Type and Amount of Stored Information". The subsection " General Restrictions on Record and Play"may also provide more information about how it works.
Use of the Cmicro Recorder makes sense whenever an SDL system is executed in real-time on the target in combination with a host.
The amount of information transferred via the communications link and stored into a file on the hard disk is kept small and compact, so that the real-time properties are not influenced. Only information is stored, which is necessary in order to replay an SDL session later. It is the communication of the environment to the SDL system, and the expiration of timers, which is recorded.
It is not possible to receive information about the inner events of the recorded SDL system, by using the recorder only. The purpose of the Cmicro Recorder has nothing to do with the purpose of the Cmicro Tracer. The user also has to use the Cmicro Tracer if he wants to get information about internal events. Additional information is then transmitted via the communications link and stored into a file which can be displayed dynamically or later on. The performance of the communications link dictates whether real-time trace is possible. The more information traced via the link, the higher the performance should be.
The record mode must be switched on within the target (by using the C function interface on target), and on the host - see subsection Record a Session).
After producing a file with the record mode, the file can be replayed in order to run the SDL system in the same order through the same system states.
When the end of file is reached which is indicated with <Play mode off> to the target, the SDL system is able to react on ordinary environment signals coming from the real environment (if programmed by the user).
The play mode must be switched on within the target by using the Cmicro Tester Command Recorder-Play. No environment signals may be handled by the user in the C function xInEnv during the play.
Sometimes, when a file is replayed, the erroneous situation can directly be viewed at another device, i.e. if the SDL system runs in an emulator with breakpoints set, or if there is, for instance, an LC display connected to the SDL environment.
In this case, it is not necessary to compare output files. In other cases, it might be of interest to do so as described later.
A comparison of two executions is possible, when two files containing the same type and amount of information are compared.
The procedure goes as follows:
The command interface and the debugging facilities are very helpful in finding errors produced within the target.
For instance, after an SDL interpretation error has occurred, it is possible to suspend the SDL system and to inspect the global state by viewing the signal queue(s). After the queue size has been dimensioned by a target compilation the queue can be inspected on the host site during a target execution.
There are several commands to check that timers are correctly processed.
The ability to set breakpoints during real-time execution and to execute a single step also helps to find an error situation.
The amount of trace information can dynamically be defined via commands. A differentiation is made between the information on the communications link and the information displayed.
The Cmicro Tester on host site is a tool chain consisting of the parts: GUI (sdtmtui), the logical part (sdtmt), the communications link gateway (sdtgate) and the glue between these components the Cmicro Postmaster (sdtmpm). Sometimes, e.g. when the Cmicro Tester uses the MSC Editor, a further tool is executed called Cmicro SDT Link.
The Cmicro 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 the ability to record and replay events to reproduce error situations.
Host features:
It is important to know how the host works independently from the target. The machine to machine communication is built automatically when the communication between them is started. Thus, the host part of the Cmicro Tester remains the same executable when changing the target hardware! Only some adaptations in the configuration file sdtmt.opt have to be made, see Configuration Possibilities of Sdtmt (sdtmt.opt).
The graphical user interface is described in Graphical User Interface.
The normal method for using the Cmicro 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 Cmicro Tester running on the host machine can be considered a controlling unit. This is described in Figure 559.
Figure 559 : Sdtmt used for target control
|
|
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 Cmicro Tester as a conversion tool:
Figure 560 : Sdtmt used for file conversion
|
|
Furthermore, by using the commands Output-NPAR and Output-PAR the SDL environment can be simulated on the host site.
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.
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:
Sdtgate must be selected in sdtmt.opt:
USE_GATE sdtgate
The file sdtmt.opt should have the following entries in order to configure the V.24 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
Then select the appropriate baud rate by specifying
GATE_INT_PARAM_1 19200
in the file sdtmt.opt. 19200 Baud is the default baud rate.
If sdtmt is invoked, it searches for the configuration file sdtmt.opt. This file is mandatory. It contains information on target options such as:
xmk_T_TIMEThis file needs to be updated, if another target system is connected.
USE_GATE <inst_dir>/bin/<platform_dir>/sdtgate (on UNIX) USE_GATE c:\tau<ver>\bin\wini386\sdtgate (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 LENGTH_CHAR 1 LENGTH_SHORT 2 LENGTH_INT 4 LENGTH_LONG 4 LENGTH_POINTER 4 ALIGN_CHAR 8 ALIGN_SHORT 16 ALIGN_INT 32 ALIGN_LONG 32 ALIGN_POINTER 32 ENDIAN_CHAR 1 ENDIAN_SHORT 12 ENDIAN_INT 14 ENDIAN_LONG 14 ENDIAN_POINTER 14
The configuration tool BodyBuilder can be used to modify sdtmt.opt (see The BodyBuilder).
limits.h).
Figure 561 : Target's alignment types
|
|
Figure 562 : Definitions of the target's endian
|
|
| Option | Description |
|---|---|
|
|
Show a short help on the command line options. |
|
|
Show the version of the Cmicro Tester without opening it. |
|
|
Change the working directory to <targetdir>. |
The Cmicro Tester can be invoked with the actual project from the Organizer. This can be done by inserting the following lines into the file org-menus.ini. For more information, see The Telelogic Tau Public Interface.
[MENU] Name=&Cmicro [MENUITEM] ItemName=&Tester Separator=0 StatusbarText=Start Cmicro Tester ProprietaryKey=1 AttributeKey=0 Scope=ALWAYS ConfirmText= ActionInterpretation=OS_COMMAND BlockCommand=0 FormattedCommand=sdtmtui -t%v
|
Note: The |
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.
Before using the Cmicro 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 Cmicro 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 Cmicro Tester's host simply needs to be started from the working (project) directory.
~/cmicro_project).cd ~/cmicro_projectsdtmtui
|
Note: If the command |
In Windows it is recommended that you create a new shortcut to the Cmicro Tester in the Window's Start menu or on the desktop. The shortcut must contain the project directory in its properties (Entry `Start in:') and should start the executable sdtmtui.exe.
|
Note: The user should ask his system administrator about adding new links to the Start menu or the desktop. |
|
|
The Cmicro Tester's host site is started when you double-click the Cmicro Tester quick-button. |
The Cmicro Tester's host tool chain responds by showing the Cmicro Tester window:
Figure 563 : Cmicro Tester window
|
|
In the text area of the UI the following is displayed:
Welcome to SDT Cmicro Tester Version 3.5.0 Starting "sdtgate.exe" ... Done. Gate is using a V.24 interface. Reading symbols file ... done.
After the target is reset its whole configuration is shown:
The current target configuration is: Compiled Cmicro KERNEL Features: Preemption is not active Signal Priorities are not used Receiver PId in signals are used Sender PId in signals are used Sending Signals the simple way is not used PId addressing is not possible SDL System Stop can not be used Additional errorchecks are switched ON Timer handling is implemented Timers with parameters are used Dynamic Create is implemented Save is implemented Dynamic Stop is implemented Only single instance processes YES Compiled Cmicro TESTER Features: Host commands can be used Profiling can be used Debugging can be used Trace is implemented SDLE-trace is implemented Signalfilter can be set Time stamps are implemented Recorder can be used Realtime play can be used Selected TARGET Modes: Trace is currently switched ON Recorder is curently switched OFF Player is currently switched OFF Message Coder configuration: Coding for SDL process ID's (xPID size) is :char=1 Coding for SDL state ID's (xmk_T_STATE size) is : char=1 Coding for SDL signal ID's (xmk_T_SIGNAL size) is : char=1 Coding for SDL time values (xmk_T_TIME size) is : int/long=4 Coding for message length values (xmk_T_MESS_LENGTH size) ... SDL System ready for configuration. Start with "Go-Forever".
After the start-up message is received the target is ready to be traced.
By typing
Go-Forever
the SDL system is started 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:
STATIC CREATE:
process :Central_0
TASK:
process :Central_0
NextFree := ...
NEXTSTATE:
process :Central_0
state :Idle
STATIC CREATE:
process :PanelController_0
OUTPUT:
signal :Display
prio :100
snd :PanelController_0
rec :ENVIRONMENT
time :0
parameters :
00 01 ..
NEXTSTATE:
process :PanelController_0
state :Idle
The following few guidelines may help to understand the different possibilities when searching for a specific command.
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.
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
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.
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
See Invoking the Cmicro Tester's Host to start-up the Cmicro 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
Output-File filename Recorder-On 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 Cmicro Tester is not involved. All traces and recorded messages are stored into the output file.
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). Recorder-Play Recorder-Realtime
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 Cmicro 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. |
The Cmicro Tester has a few restrictions:
Command names are entered character by character on the keyboard. Each command consists of ASCII characters, terminated by a carriage return. A command is interpreted, after the carriage return is given. Commands may have parameters. Command names may be abbreviated by giving sufficient characters to distinguish it from other command names. The command names are interpreted from left to right. There is no distinction between upper and lower case letters.
Consider, as an example, the command ?Breaklist. The command may be entered as "?b". However, if only `?' is typed, sdtmt will respond with the error message:
Command was ambigous
since the command cannot be distinguished from, for example, the ?Queue command.
A parameter is separated from the command name by one or morel spaces. The same is applicable to the separation of two parameters. There is no distinction between upper and lower case letters.
Each parameter is mandatory from a syntactical point of view and must be specified. No parameters may be left out.
If the parameter list following a command name is not complete, a dialog window is opened to enter the missing parameter(s).
Specifying more parameters than the command can handle, sdtmt prompts
**ERR:Extra parameters specified in command.
If the type of any parameter, which was entered, does not match the expected one, then sdtmt responds with an appropriate error message according to the expected type. Type
help commandname
or refer to the manual.
Command parameters that are SDL names, may also be abbreviated, as long as the abbreviation is unique. If a name is equal to the first part of another name, as for example Wait and Wait_For_Me, then any abbreviation of Wait is ambiguous. However, if all characters of the shorter name are given (Wait in this example), this is considered as an exact match and the short name will be selected.
If an error is detected in a command name or in one of its parameters, an appropriate, self explanatory error message is displayed on the screen. The command will be ignored.
Process type is an ASCII string identifying the SDL name of the process. Process names must be unique for all processes within the system. It is also possible to use the decimal value of the process type. The decimal value can be found by looking into the symbol file, which is also automatically generated.
The separator for process type and instance is a blank.
The value of the instance number is a decimal value beginning from 0 for the first instance of a process type. If the SDL System contains only (x, 1) declarations on SDL level, then the user has to specify "0" in any case.
Symbols are read in from a file called <systemname>.sym. There are a lot of error checks within the Cmicro Tester's host site which only work if a symbol file has been loaded.
Sdtmt gives the user some quick help when entering:
help
A complete list of commands will be displayed on the screen. Commands, which are available in the current mode, are marked with an asterisk. If a command is entered which is not available in the current context the Cmicro Tester responds with:
Sorry. The current mode of sdtmt does not allow you to enter that command. The command has been ignored.
To get a short explanation, type:
help <commandname>
for instance type:
help help
To get a complete list of commands, type:
help *
Most of the commands marked with the type "Remote" can only be executed (in the target) if the flag XMK_ADD_MICRO_COMMAND is defined in the file ml_mcf.h. See Manual Scaling.
<Processtype Instance> <Timername> <Timerparameter>
Type: Remote
Check, if a specific timer is set by a process, and has not been expired.
|
Note: The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog. |
(None)
Type: Remote
The states of all process instances in the system will be displayed on the screen. It is implemented as a procedure, which is controlled by sdtmt. Depending on the traffic load on the communications interface the responses may be delayed.
(None)
Type: Remote
This command requests to clear all the breakpoints in the break list.
<breakpoint number>
Type: Remote
This command requests to clear the given breakpoint number from the breakpoint list. The breakpoint number depends on the total number of defined breakpoints.
<Processtype Instance> <SignalName> <StateName>
Type: Remote
This command sets a breakpoint, both on the input and the nextstate of a given process. After setting the breakpoint, try to query the break list with the command ?Breaklist.
No parameter is optional. These combinations are allowed:
processname nr * statename ->Use command BPS processname nr signalname * ->Use command BPI processname nr * * processname nr signalname statename
<Processtype Instance> <SignalName>
Type: Remote
This command sets a breakpoint on the input of a given process. It is not mandatory to provide a parameter. These combinations are allowed:
processname nr * processname nr signalname processname * processname signalname
<Processtype Instance> <StateName>
Type: Remote
This command sets a breakpoint on the state of a given process. Notification is given when the command cannot be processed within the target system.
No parameter is optional. These combinations are allowed:
processname nr statename processname * processname statename processname nr *
(None)
Type: Remote
This command requests the current breaklist from the target and displays it on the screen as it was entered. If a symbol file has been specified during the invocation of sdtmt, then process IDs, signal IDs and state IDs are displayed with their symbolic value.
<directoryname>
Type: Local
The working directory of the current Cmicro Tester session is switched to <directoryname>.
<filename>
Type: Local
The current output/input file (including binary trace) with the name <filename> will be closed when using this command. (See Output-File and Input-File)
(None)
Type: Local
After invoking this command the current settings of the Target Message Coder TMCOD are display in the text area. The settings given here have to be previously made in the configuration file sdtmt.opt. See Configuration Possibilities of Sdtmt (sdtmt.opt).
(None)
Type: Remote
This command can be used to continue processing, i.e. after a breakpoint was h. Notification is given when the command cannot be processed within the target system.
<input filename> <output filename>
Type: Local
This command converts the trace messages of the target (stored in the <input filename>) into readable ASCII trace. This ASCII trace is stored into the <output filename>.
<Parent-Processtype Instance> <Child-Processtype>
Type: Remote
This command creates an SDL process of the given type . The creating process must be specified in <Parent-Processtype Instance>. If there is a free process instance, which is currently dormant, it will be created and the start transition will be executed. This can be seen in the trace.
<Child-Processtype>
If the system is under a break condition, the command will be ignored as it is not possible to send signals (dynamic creation uses signal mechanism).
|
Note: Please specify the |
(None)
Type: Remote
This command disables the processing of timers.
The command affects the SDL timers only! However, timers which are already expired and are in the queue will be input as normal. Keep in mind that the disabling of timers changes the system behavior.
(None)
Type: Local
The ASCII trace into the text area is switched off.
(None)
Type: Local
The ASCII trace into the text area is switched on.
(None)
Type: Remote
This command enables the processing of timers again, if it was previously disabled with the command Disable-Timer. Due to the fact that time (and so the system time) cannot be stopped, it might happen that all the timers set earlier may expire at the same time this command is entered. This may cause illegal system behavior, i.e. a queue overflow and the call of the ErrorHandler or another illegal behavior.
<const>
Type: Remote
Query last occurred error. The target system traces the last error within the SDL execution and stores it. The result will be displayed on the screen, both as a decimal value and as ASCII text with an explanation of the error situation.
If the value <const> is not equal to zero, further information about the error is given from this manual (the on-line Help Viewer is started).
Especially, when the SDL system is executed for the first time in a new hardware environment, the command may help in finding problems. It is also useful after a long execution of the SDL system, as any error situation arising may be detected. All the errors, warnings and information, which are handled by the ErrorHandler are explained in the section User Defined Actions for System Errors -- the ErrorHandler.
(None)
Type: Local
The single step mode (which has been entered with Single-Step) is finished.
(None)
Type: Remote
The target responds with its configuration. Compiled features are displayed in the text area as well as the current settings (e.g. trace on/off).
(None)
Type: Remote
After initializing the target (for example switching the recorder mode on) the target is started with this command. It is necessary that the target is compiled with the flag XMK_WAIT_ON_HOST.
[<commandname> or *]
Type: Local
A complete list of commands will be displayed on the screen. Commands available in the current mode of the Cmicro Tester are marked with an asterisk.
Type
Command>help <commandname> ,
to get a short explanation of one or several commands, e.g.
help help
which is the same as
he he
A list of all commands beginning with b can be requested by typing:
help b
A complete list of commands can be requested by typing:
help *
<filename>
Type: Local
The file named <filename> is opened to get the stored trace information (binary format). This command must be used if, for example, a recorded session should be replayed. The file <filename> must contain trace information in binary format.
(None)
Type: Local
The command displays the line status of the communications interface. It can be used for checking if characters, frames and XONs / XOFFs have been received/transmitted and the kind of device that is actually connected.
(None)
Type: Local
If the Cmicro Memory Management is selected (the flag XMK_USE_SDL_MEM must be defined, please view Use of Memory) this command offers the advantage of checking currently allocated memory.
(None)
Type: Local
The Cmicro Tester Release's news are displayed in the text area.
(None)
Type: Remote
This command performs one step (one transition) if single step is active. The Single-Step command must be given prior to this.
<Processtype Instance> <Statename>
Type: Remote
This command sets the state of the given process instance to the value of <Statename>. <Statename> must be one of the states which are defined for the corresponding process type in SDL. Normally, that only makes sense if the system is under break condition or is idle.
<filename>
Type: Local
All the target's trace information is stored as binary data into the file <filename>. This command can be used to store the information of a recording session in binary format.
<Receiver-Processtype Instance> <Signalname>
Type: Remote
An Output from the environment without any parameters is sent into the SDL system.
<Receiver-Processtype Instance> <Signalname> <Signal Parameter>
Type: Remote
An output from the environment into the SDL system with a signal including parameters is sent into the SDL system. The <Signal Parameter> has to be given as a buffer of hexadecimal values. See Example 474.
Output-PAR Process_A 0 Signal_1 "00-12-a3"
Signal `Signal_1' is sent to the instance 0 of process type `Process_A'. `Signal_1' contains parameters with the length of three octets and the values 0x00, 0x12 and oxa3. The ordering of the parameter octets must fit into the signal's parameter structure and the target's memory layout (alignment, endian etc.).
<filename>
Type: Local
The options file <filename> is read in so that the message coder can be initialized. By default the options file sdtmt.opt (see Configuration Possibilities of Sdtmt (sdtmt.opt)) is read in when the Cmicro Tester is started.
<filename> <EventsPerPage>
Type: Local
The file <filename> containing trace information (in binary format) is read in and displayed as ASCII trace in the text area. The constant decimal value <EventsPerPage> gives the amount of trace information to be displayed until the user confirms the next page.
(None)
Type: Local
This command gives all configuration information together, see the commands ?Coder and Line.
<Processtype Instance>
Type: Remote
The profiling of one process instance can be requested with this command. The result is the transition execution time of the longest transition and the last transition of the specified process instance. The flag XMK_ADD_PROFILE must be set when compiling the target executable to have access to this command in the target.
Please view the section Initialization.
<Processtype Instance>
Type: Remote
The state of the given SDL process instance will be displayed in its symbolic representation for that process type. If a symbol file has been specified, the Processtype and Instance are both checked.
(None)
Type: Remote
Some characteristics of the queue will be displayed. The command is very useful for determining the queue's dimensions . There is a peak hold, which shows the maximum number of entries in the queue since the system's start.
After typing the command, information is printed on the screen, which may look like:
Current Queue state: Queue size dimensioned to:Max.20 entries Peak hold :1 entry/entries Currently :0 entry/entries in queue Queue memory located at :36a40010,x
The explanation for this is: a maximum of 20 entries in the queue can be handled by the system. Since system start, there was never more than one entry being used. Currently, no signal instance has been detected in any process input port. The last value displays the physical memory allocation of the queue, which helps in debugging.
<duration>
Type: Local
If a recorded session should be replayed it is possible to insert each environment signal with a delay of <duration> seconds. This feature can be used instead of the real-time play ( Recorder-Realtime).
(None)
Type: Remote
Switches the Cmicro Recorder off. This command may be specified any time during a recording session. It can be used in order to reduce the amount of information sent via the communication interface.
(None)
Type: Remote
Switch Cmicro Recorder to record mode. It is not a good idea to enter this command when the SDL system is not idle. (Furthermore, the question is, whether it makes sense to start a record session in the middle of an SDL execution or from the start-up of the SDL system.) It may not be relevant to start a recording session after the system has started.
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
(None)
Type: Remote
The Cmicro Recorder's play mode will be set. This command can be entered in a few states of the Cmicro Kernel only. Notification is given if necessary. The same explanation as for Recorder-on apply.
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
(None)
Type: Local
The play mode of the Cmicro Tester is started as real-time play. It is necessary to compile the target with signals including time stamps.
The Cmicro Tester's host sends all environment signals with the recorded time stamp into the target while replaying. Without using this command all signals are inserted with time 0 which leads to an immediate execution in the target.
(None)
Type: Remote
This command tries to reinitialize the system. The reinitialization may fail, if the hardware drivers cannot be reinitialized again. Furthermore, all global auto variables in the user's C program parts cannot be reinitialized. However, if there is a clean implementation of driver initialization and deinitialization, and initialization of global variables, the command will work well.
<Processtype Instance>
Type: Remote
Remove all signals of the given receiver from the signal queue.
(None)
Type: Local
For each command, which is sent to the target, the host waits for an explicit acknowledgment. The last command can be removed, so that the host does not wait for that acknowledgment. That can be used when the communication is hanging for any reason, for example, when the command could not be sent to the target, or was not received by the target, or the acknowledgment could not be received by the host.
(None)
Type: Remote
All signal instances in the queue will be removed. The signal queue will be empty.
<Processtype Instance> <Signalname>
Type: Remote
Remove a specific signal of the given receiver from the queue.
|
Note: E.g. when a breakpoint is hit the signal which led to the current transition still remains in the signal queue. This means the first signal in the queue cannot be removed. |
<Processtype Instance>
Type: Remote
This command resets all SDL timers of the given process instance.
<Processtype> <Instance> <Timername> <Timerparameter>
Type: Remote
This command resets a specific SDL timer of the given process instance and with a specific timervalue.
|
Note: The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog. |
(None)
Type: Remote
Resume Cmicro Kernel, after a suspend has been accepted. The same explanations as for the Suspend command apply.
<filename>
Type: Local
The initialization commands in the log file <filename> will be executed.
<factor>
Type: Remote
Scale time when setting a timer.
Often there is a need to simulate time during an SDL execution. By specifying this command, it is possible to make SDL timers run faster or slower. The command is applied on newly set timers only, i.e. if a timer is already running then it remains unaffected from the time scale. Due to this fact, the command should only be given at the start of the SDL system.
In record mode the scaled time will be stored. This results in time being scaled in play mode. It is impossible to scale time manually in play mode!
<Processtype Instance> <Time value> <Timername> <Timerparameter>
Type: Remote
Set an SDL Timer for the given process instance with the given timevalue in units. The time value is a float value re-calculated to the target's timer ticks. Please view UNIT-NAME, UNIT-SCALE.
.
|
Note: The input of a timer parameter is mandatory. The type of the parameter has to be an integer value. For a timer without parameter enter a 0 in the parameter dialog. |
set <Processtype> <Instance> 4711 < timername> 0 set <Processtype> <Instance> 1.456 <timername> 0
(None)
Type: Remote
The command tries to shutdown the system, which means normally to exit the main program. The user can define the actions on exit within the target. The same explanations as for the reinitialization command apply.
(None)
Type: Remote
This command switches the single step mode on. Either Next-Step or Continue may follow.
<filename>
Type: Local
All the initialization commands will be written to the log file <filename>. Please view the command Run-Cmd-Log, too.
(None)
Type: Local
This command is used to start the XON communication in the default implementation of the sdtgate.
<level> <"Diagramname">
Type: Local
The MSC Editor is started and the target's trace messages will be displayed in the MSC Editor. The <level> specifies the amount of MSC symbols:
<Processtype> or *
Type: Remote
The trace on SDL symbol level is started for the specified process. The Organizer has to be running and the target needs to be compiled with the flag XMK_ADD_SDLE_TRACE (see Trace).
<filename>
Type: Local
A log file containing the whole ASCII trace of the Cmicro Tester will be written.
<Processtype Instance>
Type: Remote
This command stops an SDL Process according to the SDL semantics, no matter if the system is suspended or under break condition. The command is, after it is received, directly executed within the target. All signals which are in the queue for this process are removed, including create signals.
<None>
Type: Local
The write of initialization commands will be stopped. Please view the command Run-Cmd-Log, too.
(None)
Type: Local
This command is used to stop the XON communication in the default implementation of the sdtgate.
(None)
Type: Local
The trace on the MSC Editor is stopped.
<None>
Type: Local
The trace on SDL symbol level is stopped.
<None>
Type: Local
The trace to the trace log file is stopped. The file is closed.
(None)
Type: Remote
Disables the Cmicro Kernel from scheduling. The transition currently running will not be affected and will be ended first, before the command is accepted. The suspended SDL system cannot process any signals, neither internal signals nor signals coming from the environment. This may lead to a queue overflow. It is recommended to disable the timers to prevent this.
<systemname>.sym
Type: Local
The automatically generated symbol file <systemname>.sym is loaded. The symbolic names for process types and Signal IDs can only be used if this file is read in.
Additional error checks can be performed within the Cmicro Tester's host if this file is read in.
|
Note: The Lauterbach TRACE32 specific commands are only available if the according license is available. |
<"command">
Type: local
The <"command"> can be any TRACE32 PRACTICE command like go, break or do.
<none>
Type: local
To display symbolic names in the TRACE32's analyzer it is necessary to have all the symbolic names like Process-Types and Signals on TRACE32 side. Executing this command means to send all the symbolic names to the TRACE32.
<filename.cmm>
Type: local
The Cmicro Tester will generate a TRACE32 command file (.cmm) containing all the symbolic names of Process-Types, Process-Instances, Timers, Signals and States. This file can be used to configure the TRACE32 when using a Cmicro executable without Cmicro Tester or can even be used to configure from other command files.
(None)
Type: Remote
Some characteristics of the current timer tables are displayed. The command is useful in order to inspect the state of the SDL system, or to see if it is hanging.
After typing the command, information is printed on screen which may look like:
Current Timer states: SDL NOW :9147,d Timer dimensioned to :6 Currently :0 timer(s) active Timer memory location at :36bf0014,
Where SDL NOW represents the amount of units since system start. The value of 6 shows the maximum number of timer instances in the system. The third line is self explanatory. The last line gives the physical memory allocation of the timer linked lists which may ease debugging.
<level>
Type: Local
Define Trace detail. The command is applied locally within the Cmicro Tester's host and it works on ASCII traces to the text area only.
Output to either a file or to the MSC Editor will not be affected by this command. Thus if the target is configured correctly no inconsistency can occur and no information stored in a file or in the MSC Editor will be incomplete.
Five levels are defined (0--5). The higher the level, the more SDL events are traced. Different events are assigned the levels depicted in the following table:
<const>
Type: Local
The trace of signal parameters can be switched on or off. This command has an influence on the display in the text area only.
<const> can take the values:
<Processtype Instance> <Bitmask> or ENV <Bitmask> or * <Bitmask>
Type: Remote
This command defines which processes in the system are traced. It is applied in the target (remote command), so that the traffic load on the communications interface can be reduced interactively.
This trace command works for all instances of the given process type. No differentiation is possible between different instances of one type.
<signalname> <flag>
Type: Remote
This command defines the trace for one or all signals in the system. It is applied in the target (remote command), so that the communications interface's traffic load can be reduced interactively.
The signal name is the one from the SDL system. No qualifiers are possible, which means, that signal names have to be unique for the whole SDL system. The flag may be 0 (trace off) or any other value (trace on). If an asterisk is specified for signal name, then flag is applied to all signal types. The command works for SDL output only.
(None)
Type: Remote
The command switches the Cmicro Tester's tracer off within the target. The current option settings stored in the target will not be affected. After this command is received within the target, the trace is immediately suspended and can only be resumed with the command Tr-On. The output trace that has been written is interrupted.
|
Note: The user has to consider misinterpretation of the trace because of missing traces after resuming the trace via Tr-On. |
(None)
Type: Remote
This command switches the Cmicro Tracer on, if it is compiled within the target. None of the current option settings concerning trace within the target will be affected.
<unitname>
Type: Local
The timer unit's name can be assigned with this command, e.g. if the target's system time is `milliseconds' and the Unit-Scale is dimensioned to 1000, the <unit> should be named as `sec'.
(realvalue)
Type: Local
The target's system time, which is received with the trace data, is multiplied by this constant factor to get a "readable" system time. See Unit-Name too.
This section describes the appearance and functionality of the graphical user interface of the Cmicro Tester (sdtmtui). Some user interface descriptions common to all tools in Telelogic Tau can be found in User Interface and Basic Operations. These general descriptions are not repeated in this chapter.
The Cmicro Tester UI is automatically started from the Cmicro Postmaster. When the UI is started the definition file for the button groups (see The Button Area) is read in. The default name of this file is sdtmt.btn.
The main window provides a text area (which displays output from the monitor system), an input line (used for entering and displaying textual command line input to the monitor system) and a button area (with buttons for execution of monitor commands).
|
|
The text area displays all text output from the monitor system, including user prompts, error messages and command results.
Commands cannot be entered in this area, but a command given on the input line or through the use of the command buttons is echoed after the displayed prompt:
Command>
The input line is used for entering and editing monitor commands from the keyboard. For information on available monitor commands, see Syntax of Cmicro Tester Commands.
The last commands entered on the input line are saved in a history list. This list can be traversed by using the <Up> and <Down> keys on the input line.
When <Return> is pressed anywhere on the input line, the complete string is saved in the history list and is moved to the text area. The command is then executed.
If a command entered on the input line requires additional user input (i.e. parameter values), the information will automatically be prompted for in a dialog:
Figure 565 : A typical selection dialog
|
|
Each parameter dialog has an OK button for confirming the value and a Cancel button for cancelling the command.
The button area is used for entering monitor commands by clicking the left mouse button on a command button. Each button corresponds to a specific monitor command. The buttons are divided into groups, roughly corresponding to the different types of commands listed in Cmicro Tester Commands. Each group is shown as a module in the button area. Any number of button modules may reside in the button area. If the modules do not fit in the button area, a vertical scroll bar is added.
The definition of the buttons and button groups are stored in a button definition file (see Button and Menu Definition File). New buttons can be added and existing ones deleted or redefined by using the Group menu in a button module.
If a button's definition contains parameters, the parameter values are prompted for in dialog boxes before the command is executed, in the same way as described for commands entered from the input line. See Parameter Dialogs.
When no more parameter values are requested, the string shown on the input line is saved in the history list and moved to the text area. The command is then executed.
|
|
Each button module consists of a title bar and a number of command buttons arranged in rows and columns. The title bar displays:
The Group button contains the following menu choices:
This menu choice opens a dialog where you may add one or several new buttons to the button module. You should specify a label of the new button and a command that is to be executed when the button is clicked. Click OK or Apply, to add the button to the end of the module. For the syntax of a button definition, see Button and Menu Definitions.
Figure 567 : Adding a new button
|
|
This menu choice opens a dialog where you can select a button to edit, that is, its label and definition. You edit the button in a similar way as described in Add.
|
Note: If several buttons have the same button label, it is always the first button found that will be edited, regardless of the selection. |
This menu choice opens a dialog where you can select one or several buttons to be deleted..
|
Note: If several buttons have the same button label, it is always the first button found that will be deleted, regardless of the selection. |
This menu choice opens a dialog where you can edit the name of the current button module.
Select this menu choice deletes to delete the current module from the button area. You will be asked to confirm the operation.
The following tables list the default buttons in the button modules and the corresponding monitor command. See Cmicro Tester Commands for more information.
|
Note: The buttons in the button modules are specified in the button definition file. If the default button file is not used, the button modules may differ from those described here. See Button and Menu Definitions for more information. |
| Button | Cmicro Tester command |
|---|---|
|
Send without params |
|
|
Send with params |
| Button | Cmicro Tester command |
|---|---|
|
Go-Forever |
| Button | Cmicro Tester command |
|---|---|
|
Queue |
|
|
Process |
|
|
Last Error |
|
|
Timers |
|
|
Process List |
|
|
Active |
|
|
Profile |
| Button | Cmicro Tester command |
|---|---|
|
Set Timer |
|
|
Reset Timer |
|
|
Create |
|
|
Stop |
|
|
Nextstate |
|
|
Remove Q |
|
|
Remove S |
|
|
Remove all S |
|
|
Scale Timers |
| Button | Cmicro Tester command |
|---|---|
|
Display on |
|
|
Display off |
|
|
Show Params |
|
|
Start MSC |
|
|
Stop MSC |
|
|
Hide Params |
|
|
Start SDLE |
|
|
Stop SDLE |
| Button | Cmicro Tester command |
|---|---|
|
Inputfile |
|
|
Outputfile |
|
|
Close file |
|
|
ASCII Outfile |
|
|
Close ASCII |
|
|
Page File |
|
|
To ASCII |
| Button | Cmicro Tester command |
|---|---|
|
Trace off |
|
|
Trace on |
|
|
Trace Detail |
|
|
Trace Process |
|
|
Trace Signal |
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
| Button | Cmicro Tester command |
|---|---|
|
Recorder off |
|
|
Record |
|
|
Play |
|
|
Delay |
|
|
Real-time |
|
|
Input recfile |
Input-File recfile.trc |
|
Output recfile |
Output-File recfile.trc |
|
Close recfile |
Close-File recfile.trc |
| Button | Cmicro Tester command |
|---|---|
|
Single-Step |
|
|
Next-Step |
|
|
Exit-Single-Step |
|
|
Reinit |
|
|
Shutdown |
|
|
Resume |
|
|
Disable Timer |
|
|
Enable Timer |
|
|
Suspend |
| Button | Cmicro Tester command |
|---|---|
|
Break input |
|
|
Break nextstate |
|
|
Break all |
|
|
View Breakpoints |
|
|
Clear all |
|
|
Continue |
| Button | Cmicro Tester command |
|---|---|
|
Unit scale |
Unit-Scale 1.0 |
|
Unit name |
Unit-Name "milliseconds" |
|
Target |
This section describes the menu bar of the Cmicro Tester main window and all the available menu choices in the default configuration.
The menu bar contains the following fixed menus:
The menu bar can also contain additional menus listed in a menu definition file (see Button and Menu Definition File). The following menus are defined in the delivered version of this file:
The File menu contains the following menu choices
This menu choice opens a dialog where you can enter the path to your current project directory.
|
Hint: It is recommended to start the BodyBuilder directly from the working (project) directory. In Windows this means to set the correct properties in the shortcut which starts the BodyBuilder. |
The View menu contains the following menu choices:
This menu choice opens a dialog where you can search for text.
|
|
It is possible to use regular expressions for finding text or to select to find a process, signal or timer belonging to the SDL system.
This menu choice will search again for text already found.
This menu choice will search for text currently selected in the Cmicro Tester's text area.
This menu choice will copy the text selected in the Cmicro Tester's text area.
The menu choice will paste the content of the clipboard to the command line.
This menu choice toggles line numbering in the Cmicro Tester's text area. Line numbering allows a better overview.
This menu choice will clear the complete text area of the Cmicro Tester.
The Buttons menu contains the following menu choices:
For more information on the UI's button definition file, mentioned in the menu commands below, see Button and Menu Definition File.
This menu choice opens a dialog where you can specify a new button definition file. This will override the current button definitions. All buttons and modules currently in the button area are deleted and replaced by the buttons and modules defined in the new file.
This menu choice opens a dialog where you can specify to append the the contents of a new button definition file into the current button definitions. Buttons with new labels are added to the button area, while buttons with already existing labels in the same module will be duplicated (possibly with different definitions).
This menu choice saves the current button and module definitions in the button definition file under its current file name.
This menu choice opens a dialog where you can save the current button and module definitions in a new button definition file.
This menu choice expands all modules in the button area.
This menu choice collapses all modules in the button area.
This menu choice opens a dialog where you can specify the of a new button module to add. The new module will be added after the last module in the button area. It is also possible to add several modules.
| Item | Cmicro Tester command |
|---|---|
|
Start Gateway |
|
|
Go-Forever |
|
|
Single-Step |
|
|
Reinit |
|
|
Disable-Timer |
|
|
Next-Step |
|
|
Shutdown |
|
|
Enable Timer |
|
|
Exit-Single-Step |
|
|
Resume |
|
|
Suspend |
| Item | Cmicro Tester command |
|---|---|
|
Send with params |
|
|
Send without params |
| Item | Cmicro Tester command |
|---|---|
|
Break Input |
|
|
View Breakpoints |
|
|
Braek Nextstate |
|
|
Clear all |
|
|
Break all |
|
|
Continue |
| Item | Cmicro Tester command |
|---|---|
|
Queue |
|
|
Timers |
|
|
Active |
|
|
Process |
|
|
Process List |
|
|
Profile |
|
|
Last Error |
| Item | Cmicro Tester command |
|---|---|
|
Set Timer |
|
|
Stop |
|
|
Remove Signal |
|
|
Reset Timer |
|
|
Nextstate |
|
|
Remove all S |
|
|
Create |
|
|
Remove Q |
|
|
Scale Timers |
| Item | Cmicro Tester command |
|---|---|
|
Display on |
|
|
Start MSC |
|
|
Display off |
|
|
Stop MSC |
|
|
Show Params |
|
|
Hide Params |
| Item | Cmicro Tester command |
|---|---|
|
Binary Infile |
|
|
ASCII Outfile |
Start-Trace-Log trace.asc |
|
Page File |
|
|
Binary Outfile |
|
|
Close ASCII |
|
|
Convert File |
|
|
Close Binaries |
| Item | Cmicro Tester command |
|---|---|
|
Trace on |
|
|
Trace off |
|
|
Trace Process |
|
|
Trace Signal |
|
|
Trace Detail |
| Item | Cmicro Tester command |
|---|---|
|
Recorder off |
|
|
Delay |
|
|
Output recfile |
Output-File recfile.trc |
|
Record |
|
|
Realtime |
|
|
Close Recfile |
Close-File recfile.trc |
|
Play |
|
|
Input recfile |
Input-File recfile.trc |
| Item | Cmicro Tester command |
|---|---|
|
Unit scale |
|
|
Unit name |
|
|
Target |
|
|
Coder-Config |
|
|
Interface state |
| Item | Cmicro Tester command |
|---|---|
|
Quick Info |
|
|
Info |
Help * |
|
Remove cmd |
In the Cmicro Tester UI, the button definition information is stored on file (per default this file is named sdtmt.btn), i.e. definitions of button groups and button commands in the main window's button area. Furthermore it is possible to define menu entries.
At start-up of the UI, the file is determined in the following way. If the file name does not contain a directory path, the files are searched for in the following directories:
Once the file has been found, it is read and the contents of the corresponding window are set up. If the file cannot be found, the corresponding window area becomes empty and a selection dialog is opened to enter the required file name.
The text file can contain comment lines starting with the `#' character. Empty lines are not discarded.
|
Note: When a file is read, no checks are made upon the relevance or correctness of the definitions contained in the file. |
The button and menu definitions are stored in a definition file with the default extension .btn. The definitions are divided into groups where each group defines a button module in the main window's button area or a menu in the menu bar.
In the file, a button group has the following syntax:
:[DISPLAY_AS] <entry name> <item label> <definition> <button label> <definition> . . .
The [DISPLAY_AS] prefixes the button group's or menu's name <entry name> and can take three different keywords:
COLLAPSED
A button group is created, initially collapsed.MENU
A new menu is created.The <item label> is the either label of the button in the button module or the label of an menu item.
The <definition> is the Cmicro Tester command that will be executed when the button is pressed/the menu item is selected. The syntax of a button definition is the same as when entering a command textually to the monitor.
Missing parameters at the end of the command will open dialogs for those parameters.
After all there is no limit in the amount of buttons in a button group or the amount of items in a menu entry except the visibility and usability of the buttons/items.
Comparing with the SDT Simulator there is a simple rule of ordering the buttons shown in Figure 569. A new button row is added only if the previous row has got 3 buttons.
Figure 569 : Ordering of the buttons in a button group
|
|
The target library is a mandatory part of the Cmicro Tester. The Cmicro Tester is of no use without the functions and definitions contained within.
In order to use the options of Cmicro Tester's host site, the target library must be configured accordingly.
A lot of defines make it possible to reduce the Cmicro Tester's functions within the target, so that memory requirements can be reduced when necessary.
In the following sections are explanations of the file structure and the application program interface (API) within the target.
The following picture explains the file structure for the Cmicro Testers target library.
Figure 570 : Files of the Cmicro Library
|
|
This file is generated automatically by the Cmicro Code Generator into the directory which is currently active. It contains compilation flags used for the automatic scaling of the Cmicro Library and the generated C code. The file must not be edited by the user.
This file is the central header file in the Cmicro Package. It contains
tmcod.h is an automatically generated file of the Target Message Coder Generator (TMCOD). All the Cmicro Tester command tags and the corresponding parameter structures are defined here. It is strongly recommended not to modify this file.
This file is part of the command interface on the target site. The commands received via the communications link will be performed by this file.
This is the module which exports the functions to encode / decode any message from the Cmicro Protocol.
This module exports the functions which allow the user to define options regarding the tracer, recorder and player components.
Options may be specified to reduce the traffic load of the system, This is important when a slow communications interface is involved and the user wants to test in real-time.
This file is part of the Cmicro Recorder and it contains all the functions for the play mode.
This file is part of the Cmicro Recorder and it contains all the functions for the record mode.
This module exports functions to trace SDL actions. These functions are mainly for the use of the Cmicro Kernel and Tester.
Functions to trace either into RAM, into a file or via a V.24 interface are delivered.
The module is common for all these trace methods. The functions exported are called directly by the Cmicro Kernel if the Cmicro Tester or part of the Cmicro Tester is involved when executing the SDL system.
This module contains the functions which handle the trace of system events such as scheduler events or the trace of system errors.
These header files contain the external definitions of the corresponding .c files.
The C application program interface (API) can be used both by SDL processes and / or by any other C function on the target.
The simplest method, however, is to set some options before initializing the SDL system and hold these options during the whole run-time. A more comfortable method is to set some options before initializing the SDL system and then change the options in an SDL process, when a specific situation is detected. By using this method it is possible to reduce the amount of information and to make it easier to find unwanted behavior or an erroneous situation in a trace. This can be achieved, for example, by writing the necessary C function call(s) into an SDL task symbol using the #CODE directive.
The following pages introduce the C function interface, which is used in the target to set the trace options.
|
It is important to take care with function parameters. Any function return value should also be checked. |
void xmk_InitOptions ( void )
Initialization of the Cmicro Tester is absolutely necessary. It must be done before any other initialization, directly before the C function call xmk_InitSDL. The user should not remove this function call in the template main() function if one wants to use the Cmicro Tester.
Nothing happens before the C function xmk_OptionsSymbol is called, and xmk_TracerActive is set to XMK_TRUE.
In order to get an execution trace it is first necessary to switch it on by assigning
xmk_TracerActive = XMK_TRUE
This should normally be done after the C function xmk_InitOptions.
The settings of functions whose names begin with xmk_Options* remains unaffected when changing the above flag.
The flag is not set by default.
xmk_OPT_INT xmk_OptionsSymbol ( unsigned char process-type-id,
long bitmask )
This function must be called in order to begin the trace. By default, no symbol is selected.
Select the trace for process-type-id and then set or unset different symbols with the bit mask. If anything goes wrong the function will return XMK_ERROR, else XMK_OKAY.
It is possible to specify bit mask values for a specific SDL process, for all SDL processes, for the environment and for the kernel part of the Cmicro Library. The last possibility is necessary to allow the optional trace for system events like error trace and trace of scheduling events.
Allowed values for process-type-id:
Allowed values for bit mask:
xmk_OPT_INT xmk_OptionsSignal ( xmk_T_SIGNAL signal id,
unsigned char bitmask )
This function is optionally called because the trace of all SDL signals is switched on per default.
Select the trace for signal id. Then set or unset different symbols with bit mask. If anything went wrong, the function will return XMK_ERROR, else XMK_OKAY.
It is possible to specify either "off" for all signals, "on" for all signals, "off" for a specific signal or "on" for a specific signal.
Allowed values for signal-id:
|
0 |
First signal-id, #define from generated C code and |
|
1 |
Second..... |
|
N-1 |
Last..... |
|
XMK_ALLOW_NO |
Specify trace for all processes |
|
XMK_ALLOW_ALL |
Specify trace for Cmicro Kernel |
Allowed values for bitmask:
0x00 to 0xff. 0x00 switches the trace for the signal on. 0x00 causes the trace for the given signal(s) to be switched off.A simple method to set the trace options is to set them directly within the C function main, before the Cmicro Kernel is initialized. The user will find this example as a template in the file bare_ex.c delivered with the Cmicro Package, below the directory <sdtdir>/cmicro/template.
#include "sdl_cfg.h"
#include "ml_typ.h"
... main ( ... ) {
extern int xmk_TracerActive ;
long bitmask = 0 ;
int result = XMK_OKAY ;
/* Initialize Cmicro Tester */
xmk_InitOptions ( );
/* Set all options ON */
result = xmk_OptionsSymbol (xNULLPID, 0xffffffff);
if (result != XMK_OKAY) ErrorInUsage ();
/* Set some options ON */
bitmask = TSDL_INPUT ;
bitmask = TSDL_STATE ;
bitmask = TSDL_OUTPUT ;
/* +---- Proces-Type - Id (see automatically */
/* | generated file *.ifc) */
/* V */
result = xmk_OptionsSymbol (0, bitmask );
if (result != XMK_OKAY) ErrorInUsage ();
result = xmk_OptionsSymbol (1, 0x00000000 );
if (result != XMK_OKAY) ErrorInUsage ();
/* S w i t c h o n t h e t r a c e */
xmk_TracerActive = XMK_TRUE ;
/* Template to set options to filter signals */
/* */
/* +---- Allow all Signals to be traced */
/* V */
xmk_OptionsSignal (XMK_ALLOW_NO, 0);
/* +---- Signal id is to be set correctly ! */
/* | according to the automatically */
/* | generated *.ifc - file */
/* V */
xmk_OptionsSignal (1, 0xff);
xmk_OptionsSignal (2, 0xff);
xmk_OptionsSignal (3, 0xff);
/* I n i t i a l i z e C m i c r o K e r n e l */
xmk_InitSDL ()
/* R u n C m i c r o K e r n e l */
if (xmk_RunSDL (0xff) != XMK_STOP);
exit (0);
}
The Cmicro Code Generator generates usable traces for SDL tasks only if it is a task containing at least one SDL assignment. Whenever C code is specified within a task symbol (by using the #CODE directive), the Cmicro Code Generator is not able to generate good trace information.
There are two C functions which enable a work-around:
xmk_PrintString (const char *) or xmk_TSDL_Task (const char *)in order to get a trace from C code. The trace output of a call like
xmk_PrintString ('Hello SDL world')
looks like:
USER: Hello SDL world
The strings have to be unique, in order to distinguish a trace of one process from another. Another difference between the above function is that the C function xmk_PrintString does not check if a trace is wanted or not. The trace will be done unconditionally via the Cmicro Tester's communications link.
Of course, the function may also be applied in non SDL program parts.
xmk_OPT_INT xmk_SetRecorderMode ( int mode )
This function must be called by the user in order to:
Allowed values for mode:
XMK_RECORDER_RECORDXMK_RECORDER_PLAYXMK_RECORDER_OFFvoid xInEnv ( void )
This function is called each time the Cmicro Kernel's main loop is entered. A more detailed description of the C function xInEnv() can be found in xInEnv().
int xOutEnv ( xmk_T_SIGNAL sig,
xmk_T_PRIO prio,
xmk_T_MESS_LENGTH data_len,
void *p_data,
xPID Receiver
This function is called each time the SDL system wants to output a signal to the environment. If the environment should be another system (e.g., an MS DOS PC), the signal can be sent directly by calling the C function xmk_Cod_Encode (which is described in the following section). A more detailed description of the C function xOutEnv can be found in xOutEnv().
int xmk_Cod_Decode ( char *p_RAWBuffer, In
int *p_MessageClass, Out
int *p_MessageTag, Out
int *p_MessageLength, Out
char *p_dest, In/Out
int dest_len ) In
This function is free to be used on the target site. It decodes a given data link frame in the Cmicro Protocol format into the different pieces of data. MessageClass may be in the range from F3h to FFh. The value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the Cmicro Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.
The function is the counterpart to the C function xmk_Cod_Encode.
int xmk_Cod_Encode ( int MessageClass,
int MessageTag,
char *p_data,
int length )
This function is free to be used on the target site: It encodes the given information into a data link frame of the Cmicro Protocol format and sends it via the communications interface. MessageClass may be in the range from F3h to FFh, the value Fh in the higher nibble is used to synchronize the data stream if synchronization fails and 0h to 2h in the lower nibble is used by the Cmicro Tester itself. MessageTag may be of any value. p_struct is a pointer to a C structure which is to be transferred via the communications link. Struct_length is the result of the sizeof operator being applied to this structure.
The function is the counterpart to the C function xmk_Cod_Decode.
|
Note: The maximum amount of characters which can be transferred is restricted to 255 per default in this Cmicro Package version. |
Some defines are to be set in order to compile and link the parts of the Cmicro Tester correctly. These defines can be set either on the command line when invoking make, or within a make- or makeoptions file or in the header file ml_mcf.h. Be sure that for each configuration possibility all the defines are set appropriately.
The best way to select the compiler options for the Cmicro Tester is to use the BodyBuilder. Please view the section Using the BodyBuilder.
Here is a first idea of what has to be to set in the configuration file ml_mcf.h:
#define XMK_ADD_MICRO_TESTER #define XMK_ADD_MICRO_TRACER #define XMK_USE_V24 #define XMK_USE_COMMUNICATION
In order to reduce the amount of memory - e.g. if memory gets scarce within a progressing project - it is possible to reduce the Cmicro Tester's functionality on target site.
It is quite simple to remove any functionality used by the Cmicro Tester by specifying:
#undef XMK_ADD_MICRO_TESTER
This is possible by specifying
#define XMK_ADD_MICRO_TESTER. #undef XMK_ADD_MICRO_TRACER
This is possible by specifying
#define XMK_ADD_MICRO_TESTER. #undef XMK_ADD_MICRO_RECORDER
This is possible by specifying
#define XMK_ADD_MICRO_TESTER. #undef XMK_ADD_MICRO_COMMAND
Partial functionality may be left out by undefining one of the defines described under Message Transfer and Presentation of Messages.
Users must configure buffers used by the Cmicro Tester.
The reason behind this is that the Cmicro Tester uses an efficient way to handle those buffers. This is of great importance especially for microcontrollers.
Additionally, these buffers must be consistently dimensioned. For instance, the message buffer of the communications link must be able to handle the largest parameter list of a signal from SDL. The same situation arises in the trace of SDL tasks and procedure names.
|
If any buffer is dimensioned too small a run-time error may result. |
The following defines are used to dimension buffers.
This define restricts the amount of characters transferred via the communications link when using the C function xmk_PrintString. This function is used only by the user.
This define is used to restrict the amount of characters transferred via the communications link for the SDL tasks and SDL procedure names.
The transmit and receive buffers of the default communications link software must be configured in the data link (dl) module using the following defines:
Transmitter buffer:
#define XMK_MAX_SEND_ONE_ENTRY 80 #define XMK_MAX_SEND_ENTRIES 100
Receiver buffer:
#define XMK_MAX_RECEIVE_ONE_ENTRY 80 #define XMK_MAX_RECEIVE_ENTRIES 100
where *_ONE_ENTRY is the dimensioning of one message, and *_ENTRIES is the maximum amount of entries in the message FIFO of the data link module. Note, that *_ONE_ENTRY must be greater than the greatest of the XMK_MAX_* defines above, plus a reserve of 6 bytes.
The following sections will detail the technical requirements and the technical implementation of the connection between host and target. The following items will be outlined:
This is the structure for the communications link software, which is - in principle - applicable for host, as well as for target site:
Figure 571 : Structure of the communications link software
|
|
The following subsections describe the current implementation and how to implement a new communications link software.
For all the commands and messages, there is a small state machine to handle the correct transfer of information. All messages, which have the suffix _REQ (request) in their name (message tag) are to be confirmed from the target with one of the _CNF (confirmation) messages. (See the file tmcod.h, where all message tags are defined).
For messages which take parameters, there is always (no exception) a special _CNF message which carries the response parameters back to the requestor. The requestor is usually the host.
For the messages, which do not carry parameters, a positive confirmation is done via the message CMD_OKAY_CNF.
If a message cannot be recognized or processed within the target, a negative confirmation CMD_ERROR_CNF is used in all cases.
Each _REQ message must be confirmed before the next one can be sent.
Messages with an _IND (indication) suffix are mostly sent from target to host in order to indicate a specific situation. For these messages, the sender is always the originator.
The following subsections give a complete list of messages which can be sent to and received from the target.
Each typedef shown below is packed into a data link frame in its target representation.
That means a memcpy (destbuffer,struct,sizeof(struct)) is performed to copy a structure to/from the data link frame.
On host site, it is therefore necessary to perform message encoding and message decoding.
All messages belonging to the Cmicro Tracer are part of the message class XMK_MICRO_TRACER (F1h).
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Task Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TTASK Conditional compile:XMK_ADD_TTASKMessage description: The message is sent when a task symbol is entered in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Set Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TSET Conditional compile:XMK_ADD_TSETMessage description: The message is sent when a timer set is performed in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Reset Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TRESET Conditional compile:XMK_ADD_TRESETMessage description: The message is sent when a timer reset is performed in generated C Code and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Stop Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TSTOP Conditional compile:XMK_ADD_TSTOPMessage description: The message is sent when an SDL process stop is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL State Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TSTATE Conditional compile:XMK_ADD_TSTATEMessage description: The message is sent when an SDL nextstate is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Static create Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TSTATIC_CREATE Conditional compile:XMK_ADD_TSTATICCREATEMessage description: The message is sent for each statically created SDL process for which the start transition is executed and for which the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Create Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TCREATE Conditional compile:XMK_ADD_TCREATEMessage description: The message is sent when the SDL action create is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Dynamic create Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TDYNAMIC_CREATE Conditional compile:XMK_ADD_TDYNAMICCREATEMessage description: The message is sent for each dynamically created SDL process, when its start transition is executed, and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Decision Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TDECISION Conditional compile:XMK_ADD_TDecisionValueMessage description: The message is sent when an SDL decision is executed and the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Save Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TSAVE Conditional compile:XMK_ADD_TSAVEMessage description: The message is sent when a signal save is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Timer Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TTIMER Conditional compile:XMK_ADD_TTIMERMessage description: The message is sent when an SDL timer has expired and is input into the owner process and the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Input Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TINPUT Conditional compile:XMK_ADD_TINPUTMessage description: The message is sent when an SDL input is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Procedure Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TPROCEDURE Conditional compile:XMK_ADD_TNAMEMessage description: The message is sent when an SDL procedure is entered and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Output Sent when :Execution of that SDL symbol Direction :T->H Typedefinition :xmk_T_CMD_TOUTPUT Conditional compile:XMK_ADD_TOUTPUTMessage description: The message is sent when an SDL output is performed and the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Discard Sent when :Execution of that SDL symbol Direction :T->H Typdefinition :xmk_T_CMD_TDISCARD Conditional compile:XMK_ADD_TDISCARDMessage description: The message is sent when an SDL discard has been detected and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :User command Print string Sent when :Execution of fct.xmk_PrintString() Direction :T->H Typedefinition :xmk_T_CMD_PRINT_STRING Conditional compile:XMK_ADD_CPRINT_STRINGMessage description: The message is sent unconditionally, when the C function
xmk_PrintString is called by the user.Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Implicit consumption Sent when :Implicit consumption occurs Direction :T->H Typdefinition :xmk_T_CMD_TIMPLICIT_CONSUMTION Conditional compile:XMK_ADD_TIMPLICIT_CONSUMPTIONMessage description: The message is sent when an SDL implicit consumption is performed and when the trace is set for this symbol. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of SDL Actual reset Sent when :SDL timer is actually reset Direction :T->H Typedefinition :xmk_T_CMD_TACTUAL_RESET Conditional compile:XMK_ADD_TACTUAL_RESETMessage description: The message is sent when an SDL timer is actually reset and the trace is set for this symbol. Furthermore, the trace must be active. An actual reset applies only if a timer was previously set and has not expired.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of system error Sent when :Any kind of systemerror was detected Direction :T->H Typedefinition :xmk_T_CMD_TSYS_ERROR Conditional compile:XMK_ADD_TERRORMessage description: The message is sent when a system error of any type has been detected and the trace is set for this event. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of system schedule event Sent when :When scheduling is performed Direction :T->H Typedefinition :xmk_T_CMD_TSYS_SCHEDULE Conditional compile:XMK_ADD_TSCHEDULEMessage description: The message is sent when the Cmicro Kernel begins scheduling and the trace is set for this event. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Trace of system event : change priority level Sent when :When changing to another prioritylevel Direction :T->H Typedefinition :xmk_T_CMD_TSYS_SHOWPRIO Conditional compile:XMK_ADD_TSHOWPRIOMessage description: The message is sent when the Cmicro Kernel schedules from one priority level to another and the trace is set for this event. Furthermore, the trace must be active.
Messageclass :XMK_MICRO_TRACER Meaning :Another symbol than input is executed Sent when :Another symbol than input is executed Direction :T->H Typedefinition :xmk_T_CMD_TBETWEEN_SYMBOL Conditional compile:XMK_ADD_SDLE_TRACEMessage description: With this command the process ID of the current executed process is sent and a system wide unique identifier. The Cmicro Tester can force the SDL Editor to highlight the current SDL symbol.
Messageclass :XMK_MICRO_TRACER Meaning :An Input symbol has bee executed Sent when :An Input symbol is executed Direction :T->H Typedefinition :xmk_T_CMD_TAT_FIRST_SYMBOL Conditional compile:XMK_ADD_SDLE_TRACEMessage description: Similar like CMD_TBETWEEN_SYMBOLS the currently executed SDL input symbol will be highlighted in the SDL Editor.
All messages belonging to the Cmicro Recorder are part of the message class XMK_MICRO_RECORDER (F2h).
Messageclass :XMK_MICRO_RECORDER Meaning :Show recorded event counter to host Sent when :When ENV->SDL stimuli detected Direction :T->H Typedefinition :xmk_CMD_RECORD_COUNT_IND Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: The message is sent when the Cmicro Recorder is active and is in record mode. It is sent together with, but always before
CMD_RECORD_OUTPUT_ENV2SDL.Messageclass :XMK_MICRO_RECORDER Meaning :Indicate stimuli ENV->SDL to host Sent when :When ENV->SDL stimuli detected Direction :T->H Typedefinition :xmk_T_CMD_RECORD_OUTPUT_ENV2SDL Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: The message is sent when the Cmicro Recorder is active and is in record mode. It is sent after
CMD_RECORD_COUNT_IND.Messageclass :XMK_MICRO_RECORDER Meaning :unused Sent when :- Direction :T->H Typedefinition :- Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: This message is currently unused and is never sent.
Messageclass :XMK_MICRO_RECORDER Meaning :Request next sections from host Sent when :When current cnt reaches debit cnt Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent if the target has to put in the next stimuli (an environment signal).
Messageclass :XMK_MICRO_RECORDER Meaning :Transfer Debitcounter to target Sent when :When target requests next sections Direction :H->T Typedefinition :xmk_T_CMD_PLAY_COUNT Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent if the target requests the next stimuli (an environment signal). It is also sent in the initialization phase of the play mode. Outside the initialization phase, it is always sent together with, but after
CMD_PLAY_OUTPUT_ENV2SDL.Messageclass :XMK_MICRO_RECORDER Meaning :Transfer stimuli ENV->SDL to target Sent when :When target requests next sections Direction :H->T Typedefinition :xmk_T_CMD_PLAY_OUTPUT_ENV2SDL Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent together with
CMD_PLAY_COUNT but always before CMD_PLAY_COUNT if the target request the next stimuli (an environment signal).Messageclass :XMK_MICRO_RECORDER Meaning :unused Sent when :- Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: This message is currently unused and is never sent.
Messageclass :XMK_MICRO_RECORDER Meaning :Switch off recorder Sent when :When at end of replay session detected Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_MICRO_RECORDERMessage description: This message is sent if the host detected an end of file after the target has requested the next stimuli (an environment signal). It switches the Cmicro Recorder within the target off and execution returns from simulation to real-time.
All messages belonging to the Cmicro Commands are part of the message class XMK_MICRO_COMMAND (F0h).
Messageclass :XMK_MICRO_COMMAND Meaning :Suspend Cmicro Kernel Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CSUSPENDMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Resume Cmicro Kernel Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CRESUMEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Reinitialize SDL system Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CREINITMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Shutdown SDL system Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CSHUTDOWNMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Go into single step Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CSINGLE_STEPMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Disable processing of timers Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CDISABLE_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Enable processing of timers Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CENABLE_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Execute next step Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CNEXT_STEPMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Continue system, if halted Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CCONTINUEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Set breakpoint Sent when :User typed in command Direction :H->T Typedefinition :xmk_T__CMD_SET_BREAKPOINT_REQ Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is send if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Set breakpoint on SDL input Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_BREAK_INPUT_REQ Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Set breakpoint on nextstate Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_BREAK_STATE_REQ Conditional compile:XMK_ADD_CBREAK_STATEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Clear specified breakpoint from list Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_CLEAR_BREAKPOINT_REQ Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Clear all breakpoints Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query the breakpoint list Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query last error occured in system Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CQUERY_ERRORMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Modify processstate to value Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_NEXT_STATE_REQ Conditional compile:XMK_ADD_CNEXTSTATEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Create SDL process Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_CREATE_PROCESS_REQ Conditional compile:XMK_ADD_CCREATE_PROCESSMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query Tracebuffer Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CTBUFMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Kill process Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_KILL_PROCESS_REQ Conditional compile:XMK_USE_CMD_KILL&XMK_ADD_CKILL_PROCESSMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Define PCO Sent when :unused Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is currently not implemented and is never sent.
Messageclass :XMK_MICRO_COMMAND Meaning :Query process state Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_QUERY_PROCESS_REQ Conditional compile:XMK_ADD_CQUERY_PROCESSMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query all queues Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CQUERY_QUEUEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Flush all queues Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CRM_QUEUEMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Set SDL timer Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_SET_TIMER_REQ Conditional compile:XMK_ADD_CSET_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Reset SDL timer Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_RESET_TIMER_REQ Conditional compile:XMK_ADD_CRESET_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query timertables Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:XMK_ADD_CQUERY_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Query, if timer active Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_ACTIVE_TIMER_REQ Conditional compile:XMK_ADD_CACTIVE_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Flush signals with given ID Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_FLUSH_SIGNAL_BY_SID_REQ Conditional compile:XMK_ADD_CFLUSH_SIGNAL_BY_SIDMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Flush signals of process Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_FLUSH_SIGNALS_BY_PID_REQ Conditional compile:XMK_ADD_CFLUSH_SIGNALS_BY_PIDMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Reset all timers Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_RESET_ALL_TIMERS_REQ Conditional compile:XMK_ADD_CRESET_ALL_TIMERSMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Scale timers Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_SCALE_TIMER_REQ Conditional compile:XMK_ADD_CSCALE_TIMERMessage description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Starts the SDL system Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_START_SDL_REQ Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Sends a signal from the environment Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_OUTPUT_TO_REQ Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Sends an internal signal Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Gets the target's configuration Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Switch recorder off Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Switch recorder to play mode Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Switch recorder to record mode Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Switch trace on in general Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Switch trace off in general Sent when :User typed in command Direction :H->T Typedefinition :- Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Modify traceoptions for process Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_TRACE_PROCESS Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Modify traceoptions for signal Sent when :User typed in command Direction :H->T Typedefinition :xmk_T_CMD_TRACE_SIGNAL Conditional compile:-Message description: This message is sent if the user typed in the appropriate command.
Messageclass :XMK_MICRO_COMMAND Meaning :Indicate breakpoint hit to host Sent when :Breakpoint hit in target Direction :T->H Typedefinition :xmk_T_CMD_BREAK_HIT_IND Conditional compile:XMK_ADD_CBREAK_LOGICMessage description: This message is sent if one of the breakpoints defined in the breaklist has been hit. The SDL system is halted and waits on the next commands from that point on.
Messageclass :XMK_MICRO_COMMAND Meaning :Negative acknowledge on command Sent when :A command couldn't be executed Direction :T->H Typedefinition :- Conditional compile:-Message description: This message is sent if the target was not able to respond to a command from the user.
Messageclass :XMK_MICRO_COMMAND Meaning :Indicate Tracebuffercontents Sent when :Response to user command Direction :T->H Typedefinition :- Conditional compile:-Message description: This message is currently not implemented and will never be sent.
Messageclass :XMK_MICRO_COMMAND Meaning :Command acknowledge Sent when :Command correctly executed Direction :T->H Typedefinition :- Conditional compile:unconditionalMessage description: This message is sent from target to host as a response for all commands which do not carry parameters of any kind. It is used within the host library as a general confirmation of most messages.
Messageclass :XMK_MICRO_COMMAND Meaning :Indicate process state Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_QUERY_PROCESS_CNF Conditional compile:XMK_ADD_CQUERY_PROCESSMessage description: This message is sent as a reaction to the message
CMD_QUERY_PROCESS_REQ. It carries information about the process state.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate queue states Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_QUERY_QUEUE_CNF Conditional compile:XMK_ADD_CQUERY_QUEUEMessage description: This message is sent as a reaction to the message
CMD_QUERY_QUEUE_REQ. It carries information about the queue state.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate timer table Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_QUERY_TIMER_CNF Conditional compile:XMK_ADD_CQUERY_TIMERMessage description: This message is sent as a reaction to the message
CMD_QUERY_TIMER_REQ. It carries information about the timer tables.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate, if timer is active Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_ACTIVE_TIMER_CNF Conditional compile:XMK_ADD_CACTIVE_TIMERMessage description: This message is sent as a reaction to the message
CMD_ACTIVE_PROCESS_REQ. It carries information about the state of a timer according to SDL semantics.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate breaklist to host Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_QUERY_BREAKPOINT_CNF Conditional compile:-Message description: This message is sent as a reaction to the command
CMD_QUERY_BREAKPOINT_REQ. It carries the breaklist from target to host.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate last error occured Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_QUERY_ERROR_CNF Conditional compile:-Message description: This message is sent as a reaction to the message
CMD_QUERY_ERROR_REQ. It carries information about the last error which has occurred in the target.Messageclass :XMK_MICRO_COMMAND Meaning :Indicate ready for configuration Sent when :Response to user command Direction :T->H Typedefinition :- Conditional compile:-Message description: This message is sent when the target is ready for configuration from the host. In this state the target's SDL system is not initialized.
Messageclass :XMK_MICRO_COMMAND Meaning :Confirm SDL system start Sent when :Response to user command Direction :T->H Typedefinition :- Conditional compile:-Message description: This message is sent as a reaction to the message
CMD_START_SDL_REQ.Messageclass :XMK_MICRO_COMMAND Meaning :Send target's configuration Sent when :Response to user command Direction :T->H Typedefinition :xmk_GET_CONFIG_IND Conditional compile:-Message description: This is the first message which shows the target configuration. This means the scaling configuration (
ml_mcf.h) as well as run-time configuration.Messageclass :XMK_MICRO_COMMAND Meaning : Sent when :Response to user command Direction :T->H Typedefinition :xmk_T_CMD_GET_CONFIG_CNF Conditional compile:-Message description: This message is the reply message to the host's
CMD_GET_CONFIG_REQ. It sends the same information as CMD_GET_CONFIG_IND.The data link part of the communications link is represented by the data link module and the coder module. The coder module ensures that each data link frame is encoded / decoded according to definitions of the default protocol.
Each frame of the Cmicro Protocol is seen from the physical layer as binary data.
Each frame consists of the following items:
Message Class
Used to classify the information (is it Cmicro Tester or User defined data?). The codes F3h to FFh are free to use by the user, the other ones are reserved for the Cmicro Tester.Message Tag
Used to differentiate the different information either of the Cmicro Tester or the user defined data. For user defined data, the message tag is free to use. If more than 255 bytes are to be transferred, the most significant bit of the message tag is set, otherwise it is cleared. This means there are up to 128 free codings for the message tag.SYNC
Fixed marker 0xaa is used to check if the receiver is synchronized with the sender. This is to detect problems in the start-up phase of host and target. This field of the message header is used in combination with the message class (>= F0h) to resynchronize the data stream in the host's data link layer (sdtgate).Message Length
Used to store the information about how many bytes are to follow after the length information, excluding the CRC information.Data
Free formatted data (user data or data for the Cmicro Tester)Checksum
Used to check if the frame is OK on the receiving site. The checksum is built beginning from tag1 to the last data byte by a modulo-8 operation. The sync byte is included in the CRC.The following is an example of a coded Cmicro Protocol frame for a MS DOS PC, where the messagetag is coded as CMD_TSTATIC_CREATE. Note this is only an example and the real coding may be different.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The functions described in The API on Target can be used to encode / decode these frames.
The data link of the communications link usually handles the separately message transfer of information from host and to host.
The data link uses the services and functions of the physical layer in order to transmit and receive information.
The data link offers functionality that makes it possible to send and to receive messages via the physical layer assigned to the data link. This functionality can be used by all programs (if implemented so). Mainly it is the Cmicro Tester which uses the data link layer services in order to send and to receive messages. But the users may want to send and receive messages, too. This is possible by using the data link layer functions and by regarding the defined protocol used for each message.
The data link layer offers the following functionality:
The data link layer is represented by the following functions, which are exported by the data link (dl) module.
The Cmicro Tester's target library uses the following C functions of the template dl.c. The body of each C function may be rewritten according to the users needs.
These functions are fixed into the Cmicro Tester's data link layer and they handle the mapping and the access to the physical layer.
Any type of physical communications link can be used to connect host and target, e.g. it could be a V.24 or IEEE 488 interface or it could be any other serial or parallel interface.
The physical layer of the communications link normally handles the bytewise transfer of messages from host to target and the other way around.
It uses the services of the underlaying hardware like interrupts, CPU registers or memory mapped I/O.
The physical layer offers functionality to the data link layer in order to make it possible to transfer any kind of information, including Cmicro Tester data and / or user data.
The physical layer offers the following functionality:
As described above the data link layer of the Cmicro Tester's target library is shown in the files mt_cod.c and dl.c. Please note that dl.c is only a template with a default implementation for the connection between data link and physical layer.
Distributed with the Cmicro Tester's target library, there are several template files for the physical layer (V.24 interfaces) contained in the cmicro/template/commlink directory in the installation directory. These template files are tested only for the specific hardware in the Cmicro Package test environments. An error free compilation or execution cannot be guaranteed for the user's target hardware.
There are physical layer templates for the following target hardware:
For use in the target executable, one of the modules listed above is automatically included in dl.c. Which physical layer module is included depends on the compiler selected and the flags set in ml_mcf.h (e.g. XMK_USE_V24).
The template module dl.c works as follows:
The function xmk_DLInit initializes the buffers used for the data link and calls the initialization of the physical layer (by default this is xmk_V24Init).
xmk_DLDeinit is the counterpart of xmk_DLInit and frees the interface device. This function is normally empty in microcontroller applications but has to be used on PCs, under Microsoft Windows or UNIX.
xmk_DLWrite is called when a complete frame should be sent to the host. There are two ways the connection to the physical layer can be handled.
dl.c (for the compilers KEIL_C51 and IARC51) to get an idea of this connection.XMK_MAX_SEND_ENTRIES) the data link will still have to wait here. Also the size allowed for the ring buffer's entries must be great enough (to verify this see the macro XMK_MAX_SEND_ONE_ENTRY.xmk_DLRead will be polled with each cycle of the SDL loop xmk_RunSDL (see module mk_main.c). If the transmitter and the receiver of the physical layer are not implemented as interrupt service routines (which is strongly recommended) the transmit and receive functions have to be called here (xmk_V24Receive and xmk_V24Transmit for the distributed V.24 templates). In addition for the V.24 interface the XON handshake has to be called here doing xmk_V24Handshake.
As in xmk_DLWrite there are two ways the receiver buffers can be handled in xmk_DLRead. It is also possible to use a ringbuffer for the receiver's side. Similar as in xmk_DLWrite it is necessary to fill the macros XMK_MAX_RECEIVE_ONE_ENTRY and XMK_MAX_RECEIVE_ENTRIES with useful values.
In the distribution of the Cmicro Package there are several template makefiles.
On UNIX the existing makefile templates are called makeoptions.no_tester and makeoptions.with_tester.
In Windows the existing makefile templates are called makeno_t.opt and makew_t.opt.
The intention is to give one template makefile where the Cmicro Tester is not included (which means that there is no compilation of any Cmicro Tester C code), and to give one template makefile including the Cmicro Tester.
In the template makefiles that include the Cmicro Tester, it is necessary to define the communications link software by adding the name of the C module(s) that contain(s) this. This can be achieved by changing the list of the object files given in sctLINKTARGET_WITH_TESTER (e.g. 8051_v24.suffix). In addition, the compilation rules for this/these additional module(s) must be specified as well in the makefile.
Finally, the makefile name must be changed into makeoptions on UNIX, and into make.opt in Windows.
|
Note: The |
The data link layer for the Cmicro Tester on target site is represented by the module dl.c with the functions
xmk_DLInit()xmk_DLRead()xmk_DLWrite()xmk_DLQuery()xmk_DLDeinit()Several ways to fill these functions are already given in dl.c.
The data link layer can be build using a ring buffer for all the trace message or writing each message directly to the physical layer.
Furthermore the data link layer must be build to work together with the physical layers (E.g. ISR driven or not).
It is recommended to have a look into the distributed template dl.c which shows different ways.
TCC80166.IARC51 or KEIL_C51.IARC51 and KEIL_C51.TCC80166.There are given tested physical layers for the microcontrollers 8051 and 80166.
The structure of these physical layers should be taken and filled with the functions for the needed communications link. E.g. the function to write to a serial interface must be replaced by a function to write to an Ethernet interface.
The sdtgate is one executable of the Cmicro Tester's tool chain on host site. It is built to simplify the communication between the host and the target.
In this release of the Cmicro Tester the sdtgate is built using the V.24 interface, but as the user will see in this subsection it will be very simple to implement any other communication interface as a new executable.
The Cmicro Tester executables sdtmtui, sdtmt and sdtgate communicate with the help of the Cmicro Postmaster. The Cmicro Postmaster handles all the communication between the Cmicro Tester tool chain and is started automatically when the Cmicro Tester is invoked.
There are two groups of fork parameters handed over to the sdtgate.
Inside the Cmicro Tester configuration file sdtmt.opt there are 7 entries for the gateway executable.
USE_GATE <pathname>/sdtgate GATE_CHAR_PARAM_1 /dev/ttya 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
On UNIX, it muse be ensured that the device (/dev/ttya above) is accessible. Ask the system administrator if there are problems to open this device.
USE_GATE <pathname>/sdtgate.exe 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
USE_GATE gives the name of the used gate only.
Inside the delivered sdtgate for V.24 interface only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. For future developments there are 2 further string parameters and two further integer parameters which are handed over when forking the gate.
The delivered version of the sdtgate uses fixed values for parity, start bits, stop bits...
These are: databits = 8, startbits = 1, stopbits = 1, parity = none
There are two coding rule pieces of information the gate needs to work.
These are the length of a character on the target in octets (normally 1) and the position of the character. This value is necessary for special micro controller memory layouts e.g. the MSP58C80 gets the character length of 2 octets but the used character is the lower octet only. In this case the character position is 1. Normally if the character size is 1 the character position is 0.
All the C files and libraries necessary to re-build the default gateway sdtgate are delivered with the Cmicro Tester.
The following files are part of the sdtgate:
cmicro
+ sdtmpm
| + hppa
| | + sdtmlib.a (HP-UX version)
| + sunos5
| | + sdtmlib.a (SunOS 5 version)
| + wini386
| + sdtmpmbc.lib (Borland C++ version)
| + sdtmpmcl.lib (Microsoft C++ version)
+ mcod
| + mcodfnc.[ch]pp
| + mcodlib.[ch]pp
| + mcod.h
+ sdtgate
| + mg_ctrl.[ch]
| + sdtgate.rc (Windows only)
| + hppa
| | + sdtgate.[ch] (HP-UX version)
| + sunos5
| | + sdtgate.[ch] (SunOS 5 version)
| + wini386
| + sdtgate.[ch] (Windows version)
+ template
+ commlink
+ <interface>.[ch]
Files with suffix .h and .hpp are not listed but are still being used.
<interface> stands for the selected interface type.
On UNIX the module ux_v24.c is used.
In Windows the module win32v24.c is used.
The purpose of each module is as follows:
mcodlib.cpp this file is generated by MCOD too. It contains all MessageTags for the communication between sdtmtui, sdtmt and sdtgate and no modifications are to be done here. mcodlib.cpp and mcodfnc.cpp there is no need to make any modification inside this module because the communication between the different parts of the tool chain depends on it.makefile.template in the directory $sdtdir/cmicro/sdtgate as a template to compile and link his own gateway. With the help of the BodyBuilder, and within the user's compiler section (ml_typ.h, user_cc.h), the following settings are to be made:_GCC_XMK_UNIXSDTGATEXMK_USE_V24 (for the default gateway sdtgate) sdtgate.ide that the user may use to compile and link his own gateway with the Borland compiler. With the help of the BodyBuilder, and within the user's compiler section (ml_typ.h, user_cc.h), the following settings are to be made:BORLAND_C or MICROSOFT_CXMK_WINDOWSSDTGATE__NT__XMK_USE_V24 (for the default gateway sdtgate)It is impossible to transfer pointer values via the communications link. An example may be the SDL predefined sort charstring which is by default implemented as a pointer in C.
To avoid problems, users must not use SDL sorts that are implemented as pointers (like charstring), whenever it is required to send / receive them via the communications link (e.g. Cmicro Tracer or Cmicro Recorder functionality). This means, that this kind of sorts should only be used in signals inside the SDL system but not at it's environment.
The maximum length of the message length is restricted.
An explanation follows:
Each message is transferred as:
Header + Data + CRC
The length field contained in the header may represent the values from 0 to 255. If the MSB in the message tag is set to "1", then the length field is expected to be a 2 octet values, which makes it possible to represent the value from 256 to 65535.
However, the length field consisting of 2 octets is currently not implemented.
In fact, no message may be greater than 4 + 255 + 1 = 260 characters in total (1 character normally is equal to 1 Byte, which consists of 8 Bits).
The Cmicro Tester uses only a few C function calls in order to send and receive information via the communications link. From the C syntax point of view, users only have to implement the body of these functions and to link them together with the Cmicro Tester's target library into one executable program.
However, when considering timing constraints, critical paths, interrupts and similar things, users have to note the following.
Critical paths occur in any type of software which uses interrupts. Especially the transfer of information between ordinary C code and interrupt service routines must be considered, e.g. for the communication from the physical layer (which may be implemented as an ISR) to the data link layer (which may be implemented as ordinary C functions).
Critical paths may occur at any place in the software which accesses global C variables.
The beginning of each critical path must be blocked with something like "disable interrupts" (see XMK_BEGIN_CRITICAL_PATH in the compiler section of ml_typ.h). The end of a critical path must be released with something like "enable interrupts" (see XMK_END_CRITICAL_PATH).
Often there are timing constraints to be considered within the target system. Timing problems must be prevented. Each ISR must be implemented with a few statements only, in order to make the execution time as short as possible.
C functions which should be compiled as ISRs by the C compiler in use are mostly
marked by a preprocessor directive or by a special C compiler keyword. The C compilers reference manual must be consulted in order to implement ISRs.
The open interface can be used to implement user host executables which are able to communicate with the Cmicro Tester at the target site. The Cmicro Tester at the target site is represented by the target library.
In order to use the open interface in this way, the following are of interest:
It is not of great interest what the format of the data link frames is because it is possible either to use the existing protocol or to re-implement the protocol (e.g. it may be necessary in order to integrate the Cmicro Tester into an existing communication link's software).
The host site must send each message in target representation.
For instance, if the target system uses integers as 2 octet values with the ordering higher octet first, then the host must send an integer value with higher octet and then lower octet, irrespective of its own layout.
For the other direction (reception of messages at host site), the host must also map the information according to the relation between the target memory layout and its own internal representation.
The user can send information via the communication link by calling the C function xmk_DLWrite with appropriate parameters. The following example shows one possibility.
#define HelloWorldTag <AnyValueAllowed> char buffer [20]; char helloworld [15]; int length = 0; strcpy (helloworld, 'Hello World'); buffer [0] = 0x11; length ++; /* any value for Messageclass, except */ /* reserved values for Cmicro Tester */ /* reserved values begin from 250 to 255 */ buffer [1] = HelloWorldTag; length ++; /* any value for Messagetag */ /* Messagetag is made unique together */ /* with Messageclass, so that no */ /* conflict occurs. */ buffer [2] = strlen (helloworld); length ++; /* length of data for this message */ /* length is given without calculating */ /* the CRC field */ memcpy (buffer [3], helloworld, strlen (helloworld); length += strlen (helloworld); /* It is assumed, that no stringterminator */ /* is included in the message (the length */ /* can be calculated from Messagelength) */ buffer [length] = xmk_EvalChkSum (buffer, length); /* Evaluate the checksum of current buffer */ xmk_DLWrite (buffer, 5 + strlen (helloworld)); /* transmit buffer via communications link */
The user can receive information from the communication link by calling the C function xmk_DLRead with appropriate parameters.
xmk_RunSDL () The following section is partially implemented within the module mk_main.c
p_data = xmk_DLRead () ;
if (p_data != (char *) NULL)
{
/* if anything received, decode it */
/* according to Cmicro Protocol */
result = xmk_Cod_Decode (p_data,
&MessageClass,
&Messagetag,
&MessageLength,
buffer,
sizeof (buffer));
if (MessageClass == XMK_MICRO_COMMAND)
{
result = xmk_HandleCmd ( Messagetag, (xmk_U_CMDS*) buffer );
return;
}
/*
** Received user message
*/
if (MessageClass != 0xF8)
{
ErrorHandler (-7777);
return ;
}
if (HelloWorldTag == Messagetag)
{
/* HelloWorldTag is used in this example to */
/* identify the hello world message */
/* The user can choose any value for the */
/* Message tag */
char helloworld [15];
memset (helloworld, 0, sizeof (helloworld));
memcpy (helloworld, buffer, MessageLength);
printf ('%s', helloworld);
}
The above examples assume that the Cmicro protocol (which is described in Used Default Protocol) is used.
|
Note: The gateway for the Cmicro Tester connection to the Lauterbach ICE, BDM or Simulator needs an according license. |
This communications link delivers a communication with a target micro controller running on a Lauterbach ICE, BDM or Simulator using the Dual Ported RAM.
The connection is established via sockets between the gateway lautgate and the TRACE32.
config.t32 must have the following entries:RCL=NETASSIST PORT=20000 PACKLEN=1024This file and the environment variable
T32SYS are used by the gateway, too, and read in during the connection process to the TRACE32 sockets. So it is guaranteed that the same socket port and package length is used by the TRACE32 and the gateway.task.config.cmicro menu.rp.cmicroshould be executed in the TRACE32's command line before starting work. This can of course be done from a command file.
The gateway executable for the connection with the Lauterbach emulator TRACE32 communicates with the emulator software and does not have access to the emulator hardware.
The emulator software is polled across a Windows socket port by the gateway. The polling cyclic is fixed to 100 milli seconds.
Like the default communications link solution (sdtgate) this gateway is used as one executable of the Cmicro Tester tool chain on host side.
The fork parameters for the gateway are (see sdtmt.opt):
ICE BDM Simulator
ml_mcf.h)The emulator connection will be selected by setting the flag LAUTERBACH in the file ml_mcf.h. This is normally done by using the BodyBuilder. Please view Communications Link Configuration
ml_mcf.h)The list of C modules to be compiled and linked given in the file makeoptions (on UNIX) or respectively make.opt (in Windows) must be extended by the module laut_emu.c.
Besides this the compilation rule for laut_emu.c has to be defined.
The following steps should be followed if starting the TRACE32 and the Cmicro Tester:
Start-Gateway in the command line.
T32-Command "go" in the Cmicro Tester's command line.After the start-up message is received, the target can be started with the command Go-Forever.
There are several restrictions in the use of the Lauterbach Gateway like
sdtmt.opt against the values of XMK_MAX_SEND_ENTRIES, XMK_MAX_SEND_ONE_ENTRY and XMK_MAX_RECEIVE_ONE_ENTRY of the file ml_mcf.h sdtmt.opt against the values of XMK_MAX_SEND_ENTRIES, XMK_MAX_SEND_ONE_ENTRY and XMK_MAX_RECEIVE_ONE_ENTRY of the file ml_mcf.hThis section deals with the general file format of the different files which are written to or read by the Cmicro 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.
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 which are used by the Cmicro Tester are automatically generated by the Cmicro Code Generator. 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 following table is generated by the Cmicro Code Generator. 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 is generated by the Cmicro Code Generator into a file called <systemname>.sym. This file is to be specified when the host site is invoked (see subsection Invoking the Cmicro 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:
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 BodyBuilder and the Cmicro 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.
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.
The information given in the following sections are valid both for host and target and there is no differentiation made between these.
|
Note: The Cmicro Tester's Record and Play functions are only available if a Cmicro Recorder license is available. |
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.
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]
The occurrence of the following SDL symbols will be "counted" by an internal counter (a C integer variable):
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.
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.
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. |
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.
The target may not transfer information to the host until the host has become active.
Therefore, the Cmicro 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).
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.
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 Cmicro 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.
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.
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.
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).
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.
The modules and functions described in this subsection are used to handle first in-first out buffering, ring buffering, message coding and other possibilities.
This module contains functions to handle first-in first-out buffers and ring buffers.
It is mainly used internally by the Cmicro Tester to write and read trace information into/from a first-in first-out buffer within the RAM.
These functions are also free for users.
Three functions are implemented representing the low level functions. Each entry has to be of the same size, because the handling is in principle similar to an array. The type of each entry is not relevant. In addition, the caller of the functions contained in this module defines the memory for the trace buffer as well as a control structure representing all the internal data and variables necessary to administrate the trace buffer.
As a result, users are free to have more than 1 instance of this buffer type.
This is the header file containing the external definitions of ml_buf.c.
The Cmicro Tester gets the SDT references from the generated file <systemname>.sym in the known form #SDTREF( ... ).
As it is possible to generate an SDL system and to test it on another platform it is possible that the paths contained in each #SDTREF() are not up to date if using the Cmicro Tester.
All the paths in <systemname>.sym must simply be updated.
If the message decoder detects an error there will be a warning like the one shown in Example 485.
**WARNING: There is an inconsitency in the information decoder. This message will be suppressed form now on. Message Class: 241,d Message Tag : 5,d Number of data bytes received=6 Number od data bytes decoded =5 ***Received buffer (32 octets): ***f1 05 aa 06 00 00 00 00 - 01 04 ab ee ee ee ee ee ***ee ee ee ee ee ee ee ee - ee ee ee ee ee ee ee ee
This warning must be interpreted as follows:
CMD_TSTATE. Furthermore there is a structure called xmk_T_CMD_TSTATE. This structure looks liketypedef struct
{
xPID process;
xmk_T_STATE state;
}
CMD_TSTATE
aa -> sync bytexPID and xmk_T_STATE. In the Example 485 the xPID value is an unsigned int and the xmk_T_STATE is an unsigned char.
xmk_T_CMD_TSTATE) which is represented by the 6 data octets received a value for xPID is found like 0x00000000 as an integer is given with the length 4 octets in this example.
|
Note: The kind of C basic type the The size of the C basic type depends on the microcontroller and compiler in use. |
xmk_T_STATE is 0x01, as the length of character is 1 and the alignment of character is 8. Please view Configuration Possibilities of Sdtmt (sdtmt.opt).After all in this example there are 5 bytes (octets) decoded (4+1) and 6 received which leads to the inconsistency in the information decoder.
The user is asked to correct the settings in the file sdtmt.opt to support the Cmicro Tester's host site with the correct information about the target's memory layout.
|
The Example 485 is an exception concerning the inconsistency in the information decoder. The compiler used for this example only knows C structures with a size dividable by two which leads to a message data length of 6. The value 0x04 in the example only represents a filler octet which does not need to be noticed. |