mirror of
https://github.com/nasa/trick.git
synced 2024-12-23 15:02:25 +00:00
19025d77ad
Reorganized. Created a new top level include directory that will hold all of Trick's header files. Moved all of the Trick headers to this directory. Created a libexec directory that holds all of the executables that users don't need to execute directly. Changed all of the executables remaining in bin to start with "trick-". In the sim_services directories changed all source files to find the Trick headers in their new location. Since all of the include files are gone in sim_services, removed the src directories as well, moving all of the source files up a level. Moved the makefiles, docs, man, and other architecture independent files into a top level share directory. Renamed lib_${TRICK_HOST_CPU} to lib64 or lib depending on the platform we're currently on.
refs #63
239 lines
10 KiB
Groff
239 lines
10 KiB
Groff
.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.
|
|
|