MC-3020 Model Compiler
- User's Guide

Creation occurs in constant time. Creation can occur synchronously with the create action language statement or asynchronously with a creation event. In synchronous creation, no action is executed. In asynchronous creation, a creation state is executed and at minimum initializes the instance identifier.

Instance deletion moves an class instance from the active extent and deactivates it onto a list of inactive (``inanimate'') class instances. If no action language ever performs deletion of a particular class, no deletion accessor method is generated.

Instance selection is optimized for speed when selecting based on the instance identifier. For unoptimized selections O(N) (linear) time is required. (MC-3020 provides O(N) for all ``blind selections'', select any from instances of action language commands.) Hooks are provided for architect replacement of certain signature selection search functions.

Attributes are elements of the translated structure. Most attributes are translated with no function interface layer. No call/return overhead is incurred for most attribute read and write operations. Code is generated to directly access attribute data. Speed is optimized.

In typical models, some attributes are never accessed. MC-3020 detects this situation and omits the implementation of attribute data elements that are never accessed. Unused data is optimized away.

Actions are translated into functions associated by name and packaging with the class containing the state model containing the state action.

Adherence to Shlaer-Mellor event rules is assured in the generated code. Centralized event queues order events for the entire system.

Prioritized events can be marked by the user. 256 priority levels are provided.

Creation events are recognized and treated differently from non-creation events. The model compiler will create an instance of the class before the event is delivered. The event will cause a transition into the creation state and execution of the associated action.

Final state actions delete self after executing the specified processing.

Marking allows Nucleus BridgePoint Model Verifier flavored initialization objects to be used for system initialization. In addition, several initialization objects can be defined in the model and only one marked to generate code.

Various stylistic and implementation conventions are centralized and documented to be easily controlled by the software architect. Generated file names, directory structure, coding conventions and even coding style can be dialed in by the user. (Look for fule files with the word ``name'' in the file name.)

MC-3020 is tooled to support a measured development process. As with style, metrics can be customized easily. MC-3020 gathers and reports many metrics including statistics quantifying classes, states models, state actions, event flavors, association and marking summary information.

To indicate to MC-3020 that an xtUML domain is part of a system build, provide the following rule file function invocation in the registry.clr marking file.

Where the input parameters are:

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

To indicate to the model compiler that a realized (non-xtUML) domain is part of a system build, make the following rule file function invocation, one for each realized domain, from the registry.clr marking file.

Where the input parameters are:

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

Synchronous services, also known as domain functions, provide a convenient home for a reusable package of processing requiring no state. Synchronous services can be invoked from within the domain or from without. Bridging is only concerned with connecting the interface to external entities.

Where the input parameters are:

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

Use this invocation to declare the interface between two xtUML domains using a bridge object. [Note that this marking option is provided for backwards compatibility reasons only. Domain function (synchronous services) should be used for all bridging purposes.] The term initiating domain refers to the xtUML domain which contains the external entity (EE) against which bridge calls to the recipient domain are made. The term recipient domain refers to the xtUML domain which contains the ``Funky Bridge Object'' (FBO). The FBO is a pseudo state model that provides the implementation interface for the EE in the initiating domain.

Where the input parameters are:

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

Use this invocation to declare the interface between an xtUML domain and realized (non-xtUML) domain. MC-3020 will generate an interface framework source file that represents a compilable definition of the implementation interface. This bridge skeleton will be generated into the system/skel directory. It can be copied to the system/user/source directory and modified (if desired) to invoke user supplied code.

Where the input parameters are:

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

As of version 5.0 of Nucleus BridgePoint Model Builder, domain functions make the cleanest interfaces between xtUML and non-xtUML domains. Using domain functions for bridging is preferred over the previous (although still supported) bridge object strategy. MC-3020 will automatically generate interface declaration files into the system/skel directory for all domain functions in the system. There is no requirement to mark the domain functions in any way, the declaration occurs automatically. Use these .h declaration files for inclusion into realized code to declare the signatures of interfaces into an xtUML domain(s).

MC-3020 allows domain function bridges to be marked as callable from interrupt handlers or other asynchronous sources (such as other tasks, signal handlers, etc). Synchronous services marked here will generate a short stub interface that will defer execution of the bridge to be between dispatched state actions. When a domain function marked as safe for interrupts is invoked, its action body is posted to a queue for dispatch after any currently running state action completes. This guarantees architecture data mechanism integrity while maintaining application data access set consistency.

Synchronous services marked safe for interrupts cannot return data. They must be of return type void. However, core data type data can be passed into these domain functions. Such data is packaged safely at interrupt level and then unpacked in the bridge service.

To indicate to the model compiler that a domain function serves as a bridge operation which may be invoked in a manner safe for invocation from an interrupt handler or other asynchronous activation (one for each domain function):

Where the input parameters are:

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

MC-3020 allows "funky bridge objects" to be marked as callable from interrupt handlers or other asynchronous sources (such as other tasks, signal handlers, etc). This feature is available on bridge objects for continued support of now obsolete functionality. Using domain functions for bridges is preferred. Use of "funky bridge objects" is discouraged.

Bridge object actions marked safe for interrupts cannot return data. They must be of return type void. Bridge object actions marked safe for interrupts cannot pass parameters. Use synchronous services (domain functions) if passing data is desired.

To protect data structures for Interrupt Safe Bridges, interrupts are disabled for a very few instructions. The method of disabling interrupts varies from target to target and from compiler to compiler. Therefore, the responsibility of defining the specific flavor of EI/DI instruction is left to the user. The marking functions UserEnableInterrupts and UserDisableInterrupts are are provided for specifying the specific way interrupts are enabled and disabled with your specific target.

To define the instruction sequence for enabling and disabling interrupts, edit the system-level user defined rule file sys_functions.arc.

Bit fields provide a means of packing many small value attributes into single words of computer storage. MC-3020 allows attributes to be stored as bit fields in ANSI C structs.

Attributes are marked with Nucleus BridgePoint Model Builder. The string BIT_WIDTH: n is placed within a comment as the first line of the attribute description. ``n'' is the width in bits required to store the attribute.

It should be understood that bit fields are inherently somewhat less portable than most other ANSI C constructs. Dependence upon ``Endian-ness'', memory models and other compiler/target implementation specifics is not uncommon. Use bit fields with care.

The maximum width for a bit field member attribute is 16 bits. Bit field members are of type unsigned int.

MC-3020 provides a means of establishing the base memory address of class instance collections (extents). Within Nucleus BridgePoint Model Builder the string BASE_ADDRESS: n is placed within a comment as the first line of the class description. ``n'' is the memory address anchoring the start of the collection of class instances.

Two user defined rule file functions at the system-level define how this number (``n'') will appear in the generated code. One function (UserFixExtentBaseBegin) is used to insert code before the definition of the class instance collection memory. Another function (UserFixExtentBaseEnd) is used to insert code directly after the data definition. This combination of functions will allow a pragma around the data definition.

To define the instruction sequence for fixing the class extent, edit the system-level user defined rule file sys_functions.arc.

Mark TagDataTypePrecision may only be used for application analysis data types which are derived from either Nucleus BridgePoint core data types of integer or real. Also, user defined types that are enumerations can be marked. Such data will have core data type string, but will serve as integers. Attempting to use this mark with any other core data type will result in a fatal marking error (translation aborted). This restriction applies equally to both domain specific and system wide use of this mark.

Precision tag tagged_name may be any standard C/C++ integer or real variable type. For example, unsigned char, long long, double, etc. POSIX types are also accepted, such as uchar_t, ulong_t, etc.

When an analysis class is instantiated, the default is to initialize attributes of core type integer to 0, and attributes of core type real to 0.0 (declared as code type float). Tag initial_value may be used to re-define the default initialization value.

Casting may be used in the tag, such as "(unsigned)EACCESS", but should be used only with careful system level discretion.

No translation time error checking is performed on initial_value. Bogus tags such as "@*#$" will only be caught during compilation.

Invoke TagDataTypePrecision to indicate to the model compiler the precision of a user defined data type defined in the Nucleus BridgePoint Subsystem Partitioning Model (SPM) domain data editor.

Where the input parameters are:

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

To allow for pointer reference to arbitrarily shaped masses of data, user-defined data types can be implemented as pointers. After marking a UDT as a pointer, the pointer typed data can be passed into and returned from operation and bridge operations. Marking is used to tag pointer types. The datatype.clr provides the means for specifying these pointer data type specializations.

Invoke MapDataTypeAsPointer to indicate to the model compiler that a user defined data type defined in the Nucleus BridgePoint Subsystem Partitioning Model (SPM) domain data editor shall be implemented as a pointer.

Where the input parameters are:

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

In analysis models, enumerated types defined within Nucleus BridgePoint Model Builder (using the Data Type editor available in BP5.0+) have no initial (uninitialized) value. With marking, it is possible to explicity define this value for uninitialized enumeration variables. The datatype.clr provides the means for specifying this starting value.

To indicate to the software architecture that the uninitialized enumerator of an enumeration (defined in the Nucleus BridgePoint Subsystem Partitioning Model (SPM) domain data editor) shall have a value other than the default, use the following invocation:

Where the input parameters are:

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

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

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

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

In some target environments, it may be desirable to select the integer values of the individual enumerators in an enumeration. MC-3020 enables the assigning of discrete values to one or more of the enumerators in an enumeration.

Invoke TagEnumeratorDiscreteValue to indicate to the model compiler that a user defined enumeration data type enumerator (defined in the Nucleus BridgePoint Subsystem Partitioning Model (SPM) domain data editor) shall have a value other than the default.

Where the input parameters are:

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

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

MC-3020 provides for tasking/threading using the capabilities of the target operating system (OS) or real-time operating system (RTOS). An example of an RTOS is the Nucleus PLUS real-time operating system.

To cause MC-3020 to generate multi-tasking/threading code, invoke the following marking function. Pass it arguments that specify the type of multi-tasking environment and whether or not to serialize all action processing (across all tasks).

To enable tasking in the generated system:

Where the input parameters are:

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

Some flavors of tasking/threading allow for differing execution priorities of tasks or threads. MC-3020 allows the priorities of tasks to be set through marking. In systems that support explicit prioritization of tasks, each task (of the number specified in EnableTasking) can have a priority assigned. Use the following marking function to set the priority for each task.

To specify the priorities of tasks/threads:

Where the input parameters are:

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

MC-3020 tries to use relatively safe methods of manipulating strings. The ``n'' library functions are used (strncpy, strncpy, strncat) rather than their more dangerous (as regards buffer overruns) counterparts.

To specify the maximum length of a string in the system:

Where the input parameters are:

.invoke TagMaximumStringLength( 16 )
        

Sets of instances are collected for various AL operations. Relationships with multiplicity MANY require set container mechanisms at the implementation level to manage the collection of related instances. The maximum number of instances allowed in such collections can be controlled with a mark.

To specify the maximum ``relationship extent'' size in the system:

Where the input parameters are:

.invoke TagMaximumRelationshipExtentSize( 8 )
        

Another operation requiring set manipulation is a selection (SELECT MANY) that may result in a collection of multiple instances.

To specify the maximum ``selections extent'' size in the system:

Where the input parameters are:

.invoke TagMaximumSelectionExtentSize( 12 )
        

Collections are maintained with a mechanism of one type or another. With this mark, the type desired for a particular translation can be specified. The default is singly linked list container nodes. Doubly linked list containers can be selected as flavor 20. Doubly linked lists allow for faster deletion of instances in exchange for an additional pointer size (for ``prev'') per container in the system.

To specify the flavor of the collection nodes:

Where the input parameters are:

.invoke TagCollectionsFlavor( 20 )
        

MC-3020 attempts to dynamically calculate reasonable and safe values for queue depths within the event generation and delivery mechanism. However, for optimization purposes the user may wish to override these values.

To override the compiler calculated maximum queue depth for the self directed event queue:

Where the input parameters are:

.invoke TagMaximumSelfDirectedEvents( 3 )
        

To override the compiler calculated maximum queue depth for the instance directed event queue:

Where the input parameters are:

.invoke TagMaximumNonSelfDirectedEvents( 5 )
        

A mark is provided so the system analyst can direct the model compiler to increase or decrease the timer queue used to manage multiple pending xtUML timers (delayed events). To override the compiler calculated queue depth for pending xtUML timers:

Where the input parameters are:

.invoke TagMaximumPendingOoaTimers( 6 )
        

Use this mark to expand or reduce the depth of the queue used to interleave ``asynchronous'' bridge operations between state actions. The default will be a system divined value that should be relatively safe in most cases.

To hard-code the depth of the interleaved bridges queue:

Where the input parameters are:

.invoke TagMaximumInterleavedBridges( 4 )
        

Use this mark to define how many bytes of argument data come in across an interleaved bridge operation. The default is 8.

To hard-code the width of the interleaved bridge argument path:

Where the input parameters are:

.invoke TagInterleavedBridgeDataSize( 2 )
        

This mark works in conjunction with the Nucleus BridgePoint Model Debugger. By invoking this marking interface, target debug code is generated. Note that a significant amount of tooling code is generated in line with functional code. A debug version of the target image will run successfully on the development host computer or a socket- capable target with sufficient memory (RAM).

To enable the generation of debug code for use with Nucleus BridgePoint Model Debugger:

.invoke TagModelDebuggingOn()

This mark is used to specify the maximum number of instances and links that can be queued waiting to be flushed to non-volatile storage (NVS). As instances and links become "dirty" they get queued to NVS. When PERSIST::Commit is called these queues are flushed.

To change the default depth (128) to something different:

Where the argument:

.invoke MarkPersistenceCacheDepth( 16, 32 )

.invoke MarkPersistenceCacheDepth( 1000, 500 )

Initialization functions provide the analyst a means to specify preexisting instances for production bring-up. They also serves to set up test scenarios. Domain functions also can be activated/deactivated with marking. Use domain functions instead of initialization objects. Through marking, specific initialization functions can be chosen for system bring-up while others are marked (or erased as the case may be) as not to be translated.

Marking a function for initialization does not change the function. The function remains available for invocation by any of the action semantics that could normally call it. If more than one function is tagged as an initialization function, each will be invoked. The order of invocation is alphabetical by function name.

Identify a function in the domain to be used as the an initialization function by invoking the following rule file function in the domain.clr marking file.

Where the input parameters are:

.invoke TagInitializationFunction( "CreateAndPopulate" )
        

Initialization objects represent an obsolete (although still supported) means for the analyst to specify preexisting instances for production bring-up. All of the functionality of the obsolete TagInitializationFunction is now provided in domain functions which can activated/deactivated and marked for initialization. Use domain functions instead of initialization objects. See TagInitializationFunction.

MC-3020 can be directed to skip code generation for classes marked with the TagExcludeObjectFromCodeGen invocation. Combined with selective marking of initialization functions, class exclusion allows for a simple method of providing multiple bring-up scenarios. Exclude a class from code generation by marking it thusly:

Where the input parameters are:

.invoke TagExcludeObjectFromCodeGen( "TST_OBJ" )
        

To indicate to the model compiler that all classes in a specified subsystem should be excluded from implementation code generation, use the following invocation (one for each excluded subsystem):

Where the input parameters are:

.invoke TagExcludeSubsystemFromCodeGen( "MyVerifierUnitTests" )