University of Arizona
Proposed Statefile Syntax
Statefiles store setup information for all the tools that run in the CDP environment.[1] The huge variety of tools and setups means we need a very general, yet simple way to save this information. The basic requirements are:
1) Statefiles must provide a complete setup of all tools.
2) Statefiles must be kept in a single location to ensure portability of testcases and archives.
3) Statefiles must be easily readable, so that users can quickly locate any property they need to change in a script.
4) Syntax to set parameters in a script should be the same.
This last requirement needs some explanation. Currently most statefiles are not readable. In fact, some are not even text files. Even those that are text files are so complex that the average user will never figure them out. This leads to a scripting language that is every bit as complex as the statefiles, with dozens of intricate commands to change various setup parameters in different tools. Even with all these commands, we have access to only a small fraction of the needed setup parameters.
What if we could make the scripting language change setup parameters directly via the statefiles. That would give us complete control over every setting of every tool. Statefiles must be complete or we will never have repeatability. It should not be necessary to repeat this effort in an attempt to make a complete scripting language. If instead, we make changes via statefiles that have a sensible format, then there is no need for huge volumes of documentation on the scripting language. The statefiles can be self-documenting. Users can read those files, and copy settings directly into a script.
The basic scripting commands to run any tool should be: load one or more statefiles, change whatever parameters you want, and initiate the run. With these three commands, and a complete set of statefiles, we can do anything. Actually, we can do anything with just two commands, but the command to change individual statefile parameters will be a great convenience. Design variables, for example, could be changed by loading a new statefile, but this may be cumbersome if we are changing one variable repeatedly. A general purpose ‘setparam’ command will be handy.
loadstate ( , , ... ) # default is all files
setparam ( , “ , ... ” )
run ( )
Note: ‘section’ is optional, and can be a hierarchical name, e.g.
setparam (“wavescan.template7”, “window1.subwindow2.xaxis.label.font.size 12” )
The details of this long hierarchical name are easily discovered by running the tool interactively, saving the statefile, then looking at the hierarchical set of properties listed in the saved file. This is far easier than searching through manuals, hoping to find a special command to change the size of a label on a graph.
In this proposal we offer two alternative statefile syntaxes to satisfy the basic requirements above. One other requirement is that we follow existing standards to the extent that we can without sacrificing our primary requirements. For example, in the syntax for quoted strings, we follow the conventions of Python, a modern scripting language that has made great efforts to define such things in a simple and versatile way. A side benefit is that we can use the Python string processing functions, and all the dirty details, such as escaped quotes within a quoted string, are taken care of.
Another alternative is to simply use XML. This is a well-established standard, with routines already available to read and write XML files, verify their syntax, etc. The problem with XML is readability and usability in a script. See Appendix A for a realistic example.
Syntax Proposal 1
Filename is the name of the setup to be loaded. For the example above, the filename would be wavescan. The file is a simple text file with a section for each subsetup. Subsetups in a file are optional. The simplest statefile may have nothing but parameters and values. Again, using the example above, SubSetup1 could be window1.
SubSetup1 { # This is an illustration of statefile syntax.
| param1 value1; param2 value2; param3 value3
| param4 {
| . param4a value4a
| . param4b {
| . . param4b1 value4b1
...
| . . param4bN value4bN
| . . paramX valX, paramY valY, paramZ valZ
| . }
| }
| param5
+ [ listitem1, listitem2, listitem3,
+ “listitem 4 has embedded blanks”,
+ listitem5 ]
| param6 value6
}
SubSetup2
...
SubSetupN
Notes
1) No data type declarations are needed. The tool that reads each statefile already knows what to expect for each parameter.[2]
2) Leading ‘. ’ (dot whitespace) or ‘| ’ (pipe whitespace) sequences are ignored. These are for readability only, and are very handy in statefiles that have deeply indented hierarchies running over a page boundary.
3) Column one ‘+ ’ (plus whitespace) indicates a continuation of the previous line. Lines can also be continued with a \ at the end of the first part.
4) A single parameter can contain a list of values. List items are enclosed in [] and separated by commas.
5) ‘param = value’ is also a valid syntax. Some users prefer an equal sign with numeric values.
6) # comments out remainder of any line.
7) ; has the same effect as end-of-line.
8) , separates multiple parameters with same prefix.
9) “ (double quote) or ‘ (single quote) must be used when a string value has characters that would otherwise terminate the string.
10) Blank lines are ignored.
Syntax Proposal 2
Same as Proposal 1, but let the dots be significant. This follows the Python philosophy of making good formatting a syntactical requirement. Cleaner and more compact. Not so many { }.
SubSetup1 { # This is an illustration of statefile syntax.
param1 value1; param2 value2; param3 value3
param4
. param4a value4a
. param4b
. . param4b1 value4b1
...
. . param4bN value4bN
. . paramX valX, paramY valY, paramZ valZ
param5
+ [ listitem1, listitem2, listitem3,
+ “listitem 4 has embedded blanks”,
+ listitem5 ]
param6 value6
}### end SubSetup1
SubSetup2
...
SubSetupN
Notes
1) { } are used only to delimit optional sub-setups.
2) Hierarchical parameters can be abbreviated with leading ‘. ’ (dot whitespace). In the example above, the value of param4.param4b.param4b1 is value4b1 .
3) Positioning of the leading dots is not enforced by the statefile reader, but we highly recommend putting them in the same columns as the parameters that they spot.
Some allowed variations
param4
. param4a value4a
. param4b value4b # mid-level values are optional.
. . param4b1 value4b1
...
. . param4bN value4bN
param4.param4c value4c # Repetition of ‘param4’ is harmless.
. param4d
. . p4d1 val4d1; . . p4d2 val4d2; . . p4d3 val4d3 # save space
param5 ...
4) Values are normally assigned only to the lowest level parameters, however, assignment to mid-level parameters is allowed, and will not interfere with assignment or usage of normal parameters. This additional complexity is not recommended, but if the tool requires it, the syntax will support it.
5) Repetition of higher-level parameters, although syntactically unnecessary, can clarify a long listing. Use this to improve readability of your statefile.
6) Putting high-level parameters first is usually more readable, as shown in the first two examples below, but either one is syntactically correct.
Examples
xaxis.label.font.size 12
. . . family arial
. . . color blue
. . . bold True
. . text “Frequency (MHz)”
. . position –0.5
xaxis.label.text “Frequency (MHz)”
. . position –0.5
. . font.size 12
. . . family arial
. . . color blue
. . . bold True
yaxis1.scale
. . style dB20
. . min 0
. . max 120
. . sigdigits 2
. . majdivisions 6
. . mindivisions 4
analyses.tran; . . start 10u; . . stop 20u
. . method gear2
. . skipdc yes
. . readic final50u
Setting Parameters in a Script
setparam analyses.tran method=euler # equal sign is optional
setparam wavescan.window1 {
xaxis.label.text “Frequency (MHz)”
. . position –0.5
. . font.size 12
. . . family arial
. . . color blue
. . . bold True
}
The first argument picks the setup and subsetup. Subsequent arguments are parameter-value pairs.
Curly brackets are needed only for multi-line commands. Blocks of parameters can be copied right out of the statefiles with no change in syntax.
The example above can be made even more compact by using commas for multiple parameters on the same level. This is handy when editing scripts in a small window, but can also lead to confusion.
setparam wavescan.window1 {
xaxis.label.text “Frequency (MHz)”
. . position –0.5, font.size 12
. . . family arial, color blue, bold True
}
In this example, parameters family, color, and bold are all under xaxis.label.font, not xaxis.label.position, as you might expect from reading it quickly. Perhaps the user has sacrificed too much clarity to save one line, but that is the user’s choice. Our statefile writer should never output a file like this, but the statefile reader allows it, because our simple syntax can’t rule it out. All the parser knows when it gets to the token family is that the current parameter being processed is xaxis.label.font.size, so it picks up the first three items to replace the dots ahead of family.
Syntax Errors
The following examples are illegal, and should be flagged by the statefile reader and script interpreter:
setparam wavescan.window1 ( No parameters or { before EOL
xaxis.label.text “Frequency (MHz)”
. . position –0.5
. font.size 12 ( No such parameter ‘xaxis.font’
. . . family arial
. . . color blue
. . . bold True, . italic false ( Can’t change level after a comma
# end xaxis } ( } is masked by #
Note: The font.size assignment above is actually legal syntax, but can be flagged as an error if the reader or interpreter is running in a context where all legal parameters are known.
Deeply Nested Example
This is an example of an even more deeply nested hierarchy, a piece of the Python parse tree
DOCSTRING_STMT_PATTERN = (
stmt,
(simple_stmt,
(small_stmt,
(expr_stmt,
(testlist,
(test,
(and_test,
(not_test,
(comparison,
(expr,
(xor_expr,
(and_expr,
(shift_expr,
(arith_expr,
(term,
(factor,
(power,
(atom,
(token.STRING = ['docstring'])
))))))))))),
xxx = 999)
)))),
(token.NEWLINE = '')
))
While this certainly beats XML and Javabeans for compactness and readability, it is still too hard to see the hierarchy by drawing lines with a ruler or counting parens. For example, what is the complete hierarchical name of the parameter xxx above? Here is the same hierarchy in our proposed syntax.
DOCSTRING_STMT_PATTERN
. stmt
. . simple_stmt
. . . small_stmt
. . . . expr_stmt
. . . . . testlist
. . . . . . test
. . . . . . . and_test
. . . . . . . . not_test
. . . . . . . . . comparison
. . . . . . . . . . expr
. . . . . . . . . . . xor_expr
. . . . . . . . . . . . and_expr
. . . . . . . . . . . . . shift_expr
. . . . . . . . . . . . . . arith_expr
. . . . . . . . . . . . . . . term
. . . . . . . . . . . . . . . . factor
. . . . . . . . . . . . . . . . . power
. . . . . . . . . . . . . . . . . . atom
. . . . . . . . . . . . . . . . . . . token.STRING = ['docstring']
. . . . . . . xxx = 999
. . . token.NEWLINE = ''
The complete name we need is:
DOCSTRING_STMT_PATTERN.stmt.simple_stmt.small_stmt.expr_stmt.testlist.test.xxx
While it is not likely we will ever need a statefile as deeply nested as this example, you can see that even in this extreme case, we can read this file and determine the complete name of any parameter we need to set. The dots are not just a visual aid. In this example, they guarantee that ‘xxx’ is a subparameter of ‘test’, the closest level-7 parameter above ‘xxx’. The vertical alignment of all the dots is not enforced by the statefile reader, but is highly recommended ( and also easy to type ).
Appendix A: Comparing XML to Proposed Syntax 2
The following is a typical statefile to set up a display tool (Cadence Wavescan). The original information (XML format) is in orange font, (except that we’ve added some leading dots to help decipher what properties apply to which object). The equivalent information in the proposed “statefile format” is in black. The proposed format is much more compact and readable. We need to decide if the features offered by XML and JavaBean classes are worth enough in this application to warrant the extra complexity.
Note: In the black sections, we’ve deviated from the organization of information in the original statefile in order to separate “template” information from “signal connection” information. Templates should be re-usable with different signals. Signal connection information stored with a template will only cause confusion.
.
. .
. . .
. . . .
. . . . . 465
. . . . . ~/simresults/bandgapTest/spectre/schematic/psf
~/simresults/bandgapTest/spectre/schematic/xR4=1.042
~/simresults/bandgapTest/spectre/schematic/xR4=1.04
~/simresults/_VCOtest/spectre/schematic/psf
~/simresults/_VCOtest/spectre/schematic/temp=30
~/simresults/ampTest/spectre/schematic/CAP=7e-13,temp=100
~/simresults/ampTest/spectre/schematic/CAP=7e-13,temp=0
~/simresults/ampTest/spectre/schematic/
~/simresults/ampTest/spectre/schematic/psf
~/projects/TRO/wscan/ampsim.raw
. . . . . True
875
5
431
. . . .
. . .
. .
BrowserWindow {
. windowVisible True
. height 465
. width 875
. xLocation 5
. yLocation 431
. resultsDirs
+ ~/simresults/bandgapTest/spectre/schematic/psf,
+ ~/simresults/bandgapTest/spectre/schematic/xR4=1.042,
+ ~/simresults/bandgapTest/spectre/schematic/xR4=1.04,
+ ~/simresults/_VCOtest/spectre/schematic/psf,
+ ~/simresults/_VCOtest/spectre/schematic/temp=30,
+ ~/simresults/ampTest/spectre/schematic/CAP=7e-13,temp=100,
+ ~/simresults/ampTest/spectre/schematic/CAP=7e-13,temp=0,
+ ~/simresults/ampTest/spectre/schematic,
+ ~/simresults/ampTest/spectre/schematic/psf,
+ ~/projects/TRO/wscan/ampsim.raw
}
. .
False
. . . . .
. . . . . . .
. . . . . . . .
/usr1/dmq/simresults/bandgapTest/spectre/schematic/psf
tran-tran
/usr1/dmq/simresults/bandgapTest/spectre/schematic/psf
Rectangular
Vout
. . . . . . . . /usr1/dmq/simresults/bandgapTest/spectre/schematic/psf
. . . . . . .
. . . . . 0
0
. .
chan1 { # setup for channel 1
. template template1 # set all your knobs
. signal { # connect a signal
. . name Vout
. . title “Transient Analysis `tran': time = (0 s -> 10 us)”
. . type SIGNAL
. . dataSet tran-tran
. . dir /usr1/dmq/simresults/bandgapTest/spectre/schematic/psf
. . index 0
. . compound False
. }
}
. .
. . . . . .
592
570
False
False
0
False
True
False
0.0
True
V
black
lightGray
True
1
0.0
True
9
12
0
0
white
5
False
3
5
True
True
Dialog
True
black
Vout
6
Identity
0
Vout
/usr1/dmq/simresults/bandgapTest/spectre/schematic/psf
tran-tran
0
SIGNAL
False
0
V
False
20
0
red
/usr1/dmq/simresults/bandgapTest/spectre/schematic
s
31
tran-tran
Vout
True
False
0
False
True
False
0.0
True
s
black
time
lightGray
True
1
0.0
True
2
False
Transient Analysis `tran': time = (0 s -> 10 us)
410
False
0
. . .
. .
.
template1 {
. graphType Rect2Dgraph
. xLocation 410, yLocation 0, height 592, width 570
. windowVisible False, cursorOn False, stripChartState False
. labelText # no labels
. freeze False, dataSnapOn False
. title # Null title in the template means use the signal title.
. fontSize 12, fontStyle 0
. nameId 0, backgroundName white
. stripChartOn False, visibleStripChartRows 5
. peakSnapOn False, visibleDigitalRows 3, displayType 5
. minorGridsOn True, majorGridsOn True
. useDefaultSubTitle True, useDefaultTitle True
. fontName Dialog, foregroundName black
. dependentAxis {
. . forceOrigin False
. . minGridsOn True
. . majGridsOn True
. . logScale False
. . userMin 0.0
. . userMax 0.0
. . baseUnit V
. . foregroundName black
. . minorForegroundName lightGray
. . sigDigitsDefault True
. . scaleMode 1
. . sigDigits 9
. }
. independentAxis {
. . forceOrigin False
. . minGridsOn True
. . majGridsOn True
. . logScale False
. . userMin 0.0
. . userMax 0.0
. . baseUnit s
. . foregroundName black
. . title time
. . minorForegroundName lightGray
. . sigDigitsDefault True
. . scaleMode 1
. . useDefaultTitle True
. . sigDigits 2
. }
. trace {
. . indepAxisId 0
. . depUnit V
. . symbolsOnFlag False
. . symbolCount 20
. . depAxisId 0
. . forgroundName red
. . indepUnit s
. . traceType 31
. }
}
-----------------------
[1] Setup information is also stored in “init” files, but these are less complete than the statefiles, and are intended for just those setups that occur when the tools are initialized.
[2] The need for “metadata” like variable types and default values is an open question. We could extend the proposed syntax on each parameter (at the cost of making statefiles less readable), or we could add an ‘include’ statement referencing another file that holds any parameters needing metadata. These include statements could facilitate working with tools that have not yet migrated to the new statefile syntax.
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
- instructor manual for introduction to computing and
- the trac user and administration guide¶
- programming fundamentals openalg
- university of arizona
- owasp application security verification standard 3 0
- lab parse different data types with python
- introduction stellenbosch university
- technical reference manual clemson university
- edexcel gcse in computer science lesson activities for
- juniata college
Related searches
- university of arizona salaries
- university of arizona salary list
- university of arizona salary 2018
- university of arizona financial
- university of arizona address tucson
- university of arizona admissions status
- university of arizona application 2020
- university of arizona arthritis center
- university of arizona rheumatology
- university of arizona body donation
- university of arizona employment
- university of arizona salary grades