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.

Google Online Preview   Download