gov.nasa.gsfc.drl.rtstps.core.fs
Class FrameSynchronizer

java.lang.Object
  extended by gov.nasa.gsfc.drl.rtstps.core.RtStpsNode
      extended by gov.nasa.gsfc.drl.rtstps.core.FrameSenderNode
          extended by gov.nasa.gsfc.drl.rtstps.core.fs.FrameSynchronizer
All Implemented Interfaces:
Sender, java.lang.Cloneable

public class FrameSynchronizer
extends FrameSenderNode

This class produces frames from buffers of bits, which it gives to a FrameReceiver object. It does not do CRC checking, frame inversion, or any other frame level processing. A FrameSynchronizer object is reuseable. To use, you must give it a FrameReceiver object to handle its frame output, and you must give it an setup object for configuration via the load method. You give data to it with repeated calls to putBuffer. You should call shutdown at the session's conclusion to eliminate any partial frame.


Field Summary
static java.lang.String CLASSNAME
          This is a class name for this RT-STPS node type, which is also the element name.
private  Buffer crossover
          I use the crossover buffer to hold a small fragment of the end of one buffer and the beginning of the next buffer.
private  TextStatusItem currentMode
           
private  LongStatusItem dropToSearches
           
private static int FIRST_SEARCH
          This is search mode at the very beginning of a pass for the first buffer.
private static int FLYWHEEL
          The FS is flywheeling.
private static int FLYWHEEL_SPLIT_SYNC
          This is a special split-sync scenario.
private static java.lang.String FLYWHEEL_STATUS
           
private  Flywheeler flywheeler
          This class handles all flywheeling.
private  FrameClock frameClock
          This class is the annotation timestamp clock.
private  Frames frameList
          This is where the FrameSynchronizer collects frames from a single buffer.
private  AbstractSynchronizer invertedSync
          This object handles inverted sync detection.
private  boolean isSlipped
          The current sync pattern is slipped.
private  boolean isTrueSync
          The current sync pattern is true, not inverted.
(package private) static int LOCK
          An internal state only.
private static int LOCK_SPLIT_FRAME
          Locked to sync.
private static java.lang.String LOCK_STATUS
           
private static int LOST_SYNC
          An internal state only.
private static int SEARCH
          The following parameters are FrameSynchronizer states.
private static java.lang.String SEARCH_STATUS
           
private  IntegerStatusItem searchBuffers
          The number of buffers searched without finding lock.
private  FsSetup setup
          The configuration for the current pass.
private static int SPLIT_SYNC
          The FS expects the sync pattern to be split across two buffers.
private  int state
          The current FrameSynchronizer state.
private  LongStatusItem totalFrames
          The FrameSynchronizer saves status information here.
private  AbstractSynchronizer trueSync
          This object handles true sync detection.
private  Buffer workBuffer
          I use a Buffer object to hold an input buffer.
 
Fields inherited from class gov.nasa.gsfc.drl.rtstps.core.FrameSenderNode
output
 
Fields inherited from class gov.nasa.gsfc.drl.rtstps.core.RtStpsNode
linkName, statusItemList, typeName
 
Constructor Summary
FrameSynchronizer()
          Create a Frame Synchronizer node.
 
Method Summary
private  void doFirstSearchScenario(Buffer buffer)
          The FS begins this buffer in a search state.
private  void doFlywheelScenario(Buffer buffer)
          The FS begins this buffer in a flywheel state.
private  void doLockScenario(Buffer buffer)
          In lock.
private  int doLostSync(Buffer buffer)
          The FrameSynchronizer has lost sync.
private  int doSearch(Buffer buffer)
          Search the buffer for a sync pattern beginning at its current index.
private  void doSearchScenario(Buffer buffer)
          The FS begins this buffer in a search state.
private  void doSplitSyncScenario(Buffer buffer)
          The FS begins this buffer looking for the second fragment of a sync pattern.
private  Location findSyncPattern(Buffer buffer)
          Find the first occurrence of a sync pattern in the buffer beginning at its current index but ending within X bytes of the buffer end.
 void flush()
          Flush the pipeline.
 int getFrameLength()
          Get the frame length.
 int getSyncPatternLength()
          Get the sync pattern length in bytes.
 void load(org.w3c.dom.Element element, Configuration configuration)
          Load the FrameSynchronizer with a configuration.
 void putBuffer(byte[] data, int dataLength)
          Give a buffer of bits to the FrameSynchronizer.
 void shutdown()
          End a session.
private  int verifySync(Buffer buffer)
          Verify there is sync at the current buffer index.
 
Methods inherited from class gov.nasa.gsfc.drl.rtstps.core.FrameSenderNode
addReceiver, finishSetup, setOutputIsRequired
 
Methods inherited from class gov.nasa.gsfc.drl.rtstps.core.RtStpsNode
clear, clone, getElementName, getLinkName, getStatusItems, setLinkName, toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASSNAME

public static final java.lang.String CLASSNAME
This is a class name for this RT-STPS node type, which is also the element name. It is not necessarily the link name, which is the name of one particular object.

See Also:
Constant Field Values

SEARCH

private static final int SEARCH
The following parameters are FrameSynchronizer states. In SEARCH, the FS is looking for a synchronization (sync) pattern.

See Also:
Constant Field Values

LOCK_SPLIT_FRAME

private static final int LOCK_SPLIT_FRAME
Locked to sync. The frame is split across two buffers, and the FS is waiting for the second buffer.

See Also:
Constant Field Values

SPLIT_SYNC

private static final int SPLIT_SYNC
The FS expects the sync pattern to be split across two buffers. It is waiting for the second buffer. Also see FLYWHEEL_SPLIT_SYNC.

See Also:
Constant Field Values

FLYWHEEL

private static final int FLYWHEEL
The FS is flywheeling. A "frame" is split across two buffers, and the FS is waiting for the second one.

See Also:
Constant Field Values

FLYWHEEL_SPLIT_SYNC

private static final int FLYWHEEL_SPLIT_SYNC
This is a special split-sync scenario. The FS is just coming out of flywheel, and the first sync it sees is split. In this scenario, if that sync turns out to be invalid, the FS drops to search immediately. It does not begin flywheel (again), which is what happens in the standard split-sync scenario.

See Also:
Constant Field Values

FIRST_SEARCH

private static final int FIRST_SEARCH
This is search mode at the very beginning of a pass for the first buffer. The difference is there are no "crossover" bytes that straddle buffers, which is a consideration when looking for potential split sync patterns.

See Also:
Constant Field Values

LOCK

static final int LOCK
An internal state only. The FS is never in this state between buffers. It is locked and moving frames.

See Also:
Constant Field Values

LOST_SYNC

private static final int LOST_SYNC
An internal state only. The FS is never in this state between buffers. It has just lost sync and next will either flywheel or drop to search.

See Also:
Constant Field Values

state

private int state
The current FrameSynchronizer state. The state is critical to proper processing across buffers.


trueSync

private AbstractSynchronizer trueSync
This object handles true sync detection. It skips true sync detection if trueSync is null.


invertedSync

private AbstractSynchronizer invertedSync
This object handles inverted sync detection. It inverted true sync detection if trueSync is null.


workBuffer

private Buffer workBuffer
I use a Buffer object to hold an input buffer. The Buffer class helps me keep track of where I am.


crossover

private Buffer crossover
I use the crossover buffer to hold a small fragment of the end of one buffer and the beginning of the next buffer. I must do this to detect split sync and slip.


isTrueSync

private boolean isTrueSync
The current sync pattern is true, not inverted. This is meaningful only when sync is detected.


isSlipped

private boolean isSlipped
The current sync pattern is slipped. This is meaningful only when sync is detected.


frameList

private Frames frameList
This is where the FrameSynchronizer collects frames from a single buffer. It usually sends them to the FrameReceiver in a bunch.


setup

private FsSetup setup
The configuration for the current pass.


totalFrames

private LongStatusItem totalFrames
The FrameSynchronizer saves status information here.


dropToSearches

private LongStatusItem dropToSearches

currentMode

private TextStatusItem currentMode

LOCK_STATUS

private static final java.lang.String LOCK_STATUS
See Also:
Constant Field Values

FLYWHEEL_STATUS

private static final java.lang.String FLYWHEEL_STATUS
See Also:
Constant Field Values

SEARCH_STATUS

private static final java.lang.String SEARCH_STATUS
See Also:
Constant Field Values

searchBuffers

private IntegerStatusItem searchBuffers
The number of buffers searched without finding lock. Useful to indicate the FrameSynchronizer is receiving data packets in a server setting.


flywheeler

private Flywheeler flywheeler
This class handles all flywheeling.


frameClock

private FrameClock frameClock
This class is the annotation timestamp clock.

Constructor Detail

FrameSynchronizer

public FrameSynchronizer()
Create a Frame Synchronizer node.

Method Detail

load

public void load(org.w3c.dom.Element element,
                 Configuration configuration)
          throws RtStpsException
Load the FrameSynchronizer with a configuration.

Specified by:
load in class FrameSenderNode
Throws:
RtStpsException

getFrameLength

public final int getFrameLength()
Get the frame length. Do not use this method until after this object is loaded.


getSyncPatternLength

public final int getSyncPatternLength()
Get the sync pattern length in bytes. Do not use this method until after this object is loaded.


shutdown

public void shutdown()
              throws RtStpsException
End a session. The FrameSynchronizer discards any partial frame and will put itself into a search state.

Throws:
RtStpsException

flush

public void flush()
           throws RtStpsException
Flush the pipeline. This behaves the same as shutdown.

Overrides:
flush in class FrameSenderNode
Throws:
RtStpsException

putBuffer

public void putBuffer(byte[] data,
                      int dataLength)
               throws RtStpsException
Give a buffer of bits to the FrameSynchronizer. It will find all frames and send them to the FrameReceiver.

When the FrameSynchronizer is in search mode, then the buffer size must be at least as large as twice the sync pattern length (i.e. at least 8 bytes for a 4-byte pattern). The searcher cannot reliably find sync if the buffer is smaller than the minimum. This limitation does not hold when it is in any other mode.

Throws:
RtStpsException

doFirstSearchScenario

private void doFirstSearchScenario(Buffer buffer)
The FS begins this buffer in a search state. This case is the first buffer of a pass, so there are no crossover bytes from a previous buffer. When it returns, there is no more processing to be done on the buffer.

The buffer size (remaining bytes) must be at least as large as twice the sync pattern length (i.e. at least 8 bytes for a 4-byte pattern). The searcher cannot reliably find sync if buffers are smaller than the minimum. If you pass a too-small buffer, the searcher will simply return still in search mode.


doSearchScenario

private void doSearchScenario(Buffer buffer)
The FS begins this buffer in a search state. Unlike a first search, it is holding some bytes from the previous buffer. When it returns, there is no more processing to be done on the buffer.

The buffer size (remaining bytes) must be at least as large as twice the sync pattern length (i.e. at least 8 bytes for a 4-byte pattern). The searcher cannot reliably find sync if buffers are smaller than the minimum. If you pass a too-small buffer, the searcher will simply return still in search mode.


doFlywheelScenario

private void doFlywheelScenario(Buffer buffer)
The FS begins this buffer in a flywheel state. When it returns, there is no more processing to be done on the buffer.


doSplitSyncScenario

private void doSplitSyncScenario(Buffer buffer)
The FS begins this buffer looking for the second fragment of a sync pattern. When it returns, there is no more processing to be done on the buffer.


doLockScenario

private void doLockScenario(Buffer buffer)
In lock. The FrameSynchronizer attempts to collect as many frames as possible. It may drop sync, but it handles it. When it returns, there is no more processing to be done on the buffer.


doLostSync

private int doLostSync(Buffer buffer)
The FrameSynchronizer has lost sync. It flywheels and then drops back to search if necessary. It attempts to relock.

Parameters:
buffer - The input buffer. Its length must be greater or equal to the sync pattern length. If not, it remains in search.
Returns:
the FrameSynchronizer state

doSearch

private int doSearch(Buffer buffer)
Search the buffer for a sync pattern beginning at its current index. I search the crossover buffer first, but someone else must set it up.

Returns:
the FrameSynchronizer state: LOCK or SEARCH.

findSyncPattern

private Location findSyncPattern(Buffer buffer)
Find the first occurrence of a sync pattern in the buffer beginning at its current index but ending within X bytes of the buffer end. (X is the sync pattern length.) It detects both true and inverted sync. It does not change the buffer index.


verifySync

private int verifySync(Buffer buffer)
Verify there is sync at the current buffer index.

Returns:
the FrameSynchronizer state: LOCK, LOST_SYNC, or SPLIT_SYNC.