MC-3020 Model Compiler
- User's Guide

The purpose of this guide is to enable the user of the MC-3020 model compiler to generate and execute an ANSI C program from Shlaer-Mellor xtUML models specified in the Nucleus BridgePoint Model Builder. Essential tasks that this guide will enable the user to perform include the following.

This guide is written for software engineers who are using the Shlaer-Mellor development method and will implement their system using the MC-3020 model compiler. It assumes that the user is familiar with the ANSI C programming language and general usage of the development platform and its software development utilities.

There are various roles that software engineers can play in the course of developing a system. These roles reflect the different types of tasks that must be undertaken to successfully specify, design, construct, and test a system. Roles that are relevant to the usage of the MC-3020 model compiler include the following.

An engineer in each of these roles will be looking for different types of information in this guide to fulfill the tasks of that role.

The Analyst will want to understand how to use MC-3020 modeling conventions to specify such things as instance initialization and bridge operations. The Analyst will also be interested in understanding the limitations that MC-3020 places on the xtUML models.

The Software Architect will want to understand how to install and run MC-3020 as well as understand its structure well enough to maintain it.

The System Architect will want to understand the underlying software design or architecture provided by MC-3020 and the marking options that are available for translating the xtUML models into ANSI C code.

The Programmer will want to understand the published interfaces to the MC-3020 generated system and how to use them to successfully interact with the generated components.

The Tester will want to understand how to execute and debug the generated system for ``black box'' testing, and how the system is constructed and operates for ``white box'' testing.

The following section provides guidance on using this guide to meet these needs.

The guide is assembled with the more frequently accessed chapters toward the front. These chapters are in roughly chronological order according to how they will be used. General Shlaer-Mellor development background is provided toward the end.

Here is a short description of each chapter and appendix.

Appendices have been provided.

The translation engine embodied in the MC-3020 Model Compiler performs two passes across the xtUML model under translation. The first pass analyzes the model structure and action language semantics of each domain. The results of this analysis drive the generation in the second pass. The second pass generates code and data that is minimized and optimized for speed. Unaccessed data and unneeded code are eliminated.

This multi-pass intelligence spans domains and allows for optimizations at the system level based on information collected and collated from all domains in the system.

Preemptive multi-tasking is supported on the Nucleus PLUS® real-time operation system (RTOS) and on systems supporting POSIX threading. Single-task operation (with or without and RTOS) is also supported. Tasking supplies a rich means of providing preemptive prioritization among the xtUML classes running in the system.

Preemptive task/thread prioritization is provided in the generated C code. Groups of xtUML classes are mapped to tasks running at differing priorities.

MC-3020 also provides for prioritization through the marking of events. Higher priority xtUML threads of control can run without being preempted by lower priority activities.

MC-3020 cleanly translates large systems consisting of multiple xtUML and realized domains. Support is provided to integrate and interface to hand-craft, legacy and/or off-the-shelf code.

MC-3020 supports the marking of persistent classes. The instance data for classes marked as persistent is restored at power-up from a non-volatile storage (NVS) device.

A set of metrics is generated and reported each time the model compiler is run. Statistics on classes, associations, events and first pass analysis results are stored in a report directory.

Metrics provided can be fed back to the analyst to provide a focus on recognized dangerous practices and fully illegal operations and accesses. Some of the metrics relate to sizing and complexity. These metrics could easily be tracked over the life of a project to provide quality and effort related measurements.

Based upon information modeled in Nucleus BridgePoint Model Builder MC-3020 automatically generates source code frameworks for operations and outbound bridge implementation. These skeleton files will actually compile as generated. The user is saved from delving into generated code to divine interfaces required for these boundary functions. Kind and helpful comments are provided to guide insertion of bridge and operation implementation code.

Support is provided for translation of AL in operation and bridge descriptions. The same action language used for Nucleus BridgePoint Model Verifier is translated into the of bodies of the operation C source files and the bridge skeleton files.

Several hooks have been supplied to allow easy interfacing of user supplied code to the system level generated code. A source module is automatically generated that supplies empty functions which are invoked at various points during initialization, dispatch processing and shut down. These empty functions can be populated with user code for ``can't happen'' events, hardware bring-up, ``background'' processing, legacy clean-up and more.

To allow optimization for space and control over precision, the storage classes of integer and real based user-defined data types (UDTs) can be supplied by the user. MC-3020 also allows user-defined data types to be implemented as pointers. The pointer types are very convenient for passing across bridges (in both directions). Precision and pointer information is provided to the model compiler through marking.

Further optimization of space is provided through ANSI C bit field support. Multiple attributes can be packed into a single word of storage. This feature may also be used (with caution) in conjunction with memory mapped classes to model hardware with xtUML constructs.

MC-3020 attempts to optimize select any [inst_ref] from instances of [key_letters] where [where clause] when the where clause is checking for equality of the identifier. MC-3020 optimizes for code space. In addition, hooks into the scanning routines are provided to enable customizations to the selection search algorithms. Applications dealing with large collections of class instance data (hundreds or thousands) may use these hooks to further speed the selection process.

MC-3020 provides a safe way to bridge into the application from interrupt handlers (or other external tasks). Consistency is maintained in software architecture data structures and application data access sets.

A means is provided for the user to supply application specific fule file functions. This capability serves to extend the marking capabilities of MC-3020. It is possible to steer code generation in such a way as to provide customizations characteristic of particular target platforms, compilers and tool sets.

MC-3020 is purely ANSI C and generates code that can be compiled by any compiler compliant with the ANSI standard. The core model compiler uses no libraries or system functions. stdio.h is included simply for convenience during debug (for printf, etc). All generated code is simple, native C.

As of version 3.1, MC-3020 supports initialization of preexisting instances in data. This provides a substantial optimization in both bring-up execution speed and overall code footprint. Instead of creating, relating and initializing all of the classes at start-up, pre-existing class instances can be pre-populated with static initializers. Support is maintained for dynamic initialization using an initialization function (or an initialization object).

As of version 3.1, MC-3020 supports xtUML-level model debugging with Nucleus BridgePoint Model Debugger. This support allows execution tracing at state action as well as the AL statement level. The state of the system can be openly queried and viewed at any point of execution. Support is limited to execution on the host computer or socket-capable targets with sufficient RAM capacity.

Each class is translated into an ANSI C structure. Instances are maintained in collections of instances of classes (class extents). Space for class instances is pre-allocated at bring-up time.

Associations are optimized by storing a copy of the instance handle as extended attribute data. This optimization is implemented between sub/super-types as well.

As with data attribute elements, MC-3020 optimizes away unused referential attributes. Relate, unrelate (link and unlink) and association traversal operations are optimized for low overhead. These operations are performed directly on instance data when appropriate avoiding the generation and associated run time overhead of function calls.

The translated state models are optimized for speed. State transitions and action dispatches execute in constant time. The state event matrix is implemented as a two dimensional array. Rows represent states; columns are indexed by event to obtain the transition.

Domain functions (bridges) and operations are listed together, because MC-3020 treats them with a great deal of symmetry. Domain functions and operations translate into C function invocations. Any number of arguments can be passed.

Domain functions (synchronous services) are supported between domains. Events across bridges are not allowed.

MC-3020 generates bridge and operation frameworks. These frameworks provide the entire invocation interface. A comment is provided to guide the user in where to insert implementation code. These skeletons will compile with or without inserted user code. However, the bridge must be declared to the generation system and the bridge must be wired. See Chapter 4, Marking for details on how to accomplish this.

These are the unclassified features.

All of the marking files for a project will be found in the gen folder. These files can be edited by double-clicking on the file or by right clicking and opening the file for editing. Note that the marking files end with the file extension .mark. System level marking files include bridge.mark, datatype.mark, registry.mark and system.mark.

The domain level marking files are prepended with the name of the xtUML model (domain) with which they are associated. There will be a class marking file [model]_class.mark, a domain marking file [model]_domain.mark and an event marking file [model]_event.mark for each model (domain) in the project.

To supply marking to the code generation process, edit the marking files. Chapter 4, Marking explains the markings available to control the code generation of MC-3020

The code generation process creates a folder called code_generation in the gen folder. The is the generation workspace and is largely a temporary ("scratch") work area for the model compiler. It will be deleted before new code generation begins. The code_generation folder contains the files and folders that users of MC-3020 versions 3.3 and before are accustomed to seeing.

After code generation runs to completion, the generated source code will be copied into the src folder of the project. If running with Nucleus BridgePoint Model Debugger marking enabled, an XML file for each debugged model will also be copied into this folder.

Domain Registration is a reflection of the Shlaer-Mellor domain chart. All domains are declared in the registration marking file.

The registry.clr marking file is used to register all the domains, both xtUML and realized, which will be used to construct system load images. Domain registration is a mandatory marking file. Domains are registered by providing a registered name in correlation with a repository name. Registration of domains provides indirection between the name space of Nucleus BridgePoint Model Builder and the generation and build environments. Registration provides a clean break between the naming choices of the analysts and model maintainers and the back end code generation. This conveniently allows the same model to be named differently in different repositories, or for versioning of models to be independent of versioning of the generation.

To register the domains in the system, edit registry.clr.

.invoke RegisterOoaDomain( "autosampler", "AS", 69 )
        

.invoke RegisterRealizedDomain( "", "CARPIO", 101 )
        

The registry.clr described above declares the names and types of the domains on the domain chart to be included in the system build. To round out the manifestation of the domain chart, bridges are wired together in the bridge.clr file. The word ``wiring'' is used as an analogy to an electrical circuit. After the components of a circuit are placed, the interconnecting wires must be defined. In like manner, domains on a domain chart are interconnected with bridges. These bridges must be declared in the bridge marking file.

The bridge.clr marking file is used to wire together all the domains, both xtUML and realized. This marking file is used to specify inter-domain bridge signatures to the model compiler's translation engine. All references to a domain name in this file correspond to the registered domain name, and not the Nucleus BridgePoint domain repository name.

Beginning with version 2.0 of MC-3020 there are two ways to wire bridges between xtUML domains. The new method wires bridges using Synchronous Services (Domain Functions); the old way uses Bridge Objects (FBOs). Synchronous Service bridges are preferred, because they provide a cleaner interface.

To wire the domains in the system together, edit bridge.clr.

.invoke WireSynchServiceOoaBridge( "HOME", "AWAY_EE", "AWAY" )
        

.invoke WireOoaBridge( "HOME", "AWAY_EE", "AWAY", "AWAY_FBO" )
        

.invoke WireRealizedExternalEntity("ODMS", "PIO", "PIO", "PIO", "PIO_bridge.h")
        

.invoke TagSyncServiceSafeForInterrupts( "ILB", "kick_start" )
        

Nucleus BridgePoint allows the user to define special data types. Marking is used to define the precision of these data types. This is particularly useful to reduce the storage (say from 16 or 32 bits to 8 bits) of class attributes when the ranges of the attributes are known to be limited. User defined types which are also enumerations are included in the category of types that can be controlled. The datatype.clr provides the means for specifying these data type specializations.

Note that core types can be marked with this function as well as user defined types (UDTs). For example, the core type real can be marked to generate "double" precision.

The return data type for bridges and operations can be user defined data types. Empty operations can be used as a sort of variable declaration in conjunction with UDT precision tagging.

.invoke TagDataTypePrecision( "MyDom", "Octet", "uchar_t", "" )
.invoke TagDataTypePrecision( "MyDom", "FunkyReal", "double", "666.999" )
.invoke TagDataTypePrecision( "*", "SysWideLong", "long int", "-1" )
        

.invoke MapDataTypeAsPointer( "MyDom", "DataPacket", "char", "" )
.invoke MapDataTypeAsPointer( "DomA", "AcmeType", "SomeStruct_t", "legacy.h" )
        

.invoke TagUninitializedEnumerationValue( "MO", "wattage", "4" )
        

.invoke TagUninitializedEnumerationValue( "MO", "*", "0x40" )
        

.invoke TagUninitializedEnumerationValue( "*", "wattage", "0x20" )
        

.invoke TagUninitializedEnumerationValue( "*", "*", "100" )
        

.invoke .invoke TagEnumeratorDiscreteValue( "MO", "wattage", "low", "4" )
.invoke TagEnumeratorDiscreteValue( "MO", "wattage", "med", "0x20" )
        

.invoke TagEnumeratorDiscreteValue( "*", "wattage", "high", "0x40" )
        

There are characteristics of the system as a whole that may need to be controlled during translation. Several constants define resource allocation and generation constraints. Some constants allow for ``tweaking'' the system to obtain optimal performance in terms of size or speed. These constants can be marked as the system architect desires.

Marking at the system level is provided by a set of marking files in the system directory in the build area. The file system.clr provides the means for specifying these system constants.

Within system marking, the flavor of collection containers can be specified. Different collection flavors provide optimizations for space or speed.

.invoke EnableTasking( "Nucleus", "", 4 )
.invoke EnableTasking( "POSIX", "serialize", 2 )
        

.invoke SetTaskPriority( 0, "100" )
.invoke SetTaskPriority( 3, "high" )
        

.invoke TagMaximumStringLength( 16 )
        

.invoke TagMaximumRelationshipExtentSize( 8 )
        

.invoke TagMaximumSelectionExtentSize( 12 )
        

.invoke TagCollectionsFlavor( 20 )
        

.invoke TagMaximumSelfDirectedEvents( 3 )
        

.invoke TagMaximumNonSelfDirectedEvents( 5 )
        

.invoke TagMaximumPendingOoaTimers( 6 )
        

.invoke TagMaximumInterleavedBridges( 4 )
        

.invoke TagInterleavedBridgeDataSize( 2 )
        

.invoke TagModelDebuggingOn()

.invoke MarkPersistenceCacheDepth( 16, 32 )

.invoke MarkPersistenceCacheDepth( 1000, 500 )

Within MC-3020 domain level customizations can be applied. The marking file domain.clr is the place to tag the customizations.

.invoke TagInitializationFunction( "CreateAndPopulate" )
        

.invoke TagExcludeObjectFromCodeGen( "TST_OBJ" )
        

.invoke TagExcludeSubsystemFromCodeGen( "MyVerifierUnitTests" )
        

.invoke TagFunctionTranslationOff( "CreateRelateInit" )
.invoke TagFunctionTranslationOff( "TestScenarioFive" )
        

.invoke TagStateTransitionTracingOn()
        

.invoke TagActionStatementTracingOn()
        

.invoke TagEmptyHandleDetectionOn()
        

.invoke TagFirstPassOptimizationsOff()
        

MC-3020 provides several customizations that can be selected on a class boundary. The object.clr provides the means for marking these class specializations.

.// NOTES:
.// (1) To map a specific class, use "" for "ss_name"
.//     and provide the class key letters in "class_key_letters".
.// (2) To map all classes in the subsystem to the given task, provide
.//     the subsystem name for "ss_name" and "*" for the "class_key_letters".
.// (3) To mark all classes in the domain as mapped to a task, use "*"
.//     for "ss_name" and "class_key_letters".
.//
.invoke MapClassToTask( "", "MP", 1 )
.invoke MapClassToTask( "TRACKING", "*", 3 )
.invoke MapClassToTask( "*", "*", 0 )
        

.invoke TagObjectExtentSize( "FRODO", 20 )
        

.invoke TagSystemObjectDefaultExtentSize( 24 )
        

.invoke TagPEIsDefinedInData( "", "DOG" )
.invoke TagPEIsDefinedInData( "VET", "*" )
        

.invoke TagStaticInstancePopulation( "", "EXP" )
.invoke TagStaticInstancePopulation( "LAB", "*" )
        

.invoke TagReadOnly( "", "BBALL" )
.invoke TagReadOnly( "GYM", "*" )
        

.// To mark as persistent a specific class, use "" for "ss_name"
.// and provide the class key letters in "class_key_letters".
.invoke TagPersistentClass( "", "MP" )

.// To mark all classes in the subsystem as persistent, provide
.// the subsystem name for "ss_name" and "*" for
.// the "class_key_letters".
.invoke TagPersistentClass( "TRACKING", "*" )

.// To mark all classes in the domain as persistent, use "*"
.// for "ss_name" and "class_key_letters".
.invoke TagPersistentClass( "*", "*" )

.// To mark as non-persistent a specific class that had previously
./  been marked as persistent, use "" for "ss_name" and
.// provide the class key letters in "class_key_letters".
.invoke TagNonPersistentClass( "", "ASN" )
        

.invoke TagClassOperationTranslationOff( "T", "Cooking_Initializing" )
        

MC-3020 provides prioritization through the marking of events. Events can be tagged to have priorities that accelerate the delivery of past events of lower priority that are currently outstanding. This provides the user with a degree of control over the sequencing of xtUML threads of control within the system. event.clr provides the means for specifying these event prioritizations.

.invoke TagPriorityEvent( "CAR1", 4 )
        

First pass translation collects statistics used to conservatively estimate the number of container nodes (containoids) required by the system.

There are three different uses for instance containoids: class extents, association extents and selection extents. Selection extents govern the total size of transient instance reference set variables in the actions. This represents values in the variable type inst_ref_set. The required number of containoids for each flavor is summed to provide the upper limit to total containers.

#define SYS_MAX_CONTAINERS \
    ( SYS_MAX_OBJECT_EXTENT + SYS_MAX_RELATIONSHIP_EXTENT + SYS_MAX_TRANSIENT_EXTENT )

SYS_MAX_OBJECT_EXTENT is a sum of all of the extent counts across all the domains of the system, which are sums of the class extents in each domain. Each class extent is allocated to be the system default for class extents, a marked value of the system default or the marked value for the specific class.

Selection extents are calculated by multiplying the largest number of selects that can occur in any action by the largest extent of any class. Thus allowing for the worst case action to select the largest class extent each time. This value is set in SYS_MAX_TRANSIENT_EXTENT.

transient containers = ( max selects ) * ( largest class extent )

Association extents are allowed to be as big as they would need to be if all instances on the MANY side were always participating. This value is set in SYS_MAX_RELATIONSHIP_EXTENT.

association containoids = ( number of MANYs ) * ( largest class extent )

The following marks govern these extent sizes:

See the proper sections in the MC-3020 Users Guide for details on these marking parameters.

Association extents refer to the sets of instances participating in a association with multiplicity MANY. Sets built from linked lists are used to optimize traversal of associations with multiplicity MANY. For example, in the following model, A 1---R1---* B, class B does not need an extent set; it simply needs a single pointer reference to the A instance. The A instance however does need a set of instance references. Such a set uses "containoids" to collect the B instances related to the A instance. MC-3020 calculates the worst case (biggest possible) association extent.

The extent can be marked to be smaller than the worst case maximum using TagMaximumRelationshipExtentSize. TagObjectExtentSize will also have an effect on the calculated total.

If no extent size marking is supplied, MC-3020 will calculate a worst case for a model of a higher number of containers. MC-3020 will see R1 and allow for all possible instances of B to participate with instances of A. (This is the most important point!)

Another way to understand how MC-3020 calculates this maximum is as follows:

This sum across all domains in the system will be the SYS_MAX_RELATIONSHIP_EXTENT.

The application node is created using the rox_init_node command found in the MC-3020 bin directory. The application node is divided into two flavors of subdirectories that represent the division of the architecture oriented code and the application oriented code. The architecture code is stored into the subdirectory called system. The application subdirectories are named according to their domain repository names.

The application node has a few files in its root.

A command line build utility called rox_build allows for custom automation of the build process and for building from exported model files. rox_build operates on Nucleus BridgePoint models exported to *.xtuml/*.sql/*.bak files as well as *.xtuml files from Nucleus BridgePoint version 7 and beyond. rox_build will create a build directory, copy in the supplied marking files and translate a model supplied in a file. This frees the build process from the Nucleus BridgePoint model repository.

One expected use for rox_build would be automation of batch oriented build operations. Once marking and configuration of a particular build have been established interactively, rox_build can be used to repeat the build in a single step.

rox_build can also be used in conjunction with third-party version control systems (such as CVS, CleareCASE). rox_build could also be used when building models extracted from multiple repositories. A build server could use this utility to perform automatic translation of newly checked in materials. rox_build also serves in test suite automation.

Note that .mark is superceding .clr for the extension of marking files (formerly coloring files). .clr is maintained for backward compatibility.

To get the latest syntax for rox_build run: rox_build -h. Command line help will be supplied.

Where the command line parameters are:

rox_build -d d -o dogs -m dogs.xtuml -r ARCH -f dogs_domain.mark -f registry.mark 
      

rox_build -d ae1 -o as2 -s as2.sql -r CARPIO -r SPPIO -r UI -f as2_domain.mark
-f as2_event.mark -f bridge.mark -f registry.mark -f datatype.mark -o exp
-s exp.sql -f exp_domain.mark -f sys_user_co.c -f sys_user_co.h -f link_sys
      

Note that (-f) files should be listed immediately following their own domain when making a multi-domain build.

MC-3020 supports the specification of a discrete value for each of the enumerators for an enumeration. There are two ways in which the value can be assigned: 1) through the use of a keyword in the description of the enumerator, and 2) through marking. In the absence of any value specified by the user, MC-3020 assigns a default. MC-3020 gives priority to those values specified via marking.

Each domain that uses an enumeration must define the enumeration. In other words, Nucleus BridgePoint Model Builder currently provides no means to place a set of enumerations in a common area where all domains being modeled can access them.

In order to avoid duplicate definitions for identical sets of enumerations in the generated code, MC-3020 provides the ability to inform the translation process of a single domain that ``owns'' the enumeration. Doing so produces a declaration for the enumeration in a single translated domain which other domains include.

Enumerations that are defined within a modeled domain can also be used by manually written code.

The user-defined type that represents an enumeration is a legal type for all of the following data items:

Enumerators can also be used in the following operations:

Edit sys_user_co.h to activate particular callout functions. Edit sys_user_co.c to add code to the defined callout routines. It is important that both files be edited to enable the callout capability.

        void UserInitializationCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserPreOoaInitializationCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserPostOoaInitializationCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserBackgroundProcessingCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserPreShutdownCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserPostShutdownCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserEventCantHappenCallout( const Escher_StateNumber_t current_state,
                                         const Escher_StateNumber_t next_state,
                                         const Escher_EventNumber_t event_number
        )
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserEventNoInstanceCallout( const Escher_EventNumber_t event_number
        )
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserEventFreeListEmptyCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserEmptyHandleDetectedCallout( const char * object_keyletters,
                                             const char * s )
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserObjectPoolEmptyCallout( const char * domain,
                                         const char * object_name )
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserNodeListEmptyCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserInterleavedBridgeOverflowCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

        void UserSelfEventQueueEmptyCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        void UserNonSelfEventQueueEmptyCalloutf()
        {
          /* Insert implementation specific code here.  */
        }
        

When specifying a system with xtUML models, the analyst is allowed to assume that there are preexisting instances of classes within the models. MC-3020 provides two methods for specifying these preexisting instances, the values of their attributes, and the relationships between them. This dynamic creation, linking and initialization of preexisting instances is described in the section called “Dynamic Initialization”. Defining preexisting instances with data is described in the section called “Constant Initialization”.

The preexisting instances of xtUML classes can be created during system bring-up from the specifications provided by the analysts in the form of initialization functions. These preexisting instances are created before normal execution of the system is allowed to proceed. Thus, the xtUML models can assume that all the preexisting instances exist before any events are accepted.

Note that MC-3020 automatically creates a single instance for every assigner in the system. The analyst does not need to model or mark anything to make this happen.

In order to avoid confusion resulting from the following paragraphs as well as in future documentation, the following definitions will be used with respect to instance populations and preexisting instances:

It is easy to see that many combinations of static/dynamic, read-only, implicit/explicit and preexisting can occur in normal system analysis.

In MC-3020 3.1 and beyond, preexisting instances can be defined in data for any normal modeling construct supported by MC-3020 For example, dynamic or constant initialization can be defined for:

Dynamic initialization uses sequences of action language statements to create, relate and set attributes of preexisting instances. This form of initialization has been supported by MC-3020 since the first release (1.0).

Action language statements in initialization functions (or previously in init objects) are executed once when a system first starts. The action language statements perform create statements to create the preexisting instances. Relate statements execute to establish associations between these newly created instances. Action languages statements are executed which write the attribute values of the preexisting instances.

When all of the action language statements are complete for all init functions (tagged with TagInitializationFunction), then all preexisting instances are fully established and initialization is complete.

Advantages to dynamic initialization include:

Disadvantages to dynamic initialization include:

The basic building block for specifying preexisting instances is the initialization function. This approach provides the user with the ability to use the same set of preexisting instances for simulation with the Nucleus BridgePoint Model Verifier as are used during the actual execution of the system on the target platform.

Initialization functions contain the action language that describes the set of preexisting instances for the subsystem or domain. Initialization functions are normal functions and can be invoked during normal system execution as well as at start-up.

The rules for constructing initialization functions are enumerated below.

Figure 8.1, “Autosampler Class Diagram” shows the xtUML class diagram for the autosampler example model. Note that the autosampler example model can be found in the examples directory of your MC-3020 installation. Figure 8.2, “Autosampler Init Function” shows the action language statements contained in the initialization function for the autosampler domain. The function is marked as an init function with the statement

TagInitializationFunction( "setup" )

in the object.clr marking file. This init function executes creates, relates and attribute writes to establish all preexisting instances. The function runs once and only once at system start.

Figure 8.1. Autosampler Class Diagram

create object instance car of CAR;
car.carousel_ID=10;
car.current_position=10;
create object instance row of ROW;
relate row to car across R1;
row.radius=10;
row.current_sampling_position=0;
row.maximum_sampling_positions=20;
row.sampling_time=3000000;  // 3 seconds
row.needs_probe=false;
create object instance probe of SP;
probe.probe_ID=1;
probe.radial_position=20;
probe.theta_offset=40;
probe.current_position="up";
probe.available = true;
    

In systems with more than one domain, dynamic init is only slightly more complex. Initialization functions are written for each domain. These multiple init functions establish the preexisting instances (PEIs) for the multiple domains. The init functions are each marked with TagInitializationFunction in each domain's corresponding object.clr marking file.

In some systems it is important that certain domains be initialized before other domains. Or, there may be requirements on the ordering of the initialization between domains. In these cases, a function in only one domain is tagged as an init function (using TagInitializationFunction). This function then invokes functions in the other domains, thus imposing the desired order on the initialization sequence.

To simulate the xtUML models with the same set of preexisting instances that are used on the target system, the analyst must invoke the initialization functions. Nucleus BridgePoint Model Verifier provides a facility to do this very easily.

Constant initialization involves providing the preexisting instances (PEIs) in the form of constant data. Instead of executing action language statements to create, relate and set attributes of preexisting instances, these PEIs are supplied as constant data already created, related and set.

ANSI C provides a construct called a static initializer. This construct allows constant data to be assigned to a variable at initialization time. MC-3020 provides a method for establishing the preexisting instances data in the form of ANSI C static intializers. The instance collections in the generated system are initialized with this data.

To obtain the PEI data necessary to provide constant initialization, a process must execute action language statements just as in dynamic initialization and then take a "snap shot" of the initialized data elements (PEIs) for use later. The PEI data from the snap shot is captured in an XML format. This PEI data is then used in placed of dynamic initialization action language.

Dynamic initialization as described in the section called “Dynamic Initialization” defines preexisting class instances and the associations between them by producing executable code from analysis model initialization function action language. The code produced in this fashion is executed once at system startup in order to establish any necessary preexisting instances. This mechanism may be unsatisfactory due to:

MC-3020 addresses this issue in such a way as to provide an alternative approach for the establishing preexisting instances.

This approach, illustrated in Figure 8.3, “ Model Debugger Architecture” directly addresses both of the issues of speed and space identified in the introduction to this section.

Figure 8.3.  Model Debugger Architecture

An XML data format has been defined which can represent instances, their associations and their attribute values. A file containing this XML data is generated. Then the constants of this file are supplied when generating the target system. Constant PEI initializers are created which establish PEIs just as if an init object had been executed.

Advantages to constant initialization include:

Disadvantages to constant initialization include:

To use the preexisting instance support, an XML file containing the preexisting instance definitions needs to be supplied to the translation process. It is supplied into the (domain)/schema/sql directory. It is named (domain)_pei.xml.

Note that when the model is changed in any substantial way, the PEI data needs to be regenerated.

To create this file you must run the debugger, execute initialization code and save the results as XML. Two marks facilitate this. TagInitializationFunction marks function(s) to be executed during bring-up. This effectively replaces initialization objects. (Initialization objects are still supported, but discouraged.) Functions tagged to run at initialization bring-up can also be called during run time processing. Functions tagged for initialization are run in alphabetical order.

TagFunctionTranslationOff disables the translation of functions. This is convenient for enabling/disabling test cases. It is especially nice for PEI support. An init function can be tagged for running with model debugger. It can then be tagged off for the production compile using Preexisting Instances defined in data.

In the following example the pei test case (found in the pei directory in the MC-3020 installation) will be translated to use constant initialization. Figure 8.4, “PEI Test Case Class Diagram” shows the class diagram for this model.

Figure 8.4. PEI Test Case Class Diagram

The model is designed to test various forms of associations between classes. Import the backup file, pei.sql, into your installation of Nucleus BridgePoint Model Builder as a model called pei. Check it in and create a configuration view. (Ensure all of the actions are parsed.)

Build a system node for the build (rox_init_node [dir]) and make the domain node (make dom_node domain=pei). Register the pei domain and the "LOG" realized domain by supplying the appropriate Register commands in registry.clr. Enable model debugging in system.clr. Wire the bridge between pei and LOG in bridge.clr, make the bridge skeleton files (make bridge_skel domain=pei ee=LOG) and copy the generated .c and .h files from the system/skel directory into the user/source and user/include directories. Build the executable as normal (make all).

Fire up Nucleus BridgePoint Model Debugger and run the generated executable (bin/rox.exe). Invoke the domain function "setup" from the system browser as shown in Figure 8.5, “MD System Browser for PEI Test Case”. (In Appendix E, PEI Test Case Setup the entire listing of the PEI test case is shown in detail.)

Figure 8.5. MD System Browser for PEI Test Case

After invoking and stepping through the setup function, the Nucleus BridgePoint Model Debugger should show results as in Figure 8.6, “MD PEI Test Case Initializing”.

Figure 8.6. MD PEI Test Case Initializing

Save the session XML into schema/sql/pei_pei.xml under the system node created for this build.

Turn off model debugging in system.clr and block translation of the domain function "setup" (with

.invoke TagFunctionTranslationOff( "setup" )

in domain.clr). Clean out the source code generated with model debugging capability (make clean_all_src and make clean_sys_src). Activate the constant initialization capability by marking on the PEIs with

.invoke TagPEIsDefinedInData( "*", "*" )

in the object.clr marking file. By using the asterisks all available XML PEI data will be used.

Rebuild the application with the new marking (make all). The generated executable will be smaller and will start up faster because of the constant initialization.

To perform multiple domain constant initialization the user must collect XML data for each domain separately. A separate Nucleus BridgePoint Model Debugger session is started for each domain. The XML data is saved for each domain under the correct schema/sql directory. Below is a summary example using the autosampler example model (found in examples/ae of the MC-3020 installation).

In Figure 8.7, “Experiment Class Diagram” the experiment (exp) xtUML class diagram is shown. The autosampler class diagram is shown in Figure 8.1, “Autosampler Class Diagram”.

Figure 8.7. Experiment Class Diagram

After the model is built with model debugging enabled, Nucleus BridgePoint Model Debugger and the generated executable (bin/rox.exe are started and the System Browser shows as in Figure 8.8, “MD System Browser for exp and as2”.

Figure 8.8. MD System Browser for exp and as2

The initialization code is run for each domain separately. First, the autosampler domain function "init" is run as shown in Figure 8.9, “MD Initializing Autosampler”. The XML data is saved into as2/schema/sql/as2_pei.xml under the system node created for the build.

Figure 8.9. MD Initializing Autosampler

The Nucleus BridgePoint Model Debugger is exited and restarted (also restarting the generated application). The exp domain function "init" is run as shown in Figure 8.10, “MD Initializing Experiment”. The XML data is saved into exp/schema/sql/exp_pei.xml under the system node created for the build.

Figure 8.10. MD Initializing Experiment

Turn off model debugging in system.clr and block translation of the domain functions "init" in both domains (with

.invoke TagFunctionTranslationOff( "init" )

in the domain.clr marking files). Clean out the source code generated with model debugging capability (make clean_all_src and make clean_sys_src). Activate the constant initialization capability by marking on the PEIs with

.invoke TagPEIsDefinedInData( "*", "*" )

in the object.clr marking files of both as2 and exp domains. Rebuild the application with the new marking (make all).

Following is an example of the gain (reduced code size) achieved by defining preexisting instances in data. Below are size measurements of a test case. The first case shows the output of the size command for a normal init-object-style generation (gcc/Cygwin). The second shows using PEIsDefinedInData.

To interpret the table:

This is a conservative test case. There are no state machines in the model. However there is procedural action language to access all of the instances either created or defined in data. The test case creates a total of 84 instances of 23 different objects with 39 links.

This simple test demonstrates a 15% reduction in code space and a significant speed-up in terms of initialization. Models with many preexisting instances will see very large reductions in code size.

Collections of class instances (objects) must be supported by any model compiler. Processing performs operations on these sets of data. Instances can be collected and organized in several ways. At minimum, a model compiler must be able to support:

We refer to the first case as instance extents. The second are referred to as association extents. The third are transient set variables (often called selection extents).

As of version 3, MC-3020 maintains collections in linked lists. Linked lists are flexible and relatively light weight (small, simple code).

Operations on sets include Insert, Remove, Clear, Copy, Cardinality, IsEmpty, Equality, Contains and Iterate. Some variations on these methods may also be included for various optimizations.

SELECT MANY makes a copy of an instance extent or association extent into a transient set variable. Cursors are used to iterate through sets of instances.

SELECT ANY returns the first element in the instance extent or association extent.

A set generates a different type of variable than does an element in a set. This allows for sets to have attributes such as a head (and perhaps a tail and cardinality). Set elements have attributes such as a link to the next element and a pointer to the substance of the data they contain.

Consistency between the three flavors of collections makes the model compiler simpler. Simpler usually means smaller code, but there are some exceptions to this general rule. Up through version 2.2 of MC-3020, instance extents, association extents and transient sets were treated almost identically. In versions above 2.2, instance extents get special treatment so that the model compiler can optimize for size and speed based upon characteristics true only of instance extents.

Instance extent sets are treated special in that their containers are never returned to the free pool and remain permanently attached to the instance data. Since the instances basically move between active (animate) and inactive (inanimate) lists, there is no need to detach the container as in association extents and transient set variables. Although this breaks the symmetry, it enables the generation of smaller and faster code.

MC-3020 applies these specializations as marking options to enhance the set operation performance of the model compiler generated code.

Singly linked lists are simple and small. For most of the set operations, singly linked lists are fast because of their simplicity. The exception to this is the delete operation. A delete operation on a singly linked set requires the address of the container of the data element being deleted. Delete also requires the address of the container preceding the deleted data and the address of the container following the deleted item. As input we have none of these three addresses but only the address of the data (object) being deleted.

In MC-3020 marked with slist containers, this meant that a search for the data element is required. This search begins at the head of the list and proceeds down the list until the data element is found. Variables track the current node and previous nodes as the list is traversed. Once the data element is found, these node variables contain 2 of the 3 three needed container addresses. A simple dereference of current->next yields the final container address. The singly linked list delete links the previous container to the next container thus unlinking the current node.

As collections get large, this linear search involved in set item deletion gets burdensome.

Figure 9.1.  Singly Linked Lists of Instances

Adding a more capable container node structure alleviates the delete instance problem. With a prev pointer together with the next pointer, it is an easy matter to learn the address of the previous and following containers given the address of the container containing the data to be deleted. Note however, that we are not given the address of the container but the address of the data itself. Thus, unless a clever mechanism exists for deriving (divining) the container from the data handle, we are relegated to linear searches once again.

Figure 9.2.  Doubly Linked Lists of Instances

If data allocation of instances and containers is performed in a special way, there does exist a mechanism for deriving the address of the container from the address of the data.

In MC-3020 versions beyond 2.2, a doubly linked list container is available. Instances and containers are allocated in memory in a way that relates the instances to their containers mathematically. One container pool is allocated for each pool of class instances. These are parallel arrays. Remember that the container stays attached to the instance for the duration of system run time, since instances from the extents are simply moved from inactive to active and back for create and delete respectively.

During initialization, containers are linked to instance data in parallel. Container 0 is the container for instance index 0 of any particular class. Container 1 is the container for the instance at index two in the class pool array for this class. In other words, the array indexes for the containers are the same as the array indexes of the instances for which they serve.

Figure 9.3.  Parallel Container/Object Arrays

Thus, if we know the index of an instance data element, we know the index of the instance extent container pointing to it. We can derive the index of any pointer to an array element through pointer arithmetic.

    index = pointer_to_array_element - address_of( array_element[0] )
    

We now have all the information needed to derive the address of an instance container, its previous container and next container all in constant time. The delete operation on an instance no longer involves a linear search of the extent.

Note that this "magic" only applies to sets managing instance extents. Deletions from association extents, UNRELATES, are not helped and still involve a search of the set. UNRELATES from very large association extents (hundreds or thousands) can suffer from linear search overhead.

A comparison of the two collection mechanisms in light of deleting instances shows the power of the constant time address derivation. Once instance extents grow larger than one hundred, the doubly linked collection mechanism with address derivation begins to show benefit. At extent sizes of ten thousand (10,000), the singly linked collection mechanism becomes two orders of magnitude slower than the doubly linked counterpart.

Another clever way to relate the instance containers to the instances themselves is to allocate them inside of the instances themselves. Under such a scheme, the base instance class would have the container class as its first element. This would amount to overloading the class with container members as data elements, namely next, prev, and object. Such a scheme renders trivial the mathematics of deriving the address of the instance from the address of the container. They are exactly the same. The address of the container is the address of the instance (and vice versa).

Figure 9.4.  Containers Merged Into Instance Data

Such a scheme suffers a weakness in light of preexisting instance (PEI) support. The merged containers scheme adds two or three pointer size data elements to every class instance. To populate the instances with data, it would be necessary to populate the container pointers with the instances. Even if zero, this would mean 4 to 12 bytes of additional constant initializer data per instance in the system.

In light of this weakness, MC-3020 has opted for the parallel array approach to mathematically relating the containers to the instances. Even though MC-3020 does not (currently) use merged containers, there remains a great deal of merit in the approach.

The Model Debugger architecture, as originally conceived, is composed of four primary components: the Model Debugger itself, a host monitor, a target monitor, and an executable image generated from the model to be debugged. The host and target monitors, are separate entities with well-defined functionality. From a conceptual perspective, these four components can be allocated to completely separate processes or processors if it should prove beneficial to do so. Conversely, they can all be placed on the same processor. The Model Debugger will always runs as a separate process. These four components and the form of interaction between them are depicted in Figure 10.1, “ Model Debugger Architecture”.

Figure 10.1.  Model Debugger Architecture

In version 3.1, MC-3020 implements this architecture as shown in Figure 10.2, “ Current Debugger/Compiler Interface”. This provides full code generation and debug capability, but restricted to the host development platform or to a TCP/IP socket-capable target.

Figure 10.2.  Current Debugger/Compiler Interface

Note that the host and target monitors are not only combined, but are incorporated into the executable image. As such, these three components exist as a single process that communicates with the Model Debugger process via XML messages across TCP/IP sockets. Both the Executable Image and Model Debugger processes run on the same host machine.

An interest in debugging models in a target environment using a Model Debugger compatible version of MC-3020 currently exists. In order to field such a capability in the first release, it was required to bundle host and target monitor capabilities with the executable image and communicate with the Model Debugger using XML Messages as shown in Figure 10.2, “ Current Debugger/Compiler Interface”. This assumes that the target is a socket-capable platform with sufficient RAM to run the tooled executable.

Figure 10.3.  Near Term Debugger/Compiler Interface

To run with Nucleus BridgePoint Model Debugger it is necessary to mark the system to generate the target monitor. This is accomplished with the marking function TagModelDebugginOn. See the section called “Marking On Model Debugger” for more details on this marking.

Before running the application with the debugger, an XML extraction of the model must be prepared. Use the command make gen_all_xml to create XML extractions for each domain in the system. If you do not prepare this XML file, Nucleus BridgePoint Model Debugger will detect an error and may exit with a fatal error.

When running with the target monitor enabled, additional code is translated into the generated code. There is code to communicate with the Model Debugger through a socket interface. There is an XML parser which parses the XML messages received from the debugger. In line with normal action processing are calls to debug processing which keeps the Model Debugger synchronized with the state of the generated target code.

There are a great number of options for non-volatile storage (NVS) technologies in the embedded control world. Applications exist which use more than one non-volatile storage technology within the same system. It is required that modularity exist at the interface between general persistence services and the driver level code storing and retrieving data from non-volatile storage. A bridge is defined to allow MC-3020 users to build or replace this driver layer.

An option must be supplied to allow for the persisting of the current state of a persistent class instance or to use the default initial state. By default MC-3020 must restore the current state of instances. But the user must have a way of causing the current state to be the default current state that would normally be established for non-persistent class instances.

Different applications need to persist different amounts of data. The ability to persist at the class and domain levels allows for both large and small amounts of persistent data. MC-3020 supports persistence at class, subsystem and domain levels.

Some approaches to persistence can add tremendous complexity to the model compiler. Overly simplistic approaches to persistence support can pollute the application analysis. MC-3020 strikes a balance that makes sense for the embedded applications to which MC-3020 is best suited.

Persistence services for MC-3020 are light weight and flexible in terms of non-volatile storage technology. The persistence services are broken between two domains, PERSIST and NVS.

The PERSIST domain performs the commit and restore operations which commit instances to non-volatile storage and restore instances from non-volatile storage respectively. The PERSIST domain keeps track of which instances have been persisted, which links have been persisted and manages keeping the links synchronized with the instances during the power-up system initialization.

The NVS domain supplies a rudimentary but functionally complete persistent data storage and retrieval interface. The interface has characteristics of both a database and of a file system. The interface is rich enough to provide flexibility in the application of different non-volatile storage technologies.

MC-3020 persistence does not specify or depend upon a specific persistent storage technology. Therefore, only a standard interface (bridge) is defined. The user may deploy whatever available technology desired behind the bridge to the NVS domain. A sample implementation is supplied (in a file called sys_nvs.c/h) for use as the developer desires.

The domain chart below shows the bridge operations made visible to the application. commit is the primary function used by the application.

The architecture domain (MC-3020) automatically performs the inserts, updates and deletes to shuffle instance data between the RAM based collections of the application and the non-volatile persistent storage. Additionally, MC-3020 automatically performs the restore operation at power-up time.

Other domain interfaces are exposed and may be used at the discretion of the analyst.

A manual commit occurs when the user forces a commit of instance and link data to non-volatile store by synchronously invoking a PERSIST domain function (e.g. PERSIST::commit()). An automatic commit occurs when a commit is initiated by the software architecture "behind the scenes" based on pre-defined policy.

MC-3020 supports manual commit operations and performs automatic commits when necessary. Such automatic commits occur when instance and link delete operations are required.

When persistence and tasking are both enabled in the generated system, MC-3020 performs all commits automatically. It is not advised to manually commit in a multi-tasking system.

The commit function is called to indicate to the domain that the application wants to commit instances of classes and associations to non-volatile storage. This in turn causes NVS::insert to be called flushing to NVS elements from a list of instances and links that were queued when modified.

A return value of 0 indicates success.

The restore function is called by the architecture during bring-up after a power cycle. The restore function causes the classes contained in non-volatile storage to be read from store and written to the instance collection list.

A return value of 0 indicates success.

Many NVS domain functions return an integer return code. The values that the return code can take are outlined in the following listing:

#define NVS_RETURN_SUCCESS    0 /* All is well.                    */
#define NVS_ERROR_BAD_OPEN   -1 /* Could not open file.            */
#define NVS_ERROR_ITEM_LONG  -2 /* Data item is too long.          */
#define NVS_ERROR_BAD_SEEK   -3 /* Could not seek correctly.       */
#define NVS_ERROR_BAD_WRITE  -4 /* File did not write correctly.   */
#define NVS_ERROR_NOT_FOUND  -5 /* Did not find searched record.   */
#define NVS_ERROR_BAD_READ   -6 /* Read incorrect length of data.  */
#define NVS_ERROR_NO_ROOM    -7 /* Not enough room for insert.     */
#define NVS_ERROR_LENGTH     -8 /* Length not correct.             */
    

This can be found in the generated NVS_bridge.h file. A positive value is used to indicate the length of a buffer.

Function checksum provides a mathematical redundancy check on the integrity of the contents of the non-volatile store (NVS). This mathematical algorithm and the capabilities of the function are supplied by the implementor of the internals of the NVS module.

checksum provides an integer return code representing an integrity check on the contents of the NVS.

The defrag function coalesces deleted records together and written records together. This allows for small fragments of free storage to be collected into a single contiguous free piece of storage. This function will typically take significant time to run. This time is a function of the specific non-volatile storage technology.

defrag provides an integer return code as listed above.

delete searches the store for an item matching the input and deletes it. Deleted items cannot be retrieved from NVS in future invocations of select or search. delete chooses the item to erase based on two combinations of input arguments. If the delete is called with a key and a type, then the item in the NVS matching these key and type arguments is erased. Otherwise, if non-null data is given, the data and type arguments are used to identify the item to delete. When found, the item is marked as deleted and will not be readable from the store.

delete provides an integer return code as listed above.

The format function erases the non-volatile store (NVS). It is only to be called when it is desired that a new NVS be cleared and prepared for writing for the first time.

The initialize function resets the internal counters of the non-volatile store. (Note that these internal counters are the responsibility of the implementor of the internal of NVS and can contain information about the amount of data being used, etc.) No application/user data is written or changed in the store. This function is called automatically at power-up to prepare the store for access.

initialize provides an integer return code as listed above.

The insert function adds items to the store. There are four input arguments. The first, key is the lookup key to the item. In the case of instance data, this key is a unique identifier for the item being inserted (added to the store). length is an integer representation of the length of the data byte sequence pointed to by pointer. type is the class type (instance or link) in integer form. The data pointed to by pointer is not modified. If the record being inserted already exists in the non-volatile store, the existing record will be updated. A return code provides status on the insert.

next provides a way to cycle through reading each item from the store one at a time. This function returns the item currently being pointed to by the cursor (maintained inside the store). The buffer space available on the calling side is passed in as the length argument. If sufficient space is available in the buffer, the next item data will be copied into the given buffer pointed to by pointer. The length of the written data is returned as the return value. Also returned are the values of the key and type. The initialize function resets the internal cursor to the first item in the store.

The select function searches the store for a specific item with a key and type matching those given as input arguments. If a record is found that matches, it is copied into the data buffer pointed to by pointer. The length argument provides the amount of buffer space available on the calling side. The actual length of the returned record (if one is returned) is provided in the return value. The data behind the pointer argument is modified with the data found in the non-volatile store.

The space_available function returns an integer representing the number of bytes not being used in the store. This number of bytes will actually hold fewer bytes due to the overhead of item meta-data (key, type, etc).

The space_total function returns the overall size in bytes of the non-volatile store.

The space_used function returns the number of bytes currently written in the store.

The update function searches for a record in the store the same way that select does. When (and if) a record is found, the new data of length length pointed to by pointer is written into the store over the existing item. Since insert will perform an update when a record exists, it is more often used than update. No arguments are modified calling this function.

update provides an integer return code as listed above.

Function version provides an integer return value indicating the version of the data and/or format of the non-volatile store (NVS). This versioning algorithm and the capabilities of the function are supplied by the implementor of the internals of the NVS module. Two input arguments are used to provide flexible utility.

version provides an integer return code representing the version of the NVS (contents).

Primary infrastructure changes involve the centralization of the create, delete and initialization of class instances. The following paragraphs explain this change and its design. A description of the implementation of the generated code follows with an explanation of the effects on speed, space and execution.

MC-3020 3.3 and before has a class-based create, delete, init design. The generated code contains a create accessor, delete accessor and factory initializer for each class in the modeled system. When an instance needs to be created, a routine specific to the class is invoked to allocate the implementation memory for the class instance. The attributes for the class instance are given reasonable default initial values. Identifying attributes of type unique_id are initialized to values certain to be unique with the generated system. The initial state of the new instance state machine is set.

In MC-3020 3.3 and before, when an instance needs to be deleted, a routine specific to the class is called to deallocate the implementation memory for the instance and perform needed clean-up.

MC-3020 3.3 generates "object factory initialization" routines. There is one of these methods for each class in the modeled domains. These methods are called exactly once at bring-up time to initialize the instance memory data pool for the collection of instances for the class. This routine took into consideration the fact that some of the instances in a collection may be allocated and initialized statically as preexisting instances.

The class-based create/delete/init approach is very flexible. It allows the model compiler designer the liberty of considering only the class in hand when generating the code. Different profiles of deployment code can be generated based upon the type of class (passive, active, associative, having preexisting instances, etc). However, having the create, delete and init accessor dispersed to every class is troublesome when considering a persistent restore operation from centralized non-volatile storage (NVS).

MC-3020 3.4 and beyond centralizes the create, delete and initialize operations. This is accomplished by moving the intelligence of the class-based create/delete/init procedures into a class-based data structure. This class_info array contains information about each class such that centralized operations can intelligently create, delete and initialize classes and instances.

The information contained in the class_info structure includes:

With the above information, it is possible to have centrally defined create, delete and initialization routines. These central routines rely on class-specific information from the class_info array rather than on class-specific generated procedures.

The persistence restore operation relies heavily upon the centralized create and initialization routines. Assuming for a moment a system that has no preexisting instances defined in data, a system having persistent classes must restore the class instance data from a central non-volatile storage unit (NVS).

When a system powers up, it performs the standard system level initialization to bring up event queues and timer support and other system level infrastructure. The system then initializes the collection mechanisms for all of the classes in the generated system. This involves linking the instance storage into lists (singly or doubly linked).

At this point in a non-persistence supporting system the initialization functions would be invoked to allow application level user initialization to occur. In a persistence supporting system, persistent class instances are restored from non-volatile storage before the user initialization functions are run.

The process of restoring class instances involves invoking the central create routine and populating the newly created instance with data from NVS. The data in the NVS needs to be rich enough such that the create routine knows which type of class to create. Once the type is communicated, the class_info array provides the necessary details to enable the correct instantiation of the new instance.

In MC-3020 3.3 the files *_object.c contain methods to create, delete and perform factory initialization of class instances. To compare implementations, view one of these files in 3.3 generated code.

In MC-3020 3.4 and beyond, these routines are centralized. The class_info structure is simply an array of pointers to elements of the structure which reside in the individual *_class.c files.

Each domain is assigned a unique number, and each class within a domain is assigned a unique number. An array of class_info arrays exists for the system containing information for all classes in all domains. During translation a domain-unique number is assigned to each class. This number serves as an index into the class_info array thus allowing centralized create, delete, init and other routines to look up statistics on any class in the modeled system.

Centralizing the create, delete and init functions has the intended effect of enabling a persistent restore operation that can rely on these class-independent routines (namely create). There are positive side-effects of this centralization.

Code space savings is the primary positive side effect. Instead of three routines for each class, there are now three routines for the entire system. This saves substantially on code size in the generated system. This effect will be greatest on systems with a large number of classes.

Other positive side effects include greater flexibility in features such as persistence.

Persistence services have cost in terms of execution speed, instruction store space, data memory and non-volatile storage space. This section enumerates those costs in as detailed a manner as practical.

An xtUML model may be inherently concurrent, but it is not inherently prioritized.

Simple prioritization of execution of a translated xtUML model can be achieved without multi-tasking. Events can be prioritized to modify the sequencing of state actions. MC-3020 provides event prioritization.

In a single tasking environment, a state action cannot be preempted. Therefore, a single task deployment environment is limited by the duration of the longest state action. Without preemption, a higher priority action may need to wait the entire duration of a state action of lower priority processing. Sometimes this is not an issue.

However, in many embedded applications the limits of a single task cannot be tolerated. We must map the xtUML application onto a multi-tasking/multi-threading architecture. By doing so, it is possible to map processing to various tasks based upon the required priorities. Higher priority action processing can be designed to preempt lower priority actions. We can take control away from the lower priority action and context switch into the higher priority action running in a higher priority task.

There are many possible strategies for mapping the components of an xtUML application to tasks. Event-based strategies and strategies based upon sequences of actions have been implemented successfully. MC-3020 has supported event based prioritization since version 2. As of MC-3020 version 4, prioritization using tasks/threads is supported. The mapping of xtUML artifacts to these tasks/threads is by class. Groups of classes are mapped to the tasks/threads running in the generated system.

xtUML model marking is used to identify which classes are translated to run in which tasks in the deployment target. Each class is marked identifying the task in which its generated code runs. The priority of the action processing of the class is used to determine an appropriate task. Higher priority classes get mapped to higher priority tasks. This separation allows for the processing of higher priority classes to preempt the processesing of lower priority classes.

Classes with state charts requiring low latency response to application events are mapped to high priority. Classes with little or no requirement for quick response are mapped to lower priority RTOS tasks.

The number of tasks required by the application is largely driven by prioritization. Concurrency plays a part in determining the number of tasks needed. The mapping to tasks must be accomplished with a clear understanding of both the xtUML application and of the deployment target hardware and RTOS.

A simple starting point is to have one task for each required level of priority. Map all classes having the same priority to the same task. For example map classes with tight coupling to time sensitive hardware to high priority task(s). Map classes that do non-critical "background" types of processing to a low priority task. Map everything else to a normal priority task.

In an xtUML application concurrency is assumed unless purposefully sequenced. Access to data that is shared between various classes/actions/functions must be synchronized. A simple, single-tasking deployment target may hide synchronization issues. A multi-tasking environment will not hide these modeling defects and indeed may aggravate them. If an xtUML application has not been properly synchronized, a truly preemptive multi-tasking kernel can uncover the modeling deficiencies.

Note that it is wise to map classes with strong processing and data interaction (coupling) into the same task. An improper mapping of classes to tasks can increase the overhead of processing by introducing undue task switching.