Here, you can find some general explanations and hints that did not
fit anywhere else.
Topics:
How to start working with SimUTC
Choosing the target environment
Simulation Types
Compiler Macros
Page Layout
Access Icons
Resources In Use
How to start working with SimUTC
SimUTC consists of lots of small files, each of which probably contains
not more than one class. That makes it very hard at first to overlook the
whole project. However, as you become more proficient and know where you
can find what you seek, you will see that it is easier to trace down errors
and to test and maintain the project. The drawback is that there is no
obvious modularization (p.e., several files have to do with error handling,
there is not one general file where one can find everything) and that it
is hard at first to find the file you need.
For starters, only try to change things that are described in the manual.
Do not try to understand all at once. Start by adding your own synchronization
algorithm or your own network. Take a look at the manual pages (Online
Manual) describing the base classes you need. Every class description contains
lots of links to other classes that are needed. Try not to get lost in
details, just look at the things you really need. The advantage of having
many files is that you will never have to look at most of them. They just
do work for you, but they are all tested and can be assumed to work correctly,
so you need not bother with them at all.
Choosing the target environment
The project SimUTC was originally developed as a full simulation which
is executed on a Linux PC. However, it was intended to be easily portable
to a certain target hardware where some components like the network and
the clock are available and need not be simulated. The operating system
on this target is pSOS. Since there are always some operating system specific
details to consider, it was not possible to fully and transparently simulate
the pSOS environment in Linux. Therefore, you have to choose the operating
system by defining exactly one of the following constants:
-
DOS_SIM: this constant is only used for code
tests in Windows, you will never need it
-
LINUX_SIM: define it when using the C++SIM simulation library
on Linux
-
PSOS_SIM: should be defined when porting to the hardware
The definition should be passed to the compiler, probably with an option
like -D. For example, the GNU compiler used in Linux would require the
option -DLINUX_SIM.
Simulation Types
-
pure simulation: This means the full simulation which is executed
in Linux. The simulation uses the C++SIM simulation library to simulate
pSOS tasks. Files with this classification are only needed when working
in Linux.
-
hardware-based simulation: This is the ported simulation which
works on the target environment and uses pSOS as operating system. Files
with this classification are only needed when working with pSOS.
-
simulation: This classification is used for files that are always
needed, independent of the environment.
-
evaluation: With SimUTC comes a small evaluation program (SimUTC/Sources/EvalSys).
Files with this classification are only needed by the evaluation and have
nothing to do with the simulation.
Compiler Macros
These are all macros that influence the behaviour of SimUTC. You should
define them with the -D compiler option and recompile the whole project.
-
ADDITIONAL_PNODE_DATA: Set it to a positive integer if a P-Node
should send its data more than once. The value of the macro specifies the
number of additional sends.
-
CPPSIM_V1_5: If you use C++SIM version 1.5. This is not recommended,
because SimUTC has not been tested with it since C++SIM 1.6.1 was used.
You should better upgrade to at least 1.6.1, but if for some reason you
have to use version 1.5, you can define the macro and give it a try. However,
SimUTC may not work.
-
DOS_SIM: If you are working with C++SIM under Windows95 or NT.
This version of SimUTC does not support these operating systems, so you
should not define the macro. In any case, always define exactly one of
the macros DOS_SIM, LINUX_SIM,
PSOS_SIM.
-
LINUX_SIM: Define the macro if you are working with C++SIM under
Linux.
-
NDEBUG: Define the macro if you do not want any error outputs.
In this case, all Assert(), Check()
and Report() statements will expand to void. Not
recommended, since the output of the simulation can help you to find configuration
errors.
-
NO_PRELOAD: If you define this macro, then the clock synchronization
algorithm does not preload a new clock value so the clock can take it over
at once at the resynchronization time, but it sets the new clock value
at the resynchronization time. Unfortunatly, a bug in SimUTC currently
makes it necessary to define this macro in pure simulation.
Note that in pure simulation, the two approaches yield the same result,
and that in hardware-based simulation, the code which contains the bug
is not necessary anyway. So setting the macro in pure simulation is no
problem. The only difference is that with NO_PRELOAD defined, SimUTC will
send the event ClockUpdate, whereas without the
macro, it will send the event ClockPreload.
-
PACKED: You have to set the macro to whatever keyword your compiler
uses to pack structures.
In pure simulation, structures do not have to be packed, so you can
also set it to the empty string.
In hardware-based simulation, structures must be packed. If your compiler
has no keyword for packing structures, you should set it to the empty string
and you will have to use some other means to guarantee packing of NTI driver
structures (maybe some other compiler option).
-
PSOS_SIM: Define the macro if you are working with the hardware-based
simulation under pSOS. You have to port SimUTC to the hardware before you
can use the program, so probably you should not define the macro right
now. In any case, always define exactly one of the macros DOS_SIM,
LINUX_SIM,
PSOS_SIM.
-
SIMUTC_DEBUG: If you define this macro in pure simulation, then
error output is printed to the screen at once, not passed to a task. This
can be useful if there are problems with C++SIM and process scheduling
does not work. But as long as SimUTC works (can at least be started and
stopped without any SegFaults), do not define it.
In hardware-based simulation, the macro is not used.
Page Layout
All pages of the Online Manual have the following structure:
-
file name: one or more files, which are described in this page.
-
author: the name of the author of the original code, if the code
was not developed by the author of SimUTC.
-
classification: the classification of the file(s). This must be
one of
-
pure simulation: the file is only available in pure simulation
-
hardware-based simulation: the file is only available in hardware-based
simulation
-
simulation: the file is available in both simulation types
-
evaluation: the file belongs to the dummy evaluation and has nothing
to do with the simulation
-
contents: the contents of the files (types, classes, functions)
which are described.
-
derived from: if the page describes a class, this line names the
base class. The line may not be there if there are no classes, or if they
do not have a base class.
-
use: the use of the items.
-
text describing the contents of the file(s).
Access Icons
Coloured icons are used to mark the access type of types, functions
or variables:
marks
global
items, which may be accessed by everyone.
marks
local
items, which cannot be used outside the scope of the implementation file
in which they are defined.
marks
public
class members, which can be used by everyone through an object of the class.
marks
protected
class members, which cannot be used outside the scope of their class or
derived classes.
marks
private
class members, which cannot be used outside the scope of their class.
Static functions of a class are marked like normal class member functions,
but have the keyword static in their function prototype.
Resources In Use
The paragraph lists the UTCSU resources, namely the duty timers, that
are already in use. If you plan to enhance SimUTC and want to use duty
timers, you have to restrict yourself to those that are not on the following
list. Please note that the UTCSU itself needs some duty timers as well,
so you should not use these either (refer to the UTCSU documentation for
a list of all internally used timers).
-
Duty Timer B1: is used by CClockInterface to
trigger amortization
-
Duty Timer B4: is used by CClockSync to achieve
the synchronization round period
-
Duty Timer B5: is used by CLance to delay messages
-
Duty Timer B6: is used by CClockInterface to
achieve the drift wobbling period
Do not use any of these timers, even if you know that they are not needed
(p.e., if you have disabled drift wobbling). The timers are always initialized
by the modules and are affected by resets. They may be accessed (most likely
turned off) during normal operation even if they are not used.
last modified: Fri Feb 5 18:56:18 1999