cfe_time.dox

/**
  \page cfetimeovr cFE Time Services Overview

  The cFE Time Service (TIME) is one of the cFE core services.  TIME provides time
  correlation, distribution and synchronization services.  TIME exists in two varieties:
  a Time Server responsible for maintaining the master time reference for all remote systems,
  and a Time Client responsible for synchronizing to that master time reference.

  Since TIME is a generic implementation aimed to meet the needs of a variety of
  mission configurations, there are numerous configuration parameters, which dictate
  the behavior of TIME (see cfe_mission_cfg.h and cfe_platform_cfg.h for the specific
  mission configuration).

  With the exception of those sections specific to Time Clients and Servers, this
  document assumes the most common physical environment - one instantiation of cFE
  installed on a single processor.  Therefore, TIME represents cFE Time Services
  configured as a Time Server.

  For additional detail on Time Services and how to manage it, see the following sections:

  <UL>
    <LI> \subpage cfetimeugcomponents <BR>
    <LI> \subpage cfetimeugstruct <BR>
    <LI> \subpage cfetimeugformat <BR>
    <LI> \subpage cfetimeugconfig <BR>
    <UL>
       <LI> \subpage cfetimeugformsel <BR>
       <LI> \subpage cfetimeugfaketone <BR>
       <LI> \subpage cfetimeugtoneorder <BR>
       <LI> \subpage cfetimeugtonewindow <BR>
       <LI> \subpage cfetimeugserver <BR>
       <LI> \subpage cfetimeugendian <BR>
       <LI> \subpage cfetimeugvirtualmet <BR>
       <LI> \subpage cfetimeugsource <BR>
       <LI> \subpage cfetimeugsignal <BR>
    </UL>
    <LI> \subpage cfetimeugparadigm <BR>
    <LI> \subpage cfetimeugflywheeling <BR>
    <LI> \subpage cfetimeugstate <BR>
    <LI> \subpage cfetimeuginit <BR>
    <UL>
       <LI> \subpage cfetimeugpoweron <BR>
       <LI> \subpage cfetimeugprocessor <BR>
    </UL>
    <LI> \subpage cfetimeuginit <BR>
    <UL>
       <LI> \subpage cfetimeugpoweron <BR>
       <LI> \subpage cfetimeugprocessor <BR>
    </UL>
    <LI> \subpage cfetimeugnormal <BR>
    <UL>
       <LI> \subpage cfetimeugclientops <BR>
       <LI> \subpage cfetimeugserverops <BR>
       <UL>
          <LI> \subpage cfetimeugsettime <BR>
          <LI> \subpage cfetimeugadjust <BR>
          <LI> \subpage cfetimeugsetmet <BR>
       </UL>
    </UL>
    <LI> \subpage cfetimeugfaq <BR>
  </UL>
**/

/**
  \page cfetimeugcomponents Time Components

  Time knowledge is stored in several pieces, so that the time information can more
  easily be manipulated and utilized. These components include:

  The <B>Ground Epoch</B> is an arbitrary date and time that establishes the zero point
  for spacecraft time calculations.  The selection of the epoch is mission specific,
  although in the past, it was common to select the same epoch as defined for the
  Operating System used by the computers hosting the ground system software.  Recent
  mission epoch selections have also included using zero seconds after midnight,
  Jan 1, 2001.

  <B>Spacecraft Time</B> is the number of seconds (and fraction of a second) since the
  ground epoch.  Spacecraft time is the sum of <B>Mission Elapsed Time</B> (MET) and the
  <B>Spacecraft Time Correlation Factor</B> (STCF).  By definition, MET is a measure of
  time since launch or separation.  However, for most missions the MET actually
  represents the amount of time since powering on the hardware containing the MET
  timer.  The STCF correlates the MET to the ground epoch.

  The <B>Tone</B> is the signal that MET seconds have incremented.  In most hardware
  configurations, the tone is synonymous with the <B>1 PPS</B> signal.  The tone signal
  may be generated by a local hardware timer, or by an external event (GPS receiver,
  spacewire time tick, 1553 bus signal, etc).  TIME may also be configured to
  simulate the tone for lab environments that do not have the necessary hardware
  to provide a tone signal.  Note that MET sub-seconds will be zero at the instant
  of the tone.

  <B>Time at the Tone</B> is the spacecraft time at the most recent "valid" tone.

  <B>Time since the Tone</B> is the amount of time since the tone (usually less than one
  second).   This value is often measured using the local processor clock.  Upon
  detecting the tone signal, TIME stores the contents of the local processor clock
  to facilitate this measurement.

  Thus, <B>Current Spacecraft Time</B> is the sum of "time at the tone" and
  "time since the tone".

  <B>Leap Seconds</B> occur to keep clocks correlated to astronomical observations.  The
  modern definition of a second (9,192,631,770 oscillations of a cesium-133 atom)
  is constant while the earth's rotation has been slow by a small fraction of a
  second per day.  The <B>International Earth Rotation and Reference System Service</B>
  (IERS) maintains the count of leap seconds as a signed whole number that is
  subject to update twice a year.  Although it is possible to have a negative
  leap second count if the earth rotates too fast, it is highly unlikely.  The initial
  count of leap seconds (10) was established in January of 1972 and the first leap second
  was added to the initial count in June of 1972.  The most recent leap seconds are announced
  by the International Earth Rotation Service (IERS): <a href="https://www.iers.org">
  https://www.iers.org </a> in IERS Bulletin C (leap second announcements).  Search the IERS site
  for "Bulletin C" to obtain the latest issue/announcement.
**/

/**
  \page cfetimeugstruct Time Structure

  The cFE implementation of the <B>System Time Structure</B> is a modified version of the
  CCSDS Unsegmented Time Code (CUC) which includes 4 bytes of seconds, and 4 bytes of
  subseconds, where a subsecond is equivalent to 1/(2^32) seconds.  The system time
  structure is used by TIME to store current time, time at the tone, time since the
  tone, the MET, the STCF and command arguments for time adjustments.  Note that typically
  the 32 bits of seconds and the upper 16 bits of subseconds are used for time stamping
  Software bus messages, but this is dependent on the underlying definition.

  The system time structure is defined as follows:

  \verbatim
  typedef struct {
        uint32      Seconds;      /* Number of seconds */
        uint32      Subseconds;   /* Number of 2^(-32) subseconds */
  } CFE_TIME_SysTime_t;
  \endverbatim
**/

/**
  \page cfetimeugformat Time Formats

  <B>International Atomic Time</B> (TAI) is one of two time formats supported by cFE TIME.
  TAI is the number of seconds and sub-seconds elapsed since the ground epoch as measured
  with the atomic clock previously described.  TAI has no reference to leap seconds and is
  calculated using the following equation:

  \verbatim
  TAI = MET + STCF
  \endverbatim

  It should be noted that TAI is only "true" TAI when the selected ground epoch is the same
  as the TAI epoch (zero seconds after midnight, January 1, 1958).  However, nothing precludes
  configuring cFE TIME to calculate time in the TAI format and setting the STCF to correlate
  to any other epoch definition.

  <B>Coordinated Universal Time</B> (UTC) is the other time format supported by cFE TIME.  UTC
  differs from TAI in the fact that UTC includes a leap seconds adjustment.  TIME computes UTC
  using the following equation:

  \verbatim
  UTC = TAI - Leap Seconds.
  \endverbatim

  The preceding UTC equation might seem to imply that TAI includes leap seconds and UTC does
  not - which is not the case.  In fact, the UTC calculation includes a leap seconds adjustment
  that subtracts leap seconds from the same time components used to create TAI.  Alternatively,
  it might be less confusing to express the UTC equation as follows:

  \verbatim
  UTC = MET + STCF - Leap Seconds
  \endverbatim
**/

/**
  \page cfetimeugconfig Time Configuration

  All configurations of TIME require a local processor source for a 1Hz interrupt and access
  to a local clock with a resolution fine enough that it can be used to measure short periods
  of elapsed time.  The local interrupt is used to wake-up TIME at a regular interval for the
  purpose of verifying that the tone is being received.  The local clock is used to measure
  time since the tone and to provide coarse verification that the tone is occurring at
  approximately one second intervals.  The presumption is that the tone is the most accurate
  timer in the system and, within reason, is to be trusted.  Note that nothing precludes the
  use of the MET as the local clock, assuming the MET is both local and provides sub-second
  data.  However, the tone must not be used as the source for the local 1Hz interrupt.

  Consider the following brief description of three hypothetical hardware configurations.
  These sample systems may be used as reference examples to help clarify the descriptions
  of the various TIME configuration selections.

  In the first system, there is no MET timer and therefore no tone signal.  The MET is a count
  of the number of "fake" tones generated by TIME software.  There is no validation performed
  regarding the quality of time data.  This hardware configuration is a common lab environment
  using COTS equipment.

  In the second system, the MET timer is a hardware register that is directly accessible by TIME.
  When MET seconds increment, a processor interrupt signals the tone.  Upon detecting the tone,
  TIME can read the MET to establish the time at the tone.  To verify that the tone is valid,
  TIME need only validate that this tone signal occurred approximately one second after the
  previous tone signal (as measured with the local clock).

  In the third system, the MET is located on hardware connected via spacewire.  When MET seconds
  increment, a spacewire time tick triggers a local processor interrupt to signal the tone.
  Shortly after announcing the tone, the hardware containing the MET also generates a spacewire
  data packet containing the MET value corresponding to the tone.  TIME must wait until both
  the tone and data packet have been received before validating the tone.  The tone must have
  occurred approximately one second after the previous tone signal and the data packet must
  have been received within a specified window in time following the tone.

  The hardware design choice for how the tone signal is distributed is not material to TIME
  configuration.  The software detecting the tone need only call the cFE API function announcing
  the arrival of the tone.  This function is designed to be called from interrupt handlers.

  For detail on each of the individual configuration settings for cFE Time Services, see the
  following sections:

  <UL>
     <LI> \subpage cfetimeugformsel <BR>
     <LI> \subpage cfetimeugfaketone <BR>
     <LI> \subpage cfetimeugtoneorder <BR>
     <LI> \subpage cfetimeugtonewindow <BR>
     <LI> \subpage cfetimeugserver <BR>
     <LI> \subpage cfetimeugendian <BR>
     <LI> \subpage cfetimeugvirtualmet <BR>
     <LI> \subpage cfetimeugsource <BR>
     <LI> \subpage cfetimeugsignal <BR>
  </UL>
**/

/**
  \page cfetimeugformsel Time Format Selection

  Time format is defined in the mission configuration header file.

  This selection defines the default time format as TAI or UTC.  The API functions
  to get time in either specific format are still enabled, but the API function to
  get time in the default format will follow this selection.   Enable one, and <B>only
  one</B>, of the following time format definitions:

  \verbatim
  #define CFE_MISSION_TIME_CFG_DEFAULT_TAI  TRUE
  #define CFE_MISSION_TIME_CFG_DEFAULT_UTC  FALSE
  \endverbatim

  or

  \verbatim
  #define CFE_MISSION_TIME_CFG_DEFAULT_TAI  FALSE
  #define CFE_MISSION_TIME_CFG_DEFAULT_UTC  TRUE
  \endverbatim

  The choice of time format is a mission specific decision and is not directly
  affected by the hardware configuration.

  \sa #CFE_MISSION_TIME_CFG_DEFAULT_TAI, #CFE_MISSION_TIME_CFG_DEFAULT_UTC <BR>
**/

/**
  \page cfetimeugfaketone Enabling Fake Tone Signal

  The fake tone is defined in the mission configuration header file.

  If this selection is set to TRUE, TIME will generate a "fake" tone signal by calling
  the same API function as would be called upon detection of the "real" tone signal.
  Enable the fake tone only for hardware configurations that do not provide a tone
  signal.

  \verbatim
  #define CFE_MISSION_TIME_CFG_FAKE_TONE  TRUE
  \endverbatim

  Hypothetical hardware configuration number one (described above) would enable the fake tone signal.

  \sa #CFE_MISSION_TIME_CFG_FAKE_TONE
**/

/**
  \page cfetimeugtoneorder Selecting Tone and Data Ordering

  Tone and data order is defined in the mission configuration header file.

  This selection defines which comes first - the tone or the time at the
  tone data.  Does the time data describe the tone that already occurred,
  or the tone that has not yet occurred?  This decision may be driven by
  the hardware design but can also be arbitrary.  Enable one, and only one,
  of the following:

  \verbatim
  #define CFE_MISSION_TIME_AT_TONE_WAS
  #define CFE_MISSION_TIME_AT_TONE_WILL_BE
  \endverbatim

  Hypothetical hardware configuration number three (described \ref cfetimeugconfig above) would
  enable "time at the tone was".

  \sa #CFE_MISSION_TIME_AT_TONE_WAS, #CFE_MISSION_TIME_AT_TONE_WILL_BE
**/

/**
  \page cfetimeugtonewindow Specifying Tone and Data Window

  The tone and data window is defined in the mission configuration header file.

  In concert with the definition of tone and data order, this selection defines
  the valid window in time for the second of the pair to follow the first.
  Both must be defined, units are micro-seconds.

  \verbatim
  #define CFE_MISSION_TIME_MIN_ELAPSED  0
  #define CFE_MISSION_TIME_MAX_ELAPSED  100000
  \endverbatim

  Hypothetical hardware configuration number three (described above) might use
  these values which describe a window that begins immediately after the tone
  and lasts for one tenth of a second.

  \sa #CFE_MISSION_TIME_MIN_ELAPSED, #CFE_MISSION_TIME_MAX_ELAPSED
**/

/**
  \page cfetimeugserver Specifying Time Server/Client

  Configure TIME as a client only when the target system has multiple processors
  running separate instantiations of the cFE.  One instantiation must be configured
  as the server and the remainder configured as clients.  If the target system has
  only one processor running the cFE, then TIME must be configured as a server.

  Enable one, and only one, of the following definitions in the platform configuration
  header file:

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SERVER   TRUE
  #define CFE_PLATFORM_TIME_CFG_CLIENT   FALSE
  \endverbatim

  or

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SERVER   FALSE
  #define CFE_PLATFORM_TIME_CFG_CLIENT   TRUE
  \endverbatim

  \sa #CFE_PLATFORM_TIME_CFG_SERVER, #CFE_PLATFORM_TIME_CFG_CLIENT
**/

/**
  \page cfetimeugendian Specifying Time Tone Byte Order

  By default, the CFE time tone message is a payload of integers in
  platform-endian order (containing the tone's timestamp, the leap seconds,
  and state information.) In some configurations, it may be better to
  have the payload produced in big-endian order--particularly in mixed-endian
  environments.

  In order to force the tone message to be in big-endian order, you must
  define the following:

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_BIGENDIAN
  \endverbatim
**/

/**
  \page cfetimeugvirtualmet Virtual MET

  This configuration option refers to whether the MET is local to this instantiation
  of TIME.  If the MET is not local then TIME must be configured as using a virtual MET.

  Therefore, all TIME clients must be configured as using a virtual MET.  If the MET was
  local to any TIME client, then that instantiation of TIME would have to be the server.

  TIME servers must be configured as using a virtual MET
**/

/**
  \page cfetimeugsource Specifying Time Source

  TIME configuration provides the ability to specify where the source for time data
  is originating - either internal or external.  In hypothetical system one, the MET
  is internal.  In system two, TIME cannot directly read the MET, therefore time data
  must be received from an external source.

  This selection also enables a command interface to switch between internal and
  external input.  When commanded to use internal time data, TIME will ignore the
  external data.  However, TIME will continue to use the API function as the trigger
  to generate a "time at the tone" command packet regardless of the internal/external
  command selection.

  Set the following definition to TRUE only for TIME servers using an external time data source.

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SOURCE  TRUE
  \endverbatim

  The remainder of this section pertains only to TIME servers configured to accept
  external time data.

  When configured to accept external time data, TIME requires an additional definition
  for the type of external data (GPS, MET, spacecraft time, etc.).  This selection
  will enable an API function specific to the selected data type.  Regardless of how
  the time data is received, the receiver need only pass the data to the appropriate
  API function.

  TIME servers using an external time data source must set one, and only one, of
  the following to TRUE, for example:

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SRC_MET   TRUE
  #define CFE_PLATFORM_TIME_CFG_SRC_GPS   FALSE
  #define CFE_PLATFORM_TIME_CFG_SRC_TIME  FALSE
  \endverbatim

  configuration definitions for the particular source.

  If the cfe_platform_cfg.h file contains "#define CFE_PLATFORM_TIME_CFG_SOURCE  TRUE" then time is
  configured to allow switching between internal and external time sources
  (see #CFE_TIME_SET_SOURCE_CC).  If this configuration parameter is set to FALSE then
  the command to set the source will be rejected.

  If this configuration parameter is set to TRUE then ONE and ONLY ONE of the following configuration
  parameters must also be set TRUE in order to specify the external time source, for example:

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SRC_MET   TRUE
  #define CFE_PLATFORM_TIME_CFG_SRC_GPS   FALSE
  #define CFE_PLATFORM_TIME_CFG_SRC_TIME  FALSE
  \endverbatim

  Note that Internal MET source depends on available hardware.  It may be the local
  count of tone signals, the contents of a hardware register or an OS specific time function.

  Note also that when configured to use an external time source, commands to set the
  time will be overwritten.


  \sa #CFE_PLATFORM_TIME_CFG_SRC_MET, #CFE_PLATFORM_TIME_CFG_SRC_GPS, #CFE_PLATFORM_TIME_CFG_SRC_TIME
**/

/**
  \page cfetimeugsignal Specifying Time Signal

  Some hardware configurations support a primary and redundant tone signal selection.
  Setting the following configuration definition to TRUE will result in enabling a TIME
  command to select the active tone signal.

  \verbatim
  #define CFE_PLATFORM_TIME_CFG_SIGNAL  TRUE
  \endverbatim

  Note: this feature requires additional custom software to make the physical signal switch.

  \sa #CFE_PLATFORM_TIME_CFG_SIGNAL
**/

/**
  \page cfetimeugparadigm Time Services Paradigm(s)

  In order for the cFE Time Services to work for a particular mission, the methods of
  obtaining time, distributing time and translating time must follow some standard
  paradigms used in previous missions.  The following describes this expected context:

  Mission dependent hardware provides the Tone.  When this Tone message is received,
  TIME latches the local time based on the local clock.  Note that in lab environments,
  a simulated Tone capability exists which uses an SB message.  Mission dependent
  hardware also provides the "time at the tone" message based on the hardware latched
  time and the reference times stored by TIME Server. The TIME Client then updates
  its local reference time based on the local hardware latched time at the Tone and
  the provided Time-at-Tone message packet when certain checks (such as the Validity bit
  being set) pass.

  When used in an environment that includes multiple processors, each running a separate
  instantiation of cFE software, the presumption is that TIME will be distributed in a
  client/server relationship.  In this model, one processor will have TIME configured
  as the server and the other processors as clients.  The TIME server will maintain the
  various time components and publish a "time at the tone" message to provide synchronized
  time to the TIME clients.  Environments that have only a single instance of TIME must be
  configured as a TIME server.

  In all configurations, the final step in calculating the time "right now" for any
  instantiation of TIME is to use a local processor clock to measure the "time since the tone".

  The specific MET hardware properties will determine whether the MET value can be modified.
  However, the cFE design is such that there should never be a need to purposefully change or
  reset the MET.

  Regardless of the physical hardware implementation for the MET (elapsed seconds,
  elapsed ticks, etc.), cFE TIME will convert the hardware MET value into a System Time
  Format structure for time calculations and will report the converted value in telemetry.
  cFE TIME will also maintain and report the STCF in a System Time Format structure.

  cFE TIME has no knowledge of the current epoch; it is up to the user to keep time on the
  spacecraft correlated to an epoch.  An exception might appear to be the epoch definition
  required in the cFE mission configuration definition file.  However, this definition is for
  use only by the API functions that convert spacecraft time and file system time, and the
  API function that prints spacecraft time as a date and time text string.  The cFE "get time"
  functions are independent of the ground epoch.

  The mission configuration parameters, #CFE_MISSION_TIME_CFG_DEFAULT_TAI and #CFE_MISSION_TIME_CFG_DEFAULT_UTC
  specify the default time format.  Applications are encouraged to use the #CFE_TIME_GetTime API,
  which returns time in the format specified by this configuration parameter.
**/


/**
  \page cfetimeugflywheeling Flywheeling

  Flywheeling occurs when TIME is not getting a valid tone signal or external "time at the tone"
  message.   While this has minimal impact on internal operations, it can result in the drifting
  apart of times being stored by different spacecraft systems.

  Flywheeling occurs when at least one of the following conditions is true:<BR>
  <UL>
     <LI> loss of tone signal <BR>
     <LI> loss of "time at the tone" data packet <BR>
     <LI> signal and packet not within valid window <BR>
     <LI> commanded into fly-wheel mode <BR>
  </UL>

  If the TIME server is in Flywheel mode then the TIME client is also in flywheel mode.
**/


/**
  \page cfetimeugstate Time State

  Clock state is a combination of factors, most significantly whether the spacecraft time has
  been accurately set and whether Time Service is operating in FLYWHEEL mode.   A ground
  command is provided to set the state to reflect when the ground has determined the spacecraft
  time is now correct, or that time is no longer correct.  This information will be distributed
  to Time Clients, and in turn, to any interested sub-systems. If time has not been set then TIME
  services reports the state of time as invalid, regardless of whether time is flywheeling or not.
  Also, this command may be used to force a Time Server or Time Client into FLYWHEEL mode.
  Use of FLYWHEEL mode is mainly for debug purposes although, in extreme circumstances, it
  may be of value to force Time Service not to rely on normal time updates.  Note that when
  commanded into FLYWHEEL mode, the Time  Service will remain so until receipt of another
  "set state" command setting the  state into a mode other than FLYWHEEL.   Note also that
  setting the clock state to VALID or INVALID on a Time Client that is currently getting
  time updates from the Time Server will have very limited effect.  As soon as the Time
  Client receives the next time update, the VALID/INVALID selection will be set to that of
  the Time Server.  However, setting a Time Client to FLYWHEEL cannot be overridden by the
  Time Server since the Time Client will ignore time updates from the Time Server while in
  FLYWHEEL mode.
**/


/**
  \page cfetimeuginit Initialization

  No action is required by the ground to initialize the TIME software; however, time
  variables in the TIME Server must be set by command to allow correct time to propagate.

  For a description of what happens during each type of reset, see below: <BR>

  <UL>
     <LI> \subpage cfetimeugpoweron <BR>
     <LI> \subpage cfetimeugprocessor <BR>
  </UL>
**/


/**
  \page cfetimeugpoweron Power-On Reset

  TIME initializes all counters in housekeeping telemetry, sets the Validity
  state to Invalid, and initializes the STCF, Leap Seconds, and 1 Hz Adjustment to zero.
**/


/**
  \page cfetimeugprocessor Processor Reset

  In the event of a processor reset, the following time values are preserved: <BR>
  <UL>
     <LI> MET <BR>
     <LI> STCF <BR>
     <LI> Leap Seconds <BR>
     <LI> Clock Signal Selection <BR>
     <LI> Current Time Client Delay (if applicable) <BR>
  </UL>

  Note that since it is virtually impossible for TIME services to validate the
  actual data that is saved across a processor reset, a signature pattern is
  written to the preserved area.  On a processor reset, TIME queries that
  signature to make sure that it matches what is expected.  If the signature
  does not match, then TIME is initialized as if a cFE power-on reset occurred.
**/


/**
  \page cfetimeugnormal Normal Operation

  The following sections describe the operator's responsibilities for maintaining
  time under nominal conditions: <BR>

  <UL>
     <LI> \subpage cfetimeugclientops <BR>
     <LI> \subpage cfetimeugserverops <BR>
  </UL>
**/


/**
  \page cfetimeugclientops Client

  Under normal operation, TIME Client systems do not require any attention from the ground,
  however TIME clients do provide commands to set the persistent latency between the server
  and client.  Latency can be either added or subtracted  to the current TIME client time
  calculation to account for the latency.
**/


/**
  \page cfetimeugserverops Server

  TIME Servers require maintenance by the operations team to ensure the spacecraft is maintaining
  a time that can be successfully correlated to other entities.  The following sections describe
  the commands that the operations team can use to help maintain a proper time reference: <BR>

  <UL>
     <LI> \subpage cfetimeugsettime <BR>
     <LI> \subpage cfetimeugadjust <BR>
     <LI> \subpage cfetimeugsetmet <BR>
  </UL>
**/


/**
  \page cfetimeugsettime Setting Time

  The Time Server provides commands to set time.  The new time value represents the
  desired offset from mission-defined time epoch and takes effect immediately upon
  execution of this command.  Time Service will calculate a new STCF value based
  on the current MET and the desired new time using one of the following:

  If Time Service is configured to compute current time as TAI:

  \verbatim
  STCF = new time - current MET
  current time =  current MET + STCF
  \endverbatim

  If Time Service is configured to compute current time as UTC:

  \verbatim
  STCF = ((new time) - (current MET)) + Leap Seconds
  current time = ((current MET) + STCF) - Leap Seconds
  \endverbatim

  \sa #CFE_TIME_SET_TIME_CC
**/


/**
  \page cfetimeugadjust Adjusting Time

  The TIME Server includes commands to set the STCF, Leap Seconds,
  and Validity state. The STCF should be set implicitly using the
  #CFE_TIME_SET_TIME_CC or explicitly using #CFE_TIME_SET_STCF_CC.
  TIME provides the ability to command a one time adjustment
  (#CFE_TIME_ADD_ADJUST_CC and #CFE_TIME_SUB_ADJUST_CC)
  to the current STCF.  In addition there is a 1Hz adjustment
  (#CFE_TIME_ADD_ONEHZ_ADJUSTMENT_CC and #CFE_TIME_SUB_ONEHZ_ADJUSTMENT_CC)
  that can be made to the STCF to compensate for oscillator drift.
  Mission specific ground correlation should be used to assist in
  determining the proper values to use. The Leap Seconds should be
  set to the current TAI-UTC. Note that the International Earth
  Rotation and Reference Systems Service Bulletin C, which defines
  the current difference, reports it as UTC-TAI, and thus that value
  must be negated. <B>The Leap Seconds value will always be a positive
  number.</B> The Validity state does not have to be set to invalid to
  change the STCF or Leap Seconds, and should be set to valid at
  any time that the TIME Server time reference should be synchronized
  to by the other systems.

  \sa #CFE_TIME_ADD_ADJUST_CC, #CFE_TIME_SUB_ADJUST_CC, #CFE_TIME_SET_STCF_CC,
  #CFE_TIME_ADD_ONEHZ_ADJUSTMENT_CC, #CFE_TIME_SUB_ONEHZ_ADJUSTMENT_CC, #CFE_TIME_SET_LEAP_SECONDS_CC
**/


/**
  \page cfetimeugsetmet Setting MET

  The TIME Server provides the capability to set the MET.  Note that the
  MET (as implemented for cFE Time Service) is a logical representation
  and not a physical timer.  Thus, setting the MET is not dependent on
  whether the hardware supports a MET register that can be written to.
  Note also that Time Service "assumes" that during normal operation,
  the MET is synchronized to the tone signal.  Therefore, unless operating
  in FLYWHEEL mode,  the sub-seconds portion of the MET will be set to zero
  at the next tone signal interrupt.  The new MET takes effect immediately
  upon execution of this command.

  \sa #CFE_TIME_SET_MET_CC
**/


/**
  \page cfetimeugfaq Frequently Asked Questions about Time Services

  None submitted
**/


/**
**  \page cfetimecmds cFE Time Services Commands
**
**  Upon receipt of any command, the Time Services application will confirm that the
**  message length embedded within the header (from `CFE_MSG_GetSize()`) matches the expected
**  length of that message, based on the size of the C structure defining that command.
**  If there is any discrepancy between the expected and actual message size, TIME will generate
**  the #CFE_TIME_LEN_ERR_EID event, increment the command error counter (\TIME_CMDEC), and the
**  command will _not_ be accepted for processing.
**
**  The following is a list of commands that are processed by the cFE Time Services Task.
**/

/**
**  \page cfetimetlm  cFE Time Services Telemetry
**
**  The following are telemetry packets generated by the cFE Time Services Task.
**/

/**
**  \page cfetimecfg  cFE Time Services Configuration Parameters
**
**  The following are configuration parameters used to configure the cFE Time Services
**  either for each platform or for a mission as a whole.
**/