April 17, 1998

This section provides a more detailed description of Earthworm structure and features. Two examples are used to present a number of concepts in increasing level of detail.

Example 1

Diagram 1 shows a very simple construction to illustrate the basic concepts. The circle in the diagram represents a message ring, and the rectangles represent modules. Each module can establish linkages to message ring(s) via its configuration file. A module may specify one input ring, from which it can receive desired message types, and one output ring into which it may broadcast its output messages. These linkages are represented in the diagram by the arrows to and from the single message ring.

Briefly, this system would function as follows: The system is started by executing the program startstop. Its job is to create the message ring(s) and start the modules. It does this by reading its configuration file (startstop.d), which lists the ring(s) to be created, the modules to be started, and the configuration files each module will read. As each module starts, it reads its configuration file, which specifies the identity of the instance of that module (in case several copies of a module are desired), the names of the message rings the module is to use for input and output, and any other module-specific parameters.

adsend is a digitizer module which controls an A/D converter, and outputs trace data messages. pick_ew is the Rex Allen picking algorithm that listens to trace data messages, and produces pick- and coda-messages. binder_ew listens to pick messages and produces trial location messages. eqproc consists of a number of sub-modules which pre-process binder_ews trial locations, and run hypo-inverse. The output of eqproc is a message containing the hypo-inverse arc output. menlo_report listens to arc messages, and passes them to remote computer(s) for further processing.

Example 2

Diagram 2 shows a simplified version of the configuration in operation at University of Washington, Seattle. Several key features have been omitted for the purpose of this example.

Note that multiple message rings are used. There are two main reasons for this. One is conceptual: the configuration is easier to understand and maintain if different rings are used to carry related types of messages (and the diagram is easier to draw). The other is performance related: if the rate of message production into a single ring is too high, the computer may be unable to run all receiving modules quickly enough, with the result that some modules may miss messages of interest (note that this is a detectable error, and constitutes a system crash). Given contemporary processor speeds, this is generally no longer a problem. Missed messages do indicate that the hardware is being severely over-driven.

Internal names: Earthworm uses names to identify four types of system components. Each set is defined by a table of names and associated numeric values. In operation, the user creates the desired entries in these tables, and then uses the names in the configuration files. At run time, utilities are used to resolve the names to their respective numeric values. The four categories of names are:

The modules copystatus and statmgr are part of the earthworm error-processing scheme. The scheme offers two services: detection of lost heartbeats and individualized processing of various errors. Such processing includes use of pagers, email, permissible rates, limiting the number of notifications, and restarting the offending module. The scheme is optional in two ways: First, a given earthworm configuration may choose to not run statmgr. In this case, no system-wide error processing will be performed. Second, if statmgr is run, each module can decide whether to utilize the scheme. To participate, a module must do three things:

This configuration has three sources of trace data, all of which broadcast into a message ring named Wave_Ring:

The trace data messages must be in the standard internal Earthworm format, as described in .../src/include/trace_buf.h. Briefly, this format consists of a header followed by a variable number of data samples, represented as either 16 or 32 bit signed integers in either byte order. This format supports two channel identification schemes: The dominant scheme consists of three ASCII strings defining the 'station', 'component', and 'network' (SCN names). The second is the 'pin number'. This is an integer that can be used to identify the sensor and signal path of a channel. It addresses the case where a given sensor is acquired by two different telemetry paths. It also provides support for processing data from sensors that do not have SCN names.

Four modules listen to the messages on the Wave_Ring:

Three modules listen to the messages on Pick_Ring: Three modules listen to the messages on Hypo_Ring:

Return to the Earthworm Table of Contents Page.

Questions? Issues? Subscribe to the Earthworm Google Groups List.