Take the following two lines from the Numato tutorial:
set_property -dict { PACKAGE_PIN "N17" IOSTANDARD LVCMOS33 SLEW FAST} [get_ports { A }]; # IO_L21P_T3_DQS_14 Sch = SW3
set_property -dict { PACKAGE_PIN "M16" IOSTANDARD LVCMOS33 SLEW FAST} [get_ports { B }]; # IO_L24N_T3_RS0_15 Sch = LED7
If we can understand these two lines, we will be well on our way.
First of all, be advised that this is actually the Tcl language. If you have any familiarity with Tcl syntax, it will help you to generate proper XDC files. Secondly, we are going to use the ug903 user guide (69 pages) entitled "using constraints" to try to educate ourselves. It turns out that ug903 is pretty dismal as a reference as it mostly assumes a bunch of prior knowledge and is not the reference manual for XDC file format that I had hoped.
XDC stands for Xilinx Design Constraints. It is based on Synopsis Design Constraints, which doesn't help us at all since we are new to all of this, but as of 2012 it had been around for 20 years or so. There are timing constraints and physical constraints, and constraints can be separated into multiple files.
The syntax for a physical constraint (which is what we have above) is:
set_property property value object-listI have discarded (and/or burned) all of my Tcl books, which I don't really regret, but let's hold our nose and examine the Tcl syntax in the above example lines.
Square brackets are not what you think -- they say to evaluate what is inside of them and replace them (and what is in them) with the result. So consider the following:
[get_ports { A }]
This says to call the "get_ports" function and pass "A" as an argument.
The square brackets say to do it now and interpolate the result in place.
Whatever comes back as the result of this serves as the "object-list" in some mysterious way.
Curly braces are not what you think either. They tend to group several things into one and act
like a certain kind of quote that inhibits substitution within it -- but they seem to have uses
that aren't described by this, such as the following with just one thing inside the braces.
Consider the following:
set_property -dict { PACKAGE_PIN "N17" IOSTANDARD LVCMOS33 SLEW FAST} [get_ports { A }]; # IO_L21P_T3_DQS_14 Sch = SW3
Here the -dict "switch" says that a dictionary of settings follows (as a single argument).
The dictionary has (in this case) 3 property value pairs:
PACKAGE_PIN "N17" IOSTANDARD LVCMOS33 SLEW FASTSome people would do this with separate lines as follows:
set_property PACKAGE_PIN E15 [get_ports {GPIO_O[0]}]
set_property IOSTANDARD LVCMOS25 [get_ports {GPIO_O[0]}]
A Tcl list is just a bunch of things separated by spaces. So you can define a list like this:
set mylist {red green blue}
Allow me a short rant on "set". Tcl has no infix assignment like a = 1, you say "set a 1" instead.
On top of that, Tcl is generally dealing with strings (so "a" here is not a numeric value, but a string "1").
If you want to do math, you do something like "set a [expr $a+1]" if you can believe it.
Indeed, this would be "a++" in C or many other modern languages.
The built in "expr" function handles infix notation in its arguments, without it we would have to do
something like "set a [add $a 1]" with a variety of math operator words like "add".
Note also the use of the dollar sign. Without it, we are just dealing with the string "a", with it (as in $a) we are dealing with the value stored in the variable of name "a". I trip over this all the time. The bottom line is that Tcl has virtually no parser as we know it in modern languages, and it is up to you to help it along every step of the way.
One last thing (maybe) to mention is the semicolon. This ends a Tcl statement with authority. It is sort of optional, but may either be a good idea or essential if a pound sign introduces an online comment that follows.
The following looks like a pretty good one page summary of Tcl fundamentals:
Tom's Computer Info / tom@mmto.org