Changes between Version 1 and Version 2 of ringtocoaxII


Ignore:
Timestamp:
03/18/12 19:24:13 (9 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ringtocoaxII

    v1 v2  
    3333This module does connection-less broadcasts. In normal usage, it broadcasts onto an isolated, dedicated class b subnet. There must be no routing to or from that subnet. The broadcast is restricted to the subnet specified in the configuration file. Note that the companion module, coaxtoring, has strange system-specific addressing requirements. 
    3434 
     35 
     36 
     37NB: This was updated with the ringtocoaxII.d file, but the commands were not updated. Note the new INPUT QUEUE commands and the Min/MaxPacketsPerBurst commands in red font below in the .d file example. 
     38 
     39On startup, ringtocoaxII reads the configuration file named on the command line. Commands in this file set up all parameters used in reading Earthworm messages from shared memory and broadcasting them onto ethernet as UDP packets. In the control file, lines may begin with a valid ringtocoaxII command (listed below) or with one of 2 special characters: 
     40{{{ 
     41#  marks the line as a comment (example: # This is a comment). 
     42    
     43@  allows control files to be nested; one control file can be  
     44   accessed from another with the command "@" followed by  
     45   a string representing the path name of the next control file  
     46   (example: @model.d). 
     47}}} 
     48Command names must be typed in the control file exactly as shown in this document (upper/lower case matters!). 
     49 
     50=== EXAMPLE CONFIGURATION FILE === 
     51{{{ 
     52# 
     53#This is RingtocoaxII's parameter file 
     54# 
     55# This program gets earthworm messages from a transport ring and broadcasts 
     56# them to ethernet. 
     57# 
     58#       *** WARNING *** 
     59#       This module does connection-less broadcasts. 
     60#       In normal usage, it broadcasts onto an isolated, dedicated class b 
     61#       subnet. There must be no routing to or from that subnet. 
     62#       The broadcast is restricted to that subnet as stated below. 
     63#       Note that the companion module, coaxtoring, has strange 
     64#       system-specific addressing requirements 
     65 
     66# General Info 
     67MyModuleId        MOD_RINGTOCOAX   # Module id for this instance of ringtocoax 
     68RingName          WAVE_RING        # Shared memory ring for input/output 
     69HeartBeatInterval 30               # Seconds between heartbeats 
     70LogSwitch         1                # If 0, turn off disk log file 
     71                                   # If 1, log to disk file and stderr/stdout 
     72                                   # If 2, log only disk file 
     73Debug             1                # If 1, print Adaptive PacketsPerBurst info 
     74                                   # If 2, also print message logos on screen 
     75                                   # If 0, don't print debug info. 
     76                                   # NOTE: Logging logos / Adaptive info to disk can  
     77                                   # slow down RingtocoaxII's performance.  Debug 
     78                                   # should only be used for troubleshooting. 
     79                                   # OPTIONAL, defaults to 0. 
     80# Message Settings 
     81MsgMaxBytes       4096             # Size of biggest message to be sent 
     82CopyStatus        0                # If 0, don't pass heartbeats, errors, or restarts.   
     83                                   # If 1, pass them. 
     84MaxLogo           256              # Maximum number of logos we can handle 
     85                                   # Set to a number >= 0 
     86# List each logo that you want to broadcast in a BroadcastLogo command. 
     87# If the BroadcastLogo is omitted, all messages in RingName will be shipped. 
     88#               installation   module_id     message_type  
     89#               ------------   ---------     ------------ 
     90BroadcastLogo   INST_WILDCARD  MOD_WILDCARD  TYPE_TRACEBUF 
     91 
     92# Network Settings 
     93OutAddress        192.168.14.255   # IP address of net to broadcast to. 
     94                                   # Set the node number to 255 
     95                                   # eg. OutAddress    192.168.4.255 
     96OutPortNumber     10001            # The well-known port number to broadcast on. 
     97                                   # Note: Under Solaris, if the port number is at or below  
     98                                   #       1024, ringtocoax must run as root. 
     99# Queue Settings 
     100InputQueueLen       1000           # The Desired Size of the Input Queue in Messages, 
     101                                   # Note: Actual size is InputQueueLen-1. 
     102QueueOptimumPercent 10             # Optimum queue level in percent.  Used to determine  
     103                                   # percent excedence.  OPTIONAL, defaults to 10 
     104ExcedenceConstant   1              # Constant to multiply the percent excedence by to control 
     105                                   # how much the desired excedence rate can change. 
     106                                   # OPTIONAL, defaults to 1. 
     107STAInterval         1.5            # Interval in seconds over which the short term average 
     108                                   # of the queue height is computed.  
     109                                   # OPTIONAL, defaults to 1.5. 
     110QueueReportInt    20             # Seconds between queue size reports 
     111                                   # OPTIONAL, defaults to 300 seconds. 
     112# Data Export Rate Settings 
     113MaxPacketsPerBurst  200            # Maximum allowed Number of packets per burst the reciver  
     114                                             # can send 
     115MinPacketsPerBurst  10             # Minmum allowed Number of packets per burst the reciver 
     116                                             # can send. OPTIONAL, defaults to 1. 
     117SqrtCount           2000           # Number of square roots between packets within a burst. 
     118BurstInterval       10             # Sleep this many msec between bursts 
     119ThroughputReportInt 20             # Seconds between throughput reports 
     120                                   # OPTIONAL, defaults to 300 seconds. 
     121}}} 
     122 
     123=== FUNCTIONAL COMMAND LISTING === 
     124Below are the commands recognized by ringtocoax, grouped by the function they influence. All of the commands are required; they must be specified in the control file in order for ringtocoax to operate. 
     125{{{ 
     126         Earthworm system setup: 
     127                HeartBeatInterval       required 
     128                MyModName               required 
     129                RingName                required 
     130 
     131        Network Information: 
     132                OutAddress              required 
     133                OutPortNumber           required 
     134 
     135        Message Handling: 
     136                CopyStatus              required 
     137                MaxLogo                 required 
     138                MsgMaxBytes             required 
     139                BurstInterval           required 
     140                BurstCount              required 
     141                SqrtCount               required 
     142                BroadcastLogo 
     143 
     144        Output Control: 
     145                ScrnMsg                 required 
     146                LogSwitch               required 
     147}}} 
     148 
     149=== ALPHABETIC COMMAND LISTING & DESCRIPTION === 
     150 
     151In 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. 
     152 
     153The following list is organized by: 
     154 
     155command [argument here] 
     156 
     157 
     158 
     159'''!BroadcastLogo [instid  modid  msgtype]'''[[BR]] 
     160Processed by: ringtocoax_config[[BR]] 
     161Function: msg handling           
     162 
     163Specifies one message logo (instid, modid, and msgtype) to read from the shared memory region (named in the "!RingName" command) and to broadcast onto ethernet. The instid must be a valid string in earthworm.h; modid and msgtype must be valid strings in earthworm.d. List one logo per "!BroadcastLogo" command, and use as many commands as needed. If msgtype is TYPE_HEARTBEAT or TYPE_ERROR, be sure that the CopyStatus value is non-zero. If no "!BroadcastLogo" command is given, ringtocoax defaults to broadcasting all messages in the designated shared memory region. 
     164{{{ 
     165Example:  BroadcastLogo INST_MENLO MOD_WILDCARD TYPE_TRACEBUF 
     166}}}  
     167 
     168'''!BurstCount [!BurstCount]'''[[BR]] 
     169Processed by: ringtocoax_config[[BR]] 
     170Function: msg handling 
     171                 
     172Defines the number of UDP packets, !BurstCount, in a broadcast "burst". Three commands, "!BurstCount", "!SqrtCount", and "!BurstInterval", control the temporal spacing of UDP packets broadcast by ringtocoax. Ringtocoax broadcasts messages in groups of BurstCount packets; between the packets within a "burst", ringtocoax loops thru !SqrtCount square root calculations to waste a little time. After broadcasting a "burst" of packets, ringtocoax sleeps for BurstInterval milliseconds, then it starts sending the next burst. The goal of spacing packets a tiny bit in time is to give the receiving program a better chance of catching every packet. 
     173 
     174UDP packets are variable in length up to a maximum of 1472 bytes (6 bytes of header, 1466 bytes of data). If an Earthworm message has a length less than or equal to 1466 bytes, it will be broadcast in a single UDP packet. If an Earthworm message is longer than 1466 bytes, it will be fragmented by ringtocoax, broadcast in multiple UDP packets, and reassembled by the receiving program (coaxtoring). Ringtocoax will never pack more than one Earthworm message in a single UDP packet. 
     175 
     176It is very important that the overall rate of broadcast is as at least as fast as the rate of local information production. For example, if your system produces 256 TYPE_TRACEBUF messages per second (464 bytes each = 1 UDP packet each), then the !BurstCount, !SqrtCount, and !BurstInterval commands should be configured such that ringtocoax will broadcast at least 256 UDP packets per second. System clock resolution must be considered when configuring the three commands, especially !BurstInterval. As of April 1999, the time resolution of each sleep on Windows NT is about 16 msec (one clock tick). On Solaris, the resolution is about 10 msec. 
     177{{{ 
     178Default:  none 
     179Example:  BurstCount 3 
     180}}} 
     181 
     182'''!BurstInterval [!BurstInterval]'''[[BR]] 
     183Processed by: ringtocoax_config[[BR]] 
     184Function: msg handling           
     185 
     186Defines the minimum interval, in milliseconds, between "bursts" of UDP broadcasts. See the !BurstCount command for a detailed description of ringtocoax's broadcasting scheme. !BurstInterval must be a number greater than or equal to zero. Remember to consider the system clock resolution when configuring BurstInterval. As of April 1999, the clock-tick resolution is about 16 msec on Windows NT, and about 10 msec on Solaris. 
     187{{{ 
     188Default:  none 
     189Example:  BurstInterval 10 
     190}}} 
     191  
     192'''!CopyStatus [!CopyStatus]'''[[BR]] 
     193Processed by: ringtocoax_config[[BR]] 
     194Function: msg handling 
     195 
     196Sets the !CopyStatus switch to control whether ringtocoax broadcasts TYPE_ERROR and TYPE_HEARTBEAT messages. If no "!BroadcastLogo" command is present, then ringtocoax will default to reading all messages in the shared memory region specified by the "!RingName" command. If !CopyStatus is non-zero, all of these messages will be broadcast onto ethernet. If CopyStatus is 0, TYPE_HEARTBEAT and TYPE_ERROR will not be broadcast, but all other messages will. 
     197{{{ 
     198Default:  none 
     199Example:  CopyStatus 0 
     200}}} 
     201 
     202'''!HeartBeatInterval [nsec]'''[[BR]] 
     203Processed by: ringtocoax_config[[BR]] 
     204Function: Earthworm setup 
     205         
     206Defines the number of seconds nsec between TYPE_HEARTBEAT messages issued by ringtocoax. 
     207{{{ 
     208Default:  none                           
     209Example:  HeartBeatInterval 15 
     210}}} 
     211 
     212'''!LogSwitch [switch]'''[[BR]] 
     213Processed by: ringtocoax_config[[BR]] 
     214Function: output         
     215         
     216Sets 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, ringtocoax will write a daily log file(s) called ringtocoaxxx.log_ccyymmdd where xx is ringtocoax's module id (set with "!MyModName" command) and ccyymmdd is the current UTC date (ex: 19990123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
     217{{{ 
     218Default:  none 
     219}}} 
     220 
     221'''!MaxLogo [nlogo]'''[[BR]] 
     222Processed by: ringtocoax_config[[BR]] 
     223Function: msg handling           
     224 
     225Sets the maximum number, nlogo, of different message logos that ringtocoax can process. Ringtocoax assigns a sequence number (unsigned char) to each message based on its logo before it broadcasts the message. Space is allocated to store the last sequence number used for up to nlogo different logos. If the tracking arrays are full and ringtocoax gets a never-seen-before message logo from shared memory, ringtocoax will not broadcast that message, but it will issue a TYPE_ERROR message explaining the problem. 
     226{{{ 
     227Default:  none 
     228Example:  MaxLogo 256 
     229}}} 
     230 
     231'''!MsgMaxBytes [nbytes]'''[[BR]] 
     232Processed by: ringtocoax_config[[BR]] 
     233Functio: msg handling 
     234 
     235Sets the size, in bytes, of the buffer that ringtocoax uses for storing Earthworm messages read from shared memory. nbytes should be the size of the largest message you expect ringtocoax to receive. If ringtocoax receives a message larger than nbytes, it will drop the entire message and issue a TYPE_ERROR message containing the string "too big for Buffer" and the logo of the dropped message. 
     236{{{ 
     237Default:  none 
     238Example:  MsgMaxBytes 51740 
     239}}} 
     240 
     241'''!MyModName [mod_id]'''[[BR]] 
     242Processed by: ringtocoax_config[[BR]] 
     243Function: Earthworm setup 
     244         
     245Sets 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 ringtocoax receives from shared memory are tagged with their original logos when they are broadcast onto ethernet. 
     246{{{ 
     247Default:  none                           
     248Example:  MyModName MOD_RINGTOCOAX 
     249}}} 
     250 
     251'''!OutAddress [a.b.c.d]'''[[BR]] 
     252Processed by: ringtocoax_config[[BR]] 
     253Function: network info           
     254 
     255Tells ringtocoax the TCP/IP address of the ethernet line onto which it should broadcast Earthworm messages. a.b.c.d is a character string in tcp/ip's standard dotted-decimal notation that ringtocoax uses along with the port number from the "!OutPortNumber" command to set up a socket to which it will broadcast UDP Datagram packets. By convention, all Earthworm broadcasts have the node ("d" part of address) set to 255 (for example a.b.c.255). 
     256{{{ 
     257Default:  none                   
     258Example:  OutAddress 192.168.4.255 
     259}}} 
     260 
     261'''!OutPortNumber [port]'''[[BR]] 
     262Processed by: ringtocoax_config[[BR]] 
     263Function: network info 
     264 
     265Defines the well-known port number port to be used by ringtocoax for broadcasting. port is an integer that ringtocoax uses along with the address from the "!OutAddress" command to set up a socket to which it will broadcast UDP Datagram packets.  
     266 
     267NOTE: The port number must be greater than 1024. Smaller port numbers require root permission. 
     268{{{ 
     269Default:  none 
     270Example:  OutPortNumber 2025 
     271}}} 
     272 
     273'''!RingName [ring]'''[[BR]] 
     274Processed by: ringtocoax_config[[BR]] 
     275Function: Earthworm setup        
     276         
     277Tells ringtocoax which shared memory region to use for input/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 ringtocoax reads from shared memory are tagged with their original logos when they are broadcast onto ethernet. 
     278{{{ 
     279Default:  none                           
     280Example:  RingName WAVE_RING 
     281}}} 
     282 
     283'''!ScrnMsg [switch]'''[[BR]] 
     284Processed by: ringtocoax_config[[BR]] 
     285Function: output 
     286 
     287Sets 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 broadcast to ethernet. If switch is 0, no messages are written to the screen. 
     288{{{ 
     289Default:  none 
     290Example:  ScrnMsg 0 
     291}}} 
     292 
     293'''!SqrtCount [!SqrtCount]'''[[BR]] 
     294Processed by: ringtocoax_config[[BR]] 
     295Function: msg handling 
     296                 
     297Defines the number of square root calculations ringtocoax performs between broadcasting each UDP packet of a "burst." See the !BurstCount command for a detailed description of ringtocoax's broadcasting scheme. !SqrtCount must be an integer greater than or equal to zero. 
     298{{{ 
     299Default:  none 
     300Example:  SqrtCount 2000 
     301}}} 
     302 
    35303== Helpful Hints ==