ADO parameters for the WFG -
a cost/benefit analysis

• The number of ADO paramters has grown to over ninety (90).
• Some parameter functionality may now be performed by applications, managers, shellscripts, etc.
• New PET features may make some parameters unnecessary.
• Perhaps some are no longer be needed by those who requested them.
• Perhaps some can be simplified or combined.
• Experience may have altered the needs or tradeoffs.

• Enhanced (flexible-formula) firmware.
• Modified "Scoreboard" and new "Scatchpad" structure.
• Impacts of caching may require changes.
• Perhaps some new parameters or features should be added for increased convenience.

As specified, the WFG module has enormous flexibility, even when restricted to anticipated RHIC operational usage, so that the number of distinct parameters could become very large. At the other extreme, it would be possible to limit the ADO to just a single parameter for message passing, and require that applications deal directly with the WFG via commands in its own language. Clearly, neither of these extremes is desirable.

As a tool for deciding about further modifications, this document examines the cost vs. benefits for various groups of parameters in the existing WFG ADO.

BACKGROUND: The WFG is controlled by firmware in an embedded processor (Intel 80960), which responds to command messages sent by the Front End Computer (FEC), as described in the WFG MESSAGES document. All external control and configuration of the WFG is accomplished via these messages, including:

• Set various WFG configuration or initialization values.
• Enable WFG interrupts (to begin output).
• Change WFG modes (e.g. for readbacks).
• Download a ramping or other "table" to the WFG's private memory.
• Upload a "table" from the WFG.
• Define a formula (which refers to tables).
• Connect a formula to an event.

• F(t) time-dependent ramping tables [16,4].
• G(x) and H(y) interpolation tables [16,4 each].
• Scale-factor table (S), for constants [25,4].
• Extrema table (X), for constraining output values [1].
• A-tables containing formula descriptors [16,4].
• Entries in the "C table", connecting an event to a formula [256,4].

The WFG ADO has parameters that allow the user to directly compose and send any command message to the WFG and to capture the reply message from the WFG. There are also some additional parameters that allow more-convenient composition and download of tables and formula descriptors more conveniently, including conversion to/from engineering units, separation of the interlaced time and sepoints into two arrays, and other, more "user-friendly" features. One set of ADO parameters is specifically for DC ramps: enter a setpoint, build a table to ramp to it, add optional sawtooths in front, and start the ramp. Other ADO parameters exist to specify configuration values before initialization, change the readback mode, display diagnostic information, turn on the debugging flag (which causes FEC messages to be displayed), etc.

For the purposes of this analysis, the WFG ADO parameters are grouped into the following categories, classified by functionality and features they provide (rather than by types of messages they send to the WFG). The ADO parameter groups are:

			#
I.	WFG Initialization	Configuration of the WFG device, (including clock rate, default table numbers, etc.), enable interrupts, etc.	6
II.	Diagnostic data	Data about the ADO and the WFG device (such as formula number, ... ) plus miscellaneous config parameters and identification data (such as FirmwareID, debugging flag, ... )
III.	Shared memory	Access to scoreboard, scratchpad, RTDL display area, etc.
IV.	WFG Measurements	such as the latest WFG output value, loopback and readback values, readback frame identifiers.
V.	Conversion	between internal WFG integer units (such as "counts" or "ticks") and user-friendly, floating-point units (such as "volts" or "gauss" or "seconds" or "hamburgers")
VI.	DC ramping	New setpoint & time for DC ramp; default table numbers.
VII.	Sawtooth feature	Adds optional hysteresis sawtooth before DC ramp.
VIII.	Other WFG Settings	including readback mode selection, table-set index, faked event.
IX.	WFG Messages	Sending commands to the WFG device (and getting replies).
X.	Formulas	Download (and upload) of formula descriptors.
XI.	Ramp Tables	Download (and upload) of F, G, and other tables. Included are parameters to compose tables from separate arrays of times and setpoints, converting from floating-point values in user units to "raw" integer WFG units, etc..

Discussion of cost/benefit tradeoffs by group

Several (????#) parameters are involved in DC ramping, which is not required for operations. While this is still useful for diagnostics (and possibly for the transfer line), it could be replaced by applications and scripts, eliminating ??? parameters and ??? lines of code.

Shared memory (scoreboard, RTDL display, etc.) must be modified due to recent firmware changes, and the 10??? parameters could be pared down to two or three. (160 lines go to about 50). Since the parameters intervalM, exhaustedM, thisM, and nextM, are fetched from the shared memory (as is wM), in principle they could all be removed from the ADO (saving 5 parameters and about 70 lines); however, this is not recommended because they are heavily used by applications and pet pages, which would have to be modified to fetch the entire scoreboard and extract them.

Removing conversion (possibly by replacing them with similar ADO features) would eliminate about ??? parameters and another 130 lines.

About 15 parameters contain diagnostic or identifying data (such as base address and firmwareID) which should be ignored by users. A few of these could be removed, but the savings in code would be only about 60 lines (and some cannot be removed).

If mere reduction of the number of parameters was an important goal, then many could be combined into larger structures. However, this would introduce more complexity both to the ADO and to the applications, and is not recommended.

Several parameters provide user-friendly methods of constructing formulas and tables for downloading. While it is possible to compose WFG command messages to do this (and use the general-purpose message-sending parameters of the ADO), there would be a great loss of convenience.

CONCLUSIONS/RECOMMENDATIONS:

setupTestS  -- Initialize the WFG for DC ramping.  Indicate width of output:  12, 13, 16, or 17 bits.; 
setupUserS  -- Initialize the WFG for DC ramping.  Indicate width of output:  12, 13, 16, or 17 bits.; 

configC[6]  -- Configuration parameters (timers, , number of DMA words +256 for local loopback); 
eventCode720C   -- Timeline event code for 720 Hz event.; 
clockRateC   -- Counts @ 5MHz for internal timer (else zero).
dmaSettingC   -- DMA setting -- 1 or 5 (+0x100 for local loopback).
widthC   -- Width of WFG output (12, 13, 16, or 17 bits).; 
shiftC   -- Shift count to be used in calculation of W; 
maxBinaryC   -- maximum output setting =  (2 ^ (widthC-1)) -1; 
maxLevelC   -- Level represented by full-scale.; 

  

ioNameC   -- Identifies I/O port(s).; 
channelC   -- channel number; 
baseID   -- First two hex digits of 24-bit base address; 
baseAddressC   -- Base Address (on VME bus) for this VME; 
firmwareID   -- version of the firmware; 
hardwareID   -- identification of the WFG hardware; 
serialID   -- WFG hardware serial number (from hardwareID); 
deviceID   -- identification of the /dev device; 
debugD   -- Debug flag -- diagnostic level.  Level 0 suppresses showMsg.; 

  

intscoreboardM[64]   -- Scoreboard (64 words). ; 
indexScoreboardC[4]   -- Indexes to extract from scoreboard into int0, int1, int2, int3; 
int0M   -- Extract any integer from current scoreboard ; 
int1M   -- Extract any integer from current scoreboard ; 
int2M   -- Extract any integer from current scoreboard ; 
int3M   -- Extract any integer from current scoreboard ; 
displayFramesM[8]   -- RTDL frame display (8 words). ; 
displayRtdlM   -- Display one RTDL frame ; 
thisM[4]  -- Current settings for event, user, and assoc.; 
nextM[4]  -- Current settings for event, user, and assoc.; 
intervalM  -- Row of F-table.  (0 to max; max+65536 if exhausted; -1 if no clock).; 
exhaustedM  -- DONE if ramp is complete.  interval, otherwise.; 

  

wM   -- Latest W output value (upper 24-bits + 8-bit ID) sent by WFG to PS.; 
readbackIDM[ 5 ]   -- readbackIDs:  Identifiers for readbacks.  (Negative for bipolar.); 
readbackRawM[ 5 ]   -- readbackRawM:  Raw measurement values.; 

  

wCookedM   -- wCookedM:  Latest W output value (sent by WFG to PS), converted to Engineering Units.; 
rampTimeS   -- The number of seconds in the ramp; 
newLevelS  -- Make a table to ramp to the new target setpoint;  -- New level (in Engineering Units) to which Power Supply shall be ramped.  (NOTE:  Changing this value BUILDS a new F-table.); 
readbackMaxC[10]   -- readbackMaxC:  Max range for each readback (2 groups of NQ).; 
readbackM[ 5 ]   -- readbacks:  Cooked measurement values.; 

  

doRampA   -- The action parameter to start a ramp.  (Fakes an event & switches tables.); 
connectA   -- The action parameter to connect for event-triggering.  (Switches tables.); 
newRampS  -- Make table & ramp new setpoint;  -- Set new level (Engr. Units), download F table, fake event, and execute the ramp.
newConnectS  -- Make table & connect;  -- Set new level (Engr. Units), download F table, and connect to event.
fakeEventA   -- Fakes an event. (Don't switch tables.); 

rampTickS   -- How many tick for ramp; 
newBinaryS  -- make an F-table to ramp to the new target setting.   -- New level (in device units) to which Power Supply shall be ramped.  (NOTE:  Changing this value BUILDS a new F-table.); 

Config. parameters for DC ramping: eventC   assocC[2]   tableC[2]   eventD   assocD   tableD   


  

sawManyC   -- How many sawtooths (if any); 
sawUpC   -- The number seconds for rising sawtooth; 
sawHighC   -- Top of sawtooth; 
sawDownC   -- The number seconds for falling sawtooth; 
sawLowC   -- Bottom of sawtooth; 
sawTableC[4]   -- Mini-table for one sawtooth.  (SawUp, SawHigh, SawDown, sawLow.); 

  

readbackModeS  -- Action button to switch readback mode (of the power supply interface);		
changeUserS  -- Change the table-set index.  
fakeEventS   -- Fake an event.;   


  

msgA  -- Send command to WFG; 
msgWordS[4]  -- Message command bytes; 
msgStringS  -- Message command may also be entered as a string; 
msgArgS[6]  // Message argument array; 
replyArgS[6]  // Reply argument array; 
msgValS[ 768 ]  // Message value array; 
msgEntryS  // Message value size; 
msgRowS  // Message values count; 
messageA   // Action button to send a WFG command.  -- Send the message (as-is); 
messageS[ 776 ]  -- Message aray (redirected to use MEMBERDATA message).;  

messageH[ 8 ]   -- Message header array.; 
messageV[ 768 ]   -- Message value array.; 
messageBytesD[ 3072 ]   -- 768 * 4  -- Message value array bytes.;  

formulaFlexS[128]   -- Formula descriptor (128 bytes).; 
formulaByteS[48]   -- Obsolete Formula descriptor (48 bytes).; 
formulaNumberS   -- Specify new formula number and UPLOAD the formula.; 
formulaDownloadS   -- Download a formula (and specify new formula number).; 
formulaConnectS   -- Connect an event to the formula (formulaNumberS).; 

  

tableValueS[256]   -- Contents of ramp table (to be downloaded); 
tableTimeS[128]   -- Times for the of ramp table (to be downloaded); 
tableLevelS[128]   -- Level values for the ramp table (to be downloaded); 
tableNumberS   -- Specify table number for next down/up-load; 
tableTypeS   -- Specify table type for next down/up-load; 
tableUserS   -- Specify table user for next down/up-load; 
tableRowS   -- Establish table size AND download the table.; 
tableEntryS   -- Specify table entry size for next down/up-load; 
uploadA   -- Upload a table from WFG;