Tooling Documentation

The functionality of TismTool includes:

TismTool uses the concept of a project to store settings for reading an UML model and generating source code. After creating a new project or opening an existing project TismTool parses the content of the specified XMI file. During parsing all kind of static tests check the consistency of the model. Remarks about the consistency are divided in 5 different categories.

A UML model is basically independent of the programming language of the intended application. For this reason, UML supplied type definitions must be translated to the chosen language. TismTool offers the option of a user-defined table to translate a source phrase to a target phrase. The table can also be used for other private translation needs.

TismTool uses -> as a delimiter in parsing triggers, irrespective of the used programming language. In case of C# or Java this delimiter is automatically translated to “.” .

The generated source code for a protocol or an execution environment includes code for components, classes, object instances and ofcourse state machines. A main entry is generated in case of verification/simulation; it will optionally be generated in case of application usage. Files of the RTE are copied to the same directory as the generated sources. This directory might contain source code of optional foreign components. The software development environment of your own choice can be used to compile and link the files, and execute/debug the executable.

The RTE consists of several parts:

  1. Basic definitions of components, classes, ports, fsms and other state machine related elements. The generated source code mostly inherits from these RTE supplied elements.
  2. Thread classes, queues, semaphores, envelopes, etc for enabling interprocess communication between (active) elements.
  3. A logging mechanism with different levels. The class Tsm with static methods Log() and Lgl() is used in particular for output of a verification session. Tsm creates in the execution directory a log file named TismLog_nnnn.txt , where nnnn stands for the first free 4-digit number.
  4. A so called Supervisor with functionality depending on the intended usage.

A Supervisor recursively activates and deactivates components and classes belonging to the generated part of the UML model. The functions called during (de)activation are implemented in class TsmComponent , see also the whitepaper :

Phase

Component function

Class function

Activation

TsmInitialiseAll

TsmInitialise

TsmConnectAll

TsmConnect

TsmPrepareAll

TsmPrepare

TsmRunAll

TsmRun

Deactivation

TsmHaltAll

TsmHalt

TsmCeaseAll

TsmCease

TsmDisconnectAll

TsmDisconnect

TsmTerminateAll

TsmTerminate

All these functions have prototype (for C#) :

public virtual void TsmXyz( object oObject )

Furthermore, each component/class has 2 functions for establishing a connection, namely:

public virtual TsmInterfacePort GetProvidedInterface( string sPortName )

public virtual void SetRequiredInterface( string sPortName, TsmInterfacePort oProvidedInterface )

Foreign components in an execution environment must override these function for establishing a connection. Example implementations are elaborated at the integration page.

Between activation and deactivation the Supervisor invokes an execution function that depends on the intended usage, being a normal application, or simulation, or verification.

Application

After activation, all started threads must remain running until they have finished their task. The Supervisor provides 2 functions to threads for giving information about their status.

public static void Announce()

public static void Abandon()

Function Announce() informs the Supervisor about a thread's existence. Function Abandon() tells that the thread will end. The Supervisor has a simple counting mechanism: when the number of calls to Abandon() equals the number of calls to Announce(), then deactivation takes place. Not every thread needs to announce itself; only a single coordinating thread would suffice. Applications without threads can still be meaningful, as is demonstrated in the Calculator example. To prevent void execution followed by deactivation, the Calculator class overrides its TsmRun() function. At the end of activation the Supervisor blocks itself then when calling such a function.

Overriding the TsmRun() function can best be done in the UML model because of the code generation. The body of TsmRun() may refer to another object to enable implementation using your own software development environment.

Simulation

At simulation, a protocol or an execution environment runs a predefined number of loops or forever. Random choices are made for the possible (native) triggers and for transitions from choice pseudostates. Variation and repetition of the simulation can be steered by the random seed value. The function:

public static void ConfigureSimulation( int iSeed, int iNrLoops )

can be called to configure the execution; parameter iNrLoops = 0 means running forever. A call to this function can best be done inside the body of an overridden TsmPrepare() function of an involved class. However, TismTool already patches the 2 configuration values from the project's options into the generated source files. Making an explicit call is only needed for overriding these values.
In case of a deadlock situation the simulation continues with an empty scenario.

Verification

The verification of a protocol or an execution environment is based on generating all possible execution scenarios. The native triggers are the driving forces of offering stimuli to scenarios. A scenario results in a situation that is characterised by the state configuration of all state machines and of all messages residing in queues. During the verification process erroneous situations can be observed:

Deadlock

there are no native triggers and queues are empty

Livelock

a scenario leads to a situation encountered earlier in that scenario without any need of external stimuli

Unhandled function

there is no trigger in the FSM matching the calling function

Error in SyncReturn

a rendez-vous semaphore is released but there is no blocked caller, or the caller was already unblocked

Queue overflow new message can not be added to a full queue

At the end of the verification a post mortem inspection of states and transitions yields:

Unvisited state

a state that has never been entered

Unvisited transition

a transition that has never been executed

The optional log file (TismLog_nnnn.txt) contains information about the erroneous situation. You can control the amount of information by changing the logging level and marking the logging of states entered / exited.

The verification executable can optionally also log data in a file TismSeq_nnnn.txt , that can be processed by TismTool to generate sequence diagrams of the verification scenarios.

Concurrency protection

A controller might be invoked by multiple clients and/or multiple servers. Concurrent access from such callers should be prevented to avoid corruption of the controller's data, i.e. class variables and state machine administration. The 2 available protection mechanisms in TismTool are based on a mutex and a thread. These mechanisms are deployed at component level. A protection mechanism is applied for the controller's component by the stereotype HasMutex or HasThread. Note that these mechanisms exclude each other. There are 3 protection configurations.

1. No protection

Protection is not needed in the absence of concurrency. Typically, the controller has a single client that invokes function calls sequentially; and the controller does not have callbacks that would be called by lower level components. An example of this configuration is the Calculator demo.

2. Protection by mutex

Each call or callback to a function of one of the provided interfaces of the component has to lock (and unlock) the mutex. This protection mechanism is best suited for a simple controller without subcomponents.

3. Protection by thread

This configuration resembles the previous; each call or callback will be transformed into a message and queued. Messages are processed inside the thread one at a time. Protection is guaranteed because data are accessed only by the threaded component in a sequential way. This protection mechanism is best suited for a complex controller with optional subcomponents.

User Interface

The user interface of TismTool consists of a window with a menu structure and 2 panes.

TismTool u/i

File


New Project

Create a new project; the Project window appears.

Open Project

Open an existing project.

Edit Project

Edit the current project properties.

Save Project

Save the current project.

Save Project As

Save the current project with a new name.

Recent Projects

Select one of the most recent projects (with a maximum of 8).

Refresh

Force parsing again the current UML model and update the pane of targets.

Exit

Exit TismTool.

Generate


Source code

Generate source code for normal application usage.

Source code + main

Generate source code for normal application usage, including an additional main() entrypoint and a commandline parser.

Simulation

Generate source code for the purpose of simulation.

Verification

Generate source code for the purpose of verification.

Check only

Check the consistency of the current UML model without generating source code.

Translation


New

Create a new translation table. Asks for a filename and shows a window for editing the table.

Edit

Edit an existing translation table.

Edit Recent

Select one of the most translation table for editting.

Tools


Report Sequence Diagrams

Asks for the file TismSeq_nnnn.txt to generate sequence diagrams (verification only). These diagrams are very helpful to trace possible errors in the verified state machines.

Extra


About

Show information about TismTool.

The left pane ‘Targets’ presents the hierarchy of protocols and execution environments in the UML model. The meaning of the entries is indicated by icons:

icon

meaning

UML package

Package

UML execution environment

Execution environment

UML protocol

Protocol

The parsing remarks are shown in the right pane under tab ‘Messages’. Each remark contains a clue of the involved UML elements. The remarks are subdivided in 5 categories.

tag

category

description

I

Information

The purpose of this remark is purely informational.

W

Warning

An issue is observed that might possibly be unintended.

E

Error

The problem encountered will probably lead to unwanted behaviour; rework might be needed.

S

Severe

The problem observed will lead to compile and/or run-time errors in the generated source code; rework is strictly needed.

F

Fatal

A problem occurred forcing TismTool to stop parsing prematurely.

The tab ‘Structure’ in the right pane shows a tree of parsed elements recognised by TismTool. Lines preceded by ‘>>>’ indicate references to elements, that are defined already elsewhere in the tree.

Project Window

TismTool project

field

description

Project name

The name of the project is used for the filename of the generated source files and for the namespace.

XMI file

Filename of the input UML model in XMI format.

Output directory

Directory for storing the generated source files.

Programming language

The programming language of the generated source code. Currently, C# , Java , C++ and C are supported.

OSAL directory (C only) Directory with the OSAL function for the target operating system. Currently, Linux and Windows are supported.
If this directory has not yet been specified, then automatically the directory of the Windows OSAL is filled in, being located relatively to the TismTool executable.

Options

Button to open window for setting additional options.

Options Window

TismTool project

field

description

Translation table

Filename of the translation table.

Include (*) The user supplied contents of the given file is pasted depending on the programming language:
C# in <Project name>.cs after the used namespaces
Java in TsmSystem.java after the imported packages
C++ in TsmSystem.h after the included files
C in TsmSystem.h after the included files

To file TismLog_nnnn.txt (*)

Store the logging data in file TismLog_nnnn.txt, where nnnn is replaced with the first free number.

To console (*)

Show the logging data in a console window.
Maximum logging level (*) Logging data with level less than or equal to this maximum are actually logged. Refer to the source code for the used levels.

State enter

Marking the checkbox logs the state when entered.

State exit

Marking the checkbox logs the state when exited.

Maximum queue size (*)

The maximum number of messages that can be stored in an external queue or an internal queue. Exceeding this queue capacity results in a Queue Overflow error. (Only for Verification and Simulation)

Simulation random seed (*) Seed value of random generator for the purpose of repeating a simulation. (Only for Simulation)
Number of simulation loops (*) Maximum number of loop iterations. (Only for Simulation)
To file TismSeq_nnnn.txt for Sequence Diagrams (*)
Store the sequence diagrams logging data in file TismSeq_nnnn.txt, where nnnn is replaced with the first free number. This file is afterwards used for generating sequence diagrams by TismTool.
Create makefiles In case of C or C++ language the makefiles are copied to all directories of generated source code. By default, the makefiles are suitable for a Linux environment. They also contain definitions for a Windows environment, that are commented out. Search in the makefiles for the keywords OS_LINUX and OS_WINDOWS to edit the definitions according to the operating system.

The settings marked by (*) are patched into the generated source files.

Translation Table Window

TismTool project

field

description

Source

Phrase to be replaced.

Target

New phrase.

WholeWord

Marking the checkbox will only translate phrases delimited with non-alphabetic characters.

Up button

Moves a row upwards.

Down button

Moves a row downwards.

Report Sequence Diagrams

TismTool report Sequence Diagrams

field

description

Input file TismSeq_nnnn.txt

Filename of sequence diagrams logging file.

Output directory

Directory for storing the generated scenarios (in SVG format) and the overview file TismSds.html .

Select scenarios

Generate all scenarios or only the scenarios with an error.

Select states

Show or hide the state configurations in the scenarios.

The generated TismSds.html file has a table with rows indicating:

A generated sequence diagram contains additional, non-UML compliant information to ease tracing of the full scenario:

  1. The (grand)parent components of the objects are shown according to the system's decomposition. Class objects are colored cyan; the color of components is vanilla, except for active components being colored purple.
  2. Active components running in their own thread have 2 message queues: an external queue and an internal queue. The external queue forms a boundary between on the one hand the thread's components, and on the other hand the components sending messages to this thread. In fact, the messages are (part of) the interface description of the thread. To highlight the boundary, represented by the external queue, a so called threadline is introduced and visualised as a thick dashed vertical line on the left side of the active component. Optionally, sub-components inside an active component can invoke callback functions to sub-components in the same thread. The involved messages are stored in the internal queue for which a threadline is visualised on the right side of the active component. Note that threadlines are only rendered when they are actually used.
  3. The RTE thread has also 2 queues. Its internal queue, rendered at the right border of the sequence diagram, will receive messages from threadless components, e.g., protocol clients. The RTE external queue receives messages due to NativeTriggers; it will not be rendered.
  4. Synchronous messages to a thread are subject to a rendez-vous mechanism. A call is blocked being indicated by a down-flag; and after encountering a SyncReturn stereotype the call is released, shown by a return message with an up-flag.
  5. Optionally, (hierarchical) states are rendered on the lifelines; compound states are surrounded by rectangles with round corners; submachine states have names followed by a '+' ; orthogonal states have regions separated by dashed lines.
  6. Choices of choice-pseudostates are visualised by a green box containing the text of the satisfied guard.
  7. Errors are shown by a red box with the error text as a clue.
  8. The end of a scenario is marked by a lightblue dashed bar. Calls below the bar have been executed for cleanup purpose, in particular exit-actions of a state.
  9. The numbers of the scenario steps are rendered at the left inside a yellow box. Neighbouring orange boxes show the numbers of parent scenarios.
  10. If a scenario ends with a state configuration equal to another scenario, then the pink box with the latter's number contains a hyperlink to that scenario.
  11. Cycles are indicated by a pink box, and a pink vertical bar on the left border.

A typical example with many of the above features can be seen in this sequence diagram.

Operating system

In principle, TismTool can be used on any operating system. The dependency of system calls in the RTE is limited to functions dealing with threads and semaphores. The required functions are supported in the system libraries of C# and Java. Any dependency on the underlying operating system is shielded by their virtual machine. Unfortunately, no thread/semaphore functions are available in the standard libraries of C++ and C. For C++, the Boost libraries are used having implementations among modern operating systems. Due to the absence of such a de facto library in C a thin OSAL API has been defined for offering thread/semaphore functions. An actual OSAL library must be implemented for each target operating system. Currently, there are OSAL library implementations available for Linux and Windows.

The OSAL implementation has reserved a fixed number of threads and semaphores. You can change these values for your own purpose, since the OSAL source code is free to use. Make a copy of the whole directory, edit the values in OSAL_Gen.h , and then select that new directory in your project settings.

Object orientation

The UML classes, components, ports, states and other data in the RTE and also the generated source code exploit the object orientation paradigm. The applied encapsulation and inheritance is supported in C#, Java, and C++ . However, since C lacks the OO features, additional effort is needed to emulate the object orientation. The following implementation choices have been taken for its realisation:


Note that in case of the C programming language the source code in the UML model can still satisfy the "object oriented" style. TismTool takes care of adapting C source code as follows:

The adaptions are made on a heuristic basis: the C source code is not semantically interpreted. So, it is recommended to use unique field names. An example of this adaptation is given for the Calculator demo, where the KbdClass overrides the TsmRun function :

void TsmRun( void* oObject )
{
KbdInput.TsmRun( rp_calc );
}

The above function is adapted into:

void Cla_0207_0209_TsmRun( struct Cla_0207_0209Struct* this, void* oObject )
{
KbdInput_TsmRun( this->rp_calc );
}

Note that the delimiter "." after KbdInput is replaced by "_" thanks to the translation table.

Programming language