Ubuntu Manpage: ion - Interplanetary Overlay Network common definitions and functions

NAME

       ion - Interplanetary Overlay Network common definitions and functions

SYNOPSIS

           #include "ion.h"

           [see description for available functions]

DESCRIPTION

       The Interplanetary Overlay Network (ION) software distribution is an implementation of Delay-Tolerant
       Networking (DTN) architecture as described in Internet RFC 4838.  It is designed to enable inexpensive
       insertion of DTN functionality into embedded systems such as robotic spacecraft.  The intent of ION
       deployment in space flight mission systems is to reduce cost and risk in mission communications by
       simplifying the construction and operation of automated digital data communication networks spanning
       space links, planetary surface links, and terrestrial links.

       The ION distribution comprises the following software packages:

           ici (Interplanetary Communication Infrastructure), a set of general-purpose libraries providing
           common functionality to the other packages.

           ltp (Licklider Transmission Protocol), a core DTN protocol that provides transmission reliability
           based on delay-tolerant acknowledgments, timeouts, and retransmissions.

           bp (Bundle Protocol), a core DTN protocol that provides delay-tolerant forwarding of data through a
           network in which continuous end-to-end connectivity is never assured, including support for delay-
           tolerant dynamic routing.  The Bundle Protocol (BP) specification is defined in Internet RFC 5050.

           dgr (Datagram Retransmission), a library that enables data to be transmitted via UDP with reliability
           comparable to that provided by TCP.  DGR is an alternative implementation of LTP, designed for use
           within an internet.

           ams (Asynchronous Message Service), cfdp (CCSDS File Delivery Protocol), and bss (Bundle Streaming
           Service), application-layer services that are not part of the DTN architecture but utilize underlying
           DTN protocols.

       Taken together, the packages included in the ION software distribution constitute a communication
       capability characterized by the following operational features:

           Reliable conveyance of data over a DTN, i.e., a network in which it might never be possible for any
           node to have reliable information about the detailed current state of any other node.

           Built on this capability, reliable distribution of short messages to multiple recipients
           (subscribers) residing in such a network.

           Management of traffic through such a network.

           Facilities for monitoring the performance of the network.

           Robustness against node failure.

           Portability across heterogeneous computing platforms.

           High speed with low overhead.

           Easy integration with heterogeneous underlying communication infrastructure, ranging from Internet to
           dedicated spacecraft communication links.

       While most of the ici package consists of libraries providing functionality that may be of general
       utility in any complex embedded software system, the functions and macros described below are
       specifically designed to support operations of ION's delay-tolerant networking protocol stack.

       TIMESTAMPBUFSZ
           This  macro  returns the recommended size of a buffer that is intended to contain a timestamp in ION-
           standard format:

               yyyy/mm/dd-hh:mm:ss

       int ionAttach()
           Attaches the invoking task to ION infrastructure as previously established by  running  the  ionadmin
           utility program on the same computer.  Returns zero on success, -1 on any error.

       void ionDetach()
           Detaches  the  invoking  task  from ION infrastructure.  In particular, releases handle allocated for
           access to ION's non-volatile database.  NOTE,  though,  that  ionDetach()  has  no  effect  when  the
           invoking  task  is  running  in  a  non-memory-protected  environment, such as VxWorks, where all ION
           resource access variables are shared by all tasks: no single task could detach without  crashing  all
           other ION tasks.

       void ionProd(uvast fromNode, uvast toNode, unsigned int xmitRate, unsigned int owlt)
           This  function  is  designed to be called from an operating environment command or a fault protection
           routine, to enable operation of a node to resume when all of its scheduled contacts are in  the  past
           (making  it  impossible  to use a DTN communication contact to assert additional future communication
           contacts).  The function asserts a single new unidirectional  contact  conforming  to  the  arguments
           provided,  including the applicable one-way light time, with start time equal to the current time (at
           the moment of execution of the function) and end time equal to the start  time  plus  2  hours.   The
           result  of executing the function is written to the ION log using standard ION status message logging
           functions.

           NOTE that the  ionProd()  function  must  be  invoked  twice  in  order  to  establish  bidirectional
           communication.

       void ionClear(char *srcEid, char *destEid, char *blockType)
           This  function  is  designed to be called from an operating environment command or a fault protection
           routine, to delete some or all of ION's Bundle Security  Protocol  rules  when  they  are  preventing
           nominal authorized operation of a node.  If the first character of blockType is '~' then the function
           applies  to  rules  for  all types of BSP block; otherwise it applies only to rules for the named BSP
           block type: "bab", "pib", "pcb", or "esb".  Only rules whose security source EIDs  match  srcEid  and
           whose  security  destination  EIDs match destEid are deleted.  A rule EID matches a "clearing" EID if
           (a) every character of the clearing EID prior to the first '~' in the clearing ID (if any)  is  equal
           to the corresponding character of the rule EID and either the first '~' character in the clearing EID
           is the clearing EID's last character or else the rule EID and clearing EID are of equal length.

       Object ionCreateZco(ZcoMedium source, Object location, vast offset, vast length, int *control)
           This  function  provides a "blocking" implementation of admission control in ION.  Like zco_create(),
           it constructs a zero-copy object (see zco(3)) that contains a single extent of source  data  residing
           at  location  in  source,  of  which the first offset bytes are omitted and the next length bytes are
           included.  But unlike zco_create(), ionCreateZco() will block (rather than return an immediate  error
           indication) so long as the total amount of space in source that is available for new ZCO formation is
           less  than length.  ionCreateZco() returns when either (a) space has become available and the ZCO has
           been created, in which case the location of the ZCO is returned, or (b) the function has  failed  (in
           which   case   ((Object)   -1)   is   returned),   or   (c)   the   function   was   interrupted   by
           ionCancelZcoSpaceRequest() before space for the ZCO became available (in which case 0 is returned).

           ionCreateZco() is interruptible if and only if a non-NULL value of control is passed to it;  in  that
           case,  passing  the  same  value of control to the ionCancelZcoSpaceRequest() function will interrupt
           ionCreateZco().  Note that the integer variable referenced by control functions as a private ION work
           area; its content need not be initialized -- and must not be  altered  --  by  the  application.   Be
           careful  when  referencing  a dynamic variable in control; static variables are safer.  If control is
           NULL then ionCreateZco() is not interruptible by the application.

       vast ionAppendZcoExtent(Object zco, ZcoMedium source, Object location, vast offset, vast length, int
       *control)
           Similar to ionCreateZco() except that instead of creating a new ZCO it appends an  additional  extent
           to an existing ZCO. Returns -1 on failure, 0 on interruption by ionCancelZcoSpaceRequest(), length on
           success.

       void ionCancelZcoSpaceRequest(int *control)
           This   function   simply   interrupts   the   currently   blocked  invocation  of  ionCreateZco()  or
           ionAppendZcoExtent() that cites the same control value.  ionCancelZcoSpaceRequest() is intended to be
           called from a signal handler, so that a signal can be used to cleanly  terminate  a  thread  that  is
           waiting for an opportunity to create a new ZCO source data extent.

       Sdr getIonsdr()
           Returns  a  pointer to the SDR management object, previously acquired by calling ionAttach(), or zero
           on any error.

       PsmPartition getIonwm()
           Returns a pointer to the ION working memory partition, previously acquired by calling ionAttach(), or
           zero on any error.

       int getIonMemoryMgr()
           Returns the memory manager ID for operations on ION's working memory partition,  previously  acquired
           by calling ionAttach(), or -1 on any error.

       int ionLocked();
           Returns  1  if  the  calling  task is the owner of the current SDR transaction.  Assuring that ION is
           locked while related critical operations  are  performed  is  essential  to  the  avoidance  of  race
           conditions.

       uvast getOwnNodeNbr()
           Returns  the  Bundle  Protocol  node  number  identifying  this  computer,  as  declared when ION was
           initialized by ionadmin.

       time_t getUTCTime()
           Returns the current UTC time, as computed from local clock time and  the  computer's  current  offset
           from  UTC  (due  to  clock  drift,  not  due  to  time zone difference; the utcdelta) as managed from
           ionadmin.

       int ionClockIsSynchronized()
           Returns 1 if the computer on which the local ION node is running has a synchronized clock ,  i.e.,  a
           clock  that reports the current UTC time as a value that differs from the correct time by an interval
           approximately equal to the currently asserted offset from  UTC  due  to  clock  drift;  returns  zero
           otherwise.

           If  the  machine's  clock  is synchronized then its reported values (as returned by getUTCTime()) can
           safely be used as the creation times of new bundles and the expiration time  of  such  a  bundle  can
           accurately  be  computed as the sum of the bundle's creation time and time to live.  If not, then the
           creation timestamp time of new bundles sourced at the local ION node must be zero  and  the  creation
           timestamp sequence numbers must increase monotonically forever, never rolling over to zero.

       void writeTimestampLocal(time_t timestamp, char *timestampBuffer)
           Expresses  the  time  value in timestamp as a local timestamp string in ION-standard format, as noted
           above, in timestampBuffer.

       void writeTimestampUTC(time_t timestamp, char *timestampBuffer)
           Expresses the time value in timestamp as a UTC timestamp string  in  ION-standard  format,  as  noted
           above, in timestampBuffer.

       time_t readTimestampLocal(char *timestampBuffer, time_t referenceTime)
           Parses  the  local  timestamp  string in timestampBuffer and returns the corresponding time value (as
           would be returned by time(2)), or zero if the timestamp string cannot be  parsed  successfully.   The
           timestamp  string  is  normally  expected  to be an absolute expression of local time in ION-standard
           format as noted above.  However, a relative time expression variant is also supported: if  the  first
           character  of  timestampBuffer  is  '+' then the remainder of the string is interpreted as a count of
           seconds; the sum of this value and the time value in referenceTime is returned.

       time_t readTimestampUTC(char *timestampBuffer, time_t referenceTime)
           Same as readTimestampLocal() except that if timestampBuffer is not a relative time expression then it
           is interpreted as an absolute expression of UTC time in ION-standard format as noted above.

STATUS MESSAGES

ION uses writeMemo(), putErrmsg(), and putSysErrmsg() to log several different types of standardized
status messages.

Informational messages
These messages are generated to inform the user of the occurrence of events that are nominal but
significant, such as the controlled termination of a daemon or the production of a congestion
forecast. Each informational message has the following format:

{yyyy/mm/dd hh:mm:ss} [i] text

Warning messages
These messages are generated to inform the user of the occurrence of events that are off-nominal but
are likely caused by configuration or operational errors rather than software failure. Each warning
message has the following format:

{yyyy/mm/dd hh:mm:ss} [?] text

Diagnostic messages
These messages are produced by calling putErrmsg() or putSysErrmsg(). They are generated to inform
the user of the occurrence of events that are off-nominal and might be due to errors in software.
The location within the ION software at which the off-nominal condition was detected is indicated in
the message:

{yyyy/mm/dd hh:mm:ss} at line nnn of sourcefilename, text (argument)

Note that the argument portion of the message (including its enclosing parentheses) will be provided
only when an argument value seems potentially helpful in fault analysis.

Bundle Status Report (BSR) messages
A BSR message informs the user of the arrival of a BSR, a Bundle Protocol report on the status of
some bundle. BSRs are issued in the course of processing bundles for which one or more status report
request flags are set, and they are also issued when bundles for which custody transfer is requested
are destroyed prior to delivery to their destination endpoints. A BSR message is generated by
ipnadminep upon reception of a BSR. The time and place (node) at which the BSR was issued are
indicated in the message:

{yyyy/mm/dd hh:mm:ss} [s] (sourceEID)/creationTimeSeconds:counter/fragmentOffset status flagsByte
at time on endpointID, 'reasonString'.

Communication statistics messages
A network performance report is a set of eight communication statistics messages, one for each of
eight different types of network activity. A report is issued every time contact transmission or
reception starts or stops, except when there is no activity of any kind on the local node since the
prior report. When a report is issued, statistic messages are generated to summarize all network
activity detected since the prior report, after which all network activity counters and accumulators
are reset to zero.

NOTE also that the bpstats utility program can be invoked to issue an interim network performance
report at any time. Issuance of interim status reports does not cause network activity counters and
accumulators to be reset to zero.

Statistics messages have the following format:

{yyyy/mm/dd hh:mm:ss} [x] xxx from tttttttt to TTTTTTTT: (0) aaaa bbbbbbbbbb (1) cccc dddddddddd
(2) eeee ffffffffff (+) gggg hhhhhhhhhh

xxx indicates the type of network activity that the message is reporting on. Statistics for eight
different types of network activity are reported:

src This message reports on the bundles sourced at the local node during the indicated interval.

fwd This message reports on the bundles forwarded by the local node. When a bundle is re-forwarded
due to custody transfer timeout it is counted a second time here.

xmt This message reports on the bundles passed to the convergence layer protocol(s) for transmission
from this node. Again, a re-forwarded bundle that is then re-transmitted at the convergence
layer is counted a second time here.

rcv This message reports on the bundles from other nodes that were received at the local node.

dlv This message reports on the bundles delivered to applications via endpoints on the local node.

ctr This message reports on the custody refusal signals received at the local node.

rfw This message reports on bundles for which convergence-layer transmission failed at this node,
causing the bundles to be re-forwarded.

exp This message reports on the bundles destroyed at this node due to TTL expiration.

tttttttt and TTTTTTTT indicate the start and end times of the interval for which statistics are being
reported, expressed in yyyy/mm/dd-hh:mm:ss format. TTTTTTTT is the current time and tttttttt is the
time of the prior report.

Each of the four value pairs following the colon (:) reports on the number of bundles counted for the
indicated type of network activity, for the indicated traffic flow, followed by the sum of the sizes
of the payloads of all those bundles. The four traffic flows for which statistics are reported are
"(0)" the priority-0 or "bulk" traffic, "(1)" the priority-1 "standard" traffic, "(2)" the priority-2
"expedited" traffic, and "(+)" the total for all classes of service.

Free-form messages
Other status messages are free-form, except that date and time are always noted just as for the
documented status message types.

NAME

SYNOPSIS

DESCRIPTION

STATUS MESSAGES

SEE ALSO