                      RTAI's Minute Virtual Machine


1 Overview

1.1 What is the Minute Virtual Machine ?

The Minute Virtual Machine (MVM) is one of the real-time control layer
on top of which the Xenomai nanokernel and RTAI's UP-scheduler module
(rtai_sched) can run. It is based on an event-driven simulation engine
that was once published by the FROGS project.

Like any other real-time layer, the MVM provides the nanokernel and
the RTAI UP-scheduler with the low-level resources it needs to
schedule threads, handle interrupts, manage memory and so on, so it
eventually thinks it runs on real hardware.

The MVM environment also comes with a graphical debugging tool named
the Xenoscope, which has been derived from the CarbonKernel project's
debugger.

1.2 Why should you use it?

Using the MVM to run your real-time applications has a lot of
advantages: it's usually much faster than running an instruction-set
emulator, does not require the cross-development tools, gives extended
debugging, monitoring and tracing features and provides an easy way to
stress the application under test with run-time situations otherwise
barely conceivable on a real target (e.g. bursts of simulated
interrupts generated at a very unreasonable rate !).

Of course, the application should not contain target-dependent code,
such as assembly code, because it runs as a regular executable
compiled by GCC on your GNU/Linux workstation. You cannot use the MVM
to collect accurate performance footprints of your system, but it can
show you precisely how the multiple threads running in your system
work together sharing the resources of the real-time interface (or
skin) (e.g. who is locking a semaphore, which thread has been readied
or suspended by a given system call, and so on).

Since the MVM is based on an event-driven simulation engine, it does
not rely on the host's "wall clock" but instead provides its own
simulated timeline to schedule the events that occur within a system.
Therefore a given test scenario can be repeated very simply an
infinite number of times, with no perturbation from the outside world
(e.g. the current load average of the host and so on). In other words,
a given line of source code will always be executed by the virtual
machine at the same time in the system's timeline across multiple
runs. This is a very desirable feature when debugging synchronization
problems.

To track the application behaviour, the MVM environment offers a
specialized tool combining an execution monitor and a symbolic
debugger called the Xenoscope. This tools can help you to isolate the
different application contexts by focusing on specific execution
paths (thread scope or global system scope) and show and/or modify
the status of the real-time operating system's objects involved
(e.g. change the value of a semaphore or post an event to a thread on
the fly).

2. Setting up a simulation

2.1 Building the simulation program

The first stage in setting up a simulation consists of generating the
executable program, called the simulator, which will include the
following parts:

      * The Xenomai nanokernel and a real-time skin (e.g. the pSOS+
      emulator) OR

      * Virtual RTAI, which is the original rtai_sched and rt_mem_mgr
      modules that have been ported to the MVM.

      * Your application code.

      * The Minute Virtual Machine core libraries.

All source code but the MVM itself is first instrumented by GCIC, then
linked in a single GNU/Linux executable.

The GCIC instrumenter prepares the real-time kernel code and your
application to run on top of the MVM. This instrumenter is able to
parse C and C++ source files. In no way the instrumenter changes the
functional behaviour of the input program, it only inserts calls to
internal functions in order to connect the simulated code to the
simulation engine.

The code instrumenter interposes itself before GCC at compilation and
link time. You usually just need to set your Makefile variables in
order to use the "gcic" command instead of "gcc" to compile and link
your code. GCIC then invokes GCC as the real compiler to produce the
object file from the instrumented source.

For instance, here are the commands needed to compile two C files,
namely foo.c and bar.c, then link the obtained object files to produce
a final executable, using Xenomai's pSOS+ emulation API:

      gcic -g -c foo.c

      gcic -g -c bar.c

      gcic -o app foo.o bar.o -lpsos_s

*******************************************************************
*******************************************************************
*******************************************************************
WARNING: NEVER, EVER LINK YOUR APPLICATION WITH THE PTHREAD
LIBRARY. THIS IS USELESS FOR NORMAL USE, FORBIDDEN BY DESIGN, AND
WOULD ALMOST CERTAINLY BADLY BREAK THE SIMULATOR.
*******************************************************************
*******************************************************************
*******************************************************************

The instrumentation engine aimed at C and C++ source code is built
upon a patched version of the GCC 2.95.3 compiler which adds the
instrumentation capabilities to the original compiler.

2.1.2 The instrumenter's role

GCIC is needed in order to have the simulation clock advance
continuously while the simulated code is executed. It achieves this
task by adding a call to an internal routine before each executable
statement found in the original source code. This routine is meant to
signal a new internal clock tick to the MVM, each time a source
statement has been executed.

After each simulation clock tick is signaled, the global MVM clock is
advanced by a quantum of time, after all events whose scheduling times
are prior to the new clock value have been processed. For instance,
one of such events could be a (simulated) hardware interrupt.

The duration of the simulation clock tick is determined by a special
setting called the Warp factor, ranging from 0 to 10. In other words,
changing this value directly affects the perceived processing speed of
the virtual processor. The higher the Warp factor, the shorter the
time quantum charged per instruction.  The time quantum is computed in
microseconds from the Warp factor by the following formula: 1 /
exp(factor). For instance, a simulation process configured with a Warp
factor of 3.7 will be charged for 1 / exp(3.7) = 0.02472, or 24.72
(simulated) nanoseconds for each source statement executed.

This time management scheme gives to all threads running inside the
MVM a single common time frame, which is independent from the
workstation's idea of time. This makes the simulated system's -
including your application - behaviour strictly repeatable between
simulation runs, which is a very desirable feature in debugging
synchronization problems.

2.1.3 Preprocessor signatures

Using RTAI's MVM to simulate an application may lead you to specially
modify or organize the application source to be simulated. You then
need to be able to check for the instrumenter's signature in order to
identify the current build context (i.e. real or simulation).

GCIC defines the CPP symbols "__MVM__" and "__GCIC__" before passing
the source file to the C/C++ preprocessor. Those signatures can be
used to have conditional compilation control over any pieces of source
code that are reserved for running on top of the MVM.

                 #ifdef __MVM__

                 <MVM-specific code>

                 #endif /* __MVM__ */

2.1.4 GCIC options

gcic accepts C/C++ compiler and linker commands, as well as its own
specific set of options. The general call syntax is as follows:

gcic [options] <cc-args>|<ld-args>

The gcic-specific options are as follows:

--dry-run

Causes the source code to be instrumented without performing the final
compilation. This option is useful for validating a module's syntax
without generating the corresponding object file.

--stdout

Processes the source file(s), whose instrumented version(s) are sent
to the standard output without calling the compiler.

--c-ext=<.c>

--c++-ext=<.cc,.C,.cxx,.c++,.cpp>

--obj-ext=<.o>

      These options specify the extensions for a C source file, C++
      source file and object to the instrumenter, respectively. For
      instance, these options are useful when the application's files
      are maintained by a revision control system that uses
      non-standard file extensions. The bracketed values are
      predefined by gcic.

--cc=<cc-command-line>

Specifies the command line used to call the C/C++ compiler for
generating an intermediate object file or the final executable. To
generate an object file, the default values are:

               "gcc for a C source file.

               "g++ for a C++ source file.

To generate a final executable, the default values are:

               "gcc"to edit links for a program consisting only of C
               object files.

               "g++ to edit links for a program containing at least
               one C++ object file.

            1.

--cpp=<cpp-command-line>

Specifies the command line used to call the C/C++ preprocessor for
generating the intermediate source file the instrumenter will work
on. The default value is obtained by appending the -E option to the
current compilation command line value. The resulting instrumented
file will then be passed to the selected compiler to get the
corresponding object file.

--with-gcic-compiler

Tells gcic to use the C/C++ instrumenter as the final compiler. When
applicable, this option must be specified during compilation and
link. (The GCC version modified to include the MVM instrumentation
generator still possesses all of its original capabilities as a
regular C/C++ compiler).

--cplusplus

Forces gcic to assume that links are being edited for a program
containing C++ code. As a result, the C++ linker (e.g. g++) is
selected from the available default values. If g++ is chosen, the
libstdc++.a STL library will also be automatically included unless
otherwise specified (i.e. -nostdlib). A command for integrated code
generation (compilation then link in the same command line)
automatically selects C++ mode if at least one C++ source file is
detected in the modules to be compiled. This option is ignored if a
--cc instruction forces the linker invocation syntax.

--temp-dir=<temp-directory>

Specifies the access path for the directory that will contain the
temporary files generated by gcic. The default value depends on the
host system. The temporary files will be deleted after processing,
unless the option--save- temps appears in the command line.

--save-temps

Forces gcic to keep the generated temporary files. These files are
produced during processing by the preprocessor as well as by the
original files instrumenter.

--verbose

This option causes the compilation and link commands issued by gcic to
be sent to the standard output.

--version

Displays the instrumenter's identification version number.

--gcc-version

Displays the version identifier for the instrumenter's host compiler.

--kernel-code
--skin-code
--user-code

Tags the instrumented code as being part whether of the Xenomai
nanokernel, a real-time skin (e.g. an API emulator), or a user
application. This information will be used in conjunction with the
current settings of the Xenoscope trace options to know whether GDB
should step in/over the statements contained in this source file.

VRTAI source code is tagged as a real-time skin (VRTAI, for "Virtual
RTAI", is a direct port of the RTAI's rtai_sched module on top of the
MVM).

By default,  --user-code is applied.

--vrtai

Instead of linking in the Xenomai nanokernel support, this option
makes GCIC link in the RTAI scheduler support libraries (i.e. -lrtai_s
-lrtaisa) when building the simulation executable. This option is
mutually exclusive with --xenomai.

--xenomai

This option ensures the Xenomai nanokernel support is linked in by
GCIC when building the simulation executable (i.e. -lxenomai_s
-lxenosa). Since this is the default operating mode, you usually only
need to specify the library containing the real-time skin
(e.g. -lpsos_s for using the pSOS+ emulator) and your application
objects to complete a link.

--help

Displays the list of options for the command.

<cc-args>

Lists the arguments that will be passed unmodified to the compiler.

<ld-args>

Lists the arguments that will be passed unmodified to the linker.

2.1.5 Caveats

o Do not pass multiple source files containing different input
languages (i.e. C and C++) on the same compilation line. GCIC is not
smart enough to handle this.

o Do not attempt to submit a compile-and-link request to GCIC on the
same command line, it will be rejected. Obscure internal reasons
forbids this. Therefore, you should first compile your object modules
with GCIC, then link them on a separate GCIC invocation.

o If you plan to develop C++ application with the MVM, you will need
to build the RTAI simulator using a 2.95.x compiler. Using GCC 3.x and
higher to build the MVM won't work in this case (you will have errors
linking your applications). This limitation does not apply to C
development.

2.2 The simulation project

A MVM simulation project associates a simulation executable to a
number of settings and preferences that apply when running it.

2.2.1 Creating a project

Open the Project menu, and then select the New command. A window is
then displayed, offering two selection fields: one to select the new
Project File, and the other to select the associated simulation
executable.

=> In the first field, enter the project file's access path. If you
wish, you can use a browser by clicking the icon displayed to the
right of the input field. The file must not already exist.  The
Xenoscope automatically adds the .mvm extension, which refers to all
simulation projects' filename.

=> You can enter the simulator's file name in the second field.
Environment variables may be used to represent all or part of the
access path, and will only be expanded when the Xenoscope actually
uses the access path. Note that the simulator's file name need not be
input at this point when the project's initial details are entered.
In that case, the project must later be modified to complete its
definition once the simulation executable is specified.

=> After you have specified all the above information, click the
Create button to create the project.

The new project is automatically selected by the Xenoscope.

The Xenoscope's commands for running a simulation can only be accessed
when a current project has been selected and the project's settings
specifies a valid simulator's executable file and simulated
configuration.

2.2.2 Changing the simulation executable

After selecting the current project, select the Edit command from the
Project menu. A window is then displayed, offering a single input
field to select the simulator's executable file. The current project's
filename appears at the top of the dialog box, in read-only form.

=> Enter the access path and name of the simulator's executable file
in the field labeled "Executable file". If you wish, you can use a
browser by clicking the icon displayed to the right of the input
field. The selected file must be a simulator's executable generated
separately by the procedure described in 2.1. Until a valid executable
file has been specified in this field, all the Xenoscope's commands
for running the simulation are inactive. This field may contain
environment variables that will be evaluated when the access path is
actually used.

=> When you have selected the previous, click the Save button to
modify the project.

2.2.3 Selecting a project

To change the Xenoscope's current project, select the Open command
from the Project menu. A browser is then displayed, with which you can
select the chosen project file. Double-click the filename displayed in
the browser, or select the file with the right mouse button and then
click OK. From then on, all the Xenoscope's commands will act upon the
new active project, whose name is displayed in the main window's title
bar.

The most recently opened projects can be quickly accessed using the
File entry in the Projects menu.

2.2.4 Editing the project settings

2.2.4.1 General simulation settings

The Xenoscope can be used to set a series of settings relating to the
MVM's general behaviour. The parameters listed under the Settings
heading of the configuration window discussed above mean the
following:

=> Simulation time is the simulation's duration. When the simulated
time reaches this value, the monitor terminates the execution.

     The value 0 is understood as an indefinite duration. In that
     case, the user must explicitly abort the simulation.

=> Display tick defines the smallest time interval that can be
displayed.

     For example, if the display tick value is 0.1 usc, all times will
     be displayed to the nearest tenth of a microsecond.

=> Time unit is the default unit for displaying time.

     For example, if the value of Time unit is msc and the value of
     Display tick is 1 usc, all times will be displayed in the
     following format: 1 010.005 u. For example, if the value of Time
     unit is sec, the time will be displayed as 1.010 005 s.

2.2.4.2 Simulation tool parameters

A second series of parameters can be accessed via the main
configuration window General tab. These can be used to modify certain
parameters for the MVM and debugger. The following input fields are
displayed:

=> TCP/Server port is the TCP/IP port number used for communication
between the Xenoscope's monitor and the simulator. The default value
was chosen in order to avoid any conflict with the system ports. In
addition, as this port only remains active for a very short period of
time while a simulation is initialized, it can be shared by several
users. Nevertheless, if any conflict arises this value can be changed
using this parameter for the active project.

=> Watchdog Timeout is the time limit before which the connection must
be made between the monitor and simulator, in seconds. If this limit
is exceeded the Xenoscope aborts the launch and displays and error
message.

=> Trace Buffer is the number of lines of text that can be stored in
the API's trace results window. A non-null value means that the oldest
messages are removed once that number of lines is reached. A null
value represents a trace buffer of unlimited size. The default value
is 200 lines.

=> GDB Path is the location of the GDB program used by the Xenoscope
to control the simulator via the graphical debugger.

=> Source Directories contains the list of access paths to the
directories that contain the application's source files; that list is
used by GDB.

=> Working Directory indicates the access path to the simulator's
startup directory. This is an optional parameter.

=> Local Arguments is an area specifically for simulator startup
arguments that are local to the application. Ideally, these options
begin with the reserved prefix (-Q) for this purpose, in order to
avoid any conflict with the simulator's internal options. These
options are always added unmodified to the end of the list of internal
options set by the Xenoscope when the simulator is run. See the
Command line" section for more detailed information on this subject.

=> Print Command contains the command line that will be used to submit
print requests to the host system. A shell interpreter is called to
run the request. The first occurrence of the "%f" control string is
replaced by the name of the file to be printed, if that string appears
in the body of the command. In this way, the name of the file that
must be printed can be positioned in the command line in the required
syntax.

2.2.4.3 Comfort options

A final series of options can be accessed via the Options tab. These
can be used to change the Xenoscope behaviour. The possible settings
are:

=> Break on Warnings: selecting this option make the execution stop
when the simulator returns a warning. If the debugger is running, the
line of code that caused the error is highlighted. In addition to the
temporary break, the message is repeated in the Xenoscope's Error log
window, which can be accessed via the Windows menu. Such warnings are
produced by the real-time system running on top of the MVM.

=> Break on Trace Alerts: selecting this option make the execution
stop when a trace alert is returned by the simulated code that has the
alert attribute set.

=> Auto-raise Error Log: selecting this option causes the Error log
window containing the simulator's alert messages to be automatically
displayed in the foreground as soon as a new message is received.

=> Fully Qualify Thread Identifiers: selecting this option allows the
long identifier to be displayed for threads in the focus selectors
(debugger and traces). A long identifier attempts to display the name
of the thread's entry point (a C routine name) instead of its internal
numeric identifier. If this information is unavailable, the internal
identifier is displayed alone.

=> Auto-Raise Trace Windows: selecting this option causes the
inspector's, the memory examiner's and the global variables windows to
be automatically raised in the foreground each time that the Xenoscope
has regained control over the simulator (e.g. code stepping, break).

=> Trace Xenomai kernel: selecting this option causes the source files
tagged as being part of the Xenomai kernel to be traced by the
debugger. You get rid of stepping in/over the statements contained in
these files by deselecting this option. The tag is specified at
compile-time on a per-file basis to the GCIC instrumenter.

=> Trace real-time skin: selecting this option causes the source
files tagged as being part of a Xenomai-based real-time skin to
be traced by the debugger. You get rid of stepping in/over the
statements contained in these files by deselecting this option. The
tag is specified at compile-time on a per-file basis to the GCIC
instrumenter.

=> Trace application: selecting this option causes the source files
tagged as being part of a real-time application to be traced by the
debugger. You get rid of stepping in/over the statements contained in
these files by deselecting this option. The tag is specified at
compile-time on a per-file basis to the GCIC instrumenter.

=> Display Source Line Numbers: selecting this option causes the
source file's line numbers to be displayed in the debugger's frames.

=> Activate Evaluation Bubbles: selecting this option causes
expressions under the mouse pointer in a debug frame to be
automatically evaluated. If you are working with simulators having
huge namelists, you may consider deselecting this option to improve
the Xenoscope's responsiveness when moving the mouse pointer over the
source window.

=> Force Focus on Breakpoint: selecting this option causes the
debugger's Follow thread function to be run whenever any break is
caused by a breakpoint hit during the execution. This automatically
sets the focus to the context that was active when the MVM was
suspended, so that that specific context can be tracked step by step
later.

=> Use glyph cursor in source: selecting this option replaces the
highlight normally used to indicate the current line in the debugger's
frame by a graphic cursor in the left margin. This mode is
automatically chosen if a monochrome display is detected.

3. Running a simulation

3.1 Interactive execution

The MVM Xenoscope offers two built-in simulation control modes. The
first mode provides a display and control monitor for handling system
objects created by the real-time skin (e.g. semaphores, threads and so
on). This mode also provides step-by-step functions that are
synchronized with certain events such as executing system calls or
changing thread status. The second mode adds a symbolic debugger to
the previous mode. The functions of this debugger are extended to the
Xenoscope multi-focus control system.

3.1.1 Using the monitor

An additional toolbar displays the functions available from the MVM
menu when the MVM is running. These functions will be described in
detail throughout this section. When the monitor is in standalone
control of the simulation, this toolbar's actions are the following,
from left to right:

         1. Inspector button (disabled in this mode).

         2. Graphical plotter button.

         3. APIs tracer button (not yet implemented).

         4. Simulation timers button.

         5. Continue execution.

         6. Stop execution (disabled).

         7. Execution speed selector (Host-wise).

         8. Iconic state information.

3.1.1.1 Starting the simulation

Starting the MVM using the monitor alone is controlled by the Run
command in the MVM menu. After starting the MVM, the list of system
objects is displayed.

3.1.1.2 Controlling the execution

Execution is automatically suspended at time value "0" after general
simulator initialization. Select the COntinue command from the MVM
menu to start execution.  You can use this command to resume execution
after any suspension, regardless of the reason (breakpoint, step-by-
step mode, etc.). After resuming the execution, the current simulated
time shown under the Time label in the monitor resumes incrementing.

=> To suspend execution again, select the Stop command from the MVM
menu or click on the corresponding Stop icon in the control bar.

=> Host-wise execution speed can be controlled using the speed
selector. Slowing the MVM process is achieved using the activity on an
internal hog thread whose sole function is to periodically suspend the
simulation process. The maximum execution speed is obtained when the
selector displays a value of 10. At the other extreme, a value of 1
corresponds to the lowest speed. The host-wise execution speed should
not be confused with the Warp factor discussed earlier. It does not
apply to the virtual processor, but rather to the Linux process
running the MVM. In other words, changing its value has effects in the
actual time, not in the simulated time.

=> To terminate the simulation, select the Kill command from the MVM
menu.

=> To restart the simulation using the monitor alone or with the
debugger, use the Restart command from the MVM or GDB menus as
appropriate.

(It is not necessary to suspend execution in order to use the monitor
functions, especially the inspector)

3.1.1.3 Execution status indicator

The current status is shown by an indicator displayed at the extreme
right of the monitor toolbar. The pictogram displayed specifies
whether or not execution is running, and in the latter case, why it
was suspended. Given the large number of conditions that may warrant
simulator suspension, it is useful to refer to this pictogram to
determine the type of suspension. The following table summarizes
possible statuses:

a) Unconditional suspension
b) Suspension caused by receiving a warning message
c) Suspension caused by a timer that went off
d) Suspension caused by receiving a trace message
e) Suspension linked to a breakpoint activated in the graphs
f) Suspension caused by a code breakpoint (debugger)
g) Suspension caused by a fatal exception (debugger)
h) End of simulation i) Simulation in progress

3.1.1.4 Using the inspector

The inspector is a useful tool displaying the real-time objects
(e.g. semaphores, threads...)  created and altered as the MVM runs the
real-time code. It allows interaction with these objects depending on
the rules defined by the real-time skin used. The main window in the
MVM mode is used by the inspector. In GDB mode, a dedicated window is
created and is accessed using the Inspect command from the MVM menu.

Each object presented has its own graphical front-end called a
dashboard that is used to display and possibly change its status
and/or its characteristics dynamically.  The possible interaction with
each object exported by a given real-time skin is dependent on the
skin implementation itself. For instance, you can change the interrupt
mask and the scheduling priority interactively of any task created by
the pSOS+ API emulator.

3.1.1.5 Setting timers

The Xenoscope can automatically stop the MVM execution at certain
programmed times. This can be used to break the simulator execution
prior to analyzing the various system objects or taking debug
actions. To access the timer manager, select the Timers command from
the MVM menu or choose the Timers icon from the control bar. After the
timer window is displayed, click on the icon to insert a new time for
stopping execution. A simulated time selection sub-window is then
displayed, in which you can enter the required time, then validate the
operation by choosing the Add button. The absolute and relative
selectors are used to specify a time-out calculation from time 0
(absolute) or from the simulated current time (relative).

=> To inhibit a timer without removing it completely, right click on
it and select the Disable command from the context related menu. For
the opposite result, select the Enable command from this same menu to
reactivate it. You can also left click on it and choose the Enable
icon from the local toolbar.

=> To toggle the enabled/disabled status of all of the timers using a
single action, choose the Toggle icon when no other items are selected
from the list.

=> To permanently delete a timer, right click on it, then select the
Remove command from the context related menu. You can also left click
on it and choose the Remove icon from the local toolbar.

=> To delete all timers using a single action, choose the Remove icon
when no other items are selected from the list. You will be asked to
confirm this command.

3.1.2 Using the debugger

The standard features of GDB have been extended with a set of
RTOS-oriented capabilities. All of the Xenoscope's debugger functions
are synchronized with the observation and interaction functions
already available through the monitor. This kind of execution
therefore offers a mixed execution control mode using the debugger and
the monitor.

3.1.2.1 Starting the debugger

The simulator is activated under the control of the debugger using the
Load command in the GDB menu. In addition, there is a Debug icon in
the toolbar for this command. While GDB is loading, a blinking
indicator showing the "Loading" condition is displayed in the upper
right hand part of the Xenoscope display. At this stage, the execution
is not yet running.

After starting the simulator under the joint control of the debugger
and the monitor, a breakpoint is hit at the entry point of the
application, the real-time skin or the Xenomai nucleus, depending on
the current trace filter.

The Run function handles start-up, without stopping the MVM at time 0,
which means that the execution starts as soon as it is loaded.

In this mode, a toolbar dedicated to debugger functions is displayed
on the left of the main widow, under the main toolbar. This is
enhanced, at the far right in the same plane, by specific source-file
management tasks and by a set of operating mode selectors.  The
available functions are from left to right, respectively :

              1. Step-over the current source statement.

              2. Step-into the current source statement.

              3. Step-out the current routine.

              4. Continue execution.

              5. Stop execution.

              6. Go one level toward the outer stack frame.

              7. Go one level down to the inner stack frame.

              8. Edit code breakpoints.

              9. Edit data watchpoints.

             10. Display global variables.

             11. Examine memory.

             12. Lock focus on current thread.

             13. Open a secondary debug frame.


Under the joint control mode, access to system objects via the
inspector is gained by choosing the Inspect command from the MVM menu
or by clicking on the Run icon in the monitor control bar.

3.1.2.2 Using the context focus

The MVM debugger offers extended control over simulation. The Focus
selector allow specifying a particular application context to track
and visualize.

The Focus selector lists the threads that are active in the system,
followed by a generic input called (system). The latter one represents
the global context, regardless of the kind of the current activity
(thread or ISR).  In this case, the last source statement of the
(instrumented) code that was executed will be presented, independently
of its context. Conversely, a focus on a specific thread will narrow
the trace to the code executed by this thread only.

The position of the Focus selector determines the scope of some
debugger commands:

The step-by-step functions (StepInto, StepOut, StepOver) always work
on the current context. For example, a step-by- step command placed
during an active focus on a given thread will only stops the MVM
execution after this thread has executed a source statement. All of
the other parallel activities will continue to run in the background
until the next time the execution is stopped.

The conditions assigned to the breakpoint inserted on-line depend on
the current focus. A breakpoint can be inserted on- line using the
local menu in the source buffer. To access this, right click on the
source code buffer, at the statement position you want a breakpoint to
be set.

3.1.2.2.1 Changing the focus

Use the Focus selector to change the traced context. The Xenoscope
automatically updates the source buffer accordingly.

3.1.2.2.2 Tracing the asynchronous code

Use the toggle selector to validate the asynchronous code trace mode
showing source statements executed on behalf of contexts such as ISR
routines. If this function is not selected, only synchronous thread
activity will be traced.

3.1.2.2.3 Multiple context display

Click on this icon to create a new debug frame. There is virtually no
limit to the number of simultaneously accessible frames. All of the
debug frames are synchronized and have their own focus. This enables
obtaining simultaneous views of the status of the various activities
observed at a given time.

3.1.2.3 Position in the source code

The current position in the displayed source code is illustrated by
yellow highlighting or a cursor located in the left hand margin if the
use glyph cursor in source option is active in the project
settings. As the Xenoscope lets the user follow more than one
different context at one time, the position shown is always dependent
on the context that is displayed according to the active focus
selection (see above).

At any time, when execution is suspended, a local menu that is called
up via the right mouse button can be accessed. The actions presented
in this menu may vary depending on the current execution context.

3.1.2.3.1 Setting a breakpoint

The Break here action lets the user add a breakpoint at the source
statement located under the mouse pointer. If the focus is not
(system), then a sub-menu displays a list of additional conditions for
the breakpoint. It therefore becomes possible to make breakpoint
conditional on the execution of any activity (thread or ISR), or on
the execution of a specific thread (if Thread "xxx" runs). Choosing
unconditionally is the same as validating this breakpoint regardless
of the context, including all activities in the system. The choice
becomes unconditional in relation to the focus. When the focus is
(system), the breakpoint is always valid, regardless of the executing
context.

3.1.2.3.2 Editing a breakpoint

If the source statement that is present under the mouse pointer
already has a breakpoint, then the Disable, Enable and Remove actions
respectively let the user disable, re-enable or definitively remove
this breakpoint.

3.1.2.3.3 Running until a source statement

The Run until function lets the user place a temporary breakpoint at
the source statement under the mouse pointer and then automatically
resume the execution. This breakpoint will be automatically deleted
the next time the execution is suspended by the debugger.

3.1.2.3.4 Searching for a character string

The Search string action allows access to a lexical search function on
a character string in the current source file.

3.1.2.3.5 Using the text selection

If a text selection is active, the character sting delimited in this
way can be used as the argument for a variable or expression
inspection function. The selection is made by double-clicking on any
word in the source code. If the expression being looked for is not
currently displayed, it is possible to enter it into the freeform text
field. Possible actions of the local menu in the source buffer
include:

=> Display to display the expression value in the local variables
window.

=> Display * to display the result of de-referencing the expression
value in the local variables window.

=> Type of to obtain the type of expression in the source code
programming language syntax.

=> Seek to bring the declaration of the variable or the function
proposed as an argument into the source buffer. This action has a
shortcut that is called up by simultaneously pressing the Control key
and the left mouse button, when the pointer is located on the
expression.

=> Find to look for the next occurrence of the argument in the source
text. The find function automatically wraps to the start of the source
file when it reaches the end.

3.1.2.4 Using Step-by-Step mode

=> Click on the first stepping icon from the debug toolbar to resume
execution from the current statement and enter the routine (Step
Into).

=> Click on the second stepping icon from the debug toolbar to resume
execution from the current statement without entering the routine
(Step Over).

=> Click on the third icon from the debug toolbar to resume execution
from the current statement until exiting the active routine (Step
Out).

3.1.2.5 Information on the Current Context

When execution is suspended under the control of the debugger, the
function name, file name and source line currently pointed to by the
step-by-step mode cursor are displayed over the source text. This
information is completed where necessary by the current interrupt
masking level (when applied, i.e. > 0), as well as by the specific
mode indicators if this is a thread. These modes are as follows:

(lock) indicates that the displayed thread cannot be preempted
by another thread (i.e. Scheduler lock).

(rrb) indicates that the system is currenly undergoing a round-robin
scheduling for the priority level the displayed thread belongs to.

(asdi) indicates that asynchronous software signals are currently
inhibited for the displayed thread.

(boost) indicates that the displayed thread temporarily benefits from
enhanced priority, as part of the priority inheritance protocol.

If these modes are meaningless to the running real-time skin, these
flags may never appear.

3.1.2.6 Displaying the execution stack

Use the stack toggle selector to validate or inhibit the display of
the call stack that corresponds to the traced context. Click on a
stack level to display the corresponding source code.

3.1.2.7 Local variables

Use the data toggle selector to validate or inhibit the display of the
local variables for the traced context. Right click on the list of
variables to pulldown the local menu to access the various additional
functions. This menu is used in exactly the same way as the one
defined for the local menu in the global variables window.

3.1.2.8 Displaying global variables

The global variables for the application program are accessed using
the global data icon in the debug toolbar. Right click on the window
displayed, then use the Select command in the local menu to choose the
variables to display.

Any variable or expression that is selected using this function is
automatically recalculated and graphically refreshed after each
suspension of execution. All of the expressions understood by GDB are
valid in this context, especially arithmetical expressions. This
feature is also accessible from the local variables display window.

3.1.2.10 Displaying the memory and evaluating expressions

Use the Examiner icon to open the memory examiner window.

The first frame contains the request results display buffer. The
intermediate frame contains a set of format selectors used to check
memory display (hexadecimal, decimal, octal and others). The third
frame is used to choose the expression to be displayed.

Two modes are available in this context: the raw memory display if the
selector in front of the text entry is in the Dump position, and the
expression evaluation mode if this same selector is in the Eval
position.  The Dump mode displays the content of the memory, from an
address expressed in the next text entry, for a number of consecutive
memory words using a general format specified by the other
selectors. The Eval mode will merely evaluate the expression shown in
the text field. In this case, the format selector is not operational.

The Eval mode also lets the user change the value of the expression
displayed by allowing it to be placed after the = operator followed by
the new value to assign to it. For example, A= 23 assigns the value 23
to variable A.

When the examiner's window remains open during step-by-step operation,
the expression normally displayed in the text entry is re-evaluated
each time execution is stopped.

The Examine button forces the evaluation of the current content of the
text entry, just like when the RETURN key is pressed in the same
field. The Clear clears the contents of the field.

3.1.2.11 Setting breakpoints

Pull down the local menu for the source frame by right clicking on the
source statement that should receive the breakpoint. Choose one of the
breakpoint conditions proposed by the current focus function. The
possible conditions may make the breakpoint dependent on the thread
currently being presented. One mode allows obtaining an unconditional
shutdown regardless of the context (equivalent to the system mode). If
the breakpoint requires a condition, use the breakpoint editor's Set
condition function (see below).

Use the Breakpoints icon to access the breakpoint manager. In this
mode, only unconditional breakpoints may be defined.

=> To insert a new breakpoint, enter its location in the text field,
then click on the Add icon.  For example, state server.c : 86 to stop
the execution at line 86 of the server.c file in our example, then
validate this by pressing the ENTER key Or alternatively, state
shm_push_q to stop the execution at the input to the shm_push_q()
function (present in the shm.c file). It is also possible to add a
condition to breakpoint triggering use of the Set condition function
from the local menu.

=> To inhibit a breakpoint without removing it definitively, right
click on it, then select the Disable command from the local menu. To
perform the reverse operation, select the Enable command from this
same menu and reactivate the breakpoint. You can also left click on
the breakpoint, and then choose the Toggle icon from the local
toolbar.

=> To toggle the enabled/disabled state of all of the breakpoints
using a single action, choose the Toggle icon when no other elements
are selected from the list.

=> To definitively remove a breakpoint, right click on it, then select
the Remove command from the local menu. You can also left click on the
breakpoint, and then choose the Delete icon from the local toolbar.

=> To definitively remove all breakpoints using a single action choose
the Remove icon when no other elements are selected from the list. You
will be asked to confirm this action.

3.1.2.12 Setting watchpoints

This function is used to stop the execution when a variable expression
changes value when the program is under control. To use the data
watchpoint in a comfortable manner, hardware support is required from
the host station, in order to reduce the execution time penalty linked
to controlling the change in value to the submitted expression. When a
watchpoint is first used, the debugger will request confirmation of
the operation to the user if this support proves unefficient at the
debug engine level. If the action is confirmed, then a software
emulation function eventually provided by the debug engine will be
used.

The unavailability of hardware support for controlling memory
watchpoints makes their use unreasonable due to the extreme slowing
effect that software emulation causes at the debug engine level
(e.g. with GDB). In addition, unavailability is most often due to a
lack of support from the debug engine itself, rather than to any
actual lack of hardware functions at the host processor level.

Use the Breakpoints icon to access the breakpoint manager. From this
mode, only unconditional breakpoints can be defined.

=> To insert a new watchpoint, enter the chosen expression in the text
entry, then click on the Add icon. It is possible to change this
expression using the Edit function in the local menu.

=> To inhibit a watchpoint without removing it definitively, right
click on it, then select the Disable command from the local menu. To
perform the reverse operation, select the Enable command from this
same menu and reactivate the watchpoint. You can also left click on
the watchpoint, and then choose the Toggle icon from the local
toolbar.

=> To toggle the enabled/disabled status of all of the watchpoints
using a single action, choose the Toggle icon when no other elements
are selected from the list.

=> To permanently remove a watchpoint, right click on it, then select
the Remove command from the local menu. You can also left click on the
watchpoint, and then choose the Remove icon from the local toolbar.

=> To definitively remove all watchpoints using a single action choose
the Remove icon when no other elements are selected from the list. You
will be asked to confirm this action.

3.1.2.13 Controlling the simulation

Execution is automatically suspended at time "0", after general debug
initialization. Select the Continue command from the GDB menu to start
execution. This command has a double alias in the form of the Continue
icon present in the debugger control bar and in the monitor that is
displayed on start up.  You can use this command to resume execution
after any kind of break state.

=> To stop the execution again and return control of it to the
debugger, select the Stop command from the GDB menu, or click on the
Stop icon in the control bar.

=> To terminate the simulation, select the Kill command from the GDB
menu.

=> To restart the simulation, with our without the debugger, use the
Restart command from the GDB or MVM menus as appropriate.

The execution control actions accessible via the monitor are also
available during a debug session using the debugger.

3.1.2.14 Selecting the source file

The following actions directly affect the contents of the source
buffer displayed by the debugger.

=> Click on the Next Statement icon to display the current breakpoint,
in the source buffer. This function is useful for returning to the
current instruction after browsing between a number of source files.

=> Click on the Reload icon to force the system to re-read the file
currently in the source buffer.

=> The graphic selector Recent files is used to access the list of the
last eight files presented in the source buffer. The other less recent
files are also retained and can be accessed via the selector's
More... input when this is available. In this case, a selection list
lets the user browse all already open files.

=> Choose the Open... input from the File menu in the main menu bar in
order to access a file selector. After validating the action, the
source code contained in this file will be presented in the current
buffer.

4. Displaying graphs

Some system objects created by the real-time skin can export one (or
more) displays of their current status to a dedicated plotter,
accessible from the Xenoscope monitor. For example, real-time thread
transitions are displayed in state diagram form, presenting every
possible state (suspended, delayed, ready, running, etc.) over time.

4.1 Selecting graphs

To access the plotter functions, select the Graphs command from the
MVM menu or click on the Graphs icon in the monitor toolbar after
starting execution.

When opening the graph window, the selection screen only appears when
no graphs are currently displayed, otherwise access to the graph trace
window is gained directly. At any time you can return to the selector
using the Select command from the File menu in the plotter window or
by using the Select icon.

The graphs are listed in hierarchical order, by graphic type first
(Time Curves for the time curves then Compounds for the composite
curves) and finally by type of objects.

All of the curves that exist at this point in the execution are
available on screen. The selection state for each node is carried via
the lower branches to the graphic objets themselves are reached. The
selected curves are initially displayed in the order of their
appearance in the list.

The MVM can export new curves throughout its operation, depending on
the performance of the real-time skin involved. For example, creating
a thread generally causes the appearance of a new state diagram that
represents it.  In this case, the graph selector will be enriched on
the fly.

4.2 Display by type of graph

4.2.1 Time curves

Curves indexed on the simulation time are grouped so that they can be
compared. The time value is assigned to the abscissa, with a sliding
left limit based on its evolution or the current presentation
choices. We will use xMin, xCur and xMax respectively as the minimum,
current (i.e.  simulation time reached prior to the last suspension)
and maximum values for this axis in the rest of this document. Click
on the Time Curves tab in the curve tracer to display this kind of
curve.

4.2.2 Composite curves

A number of time curves of the same type can be assigned together to
the same composite curve. They retain their separate properties but
appear grouped when displayed in the same graphic field.

4.3 Controlling the MVM

4.3.1 Suspending/Resuming execution

The execution in progress can be stopped temporarily and restarted
from the plotter, using the Continue and Stop icons respectively in
the control bar. These two functions are identical to the ones that
can be found in the debugger and built-in monitor interfaces.

4.3.2 Setting breakpoints

Breakpoints can be set on the time curves shown. The transition to one
of the states chosen from a state diagram, or reaching a numerical
threshold in a time graph can therefore trigger an automatic stop to
execution.  Control is then returned to the Xenoscope, which then
synchronizes all of the views available on the breakpoint (updating
the status of inspector objects, the code and the variables displayed
by the debugger etc.).

To access this function, right click on the title of a time curve to
call up the local control menu for this curve, pulldown the Mode
sub-menu, then choose Breakpoint.

4.3.2.1 Breakpoints in a state diagram

Once the Breakpoint function is validated, a list of possible states
is displayed in a selection sub-window. Check the selector for each
status required. The Close button ends the selection process.

An accelerated mode for setting breakpoints can be accessed by
directly double-clicking on the chosen part of the state diagram,
representing the ordinate value for the status or threshold.

4.3.3 Displaying and checking breakpoints

A function lets the user gain a summary overview of all of the
breakpoints set on the time curves. This function will also allow
disabling or removing these breakpoints, either individually or curve
by curve. Use the Breakpoints option from the View menu.

The breakpoints displayed are grouped by the curve they belong
to. Right click on a breakpoint value to pulldown the local control
sub-menu. The Remove, Disable, and Enable choices respectively will
remove, disable or re- enable the selected breakpoints. If you would
like to apply these actions globally to all of the breakpoints on a
given curve, right click on the name of the curve as displayed in this
same window and use the required sub- function.

The Close button closes the breakpoints control sub-window.

4.4 Scale Compression

4.4.1 Y Compression

When the initial height of the curves does not allow their complete
display and requires the use of the vertical scroll bars, then it is
sometimes useful to vertically compress these objects. Use the
Y-compress function in the View menu. Note that this option is
automatically disabled if too many objects are already compressed for
display.

Vertically uncompressing the display, i.e. returning to the previous
display scale is possible using the Y-uncompress function from the
View menu.

4.4.2 X Compression

It is often convenient to be able to display what a curve looks like
over the entire simulation time range. Use the X-compress function
from the View menu to bring all of the stored points from all of the
time curves back to a single graphic page. This operation is performed
by applying an abscissa scaling function that changes the displayed
time/pixel ratio. The left and right limits of the curve are brought
back to 0 and xCur respectively.

Horizontally uncompressing the display, i.e. returning to the previous
display scale is possible using the X-uncompress function from the
View menu.

4.4.3 Zoom In

The zoom in function expands the time/pixel scale by 200%. The left
hand limit (xMin) is retained as closely as possible, while the
display is recalculated for all of the time curves displayed. This
function is a gradation of the X compression function described
previously. It is called up by choosing Zoom In 200% from the View
menu.

4.4.4 Zoom Out

The zoom out function contracts the time/pixel scale by 50%. The right
hand limit (xMax) is changed to match the new scale, while the display
is recalculated for all of the time curves displayed. This function is
symmetrical to the zoom in function described previously, but is
however applied using a lower scaling factor. It is called up by
choosing Zoom Out 50% from the View menu.

4.5 Composite curves

In order to obtain a single curve made up from the states of a number
of other compatible curves (i.e. curves of the same type and in the
case of state diagrams, with the same states), it is possible to use
the "drag & drop" method based on the time curves title bar. To do
this, simply left click on the title bar of one of the curves to
group, then drag the mouse to the title bar of the other curve to
group, whether it is a composite curve or not, then release the left
mouse button. In the former case, the first curve will be added to the
second composite, in the latter case, the two curves will form a new
composite. In this latter case only, the plotter will prompt the user
for the name of the newly created composite curve.

4.6 Placing graphs

Graphs may be arranged for display using a simple placing mechanism,
triggered by a "drag & drop" operation performed on the Hand grab icon
provided on each one. The graph located at the source of the move
action will be inserted before the one located at the move
destination.

4.7 Selection and cross hairs

4.7.1 Actions on graph sections

Some graph analysis actions require expanding or compressing a
specific part of the time curve trace. The graphic selection concept
is used to select a precise area of application for a change of
scale. To call up this function, right click on the title of a time
curve to call up the local control menu for this curve, pulldown the
Mode sub-menu, then choose Selection.

The X-View heading in the selection window lets the user control the
time/pixel ratio (i.e. the abscissa) over the current selection. The
Y-View heading is used to control the field shown by the ordinates.

In parallel with the window display, a selection rectangle is shown on
the selected curve. Bring this rectangle over the graphic portion that
you wish to assign to the selection. To do this, left click on the
point that represents the top left corner of the rectangle, then drag
the pointer to the lower right corner, while holding the mouse button
down. The selection made is determined by the rectangle formed when
the left mouse button is released. You can rework an existing
selection by holding down the CONTROL key while performing the
operation using the left mouse button.

During this operation, the current limits of your selection are
displayed in real-time in the control window, showing both the
abscissa and ordinate values. You can change these limits manually
using the data entry fields provided.

In the X-View heading, From and To respectively control the xMin and
xMax values displayed. Time/Pixel is the display ratio between a
graphic pixel and its time correspondence.

In the Y-View heading, the system will display the limits-states for a
state diagram, or the minimum and maximum values in ordinates, for a
time graph. In the former case, only those states present between the
two limits (inclusive) will be displayed. In the second case, only
those points between the minimum value and the maximum value
(inclusive) will be displayed.

Apply the new display parameters by clicking on the Apply button. To
revert to the previous state, use the Revert button.

There is a quick way to access the selection function, by
simultaneously pressing the left mouse button and the SHIFT key while
directly selecting the target curve. Once the selection has been made,
right click on the chosen curve, then validate X-Apply or Y-Apply
respectively to change the scale or the corresponding limits.

4.7.2 Using the cross hairs

Left click on a point on a time curve to see its coordinates. The
coordinates will be displayed at the top of the selected curve. The
cross hairs let you move along this curve while holding down the left
mouse button, for a real-time display of the corresponding
coordinates.

4.8 Other local functions

The graphs shown all have a local menu that lets the user access a set
of individual functions. To access this menu, right click on the title
of the graph.

4.8.1 Local state diagram functions

=> The Seek sub-function in a curve's local menu lets the user seek
the next or the previous point received from the MVM by looking
forward (Forward input) or backward (Backward input) within the
current view. This function is useful when looking for the next or the
previous transition in a state diagram. The minimum limit xMin is
moved to bring the point found onto the display. If no point is found,
an audible beep will sound, indicating that the seek action has failed
to find anything.

=> Simple time graphs (i.e. time curves excluding state diagrams) have
an additional setting feature that can be accessed from the Advanced
sub- function in their local menu.

     The Smoothing parameter is a smoothing constant applied to the
     graph along its horizontal scale. It is expressed as a simulated
     time value.

     Selecting the Y-adjust parameter will automatically adjust the
     maximum ordinates limit according to the points received from the
     simulator. If not, the limit will not be readjusted to match the
     maximum value received from the simulator.

     Choose OK to validate the changes made to the settings, or Cancel
     to cancel the operation.

4.8.3 Common Functions

=> The color used to draw the graphs may be changed using the selector
that is accessed via the Color sub-function in the local menu for
these graphs.

=> Time curves can be printed out in PostScript format, either to a
file or directly to the chosen printing peripheral. From the graph's
local menu, use the Print sub-function to access the Print sub-window.

      In the Print sub-window, choose the destination, To printer for
      a direct print out to a printer, To file to route the print out
      to a file. In the latter case, the filename text entry next to
      the selector must be filled-in. For a direct print out, the
      current Print command settings in the simulation configuration
      parameters are used. These settings are accessible from the
      General page in the Settings window in the Xenoscope Project
      menu.

      Horizontal curve compression is applied by default, so as to
      present the entire simulated time range in the PostScript
      trace. You may disable this option by choosing the Uncompressed
      mode.

      A global print command for all of the graphs present on the
      current page can be called up from the Print command in the File
      menu.

4.8.3.3 Removing a graph

The Remove sub-function, accessed from the local menu for a graph lets
the user remove it from the display, regardless of its type. It may be
restored using the graph selector accessed via the Select command in
the File menu.

4.9 General Options

The plotter offers a number of options that affect its overall
performance.  These options are accessible via the Options menu.

=> The X-adjust mode is used to choose automatic readjustment of the
xMin and xMax limits when plotting the time curves, depending on the
minimum and maximum values received from the simulator. This allows
retaining only one active graphic page at any time during the
execution, and therefore avoids the need to use the horizontal scroll
bar. This mode is disabled by default.

=> The Scroll lock mode indexes time curve horizontal scrolling to
mouse motion, when using the horizontal scroll bar. Otherwise, the
display is only refreshed when the mouse button is released. This
mode, when it is enabled, requires a high trace speed from the host
station, due to the numerous display refreshes that take place. This
mode is disabled by default.

=> The Auto-select color mode lets the tracer choose the colors to
assign to new curves. This mode is initialized by default.

=> All of the current plotter session parameters can be saved on
demand using the Save command from the File menu. This includes the
list of curves displayed, the composite curves that are active, the
position of the breakpoints on the different curves, the advanced
configuration settings, etc. The Auto-save session option lets the
user choose to automatically run this command at the end of each
session, when the simulator is shut down.

5 Command Lines

5.1 Xenoscope Start Options

The Xenoscope has the following set of start options available:

         -f <project-file>, automatically loads the simulation project
         designated by its access path when the Xenoscope is
         initialized. This option will override the default behaviour
         to pre-load the last active project.

         -g, forces execution to start in debugger mode, as soon as
         the Xenoscope initialization is finished. Combined with the
         -f option, this selection allows the automatic execution of
         any simulation project.  The -g option is mutually exclusive
         with options -x and -p.

         -x, forces execution to start in monitor mode, as soon as the
         Xenoscope initialization is finished. Combined with the -f
         option, this selection allows the automatic execution of any
         simulation project.  The -x option is mutually exclusive with
         options -g and -p.

         -p, is an internal option used by the simulator to run a
         slave monitor interface when execution is started from the
         command line.

         -q, unconditionally shuts down the Xenoscope as soon as
         simulator execution is finished. By default, the Xenoscope
         remains active after the end of a simulation, except in the
         case of the slave mode designated by the -p option.

         -u, inhibits reloading of the last Xenoscope's working
         context, especially its last open project. By default, the
         Xenoscope restores the last project, along with some general
         display characteristics like the geometry of the graphic
         window that it uses.

         -v, sends the Xenoscope version number to the standard
         output.

Passing an argument not starting with a dash as the first argument of
the command line makes the Xenoscope take the following steps:

1) If a file named <arg>.mvm exists, Xenoscope behaves like the option
-f <arg> has been passed.
2) Otherwise, <arg> is considered as an MVM runnable file. A project
file called <arg>.mvm is automatically created with <arg> being the
simulation executable. This new project is then loaded as the current
session's one.

5.2 Simulator Start Options

Any simulator generated using the standard procedure described in
chapter 2 includes the following set of start options:

         -f <projfile>, triggers running the Xenoscope in "slave"
         mode, allowing interaction with the simulator. Only the MVM
         monitor functions are available in this mode (i.e. No
         debug). The argument entered is the access path to the
         project file that must be pre-loaded by the Xenoscope. This
         file will also provide the information on the resources
         repository and the simulated configuration to be used.

         -X is a sub-option introducer used for setting the
         simulator's boolean parameters. This option must be followed
         by the list of flags to be activated. (e.g. -Xw or
         -Xbt). Valid flags include:

               w, causes automatic execution suspension on receiving
               alert messages. This option is only active during
               interactive execution, in the presence of the graphical
               monitor. By default, a warning does not suspend the
               execution.

               a, causes automatic execution suspension on receiving
               a trace with the alert attribute set. This option is
               only active during interactive execution, in the
               presence of the graphical monitor. By default, a trace
               message does not suspend the execution.

               l, eliminates checks on code sections run in
               time-locked mode. By default, the simulator generates
               an alert if such a section exceeds 10,000 source
               statements, considering that a potential error linked
               to the absence of a section close may have occured.

               g inhibits the check performed on the maximum number
               of alert messages tolerated prior to aborting the
               execution. By default, the execution is automatically
               aborted after receiving more than 100 alert messages.

               b and t are flags for internal use that are not
               accessible to the user.

         -t <time[s,m,u]>, specifies the simulation time limit
         (simulated time). By default, the simulation duration is
         infinite. This option is equivalent to the Xenoscope's
         "Simulation time" parameter that applies to the project.

         -d <directory>, changes the simulator's current directory to
         the one specified in the parameter prior to execution. By
         default, the current directory is retained.

         -l <errlogfile>, specifies the access path to the file used
         to store the warning messages generated by the simulator. By
         default, the messages are sent on the simulator's standard
         error output.

         -z <speed>, controls the host simulation speed using a hog
         factor that runs from 1 to 10. 1 corresponds to the maximum
         slowing factor. The default is to run at full speed.

         -W <warp>, controls the Warp factor described in 2.1.2,
         defining the virtual processor velocity. This value must be
         in the range of 0.0 to 10.0. The highest velocity is 10.0.

         -b, -p, -u, -k are reserved internal options.
