The Structure and Syntax of the CadEnhance Symbol Description Language (SDL) is described here

Symbol Description Language Structure

The Symbol Description Language (SDL) was designed to be uber-efficient at describing schematic symbol construction, while still being simple to understand and easy to enter.

SDL KEY_WORDS and constructs Constructs are never Not case-sensitive. 

An SDL File is a collection of ordered SYMBOL_NAME_DEFINITIONs enclosing DEFINITIONS which enclose MATCH_STATEMENTS and SpacerSPACER_CommandsCOMMANDS.

The number of symbols you create is generally greater than or equal to the number of SYMBOL_NAME_DEFINITIONs and MATCH_STATEMENTS and Spacer_Commands DEFINITIONS.

Moving pins from one symbol to another is generally a cut and paste operation to move MATCH_STATEMENTS in between a different SYMBOL_NAME_DEFINTION.

To add another symbol, you just add another SYMBOL_NAME_DEFINTION with a new name and add or move your MATCH_STATEMENTS between the start and end.

SYMBOL_NAME_DEFINITIONS, MATCH_STATEMENTS and SPACER_COMMANDS can also appear between the start and end of special LoopLOOP_DirectivesDIRECTIVES

SDL also supports Simple Variable Substitution VARIABLE_SUBSTITUTION commands.

SYMBOL_NAME_DEFINITION

A SYMBOL_NAME_DEFINITION is used to instruct partBuilder to start placing matching pins into a named symbol.

It has 2 parts, a beginning:

SymbolName=

and an end which is just the terminating semicolon.

';'

The SymbolName is the actual name you want to use for the symbol and it should not contain spaces

 in the simple sample file, the start of the first SYMBOL_NAME_DEFINITION  was

DRAM_ACTL_PINS=

That was followed by several MATCH_STATEMENTS  

and was terminated by the

';' 

character

It instructed partBuilder to create a Symbol named DRAM_ACTL_PINS as a place to add the pins matching all the MATCH_STATEMENTS that follow until the SYMBOL_NAME_DEFINITION is closed.

MATCH_STATEMENTS

MATCH_STATEMENTS are  what tell partBuilder which pins to place within the current symbol, what side to place them on  and any other modifier to enable creating special graphics or properites for the pins that match.

MATCH_STATEMENTS are built out of   LOCATOR, MODIFIER and PIN_MATCH elements

The simplest MATCH_STATEMENT only contains a LOCATOR and a PIN_MATCH, and is entered as

LOCATOR=>PIN_MATCH

The equal-Arrow "=>" separates the PIN_MATCH from the list of LOCATORS and MODIFIERS

MODIFIERS are added on the left hand side of the '=>' either before or after the LOCATOR.

For clarity and easier cut and paste in Excel, our examples will show the LOCATOR first.

MODIFIERS and LOCATORS are separated by the colon character ':' as follows;

LOCATOR:MODIFIER1:MODIFIER2:...MODIFIERn=>PIN_MATCH

There is no restriction on the number of valid MODIFIERS that can be included in  a MATCH_STATEMENT. 

It should be obvious that only one LOCATOR is used per MATCH_STATEMENT 

Some simple MATCH_STATEMENTS are provided in the table below to help get a feel for what they look like as you read more about the structure of them.

Examples of Simple MATCH_STATEMENTS.

puts bus pins a15...a0 on the left hand side of the symbol starting from the current position on the left hand side

right:dpair=>clk_p

**presumably clk_n

LOCATOR Elements

The purpose of the LOCATOR element is to tell partBuilder what side of the symbol to place the matching pins on.

Part builder creates one list for each side  of the symbol, and as it sees a locator, it pushes the matching pins A SYMBOL_NAME_STATEMENT may often create more than one symbol if the number of pins that the MATCH_STATEMENTS assign to that symbol are greater than the current Configuration Setting of the SYMBOL_PIN_LIMIT.  For instance, a GROUND symbol definition often contains only one MATCH_STATEMENT to assign any pin matching GND to that symbol. If the part has 400 Ground pins and the SYMBOL_PIN_LIMIT is set to 100, it will create 4 SYMBOLS and create a new name for each of the extra symbols it creates (GROUND, GROUND_1, GROUND_2 and GROUND_3)

MATCH_STATEMENTS

MATCH_STATEMENTS are  what tell partBuilder which pins to place within the current symbol, what side to place them on  and any other modifier to enable creating special graphics or properites for the pins that match.

MATCH_STATEMENTS are built out of   LOCATOR, MODIFIER and PIN_MATCH elements

The simplest MATCH_STATEMENT only contains a LOCATOR and a PIN_MATCH, and is entered as

LOCATOR=>PIN_MATCH or LOCATOR>>PIN_MATCH 

The equal-Arrow "=>" or double-Arrow (recently added for easier entry in excel) separates the PIN_MATCH from the list of LOCATORS and MODIFIERS

MODIFIERS are added on the left hand side of the '=>' or '>>' either before or after the LOCATOR.

For clarity and easier cut and paste in Excel, our examples will show the LOCATOR first.

MODIFIERS and LOCATORS are separated by the colon character ':' as follows;

LOCATOR:MODIFIER1:MODIFIER2:...MODIFIERn=>PIN_MATCH

There is no restriction on the number of valid MODIFIERS that can be included in  a MATCH_STATEMENT. 

Only one LOCATOR is used per MATCH_STATEMENT 

Some simple MATCH_STATEMENTS are provided in the table below to help get a feel for what they look like as you read more about the structure of them.

Examples of Simple MATCH_STATEMENTS 

LOCATOR Elements

The purpose of the LOCATOR element is to tell partBuilder what side of the symbol to place the matching pins on. 

Valid Locators are mostly obvious, and are explained in the following table

If the LOCATOR is not provided, it implies AUTO. This is not recommended going forward, but many older SDL files were written without LOCATORS.

MODIFIER Elements

Valid Modifiers are explained in the following table. Modifiers may be further broken down by partBuilder to impart extra information as shown

PIN_MATCH Elements

The PIN_MATCH Element is the string that PartBuilder uses to test all pins in the extracted pinData for a match. 

PIN_MATCHES may be entered as a simple string or with a wildcard.

PartBuilder treats all the PIN_MATCHES it extracts from the SDL as a Regular Expression. It actually converts the wildcard '*' internally to the '.*' used in Regular Expressions.

They may also be entered as a valid Perl Regular Expression.

PartBuilder treats all the PIN_MATCHES it extracts from the SDL as a Regular Expression. It actually converts the wildcard '*' internally to the '.*' used in Regular Expressions.

A Regular Expression is a pattern describing a certain amount of Text.  The Regular Expression can be very general or very restrictive.

In the simplest context, PartBuilder uses a regular expressions to determine if a Pin contains the PIN_MATCH pattern. 

If the PIN_MATCH  is entered as "DQ", PartBuilder will match any pin that Contains DQ anywhere in the pinname.

Excellent references for Regular Expressions exist on the web like the one at this link.

PartBuilder Bus-Enhanced Regular Expressions.

PartBuilder does some behind the scenes work to change the PIN_MATCH  Regular Expressions to enable  placing  bussed pins seamlessly

Its not truly necessary to understand this detail, but In a normal regular expression, the '[]' characters in the pattern match enclose a list of characters to match against

If you were comparing a list of pins dq7 dq6 dq5 dq4 dq3 dq2 dq1 and  dq0 using the regular Expression 'dq[0:7]' , the pattern would only match dq0 and dq7 (and funny enough dq:).

You could get more useful results with 'dq[0-7]' (because 0-7 inside the square brackets says to match any character between 0 and 7) but unfortunately that would not enforce the order of the pins. 

In order to work around this, when PartBuilder sees the 'DQ[0:7]' in a PIN_MATCH it  expands it to 8 seperate PIN_MATCHES DQ0, DQ1, DQ2... DQ7** which are then used as pattern matches.

It also maintains the order of the bits so that they will be added to the symbol in LSB→MSB order if you enter busName[0:7] or MSB→LSB order if you enter busName[7:0]. As described in the table below, it also appends whats called a zero-width-lookahead assertion at the end fo each  to insure that DQ18 doesn't match DQ1 but it would still allow a match of dq1_p

(**it also appends a  zero-width-lookahead assertion to each match to ensure that no other digits are following the ones we want so that DQ18 doesn't match DQ1) 

Examples of Useful PIN_MATCH Regular Expressions

Anchor
PIN_MATCH_REGEX PIN_MATCH_REGEX

PIN_MATCH Elements

The PIN_MATCH Element is the string that PartBuilder uses to test all pins in the extracted pinData for a match. 

PIN_MATCHES may be entered as a simple string or with a wildcard.

They may also be entered as a valid Perl Regular Expression.

PartBuilder treats all the PIN_MATCHES it extracts from the SDL as a Regular Expression. It actually converts the wildcard '*' internally to the '.*' used in Regular Expressions.

In the simplest context, PartBuilder uses a regular expressions to determine if a Pin contains the PIN_MATCH pattern. 

If the PIN_MATCH  is entered as "DQ", PartBuilder will match any pin that Contains DQ anywhere in the pinname.

For more background Navigate to this page: Regular Expressions In CadEnhance Tools

Examples of Useful PIN_MATCH Regular Expressions

Assigning Pins that

match multiple

MATCH_

STATEMENTS

It takes PartBuilder 2 passes to place matching pins into the proper symbols. It first goes through every pin_match and attaches a list of every MATCH_STATEMENT that each pin matches to the pin. It then makes a second pass, and chooses the MATCH_STATEMENT with the longest PIN_MATCH string to pick the proper MATCH_STATEMENT for that pin. 

Lets provide a simple example:

We have are building a fictional part with that has 100 pins named GND, 8 pins named SGND AGND and 2 pins named GTH_RX_SGND AGND and 2 named GTH_TX_SGNDAGND

We have the following 2  SYMBOL_NAME_DEFINTIONS DEFINITIONS in the SDL File

GND_SYM=

LEFT=

>AGND

LEFT=>SPACER[1:0]

BOTH=>GND

;

GTH_BLOCK=

LEFT:dpair=>GTH_RX[7:0]_P

RIGHT:dpair=>GTH_RX[7:0]_N

!BSS+2

LEFT=>GTH_RX_

AGND

RIGHT=>GTH_TX_

AGND

;

Because of this 2 pass approach, the user does not need to concern themselves with what order a MATCH_STATEMENT is placed or what SYMBOL_DEFINTION DEFINITION it is placed in.

They do need to should be aware that the 2 pass approach is necessary and that they need to assign more specific PIN_MATCHES  if they want to seperate separate Pins like the example that have common strings in them 

Anchor

BEST_MODIFIER_

`FOR (var=start;var<=end;var inc/dec) 

`FOR VAR_NAME IN LIST 

`FOR VAR_NAME_LIST IN LIST 

DESC

SPACER_COMMANDS allow the user to easily control spacing between groups of pins

There are 3 types:

• SINGLE_SPACERS:
  • LOCATOR=>SPACER,
• MULTIPLE_SPACERS:
  
  • LOCATOR=>SPACER[5:0]
• and SPACER_DIRECTIVES:
  • !BALANCE_SYM_SIDES+n (or !BSS+n)

The first 2 resemble the MATCH_STATEMENTS pretty closely and use the LEFT, RIGHT, TOP and BOTTOM LOCATOR commands.

The !BALANCE_SYM_SIDES directive is used to start a new section in the same symbol without having to keep track of the number of pins you have been adding on the sides of your symbols.

For instance if you have 3 pins on the left and 8 pins on the right, The BALANCE_SYM_SIDES+2 directive would add 5 spacer pins on the left to Balance it with the right side, and then add 2 more spacers on each side.

LOOP_DIRECTIVES AND VARIABLE SUBSTITUTION

SDL Loop Constructs and Variables can really enhance the efficiency of creating parts that contain multiple similar interfaces like a microprocessor with 2 DRAM busses or an FPGA with multiple IO Banks with the same number and types of pins.  They can also be used to quickly break up busses into nicely structured sub-busses 

The Expanded SDL File

PartBuilder first scans the input SDL file to see if it contains  LOOP _DIRECTIVES or Variable Substitution. If it finds any, it creates a new, expanded version of the input SDL file which it saves to the local directory and then uses for the pin to symbol assigment step. One benefit of this approach is it allows the user to clearly see how the loops were expanded, and possibly catch any unintended consequences of the loops. While the user is encouraged to examine the expanded SDL File, They  should be careful not to edit it, as any changes they make to that file will be overwritten the next time PartBuilder reads and expands the input SDL file.

VARIABLE Value Assignment and Substitution

The user can use variables within Loops or just globally change a of a set of PIN_MATCHES in some MATCH_STATEMENTS that they cut and paste.

VARIABLES can be substituted anywhere in the SDL including in Comments, SYMBOL_NAME_DEFINITIONS and MATCH_STATEMENTS.

A Variable is assigned with the following statement:

`LET VAR_NAME=SOMETHING

The VAR_NAME cannot contain spaces, but it can consist of The SOMETHING can be a number or a string.  

There are 4 main types of loop constructs. Each Construct starts with the backtick '`' characater to tell partPartbuilder that this is a special line

BEST_MODIFIER_DESC

The BEST Modifier in pin matching

In some odd cases (mostly when using loops and variables), The longest match might place a pin where you don't want it to.

SDL provides the BEST modifier to allow you to work around these cases.

Lets say we have an FPGA with a bunch of pins in bank 37 that we are trying to order using a bus so we use

left=>IO_L[19:0]*_37

but there is a pin in that bank named IO_L4_VREF_37, which we want to place in a different symbol (or somewhere in the same symbol)

if we use the BEST modifier,

left:BEST=>VREF_37

we guarantee that this match will claim the signal matching VREF_37,  and not the longer IO_L4*_37 match.

SPACER_COMMANDS

SPACER_COMMANDS allow the user to easily control spacing between groups of pins

There are 3 types:

• SINGLE_SPACERS:
  • LOCATOR=>SPACER,
• MULTIPLE_SPACERS:
  
  • LOCATOR=>SPACER[5:0]
• and SPACER_DIRECTIVES:
  • !BALANCE_SYM_SIDES+n (or !BSS+n)

The first 2 resemble the MATCH_STATEMENTS pretty closely and use the LEFT, RIGHT, TOP and BOTTOM LOCATOR commands.

The !BALANCE_SYM_SIDES directive is used to start a new section in the same symbol without having to keep track of the number of pins you have been adding on the sides of your symbols.

For instance if you have 3 pins on the left and 8 pins on the right, The BALANCE_SYM_SIDES+2 directive would add 5 spacer pins on the left to Balance it with the right side, and then add 2 more spacers on each side.

l_spacer, r_spacer shorthand

**Older SDL files used the short-hand

l_spacer for LEFT=>spacer

and

r_spacer for RIGHT=>spacer.

The shorthand is still available but it is not as convienient for cut and paste in the spreadsheet format, and the SDL_EDITOR will automatically convert them to the newer LEFT=>, RIGHT=> format

Anchor
IF_LAST_MATCH_DESC IF_LAST_MATCH_DESC

IF_LAST_MATCH  modifier for SPACER_COMMANDS

It is very convenient to use loops with ranges of  FPGA bank numbers where some of the bank numbers might not exist. In that loop you would normally place a spacer command to separate the banks. In the normal case, those spacers will always be added even if a bank doesn't exist. The IF_LAST_MATCH modifier can be used to avoid placing unwanted spacers when there are no matched signals between consecutive SPACER_COMMANDS

for instance if you have an FPGA that only contains IO banks 12,13,15,17. (another FPGA in the family could have IO banks 12,13,14,15,16,and 17

You use a loop:

But for this FPGA , there will be no pins that match IO.*_14 or IO.*_16. 

If the spacer is unmodified you will get 4 spacers between the IO.*_13 pins and the IO.*_15 pins, and 4 between the IO.*_15 and IO.*_17 pins. 

if you add the IF_LAST_MATCH modifier as follows

With the IF_LAST_MATCH PartBuilder will not add the spacers if it did not see any matching pins between the last occurrence of a spacer and the next one.

so IO_.*13 will match some pins, so  the left:IF_LAST_MATCH=>spacer[1:0] will be honored, then partbuilder will clear the match count, it will look at the io.*_14 match and see no pins.. When it gets to the next IF_LAST_MATCH=>spacer[1:0] command, it will not add those spacers.

GRID_ADJUST  (Still Exists, but not really used)

Support for a  new 

LOCATOR=>!GRID_ADJUST_{fractional_space_specifier}

Command was added in version v18.5.5 to allow partBuilder to move pins off grid to let Smart-Frac exactly match pin locations from previously created symbols.

Normally pins are always added in whole grid increments, but to match pre-existing symbol pin placements it may be necessary to move a pin onto a half grid space

For example:

LEFT=>!GRID_ADJUST_0.5 will move the next pin 0.5 grid spaces so that all the next pins will start on the half grid space (until another !GRID_ADJUST  command would be used to move pins back onto the whole grid)