wiki:coaxtoring
Last modified 9 years ago Last modified on 05/02/12 09:28:50

Earthworm Module: coaxtoring

Contributed by:

Function

Reads EARTHWORM messages from Ethernet and places them into shared memory. This program copies Earthworm messages from Ethernet to local shared memory (known as a "transport ring"). Incoming messages may be of any installation id, message type, and module id, but they must have the same port number, specified in the configuration file. The program has three threads. The first thread (MsgIn) collects packets and assembles them into messages. The second thread writes messages to the transport shared memory ring buffer. The third thread generates heartbeat messages. Messages are transferred without translation of any kind.

Details

Configuration File Commands

On startup, coaxtoring reads the configuration file named on the command line. Commands in this file set up all parameters used in receiving UDP broadcast Earthworm messages from the network and placing them into shared memory. In the control file, lines may begin with a valid coaxtoring command (listed below) or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).

@  allows control files to be nested; one control file can be
   accessed from another with the command "@" followed by
   a string representing the path name of the next control file
   (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!).

EXAMPLE CONFIGURATION FILE

#
#
# coaxtoring configuration file
#
#   The setup is different for Solaris and NT. The specified address
#   will be used to receive class c subnet broadcasts.
#
# Solaris:    InAddress must be of the form xxx.xxx.xxx.255
# Windows NT: InAddress must be the complete local address, eg
#             192.168.4.107
#
MyModuleId   MOD_COAXTORING_A   # Module id for this process
RingName     WAVE_RING          # Write to this shared memory region
LogFile      1                  # 1=write log file on disk; 0=don't
                                # 2=write to module log but not stderr/stdout
nMsgBuf      16                 # There should be at least one buffer per logo
MsgMaxBytes  51740              # Size of biggest message to be received
InAddress    192.168.4.255      # IP address of ethernet line to read

PortNumber   990                # Usually 990 (waveforms) or 5555 (picks)
                                # Under Solaris, if the port number is at
                                #  or below 1024, the program must run as root.

ScrnMsg      1                  # 1=print messages on screen; 0=don't
HeartbeatInt 30                 # Heartbeat interval in seconds
BufferReportInt 300             # Print high buffer count every n seconds

RcvBufSize   260000             # Size of socket receive buffer, in bytes.
                                # Set RcvBufSize to a large number to avoid
                                #   dropping packets.
                                # Max value is system dependent
                                #  (typically 260000)
                                # If you set =0, it will default to the
				        # system default. (typically 8192)

FUNCTIONAL COMMAND LISTING

Below are the commands recognized by coaxtoring, grouped by the function they influence. All of the commands are required; they must be specified in the control file in order for coaxtoring to operate.

        Earthworm system setup:
		HeartBeatInt 	 	required
 		MyModuleId	   	required
		RingName	   	required

	Network Information:
		InAddress	   	required
		PortNumber	   	required

	Message Handling:
		nMsgBuf	   		required
		MsgMaxBytes	   	required
		RcvBufSize	   	required

	Output Control:
		ScrnMsg	   		required
		LogFile		   	required
		BufferReportInt   	required

ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

The following list is organized by:

command [argument here]

BufferReportInt [nbytes]
Processed by: coaxtoring_config
Function: msg handling

Print high buffer count every n seconds

Default:  none
Calnet:   BufferReportInt 300

HeartBeatInt [nsec]
Processed by: coaxtoring_config
Function: Earthworm setup

Defines the number of seconds nsec between TYPE_HEARTBEAT messages issued by coaxtoring.

Default:  none
Calnet:   HeartBeatInt 5

InAddress [a.b.c.d]
Processed by: coaxtoring_config
Function: network info

Tells coaxtoring the TCP/IP address of the ethernet line that it should listen to. a.b.c.d is a character string in tcp/ip's standard dotted-decimal notation that coaxtoring uses along with the port number from the "PortNumber" command to set up a socket from which it will receive UDP Datagram packets. Under Solaris, the "d" part of the address should be set to 255 (for example a.b.c.255). Under NT, the "d" part of the address should be set to the complete local address, eg 192.168.4.107.

Default:  none
Example:  InAddress 130.118.49.255 (Solaris)
Example:  InAddress 192.168.4.107 (NT)

LogFile [switch]
Processed by: coaxtoring_config
Function: output

Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is 1, coaxtoring will write a daily log file(s) called coaxtoringxx.log_yymmdd where xx is coaxtoring's module id (set with "MyModuleId" command) and yymmdd is the current UTC date (ex: 960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable).

Default:  none

MsgMaxBytes [nbytes]
Processed by: coaxtoring_config
Function: msg handling

Sets the size, in bytes, of the working buffers that coaxtoring uses for rebuilding complete Earthworm messages out of the UDP packets. nbytes should be the size of the largest message you expect coaxtoring to receive. If coaxtoring receives a message larger than nbytes, it will drop the entire message and issue a TYPE_ERROR message containing the string "Message buffer overflow" and the logo of the dropped message.

Default:  none
Calnet:   MsgMaxBytes 51740

MyModuleId [mod_id]
Processed by: coaxtoring_config
Function: Earthworm setup

Sets the module id for labeling all outgoing heartbeat and error messages. mod_id is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique single-byte number. All messages that coaxtoring receives from ethernet are tagged with their original logos when they are placed into shared memory.

Default:  none
Calnet:   MyModuleId MOD_COAXTORING

nMsgBuf [nbuf]
Processed by: coaxtoring_config
Function: msg handling

Defines the number of working buffers nbuf that coaxtoring should allocate. Coaxtoring uses the buffers for rebuilding complete Earthworm messages out of the UDP packets it receives from ethernet. There should be at least one buffer for each different message logo that coaxtoring might see. The maximum allowed number of buffers is controlled by MAX_BUF, currently defined to be 16 in coaxtoring.c. The size of each buffer is set with the "MsgMaxBytes" command.

Default:  none
Calnet:   nMsgBuf 16

PortNumber [port]
Processed by: coaxtoring_config
Function: network info

Defines the well-known port number port which coaxtoring will listen to. port is an integer that coaxtoring uses along with the address from the "InAddress" command to set up a socket from which it will receive UDP Datagram packets.

NOTE: The port number must be greater than 1024. Smaller port numbers require root permission.

Default:  none
Example:  PortNumber 2025

RcvBufSize [ring]
Processed by: coaxtoring_config
Function: Earthworm setup

Tells coaxtoring the size of the socket receive buffer, in bytes. Set RcvBufSize to a large number to avoid dropping packets. Maximum value is system dependent, typically 260000. If no buffering desired, use the system default size, typically 8192. To determine the default size, set RcvBufSize to zero. When coaxtoring is restarted, it will log a message giving you the default buffer size. The maximum size can be found by trial and error. If the value exceeds the maximum value, coaxtoring will log the message: "Error resetting receive buffer size" and exit.

Default:  none
Example:  RcvBufSize 260000

RingName [ring]
Processed by: coaxtoring_config
Function: Earthworm setup

Tells coaxtoring which shared memory region to use for output. ring is a character string (valid strings are listed in earthworm.d) that relates (in earthworm.d) to a unique number for the key to the shared memory region. All messages that coaxtoring receives from ethernet are tagged with their original logos when they are placed into shared memory.

Default:  none
Example:  RingName WAVE_RING

ScrnMsg [switch]
Processed by: coaxtoring_config
Function: output

Sets a switch for writing messages to the screen. If switch is 1, a line is printed to the screen detailing the logo and the sequence number of each Earthworm message received from the ethernet. If switch is 0, no messages are written to the screen.

Default:  none
Example:  ScrnMsg 0

Helpful Hints