Home Contact News


Applications Products Services Support About EuroSim

EuroSim

Features

EuroSim Application Programming Interface
Within EuroSim, the concept of an API refers to the set of rules about the interface between the application model and EuroSim itself. A complete EuroSim application model will typically consist of a number of sub-models.

A sub-model simulates some aspect of the real-world system, typically by providing a number of functions that operate on a dataset contained within that sub-model. In reality, a sub-model is a single file of source code.

API schema

Each interface works two ways. So, API is:
  • a set of requirements on the sub-models, i.e. constraints. These constraints allow EuroSim to run these sub-models and access the functions (Ada data and entrypoint items take their names as package.variable and package.procedure respectively) and data contained in the sub-models;
  • a set of services provided by EuroSim for direct use by sub-models, to execute some simulation/simulator specific tasks, such as stopping the simulator or getting the simulation time.
Constraints
Coding Constraints:
The constraints on the sub-models are the following:
  1. sub-models shall be coded in ANSI-C, F77 or Ada95;
  2. sub-models shall not use UNIX system calls;
  3. sub-models cannot use Ada95 tasking and exception handling features;
  4. functions that have to be scheduled by the real-time scheduler shall not have parameters nor return values; such functions are called entrypoints. (Of course a sub-model may have other functions that do have parameters);
  5. only variables with a load time fixed address in memory can be accessed by the EuroSim tools and services (the word function is used in a generic way and includes besides C functions, F77 subroutines and Ada procedures ) ; such variables are called globals.
Note that the API is only about the interface between the model and EuroSim. It does not constrain any of the interfaces between the various sub-models within a EuroSim model. The latter is the responsibility of the Model Developer, who can use explicit function calls and shared data as required. Interfacing sub-models written in different source languages is possible, by using standard Silicon Graphics conventions, for example, C variables appended with an underscore map onto F77 variables with the same name (but without the underscore).

Identification of API Items in the Source Code
When code is scanned via the EuroSim API editor, the user (the Model Developer) sees a graphical display of all available entrypoints and globals as parsed directly from the sub-model source code, and can then select which ones are required to be accessed for simulation purposes, supplying additional information for these if required. This information is stored within the sub-models by means of the so-called API keywords, in such a way that normal compilation of the sub-model is not affected (ie. in language specific comment blocks).

The following table gives a summary of the API keywords and the corresponding language constructs. All variables and functions matching these constructs will be provided to the Model Developer for confirmation of API status and further specification where necessary.

API Table


Adding Attributes to API Global Data
A number of global data sub-categories exist, depending on the use of the globals by the sub-model(s):
  • globals used only by the sub-model which declares them are called global_state; these globals are private to that sub-model, and represent (in a truly object-oriented way) the state of that sub-model; they cannot/may not be used by other sub-models;
  • globals that are written by this sub-model and may be read by other sub-models are called global_output;
  • globals that are read by this sub-model, but are defined and written into by another sub-model are called global_input.
The latter two categories are used by the Model Developer to establish data communication between the various sub-models; the categories are not mutually exclusive and some variables may fall into both.

API Schema 2

If a global variable is selected for inclusion as part of the API, attributes can be provided by the Model Developer. This information becomes available to the Test Conductor and Test Analyst, and ensures that the meaning and value of each variable is clear to all simulation users. All provided information is stored (by the API editor) within the sub-model source code. The attributes include:
  • description and unit;
  • default, minimum and maximum values.
The identified globals (identified through the API keywords) are accessible by the EuroSim tools and services. This allows the Test Conductor to monitor variables during simulation and to record them for example. He/She can also manipulate these variables and their values through events and actions within the mission definition.

The Model Developer can, however, ensure that use of and updates to data variables are meaningful in the context of the model, by using the API editor to set the minimum and maximum values of a particular global. The Test Conductor will then be able to set the variable only to a value inside these limits. Furthermore, a global may be tagged as read-only, prohibiting any modification by the Test Conductor. A read-only global is called a parameter in EuroSim.

API Table 2

A global tagged as a parameter can thus only be read, with one exception: it can be assigned an initial value, using the initial condition editor. This value will be used by EuroSim to set the value of that data item before any user defined task will run (including those tasks which initialize the model). The Model Developer can thus employ such global parameters to parameterize his model.

Adding Attributes to Scheduling Entrypoints
Selected entrypoints can also be given additional information by the Model Developer, basically a description. Entrypoints are built into schedulable entities (tasks) using the Schedule Editor, at which point further information at the task level can be provided, such as estimated execution times, breakpoints, etc. This information is specific to tasks and not API entrypoints and hence is not held in API.

Services
EuroSim provides a series of library functions (services) which can be called directly from sub-model source code. An indication of the type of functions available is given.

Realtime Memory Allocation
These memory allocation functions are equivalent to their standard malloc(3) counterparts with the exception that the EuroSim calls are optimised for parallel/realtime usage, and checks for memory exhaustion are built-in.
  • void *esimMalloc(size_t size)
  • void esimFree(void *ptr)
  • void *esimRealloc(void *ptr, size_t size)
  • void *esimCalloc(size_t nelem, size_t elsize)
Realtime Timing Functions
These functions return information on the elapsed wallclock time and simulation time. The simulation time is set to zero on leaving the initialised state, and is incremented at the highest task frequency contained in the schedule. The resolution of the high resolution version depends on your SGI platform; for a Challenge or Onyx, the resolution is 21 nanoseconds.
  • double esimGetSimtime(void)
  • double esimGetWallclocktime(void)
  • double esimGetHighResWallclocktime(void)
Realtime Simulation State Functions
This allows interrogation and setting of current simulation state. The enumerated type State has values of: unconfiguredState, initialisingState, executingState, standbyState and stoppingState.
  • State esimGetState(void)
  • Boolean esimSetState(State state)
Realtime Reporting Functions
These functions allow the Model Developer to put messages in the code which at runtime are displayed on the Test Conductor interface. These can be simply comments or verbose information, or warnings, or errors. A report can also be made where the severity level is explicitly given.
  • void esimMessage(const char *format, ...)
  • void esimWarning(const char *format, ...)
  • void esimError(const char *format, ...)
  • void esimReport(const Severity level, const char *format, ...)

Left arrow Up arrow