MIS(1)

NAME
MIS - run the Trick Module Interface Specification processor.

SYNOPSIS
MIS [-d] [-c] [source_file.c]

DESCRIPTION
The Module Interface Specification processor reads source code files and adds module interface information to the module catalog. MIS also generates Hypertext Mark-up Language (HTML) which serves as online documentation of the source code.

MIS must be executed in the version directory which holds the source code to be processed. If source file(s) are specified on the command line, only those source file(s) are processed, otherwise all source files in the current working directory are processed. MIS understands *nix wild card characters in the filename supplied on the command line.

MIS must be performed on all source code files in a version directory prior to running CP(1) on simulations which use the code in that directory. This is to ensure that the object code link list is constructed properly by CP(1) (the module catalog contains information on object code dependencies).

  Options

-d  Debug mode. MIS will echo source files to the screen as they are processed. This helps the user find his interface errors.

-c  Do not trap the common UNIX and USER signals. This feature allows a core to be dumped.

SOURCE FILE FORMAT
The source language files must have certain features to be successfully
    processed by MIS. These include a special comment header at the beginning of each function, and a special format for the function entry point and calling arguments.

A comment header must precede each function and have the following syntax:

/* PURPOSE: (purpose)
REFERENCES:
(((author) (title) (publication) (publisher) (date) (page)
[((author) (title) (publication) (publisher) (date) (page))] . . .)
ASSUMPTIONS AND LIMITATIONS: ((assumption 1) [(assumption 2)] . . .)
CLASS: (module_classification)
LIBRARY DEPENDENCY: ((object.o) [(objectN.o)] . . . [(lib.a)] . . .)
PROGRAMMERS:
(((name) (employer) (date) (CR#) (description))
[((name) (employer) (date) (CR#) (description))] . . .)
*/

Since parentheses are used as field delimiters within the comment header, it is impossible to use parentheses within the fields. The PURPOSE section should be a brief description of what the function does. The REFERENCES section may contain any number of references, with each reference possessing an author, title, publisher, date, and page number. Notice how the parentheses are nested. The ASSUMPTIONS AND LIMITATIONS section may contain any number of assumptions or limitations. The CLASS field may contain any of the module classifications listed in the "Module Classifications" section below.

The LIBRARY DEPENDENCY section must reference all object code files which the current module directly depends upon, beginning with the current module's object file. To understand direct dependence, assume that this.c calls that.c, which calls another.c. this.c should have that.o in it's LIBRARY DEPENDENCY section, but not another.o. CP(1), make_build(1), and make(1) are responsible for sorting out indirect dependencies and doing the right thing. Directory paths which begin with a "/" character (like a *nix absolute path) are assumed to be relative to the bin_${TRICK_HOST_CPU} directory. Directory paths which begin with a character other than "/" (like a *nix relative path) are assumed to be relative to the module version directory. For the purposes of the LIBRARY DEPENDENCY section, assume that the object files remain in the version directory (even though the Makefiles generated by make_build(1) move the object files to the bin_${TRICK_HOST_CPU}/model/version directory).

The PROGRAMMERS section may contain any number of programmer records, each of which contains the programmer's name, employer, date of file modification, the associated Change Request number, and a brief description of the modification.

The function entry point syntax follows standard ANSI C syntax and must come after the comment header. Between the comment header and the entry point, any valid C code or preprocessor directives are permissible. The Trick function entry point syntax requires several comments - one for the function return value and one for each calling argument. All functions which have a CLASS other than N/A should have their calling arguments passed as pointers (by reference). By default, the executive passes only addresses to the functions it calls. There exists syntax for the S_define file which allows a developer to pass arguments by value rather than by address, but always using "call by reference" will ensure consistency and reduce confusion. The Trick function entry point syntax follows:

[return type] module_name( [void)] /* RETURN units description */
[arg1_type arg1, /* IN | INOUT | OUT: units description */]
[arg2_type arg2, /* IN | INOUT | OUT: units description */]

The function entry point must be immediately followed by a comment which specifies the function return value's measurement units and description. Likewise, each calling argument must also be followed by a comment which specifies the calling argument's usage in the function, either IN, INOUT, or OUT, the argument's measurement units, and a brief description of the argument.

  Module Classifications

N/A
    Not applicable -- the module's execution is not managed by the executive, but by another module.

asynchronous
    The executive does not wait for the module to complete before returning to normal job scheduling.

asynchronous_mustfinish
    The executive does not wait for the module to complete before returning to normal job scheduling, but the job must finish before its next regularly scheduled time or the executive will initiate a shutdown.

automatic
    This module classification reschedules its own next call time.

derivative
    This module classification defines derivatives of the Equations of Motion (EOM).

dynamic_event
    Provides a continuous time dependent equation whose root defines a discontinuous event in the system EOM. Evaluation of the function returns an estimate of the time remaining before reaching the root.

effector
    This module classification is typically used to model control system effectors. It provides an interface between the simulated control system and the simulated forces.

effector_emitter
    Similar to the effector class, but used for the "action" portion of an action-reaction effector system.

effector_receiver
    Similar to the effector class, but used for the "reaction" portion of an action-reaction effector system.

environment
    Time dependent boundary conditions.

freeze
    This module classification executes cyclically during simulation FREEZE mode only.

freeze_init
    This module classification is executed once at the time of FREEZE mode initialization.

initialization
    This module classification is executed only once (at simulation time = zero).

integration
    Equations of motion state integration function.

logging
    Simulation data recording or displaying.

random
    Execution of this module classification is scheduled according to a Gaussian distribution. The mean and standard deviation of the desired cyclic period are furnished to the executive.

restart
    Similar to the initialization classification, but only executed when simulation is being restarted from a checkpoint file.

scheduled
    Typical flight software and hardware subsystems. The module is scheduled for execution periodically.

sensor
    This module classification is typically used to model control system sensors. It provides an interface between the simulated dynamics and the simulated control system.

sensor_emitter
    Similar to the sensor class, but used for the emitter portion of an integrated multi-component sensor system.

sensor_receiver
    Similar to the sensor class, but used for the receiver portion of an integrated multi-component sensor system.

sensor_reflector
    Similar to the sensor class, but used for the reflector portion of an integrated multi-component sensor system.

shutdown
    This class of module is executed once at simulation termination (e.g. you may have some hardware that you'd like to safe before shutting off its control system).

unfreeze
    This class of module executes once at the time of FREEZE mode termination.

FILES

catalog/modules
    Contains catalog information about the modules.

html/
    This directory gets the generated Hypertext Mark-up Language which documents the source files.

SEE ALSO
catalog(1), CP(1), make_build(1)

All Trick model developers and users should go through the tutorial found in the Trick Simulation Environment User Training Materials. The canonical reference for all Trick commands, files and utilities is the Trick Simulation Environment User's Guide. Information specific to a given release of Trick tools is contained in the Trick Simulation Environment Version Description for that release.

BUGS
Known bugs will be placed in the Version Description Document located in $TRICK_HOME/docs area. If you would like to report a bug, contact vetter@lincom-asg.com.

AUTHORS
The MIS command was written by Rob Bailey and is maintained by the Trick development staff. This man page was written by Rick Sykes, address all discrepancies to sykes@lincom-asg.com.