Name
userlist - User Programmable List Generator
Synopsis
userlist scriptfile projectfile jobname
Description
The
userlist utility program is a user-programmable ASCII list generator.
userlist interprets the user-defined
userlist script
<scriptfile>.usf, analyzes the net list named
<jobname> from the requested job file
<projectfile>.ddb, and produces a text output listing file named
<projectfile>.<ext>. The listing file extension
<ext>, the output format and the type of net list information to be extracted are defined in the
<scriptfile>.usf
userlist script.
Input File Format
Start Data, End Data, Comments
The
userlist script file must start with the definition of the output file name extension which is defined with the command
EXTENSION = "<ext>";
where
<ext> is the file name extension (a maximum length of up to three characters is allowed). The
userlist script must end with the
ENDSPEC keyword. Commentary text can be placed between
/* and
*/.
FOR Command
The
FOR command is used for selecting elements of a certain class. The formal syntax of the
FOR command is:
FOR (ALL <class> ) { <commands> }
where
<class> specifies the class of the objects to be scanned. Valid classes can be selected with the keywords
NETS,
PARTS,
PINS,
ATTRIBUTES or
<attname>.
NETS iterates the net list object class,
PARTS iterates the part list object class,
PINS iterates pin lists and
ATTRIBUTES iterates attribute lists.
<attname> is used for scanning the attribute value list of the attributes named
<attname>. The command list
<commands> is processed once for each element of the specified object class.
FOR commands can be nested to give more control. The nested
FOR loop in
FOR (ALL NETS) { FOR (ALL PINS) {...}}
would for example find the first net, and then for all pins of that net perform
<commands>. It would then repeat the operation on the second net and so on until it has completed processing of all nets.
Output Commands
The output commands are
PRINT and
PRINTFOR. The formal syntax of the
PRINT command is:
PRINT(<parameters>);
where
<parameters> specify the list of output items separated by commas. Output items enclosed in quotation marks are printed as literal text.
QUOTES keyword can be used to print quotation marks. The
TAB keyword prints a tab character. The
CR keyword prints a newline. Other output items can be specified with attribute names (as listed below) followed by
:<length>:<decimals>
where
<length> is the output length and
<decimals> is the output precision for the corresponding number and/or string value. Negative
<length> values apply for left-aligned output, and
%<length>:<decimals>
will include leading zeros. Default values are 3 for
<decimals> and output item length for the
<length> value. The
<length> value is adjusted to the output item length if necessary. Distance values can be converted to mm or inch units by appending
" MM" or
" INCH", respectively. The
PRINT command can be applied as in
PRINT(QUOTES,PINWIDTH:7:3,QUOTES); /* output: " 3.756" */
PRINT(QUOTES,PINWIDTH%7:3,QUOTES); /* output: "003.756" */
PRINT(QUOTES,PINWIDTH:-7:3,QUOTES); /* output: "3.756 " */
The
PRINT command syntax allows for uppercase and/or lowercase name and/or attribute value outputs by adding blank-separated
UPPER or
LOWER keywords after name or attribute specifications.
The
PRINTFOR command is used to scan through a particular object class and print a list of elements with a defined separator. The formal syntax of the
PRINTFOR command is:
PRINTFOR (ALL <class>) SEPERATOR(<sep>),ELEMENTS(<elements>);
where
<class> is the object class to be scanned (as defined in the
FOR command),
<sep> is the separator to be used (e.g.,
",",
"CR", etc.), and
<elements> are the elements to be listed. The syntax of the parameter lists in
<sep> and
<elements> is the same as for the
PRINT parameter list. If
PRINTFOR is nested in a
FOR loop, then the output is automatically restricted to the current element of the
FOR loop.
IF Command
The
IF command allows commands to operate conditionally. The formal syntax of the
IF command is:
IF (<expr>) { <commands> }
and/or
IF (<expr>) { <commands> } ELSE { <commands> }
The formal syntax of the
IF expression <expr> is given either by
? <attr>
or by the comparison expression
<attr> <operator> <attr|constant>
The
? <attr> expression is used to check whether the attribute specified by
<attr> is available. Available operators for comparison expression are
= (equal),
<> (not equal),
< (less than),
> (greater than),
<= (less than or equal),
>= (greater than or equal).
Counter
The commands
CLEARCOUNTER;
and
COUNTUP;
are used for controlling an internal counter.
CLEARCOUNTER sets the counter value to zero.
COUNTUP increments the counter value. The current counter value can be accessed via the
COUNTVALUE attribute (see also below).
Attributes
The following attributes can be accessed:
| Net Data | NETNAME | Net Name |
NETPINCOUNT | Number of Pins connected to Net |
PRIORITY | Net Priority (for the Router) |
MINDIST | Net Minimum Clearance (for the Router) |
NETNUMBER | Net Number |
| Part Data | PARTNAME | Part Name |
PINCOUNT | Number of Pins defined on Part |
FREEPINS | Number of unconnected Pins in the Part |
PARTATTRIBCOUNT | Number of Attributes in the Part |
$attributname | Value of selected Attribute in the Part |
| Pin Data | PINNAME | Pin Name |
PINWIDTH | Pin Routing Width |
| General Data | PROJECTNAME | Project and/or Design Name |
ATTRIBCOUNT | Number of Attributes matching current Name/Value Combination |
ATTRIBNAME | Name of selected Attribute |
ATTRIBVALUE | Value of selected Attribute |
COUNTVALUE | Current Counter Value |
Examples
Net list generator
conconv.usf:
/* Connection List Generator */
EXTENSION = ".con";
PRINT ("LAYOUT ", PROJECTNAME, ";", CR);
PRINT ("PARTS",CR);
FOR (ALL PARTS)
{
PRINT (" ",PARTNAME," : ",$plname,";",CR);
}
PRINT ("CONNECT",CR);
FOR (ALL NETS)
{
PRINT (" /", NETNAME,"/ ");
PRINTFOR (ALL PINS)
SEPERATOR ("="), ELEMENTS (PARTNAME,".",PINNAME);
PRINT (";",CR);
}
PRINT ("END.",CR);
ENDSPEC
The
userlist script
conconv.usf can be applied as in
> userlist conconv design board 
where net list
board of the job file
design.ddb is analyzed, and the output net list file
design.con with the following contents is produced:
LAYOUT board;
PARTS
ic1 : dil14;
ic2 : dil14;
ic3 : dil16;
CONNECT
/gnd/ ic1.1=ic2.2=ic3.9;
/vcc/ ic1.11=ic2.5=ic3.7;
END.
The part list generator
partlist.usf
EXTENSION = ".ptl";
FOR (ALL $plname)
{
PRINT (ATTRIBCOUNT," ",ATTRIBVALUE,CR);
}
ENDSPEC
would create output file
<job>.ptl with the following contents:
3 cap50
4 dil14
2 dil16
1 r75
Diagnosis
The error messages issued by
userlist are intended to be self-explanatory.
