ici::doc::pod3::ion(3) ICI library functions ici::doc::pod3::ion(3)
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.
ams (Asynchronous Message Service) and cfdp (CCSDS File Delivery Protocol), 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(unsigned long fromNode, unsigned long toNode, unsigned long 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.
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.
unsigned long 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) as managed from ionadmin.
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.
ctt This message reports on the custodial bundles for which convergence-layer transmission failed at this node, nominally 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 as a number
of seconds since the start of the DTN epoch. 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" non-administrative traffic, "(1)" the priority-1 non-
administrative traffic, "(2)" the priority-2 "expedited" non-administrative traffic, and "(@)" all administrative traffic regardless of
priority.
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.
SEE ALSO
ionadmin(1), rfxclock(1), bpstats(1), llcv(3), lyst(3), memmgr(3), platform(3), psm(3), sdr(3), zco(3), ltp(3), bp(3), AMS Programmer's
Guide
perl v5.14.2 2012-05-25 ici::doc::pod3::ion(3)