/**************************************************************************//**
 * \page des Tethys/LRAUV Software Design
 *
 * The Tethys/LRAUV software design summaries include:
 * \li \subpage des_layered
 * \li \subpage des_embed
 * \li \subpage des_universal
 * \li \subpage des_slate
 * \li \subpage des_modularity
 * \li \subpage des_script
 * \li \subpage des_threads
 * \li \subpage des_storage
 * \li \subpage des_sim
 */

/**************************************************************************//**
 * \page des_layered State-Configured Layered Control
 *
 * This section illustrates how the Tethys/LRAUV State-Configured
 * Layered Control stack behaves during a simple mission that
 * navigates around 4 waypoints 2 times, and occasionally surfaces
 * for GPS updates and satellite communications.
 *
 * The actual mission script that creates the example stack is
 * here: \ref des_script_example
 *
 * In the graphics that follow, active behaviors and commands are
 * shown in blue  * inactive ones are shown in gray. Likewise,
 * inactive "stacks", or collections of behaviors and commands
 * are shown in grey, while active ones appear white.
 *
 * \section des_layered_start 1) Vehicle starts on the surface
 *
 * Highest-level behaviors are active (they are always active, BTW),
 * along with lower-level behaviors to yo-yo beneath the surface
 * towards a waypoint.
 *
 * The middle set of commands associated with surfacing are
 * not active, as they are controlled by a "When" clause that
 * only becomes active after a period of time has elapsed.
 *
 * The ReadSensor behaviors for Temperature and Salinity are not
 * active, as their "While" clause specifies reads only below the
 * surface.
 *
 * \image html des_layered_start.png
 * \image latex des_layered_start.eps
 *
 * \section des_layered_wp1 2) Vehicle is underwater, heading towards waypoint \#1
 *
 * Since the vehicle is underwater, the ReadSensor behaviors for
 * Temperature and Salinity are now active.
 *
 * \image html des_layered_wp1.png
 * \image latex des_layered_wp1.eps
 *
 * \section des_layered_wp2 3) Vehicle reaches waypoint \#1, heads towards \#2
 *
 * The command to reach Waypoint \#1 is satisfied, so the next
 * command (Waypoint \#2) becomes active.
 *
 * \image html des_layered_wp2.png
 * \image latex des_layered_wp2.eps
 *
 * \section des_layered_gotosurface 4) Last GPS fix is so old that a new one is needed.
 *
 * Vehicle heads towards surface, but all other (lower priority) behaviors
 * remain in effect (although the lower-level DepthEnvelope is subsumed).
 *
 * \image html des_layered_gotosurface.png
 * \image latex des_layered_gotosurface.eps
 *
 * \section des_layered_onsurface 5) Vehicle is on surface, getting GPS fix.
 *
 * After the GoToSurface command has finished, the next command block
 * is Preemptive  * therefore, all lower-priority behaviors and commands are
 * temporarily disabled, and will remain disabled until the command block
 * is completed (by getting a GPS fix and completing satellite communications).
 *
 * \image html des_layered_onsurface.png
 * \image latex des_layered_onsurface.eps
 *
 * After the preemptive command block finishes, the lower-priority
 * commands and behaviors can resume, and the larger timer-triggered
 * block of commands for surfacing and communicating will become
 * disabled (until enough time passes to trigger them again).
 *
 */

/**************************************************************************//**
 * \page des_embed Embedded Scripting Language
 *
 * Under \ref req_scripting, there are several requirments that have pushed
 * us towards adopting an embedded scripting language including:
 * - \ref req_scripting_behaviors
 * - \ref req_scripting_humanReadable
 * - \ref req_scripting_machineReadable
 * - \ref req_scripting_typeChecking
 * - \ref req_scripting_unitChecking
 *
 * The requirement \ref req_arch_modular also pushes us towards the use of
 * an embedded scripting lanuage.
 *
 * But which language to use?  We defined three measures:
 * - \ref des_embed_popularity (it increases the odds that a user may know the
 *   language, and helps narrow the list of possible choices)
 * - \ref des_embed_benchmark (we are targeting a low-power processor, so wasting
 *   cycles  is considered bad -- also, we'd like performance to be within an
 *   order of magnitude of the performance of compiled c++).
 * - \ref des_embed_embeddable (goal is to embed the scripting language into the
 *   command application)
 * - \ref des_embed_size (our target has a small memory size -- smaller is better)
 *
 * \section des_embed_popularity Popularity
 * What follows is a short list of the most popular embeddable scripting
 * languages (rankings from list of all programming languages at
 * http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html:
 * - #5 PHP http://en.wikipedia.org/wiki/PHP
 * - #6 Python http://en.wikipedia.org/wiki/Python_(programming_language)
 * - #7 Perl http://en.wikipedia.org/wiki/Perl
 * - #10 Ruby http://en.wikipedia.org/wiki/Ruby_(programming_language)
 * - #11 JavaScript http://en.wikipedia.org/wiki/JavaScript
 * - #15 %Lua http://en.wikipedia.org/wiki/Lua_programming_language
 * - #47 Tcl http://en.wikipedia.org/wiki/Tcl
 *
 * \section des_embed_benchmark Benchmark Speed
 * Benchmarks are, of course, a poor measure of the performance of a specific
 * software or hardware platform for a given, unless the task, unless the
 * task is very similar to the benchmark. However, they are probably the
 * only measure we have available.
 * The recent benchmark results here:
 * http://shootout.alioth.debian.org/u32/benchmark.php?test=all&lang=all
 * shows (from the above list) %Lua finishing first, followed by Python, Perl,
 * and PHP in a wide battery of test on a single processor Linux machine
 * (JavaScrpit, Ruby, Tcl are not included in the benchmark). An older benchmark,
 * here:
 * http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=all
 * has the same results for %Lua, Python, Perl, and PHP, with Ruby, Tcl, and
 * JavaScript following behind.
 *
 * \section des_embed_embeddable Embeddability
 * From the above list, the languages most amenable to being embedded in a
 * larger application appear to be JavaScript, %Lua, Python, and Tcl.
 *
 * \section des_embed_size Size of the Embedded API
 * It is difficult to determine the size of the complied libraries for each of
 * the above languages. However there are references to the compiled
 * size of the %Lua library being 230K, while the Jim interpreter for Tcl is
 * only 70KB. Sizes of the Python and JavaScript libraries are not readily
 * available, but are sometimes described as being "large".
 *
 * \section des_embed_lua The Winner: Lua
 * Based on the above criteria, Lua appears to be the winner -- it is relatively
 * fast (only 9.9x slower than c++), has clear and concise instructions and
 * examples for embedding in a larger application, and our compiled
 * Lua lbrary is only 311KB when compiled for our target platform
 * (273KB when compiled for the host). This is larger than the smallest
 * implementation of Tcl, but small enough for our needs.
 */

/**************************************************************************//**
 * \page des_universal Universal Data Values and Units
 *
 * As described in requirement \ref req_arch_universal, the system will be
 * capable of handling data values in an abstract, "universal" manner, providing
 * for example, the best available value for pressure when "pressure" is
 * requested.
 *
 * Universal data value names are defined in the UniversalURI class. The
 * logic for handling universal data elements is contained in
 * UniversalDataElement. Essentially, for each UniversalURI actually used
 * by the system, a UniversalDataElement is created, which contains a list
 * of each DataElement that writes the "universal" value. Each time one of
 * the DataElements in the list change their accuracy or change their state
 * (to/from failed or to/from orphaned) the "best" element in the list is
 * recalculated.
 *
 * Also important to the concept of universal data values are Units.  They are
 * mentioned in several system requirements including:
 * - \ref req_scripting_units
 * - \ref req_scripting_unitChecking
 * - \ref req_storage_metadata
 *
 * The Unit class represents an engineering unit and allows engineering units
 * to be converted to/from the SI units used internally.  A useful operator
 * overload within the Unit class is Unit::operator()(), which returns a pointer
 * to a new DataValue with the specified value. The Units class
 * contains a collection of static constant instances of Unit.
 *
 * When a value is written (via DataWriter::write), a unit must be specified.
 * If the unit is not a base SI unit, the value will be converted to base SI
 * units before being written to the Slate.
 *
 * Likewise, when values are read
 * (via DataReader::read or DataReader::asDouble), a unit must be specified.
 * If the unit is not a base SI unit, the value will be converted to the
 * specified unit when it is read from the Slate.
 */

/**************************************************************************//**
 * \page des_slate Data Slate
 *
 * As described in requirement \ref req_arch_slate, all communication between
 * software units will be performed through a world-readable "slate".
 *
 * The elements of the slate are built up as modules are loaded and
 * initialize themselves. As necessary by dynamic reconfiguration, data
 * elements may be added or put into an "orphaned" state, but data elements
 * will not be removed during the course of a vehicle mission. The state
 * table will keep track of orphaned data table elements to ensure they are
 * not subsequently used, for example in a trigger or in an abstract argument.
 *
 * The slate also stores metadata about elements (units, description).
 * As much as practical, the API forces developers to include metadata
 * rather than omit it.
 *
 * Access to the table is through the read and write methods of DataReader and
 * DataWriter objects, obtained through calls to Slate::NewInputReader,
 * Slate::NewReader, Slate::NewWriter, Slate::NewUniversalReader, or
 * Slate::NewUniversalWriter.
 *
 * All read and write accesses to the table can be logged, although typically
 * only writes are logged.
 */

/**************************************************************************//**
 * \page des_modularity Modularity
 *
 * Goal is to meet the requirement to \ref req_arch_modular
 *
 * Dynamically loaded modules provide the majority of the "functional" elements
 * of the software.  Such drop-in modules include code components such as
 * behaviors, sensor readers, control interfaces, etc. The main vehicle
 * control loop will be capable of scanning a folder of drop-in-modules to
 * add and/or replace modules without stopping execution.
 *
 * Each Module provides registration information including metadata about
 * itself (name, version), and a list of the component it includes.  Then
 * each component registers:
 * - the values they write to the slate, plus metadata about these values
 *   (name, units, initial value).  It also indicates whether these variables
 *   are "Universal" variables.
 * - the type of component: controller, computation, sensor reader, etc.
 * - whether it should be run even if its data isn't being consumed.
 * - whether it should run asynchronously to the control cycle, and if so,
 *   whether there is a minimum/optimal/maximum run frequency
 *   (for example, run every 5 seconds, regardless of other triggers)
 *
 * The supervisor assimilates this information and uses it to build a component
 * list for the control thread and a similar component list for components that
 * will run in their own threads. The default behavior is that components are
 * not run unless one of the following conditions is met:
 * - it provides a data value that's required for another Component to be run,
 *   or to determine whether to run another Component
 * - it provides an "universal" data value that's required by another Component
 *   and was previously the most accurate
 * - it needs to run to meet its specified minimum run frequency
 * - it needs to run every cycle of the control thread.
 *
 * Approach is to allow either compiled c++ modules or scripted modules.
 *
 * Modules are included by the standard Lua "require" command. Hence,
 * compiled c++ modules need a Lua wrapper. This wrapper is automatically
 * generated by the makeLuaModule.lua script (in the Build folder, called by
 * the make command). The generated Lua wrapper defines named lua tables for
 * each component in the module, and popluates these tables with the named
 * entities (and enumerations) from the interface (...IF.h) file associated
 * with each component, simplifying their use in missions.
 *
 * The makeLuaModule.lua script also creates two special Lua wrappers: for the
 * Units class and for the UniversalURI class. In each of theses cases, the
 * static const objects in those classes are defined as lua objects that
 * can be used in a mission.
 *
 * For example, the ControlModlue code is:
 * \code
 * #include "ControlModule.h"
 * #include "VerticalControl.h"
 * #include "HorizontalControl.h"
 * #include "LoopControl.h"
 * #include "SpeedControl.h"
 *
 * ControlModule::ControlModule()
 *         : Module( "Control" ,
 *                   "Contains the Control components, such as Depth, Heading, and Speed Control" )
 * {
 *     registerComponent( new VerticalControl() );
 *     registerComponent( new HeadingControl() );
 *     registerComponent( new SpeedControl() ); // Note: SpeedControl before LoopControl
 *     registerComponent( new LoopControl() );
 * }
 * \endcode
 *
 * It contains the classes VerticalControl, HeadingControl, SpeedControl, and
 * LoopControl, which reference the interfaces VerticalControlIF, HorizontalControlIF,
 * SpeedControlIF, andLoopControlIf. If we examine SpeedControlIF, it contains:
 *
 * \code
 * namespace SpeedControlIF
 * {
 * /// Static const for component name
 * /// (Can be used by other components)
 * static const Str NAME( "SpeedControl" );
 *
 * /// Static consts for input settings
 * /// (Supplied so outputs can be directed to these inputs)
 * static const Str SPEED_CMD( "Speed" );
 *
 * /// Static consts for outputs
 * /// (Supplied so inputSettings can be directed to these outputs)
 * /// Probably only inputs should define names...
 * /// but we have no inputs to consume these values yet!
 * static const Str PROP_OMEGA_ACTION( "PropOmega" );
 *
 * /// Fast and slow speeds -- should probably be read from vehicle.config
 * static const double SPEED_SLOW( 0.5 ); // Nominal 0.5 m/s
 * static const double SPEED_FAST( 1.0 ); // Nominal 1.0 m/s
 *
 * }
 * \endcode
 *
 * VerticalControlIF, HorizontalControlIF, andLoopControlIf contain similar code.
 *
 * The resulting Lua module wrapper is:
 * \code
 * module("Control",package.seeall)
 * require("Tethys")
 * require("Units")
 * __CPPModule = RequireModule("Control")
 * LoopControl = findComponent("LoopControl");
 * LoopControl.PERIOD = MakeURI("LoopControl", "Period");
 * LoopControl.LOOP_FAST = 0.400;
 * LoopControl.LOOP_SLOW = 5.000;
 * LoopControl.LOOP_DRIFT = 300.000;
 * VerticalControl = findComponent("VerticalControl");
 * VerticalControl.DEPTH_MODE = MakeURI("VerticalControl", "VerticalMode");
 * VerticalControl.DEPTH = MakeURI("VerticalControl", "Depth");
 * VerticalControl.DEPTH_RATE = MakeURI("VerticalControl", "DepthRate");
 * VerticalControl.PITCH = MakeURI("VerticalControl", "Pitch");
 * VerticalControl.PITCH_RATE = MakeURI("VerticalControl", "PitchRate");
 * VerticalControl.ELEVATOR_ANGLE = MakeURI("VerticalControl", "ElevatorAngle");
 * VerticalControl.MASS_POSITION = MakeURI("VerticalControl", "MassPosition");
 * VerticalControl.BUOYANCY_GAIN = MakeURI("VerticalControl", "BuoyancyGain");
 * VerticalControl.NONE = Units.ENUM(0);
 * VerticalControl.SURFACE = Units.ENUM(1);
 * VerticalControl.DEPTH = Units.ENUM(2);
 * VerticalControl.PITCH_ZERO = Units.ENUM(3);
 * VerticalControl.PITCH = Units.ENUM(4);
 * SpeedControl = findComponent("SpeedControl");
 * SpeedControl.SPEED = MakeURI("SpeedControl", "Speed");
 * SpeedControl.PROP_OMEGA = MakeURI("SpeedControl", "PropOmega");
 * SpeedControl.SPEED_SLOW = 0.5;
 * SpeedControl.SPEED_FAST = 1.0;
 * \endcode
 */

/**************************************************************************//**
 * \page des_script Mission Scripting
 *
 *  Tethys/LRAUV top-level mission syntax
 *
 *  \code
 *  NAME = "Mission Name"
 *  STACK = \<stack\>
 *  \endcode
 *
 *  where the \<stack\> syntax is:
 *  \code
 *    {
 *       \<stateItem\>
 *      [, <stateItem>]*
 *    }
 *  \endcode
 *
 *  where a \<stateItem\> can be a Behavior, Command, or Substack
 *
 *  Behavior and Command syntax is either:
 *  \code
 *    {
 *       BEHAVIOR|COMMAND=<Behavior>
 *      [, <URI>:SET( <DataValue> )]*
 *      [, WHEN=<ValueClause>]
 *      [, WHILE=<ValueClause>]
 *      [, PREEMPTIVE=<ValueClause>]
 *      [, UNTIL=<ValueClause>]
 *      [, REPEAT=number]
 *    }
 *  \endcode
 *  or:
 *  \code
 *  BEHAVIOR|COMMAND(<Behavior>)
 *    [:SET( <URI>, <DataValue> | <URI>, Units::<unit>, number )]*
 *      [:WHEN( <ValueClause>)]
 *      [:WHILE( <ValueClause>)]
 *      [:PREEMPTIVE( <ValueClause> )]
 *      [:UNTIL( <ValueClause>)]
 *      [:WITHIN( <TimeDataValue> | Units::<timeUnit>, number)]
 *      [:REPEAT( number )]}
 *  \endcode
 *
 *  where \<Behavior\> and URI are typically defined in a module,
 *  \<DataValue\> is the result of calling a Units::\<unitName\>( value ) function,
 *
 *  ValueClause syntax is:
 *  \code
 *      false|true|<DataValue>|<URI>[:NOT( )|:<BoolOperator>( <ValueClause> )|:<CompOperator>( <DataValue>|<URI> )]
 *          where BoolOperator can be AND or OR
 *          CompOperator can be NE, LT, LE, EQ, GE, or GT
 *  \endcode
 *
 *  Syntax for a Substack is
 *  \code
 *    {
 *      <stateItem>
 *      [, <stateItem>]*
 *      [, ID="Substack ID" ]
 *      [, WHEN=<ValueClause>]
 *      [, WHILE=<ValueClause>]
 *      [, PREEMPTIVE=<ValueClause>]
 *      [, UNTIL=<ValueClause>]
 *      [, WITHIN=<TimeDataValue>]
 *      [, REPEAT=<#>]
 *    }
 * \endcode
 *
 *     - First Behaviors in the stack have the highest priority,
 *          later items have lower priority.
 *     - Execution of Commands and SubStacks goes from top to bottom
 *     - WHEN clauses force out-of-order execution
 *       -  the SubStacks become active when the WHEN condition is true,
 *          and stay active until they complete
 *     - WHILE clauses force out-of-order execution
 *       -  the SubStacks become active only while the WHILE condition is true
 *     - PREEMPTIVE, if true, causes lower priority items to be pre-empted.
 *     - UNTIL cause a SubStack to exit when its condition is true
 *     - REPEAT causes a SubStack to be repeated the specified number of times.
 *
 *  Lua code can also be included in the script. For example, the example
 *  mission that follows, Lua code reads some values from a configuration file
 *  and sets some constant values for use later in the mission stack.
 *
 * \section des_script_example Example mission that navigates around 4 waypoints 2 times, and occasionally surfaces for GPS updates and satellite communications:
 *
 * \code
 * NAME = "Test Mission"
 *
 * startLat = workSite.latitude;                   -- from workSite.cfg
 * startLon = workSite.longitude;
 * wp4 = Units.DEGREE( startLat, startLon )           -- start/end location
 * wp1 = Units.DEGREE( startLat, startLon-0.01 )      -- a bit west
 * wp2 = Units.DEGREE( startLat+0.01, startLon-0.01 ) -- a bit north from there
 * wp3 = Units.DEGREE( startLat+0.01, startLon )      -- and east again
 *
 * STACK = {
 *
 * -- some high priority behaviors
 * BEHAVIOR( Guidance.AltitudeEnvelope )
 *     :SET( Guidance.AltitudeEnvelope.MIN_ALTITUDE, Units.METER, 20 );
 *
 * BEHAVIOR( Guidance.OffshoreEnvelope )
 *     :SET( Guidance.OffshoreEnvelope.MIN_OFFSHORE, Units.KILOMETER, 1 )
 *     :SET( Guidance.OffshoreEnvelope.MAX_OFFSHORE, Units.KILOMETER, 50 );
 *
 * BEHAVIOR( Guidance.DepthEnvelope )
 *     :SET( Guidance.DepthEnvelope.MIN_DEPTH, Units.METER, 0 )
 *     :SET( Guidance.DepthEnvelope.MAX_DEPTH, Units.METER, 300 );
 *
 * -- GPS (and Iridium) Update
 * -- Once an hour, if we are already heading up,
 * -- Otherwise, once every two hours.
 * {
 *     WHEN=( UniversalURI.PLATFORM_LOCATION_FIX:ELAPSED( Units.HOUR( 1 ) )
 *            :OR( UniversalURI.PLATFORM_COMMUNICATIONS:ELAPSED( Units.HOUR( 1 ) ) )
 *          )
 *          :AND( UniversalURI.PLATFORM_PITCH_ANGLE:GT( Units.DEGREE( 15 ) ) )
 *          :OR( UniversalURI.PLATFORM_LOCATION_FIX:ELAPSED( Units.HOUR( 2 ) ) )
 *          :OR( UniversalURI.PLATFORM_COMMUNICATIONS:ELAPSED( Units.HOUR( 2 ) ) );
 *
 *     ID="NeedSatFix";
 *
 *     COMMAND( Guidance.GoToSurface );
 *
 *     {
 *         ID="SurfOps";
 *
 *         -- Surface operations are always preemptive
 *         PREEMPTIVE = true;
 *
 *         COMMAND( Guidance.ReadSensor )
 *             :SET(Guidance.ReadSensor.URI, UniversalURI.PLATFORM_LOCATION_FIX );
 *
 *         COMMAND( Guidance.ReadSensor )
 *             :SET(Guidance.ReadSensor.URI, UniversalURI.PLATFORM_COMMUNICATIONS );
 *     }
 * };
 *
 * -- A set of commands to repeat two times:
 * {
 *     ID="RepeatOps";
 *
 *     {
 *         WHILE=UniversalURI.DEPTH:GT( Units.FOOT( 1 ) );
 *
 *         BEHAVIOR( Guidance.ReadSensor )
 *             :SET( Guidance.ReadSensor.URI, UniversalURI.SEA_WATER_SALINITY );
 *
 *         BEHAVIOR( Guidance.ReadSensor )
 *             :SET( Guidance.ReadSensor.URI, UniversalURI.SEA_WATER_TEMPERATURE );
 *     };
 *
 *     BEHAVIOR( Guidance.DepthEnvelope )
 *         :SET( Guidance.DepthEnvelope.MIN_DEPTH, Units.METER, 5 );
 *
 *     BEHAVIOR( Guidance.YoYo )
 *         :SET( Guidance.YoYo.UP_SPEED, Units.METER_PER_SECOND, Control.SpeedControl.SPEED_SLOW)
 *         :SET( Guidance.YoYo.DOWN_SPEED, Units.METER_PER_SECOND, Control.SpeedControl.SPEED_FAST);
 *
 *     COMMAND( Guidance.Waypoint )
 *         :SET( Guidance.Waypoint.WAYPOINT, wp1 )
 *         :SET( Guidance.Waypoint.CAPTURE_RADIUS, Units.METER, 100 );
 *
 *     COMMAND( Guidance.Waypoint )
 *         :SET( Guidance.Waypoint.WAYPOINT, wp2 )
 *         :SET( Guidance.Waypoint.CAPTURE_RADIUS, Units.METER, 100 );
 *
 *     COMMAND( Guidance.Waypoint )
 *         :SET( Guidance.Waypoint.WAYPOINT, wp3 )
 *         :SET( Guidance.Waypoint.CAPTURE_RADIUS, Units.METER, 100 );
 *
 *     COMMAND( Guidance.Waypoint )
 *         :SET( Guidance.Waypoint.WAYPOINT, wp4 )
 *         :SET( Guidance.Waypoint.CAPTURE_RADIUS, Units.METER, 100 );
 *
 *     REPEAT=2
 * };
 *
 * } -- end of STACK
 * \endcode
 */

/**************************************************************************//**
 * \page des_threads Sequential Nested threads
 *
 * Post PDR, various multi-treading approaches were tested.
 * - Single thread (Collaborative Multitasking)
 *   - Fault detection & isolation difficult (a la Windows 3.1)
 * - Parallel threads (Preemptive Multitasking)
 *   - Complicated detection of "hung" thread
 *   - Performance penalty (ARM arch & SD i/o)
 * - Sequential, nested threads
 *   - Reasonable compromise
 *   - One thread runs at a time
 *   - The basic idea is that each Component of code (except for Behavior
 *     instances) is wrapped by Handler class that manages its execution.
 *     Each Handler has an instance of the PCaller class, which contains
 *     an instance of pthread.
 *   - PCallers have the notion of parent and child threads -- in this context,
 *     the SyncHandler owns all the PCallers in the control cycle,
 *     while the SupervisorHandler owns the SyncHandler and other
 *     independent threads (such as the Handler for CommandLine).
 *   - PCallers only allow one child thread to run at a time -- since there is
 *     only one SupervisorHandler over all the other Handler instances,
 *     then only one thread will run at a time in the entire vehicle.
 *   - However, since all blocks of code run in their own threads, signals
 *     can be trapped and logged, and the components can be re-run if necessary.
 *
 * \image html des_threads.png
 * \image latex des_threads.eps
 *
 */

/**************************************************************************//**
 * \page des_storage Binary Data Storage and Logging
 *
 * Logging is primarily done behind the scenes, by using DataReader and
 * DataWriter objects within a component. Both data reads and data writes can
 * be logged, although in the current implementation, only data writes are
 * logged. During a computation cycle, data writes are buffered (as LogEntry
 * instances) in a LogQueue. At the end of the cycle, all the accumulated
 * LogEntry instances are serialized to the log and are then released. There
 * can be zero or more LogWriter instances for any LogEntry -- a set of LogRule
 * instances can be used to define what LogWriter is used for each LogEntry.
 *
 * There are three "flavors" of LogEntry: EventEntry, DataEntry, and SyslogEntry
 *
 * \section des_storage_eventEntry EventEntry
 *
 * An EventEntry is serialized as:
 * - a 16-bit header (serialized using OutStream::writeUShortCompact) including:
 * 	 \li 12 high bits: Actor code (which can be used to look up
 *       what code unit is causing the event), or zero if this is the start
 *       of a cycle
 *   \li 2 bits: EventEntry::Action code, indicating the type of action being
 *       logged; e.g., the start of a cycle, the setting of accuracy, the setting
 *       of the state of a variable, or the setting of a variable to the "best"
 *       for its associated Universal variable
 *   \li 2 bits: the value 0, indicating this is a EventEntry
 * - Unless the action is EventEntry::START_CYCLE, 16 bits  (serialized using
 *   OutStream::writeUShortCompact) indicating the DataAccessor code of the
 *   DataElement undergoing the event.
 * - If the action is EventEntry::START_CYCLE, a 64-bit Timestamp as integer
 *   microseconds since the start of the epoch. Otherwise, a 64-bit Timespan
 *   as integer microseconds since the previous LogEntry. (In both cases,
 *   serialized using OutStream::writeLongLongCompact).
 * - If the action is EventEntry::SET_DATA_ACCURACY, a 16-bit floating point number
 *   (serialized using OutStream::writeFloat2) indicating the new accuracy of
 *   the DataElement. Or if the action is EventEntry::SET_DATA_STATE, a 8-bit
 *   ORed result of the EventEntry::StateChange flags for the DataElement.
 *
 * \section des_storage_dataEntry DataEntry
 *
 * A DataEntry is serialized as:
 * - a 16-bit header (serialized using OutStream::writeUShortCompact) including:
 *   - 13 high bits: DataAccessor code (which can be used to look up
 *     metadata about the entry that follows)
 *   - 1 bit: "Best" flag, set if this is a member of a "Universal" set
 *     of variables, and this one is the "best" one (see UniversalDataElement)
 *   - 2 bits: the value 1, indicating this is a DataEntry
 * - 64-bit Timespan as integer microseconds since the previous LogEntry,
 *   serialized using OutStream::writeLongLongCompact.
 * - the data, length determined by the DataAccessor
 *
 * \section des_storage_syslogEntry SyslogEntry
 *
 * A SyslogEntry is serialized as:
 * - a 16-bit header (serialized using OutStream::writeUShortCompact) including:
 * 	 \li 12 high bits: Actor code (which can be used to look up
 *       what code unit is writing to the log)
 *   \li 2 bits: Syslog::Severity code, indicating the severity of the message
 *       being logged: from debug messages to messages that must be relayed to
 *       shore via satellite.
 *   \li 2 bits: the value 2, indicating this is a SyslogEntry
 * - 64-bit Timespan as integer microseconds since the previous LogEntry,
 *   serialized using OutStream::writeLongLongCompact.
 * - 16-bit integer length of the character sequence that follows, serialized
 *   using OutStream::writeUShortCompact
 * - the characters of the message, with no termination character.
 */

/**************************************************************************//**
 * \page des_sim Simulation
 *
 * The approach we have taken for this vehicle is to provide a core Simulator
 * class that can be used with a simulator interface class to provide
 * simulation in a variety of situations:
 * - With the ExternalSim interface, one runs SimDaemon on a server, and the
 * ExternalSim runs in the control cycle (on either host or target) to provide
 * a simulated environment (including environmental values). Same code-base
 * runs on either host or target (although a \#define must be set to avoid
 * errors due to missing hardware on either the host or a bare-bones target).
 * - With the InternalSim interface, the Simulator object runs locally, and
 * provides a full simulation of all control sensors between GPS fixes. This
 * will be a valuable input to the CBIT component.
 * - With the NavigationSim interface, the Simulator component also runs
 * locally, but the real sensor readings are fed back to the simulator when
 * they are available -- this provides a high-fidelity dead-reckoning.
 *
 */