trick/man/man1/MIS.1

.TH MIS 1 "7 July 97" "Trick" "Trick User's Manual"
.SH NAME
MIS \- run the Trick Module Interface Specification processor.
.SH SYNOPSIS
\fBMIS\fP [\fB-d\fP] [\fB-c\fP] [\fIsource_file.c\fP]
.SH DESCRIPTION
The Module Interface Specification processor reads source code files and
adds module interface information to the module catalog.  \fBMIS\fP also
generates Hypertext Mark-up Language (HTML) which serves as online
documentation of the source code.
.PP
\fBMIS\fP 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.  \fBMIS\fP understands
*nix wild card characters in the filename supplied on the command line.
.PP
\fBMIS\fP must be performed on all source code files in a version directory
prior to running \fBCP\fP(1) on simulations which use the code in that
directory.  This is to ensure that the object code link list is constructed
properly by \fBCP\fP(1) (the module catalog contains information on object
code dependencies).
.SS Options
.TP
\fB-d\fP
Debug mode.  \fBMIS\fP will echo source files to the screen as
they are processed.  This helps the user find his interface errors.
.TP
\fB-c\fP
Do not trap the common UNIX and USER signals.  This feature allows a core to be
dumped.
.TP
.SH "SOURCE FILE FORMAT"
The source language files must have certain features to be successfully
processed by \fBMIS\fP.  These include a special comment header at the
beginning of each function, and a special format for the function entry point
and calling arguments.
.PP
A comment header must precede each function and have the following syntax:
.sp
.nf
.ne 11
\fB/* PURPOSE: (\fIpurpose\fP)
REFERENCES:
(((\fIauthor\fP) (\fItitle\fP) (\fIpublication\fP) (\fIpublisher\fP) (\fIdate\fP) (\fIpage\fP)
\fR[\fB((\fIauthor\fP) (\fItitle\fP) (\fIpublication\fP) (\fIpublisher\fP) (\fIdate\fP) (\fIpage\fP))\fR] . . .\fP)
ASSUMPTIONS AND LIMITATIONS: ((\fIassumption 1\fP) \fR[\fP(\fIassumption 2\fP)\fR] . . .\fP)
CLASS: (\fImodule_classification\fP)
LIBRARY DEPENDENCY: ((\fIobject.o\fP) \fR[\fP(\fIobjectN.o\fP)\fR] . . . [\fP(\fIlib.a\fP)\fR] . . .\fP)
PROGRAMMERS:
(((\fIname\fP) (\fIemployer\fP) (\fIdate\fP) (\fICR#\fP) (\fIdescription\fP))
\fR[\fP((\fIname\fP) (\fIemployer\fP) (\fIdate\fP) (\fICR#\fP) (\fIdescription\fP))\fR] . . .\fP)
*/\fR
.fi
.sp
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.
.PP
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 \fIthis.c\fP calls 
\fIthat.c\fP, which calls \fIanother.c\fP.  \fIthis.c\fP should have
\fIthat.o\fP in it's LIBRARY DEPENDENCY section, but not \fIanother.o\fP.
\fBCP\fP(1), \fBmake_build\fP(1), and \fBmake\fP(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 \fIbin_${TRICK_HOST_CPU}\fP 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
\fBmake_build\fP(1) move the object files to the
\fIbin_${TRICK_HOST_CPU}/model/version\fP directory).
.PP
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.
.PP
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 \fIS_define\fP 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:
.sp
.nf
.ne 3
[\fIreturn type\fP] \fBmodule_name( \fR[\fIvoid\fP)\fR] \fB/* RETURN \fIunits description\fP */
\fR[\fIarg1_type arg1\fB, /* IN | INOUT | OUT: \fIunits description\fP */\fR]\fP
\fR[\fIarg2_type arg2\fB, /* IN | INOUT | OUT: \fIunits description\fP */\fR]
.fi
.sp
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.
.SS "Module Classifications"
.TP
\fBN/A\fP
.br
Not applicable -- the module's execution is not managed by the executive, but
by another module.
.TP
\fBasynchronous\fP
The executive does not wait for the module to complete before returning to
normal job scheduling.
.TP
\fBasynchronous_mustfinish\fP
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.
.TP
\fBautomatic\fP
This module classification reschedules its own next call time.
.TP
\fBderivative\fP
This module classification defines derivatives of the Equations of Motion (EOM).
.TP
\fBdynamic_event\fP
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.
.TP
\fBeffector\fP
This module classification is typically used to model control system effectors.
It provides an interface between the simulated control system and the simulated
forces.
.TP
\fBeffector_emitter\fP
Similar to the \fBeffector\fP class, but used for the "action" portion of an
action-reaction effector system.
.TP
\fBeffector_receiver\fP
Similar to the \fBeffector\fP class, but used for the "reaction" portion of an
action-reaction effector system.
.TP
\fBenvironment\fP
Time dependent boundary conditions.
.TP
\fBfreeze\fP
.br
This module classification executes cyclically during simulation FREEZE mode
only.
.TP
\fBfreeze_init\fP
This module classification is executed once at the time of FREEZE mode
initialization.
.TP
\fBinitialization\fP
This module classification is executed only once (at simulation time = zero).
.TP
\fBintegration\fP
Equations of motion state integration function.
.TP
\fBlogging\fP
Simulation data recording or displaying.
.TP
\fBrandom\fP
.br
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.
.TP
\fBrestart\fP
Similar to the \fBinitialization\fP classification, but only executed when
simulation is being restarted from a checkpoint file.
.TP
\fBscheduled\fP
Typical flight software and hardware subsystems.  The module is scheduled for
execution periodically.
.TP
\fBsensor\fP
.br
This module classification is typically used to model control system sensors.
It provides an interface between the simulated dynamics and the simulated
control system.
.TP
\fBsensor_emitter\fP
Similar to the \fBsensor\fP class, but used for the emitter portion of an
integrated multi-component sensor system.
.TP
\fBsensor_receiver\fP
Similar to the \fBsensor\fP class, but used for the receiver portion of an
integrated multi-component sensor system.
.TP
\fBsensor_reflector\fP
Similar to the \fBsensor\fP class, but used for the reflector portion of an
integrated multi-component sensor system.
.TP
\fBshutdown\fP
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).
.TP
\fBunfreeze\fP
This class of module executes once at the time of FREEZE mode termination.
.SH FILES
.TP
\fIcatalog/modules\fP
Contains catalog information about the modules.
.TP
\fIhtml/\fP
This directory gets the generated Hypertext Mark-up Language which documents
the source files.
.SH "SEE ALSO"
\fBcatalog\fP(1), \fBCP\fP(1), \fBmake_build\fP(1)
.PP
All Trick model developers and users should go through the tutorial found
in the \fITrick Simulation Environment User Training Materials\fP.
The canonical reference for all Trick commands, files and utilities is the
\fITrick Simulation Environment User's Guide\fP.  Information specific to a
given release of Trick tools is contained in the \fITrick Simulation
Environment Version Description\fP for that release.
.\" .SH DIAGNOSTICS
.\" How to determine why the command failed.
.SH BUGS
Known bugs will be placed in the \fIVersion Description Document\fP located in
$TRICK_HOME/docs area.  If you would like to report a bug, contact
vetter@lincom-asg.com.
.SH AUTHORS
The \fBMIS\fP 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.