This page is a reference for Alchitry Constraints V2.

Alchitry Constraints File Contents

An Alchitry Constraints File (.acf extension) contains a list of pin constraints.

Comments

Comments take the same form as in Lucid.

Use // for a single line comment and /* */ for a multi-line comment.

Pin Constraints

The main purpose of a pin constraint is to tell the tools which physical pin on the FPGA corresponds to a port of your design's top-level module.

A pin constraint takes the following form.

pin port_name PIN_NAME OPTIONAL_ATTRIBUTE_LIST

Here, port_name corresponds to a port of your top-level module. If the port is an array, then it should also include array selectors to select only a single bit.

The PIN_NAME is the name of the physical pin to connect to port_name. This name is the Alchitry pin name and not the pin name of the FPGA. See the pinout section for the various pin names.

Finally, the OPTIONAL_ATTRIBUTE_LIST is a list of attributes that apply to only this pin.

Attribute Block

Specifying attributes for every single pin constraint would often become very tedious as many pins will share the same attribute values. This is where attribute blocks come into play. They take a very similar form to the connection blocks in Lucid.

ATTRIBUTES_LIST {
   ...
}

The ATTRIBUTES_LIST is a comma-seperated list of attributes.

The attributes in the list are applied to every pin constraint inside the brackets.

Attribute blocks can also be nested to allow for fine-grained assignments.

For example, the Hd constraints uses two STANDARD blocks along with a single PINOUT block.

PINOUT(V2) {
    STANDARD(LVCMOS33) { // standard 3.3V IO standard
        pin hdmi_sda_1 A70
        pin hdmi_scl_1 A72
        pin hdmi_cec_1 A76
        pin hdmi_hp_1 A78

        pin hdmi_sda_2 A69
        pin hdmi_scl_2 A71
        pin hdmi_cec_2 A75
        pin hdmi_hp_2 A77
    }

    STANDARD(TMDS_33) { // HDMI IO standard
        pin hdmi_clk_1_p A48
        pin hdmi_clk_1_n A46
        pin hdmi_data_1_p[0] A54
        pin hdmi_data_1_n[0] A52
        pin hdmi_data_1_p[1] A60
        pin hdmi_data_1_n[1] A58
        pin hdmi_data_1_p[2] A66
        pin hdmi_data_1_n[2] A64

        pin hdmi_clk_2_p A47
        pin hdmi_clk_2_n A45
        pin hdmi_data_2_p[0] A53
        pin hdmi_data_2_n[0] A51
        pin hdmi_data_2_p[1] A59
        pin hdmi_data_2_n[1] A57
        pin hdmi_data_2_p[2] A65
        pin hdmi_data_2_n[2] A63
    }
}

Attributes

An attribute takes the following form.

ATTRIBUTE_NAME(attribute_value)

This assigns the value, attribute_value, to the attribute named ATTRIBUTE_NAME.

There are a handful of different attributes currently supported.

PINOUT

This attribute is either V2, V1, PT_ALPHA, or not specified.

When it is specified, it says that the pinout used for that pin should use that version's pin mapping.

When it isn't specified, the project's board's version is used. For example, an Au V1 will use V1.

Most of the time, if specified, it should match the board's version. However, if a V1 pinout is specified when using a V2 board, then the tools assume you are using a V2->V1 adapter. In this case, the tools will translate the pinout to the adapter's pinout.

If a V2 version is used with a V1 board an error is thrown.

The value PT_ALPHA is specifically for the first batch of Pt boards that had a pinout error. It is only valid when SIDE is set to TOP. The bottom pinout of the alpha boards should use a PINOUT of V2.

SIDE

Most boards only have ports on the top side. However, the Pt has pins on both sides.

To distinguish between the top and bottom, the SIDE attribute was added.

SIDE can have a value of TOP or BOTTOM. It defaults to TOP.

On the Pt, the top and bottom connectors both have banks A and B, and the pin names are identical. This means that a constraint file that works for the top of the board can be simply wrapped in a SIDE(BOTTOM) attribute block to use the board with the bottom connectors.

STANDARD

This specifies the IO standard to apply to the pin.

Most of the time, it will be set to LVCMOS33. This is the basic 3.3V IO standard. It is also the only standard supported by the Cu.

The Au and Pt both support the same IO standards. There are too many standards to list here, but page 98 of UG471 has a nice table summarizing the requirements for each standard.

Each IO standard has various requirements that must be met in order for it to be used. The biggest one is the Vcco voltage. All the pins on the Cu and most of the Au and Pt have Vcco fixed at 3.3V.

The Au and Pt have one group of pins that can have Vcco switched between 3.3V, 2.5V, and 1.8V. This drastically opens up the IO standards available on these pins.

For example, by setting Vcco to 2.5V, the tri-voltage pins can be used as LVDS_25 outputs or enable termination when used as inputs. Any pins on the Au/Pt can be used as LVDS_25 inputs as long as they don't use internal termination.

The other common requirement is the Vref voltage. Many standards don't require a specific Vref and for the ones that do, an internal reference can typically be used. However, only one Vref can be set for a bank of pins. Here, bank refers not to the connector's bank but rather the FPGA's internal bank.

In the Au's schematic, the bank number is the first number of the FPGA's IO signal names. On page 2, you can see the header's pinout as well as the associated pin banks for each signal. The banks are numbers like 14, 34, and 35.

All the IO standards used in a bank must have at most one Vref requirement.

FREQUENCY

This attribute marks the pin as a clock input with the given frequency.

The frequency value takes the form of a number followed by a frequency unit. The unit can be Hz, KHz, MHz, or GHz. For example, 100MHz.

Clock inputs should also be typically placed on a clock capable input pin. Xilinx (for the Au/Pt) calls these MRCC or SRCC pins. Lattice (for the Cu) calls these GBIN. You can look at each board's schematic to see what pins are clock capable inputs.

For V2 boards, pins A41, A42, A47, A48, B41, B42, and B47 are clock capable inputs.

The Au also includes B48.

The Pt also includes B24, B29, B30, B48, C41, C42, C47, C48, D41, D42, D47, and D48.

PULL

This attribute is used to enable a pin's pull-up or pull-down resistors.

For the Cu, UP is the only valid value.

For the Au/Pt, UP, DOWN, or KEEP are valid values.

UP enables a weak pull-up. DOWN enables a weak pull-down. KEEP enables a weak pull to the same value the pin currently is (0 -> pull-down, 1 -> pull-up).

DRIVE

The attribute specifies the drive strength of the pin in mA.

It is not supported by the Cu.

It is only valid when paired with specific IO standards. For the valid values of each standard, see table 1-56 on page 101 of UG471.

For LVCMOS33 on the Au/Pt, these are 4, 8, 12, or 16.

This number specifies the drive strength in mA and defaults to 12.

SLEW

This attribute specifies the slew rate of the pin and is only supported by the Au/Pt, not the Cu.

The slew rate is how fast the edge transitions.

It is only valid when paired with specific IO standards. For the valid values of each standard, see table 1-56 on page 101 of UG471.

For standards that support a slew rate, the valid values are FAST or SLOW with SLOW being the default.

Using a FAST slew rate may help with high speed signals but may also cause more power consumption and noise if not used carefully.

DIFF_TERM

The DIFF_TERM attribute specifies if internal differential termination should be enabled. It can have a value of TRUE or FALSE and defaults to FALSE.

It is only available with some STANDARD values on the Au and Pt. See UG471 for details on which ones.

It is most often used with LVDS_25 on the tri-voltage pins. Using internal termination requires that VCCO be set to 2.5V for the pins using it. Failing to set the tri-voltage pins correctly could damage the FPGA.

Pinouts

The available pins vary depending on your board, but they follow a standard format.

The pins broken out on the connectors are named by the bank letter followed by the pin number. For example, pin 2 on bank A is A2.

The V2 boards have two banks on top, A and B. The Pt has two more on the bottom. They're also called A and B but distinguished via the

The V1 boards have four banks, A, B, C, and D on top.

Check the schematic for the Cu V1, Au V1, Cu V2 or Au V2 for what pins are populated on the connectors.

In addition to the pins on the connectors, there are some special internal pin names.

All boards have the pins LED0-LED7, RESET, CLOCK, USB_RX, and USB_TX.

The Cu (V1 and V2) also have SPI_MOSI, SPI_MISO, SPI_SCK, and SPI_SS that connect to the configuration flash.

The Au (V1, V1+, and V2) and Pt also have SPI_D0-SPI_D3, SPI_SCK, and SPI_SS that connect to the configuration flash. There is also VP and VN which are special analog inputs.

The Pt also has C29 - C36 that connect to where the LED signals on the Au and Cu are broken out on the control connector. The LED signals aren't broken out on the Pt.

The Pt also has USB_D2 - USB_D7, USB_RXF, USB_TXE, USB_RD, USB_WR, and USB_SIWUI for using the FIFO-based interface with the FTDI chip. Note that what would be USB_D0 is USB_RX and USB_D1 is USB_TX.

Finally, there are DDR_DQ0-DDR_DQ15, DDR_DQS0_P, DDR_DQS0_N, DDR_DQS1_P, DDR_DQS1_N, DDR_DM0, DDR_DM1, DDR_ODT, DDR_RESET, DDR_BA0-DDR_BA2, DDR_CK_P, DDR_CK_N, DDR_CKE, DDR_CS, DDR_RAS, DDR_CAS, DDR_WE, DDR_A0-DDR_A13 for interfacing with the DDR3. You generally shouldn't specify these directly as the MIG core does it for you.

Native Constraints

Sometimes you may need to do something more advanced that isn't directly supported within the Alchitry Constraint Format. For those cases, you can use a native block.

The native block takes the following form.

native {
  // Native constraints here
}

The text inside the block will be inserted into the final constraint file mostly as is. This allows you to write XDC constraints for the Au or Pt and SDC constraints for the Cu.

Inside the native block, you have access to two helper functions. acf_pin() and acf_port().

acf_pin()

The acf_pin() function allows you to access the Alchitry pin converter inside the native block. This lets you use the names of the pins on the connectors instead of the FPGA's pin.

For example, acf_pin(A3), when used with the Au, will be replaced by N6 (the name of the FPGA pin).

If the native block is wrapped in an attribute block specifying a PINOUT or SIDE, that is taken into account during the translation.

acf_port()

The acf_port() function allows you to get the name of a top-level port. The name of the port in Lucid isn't always exactly the same in the translated files, and this function ensures you use the correct name.

For example, acf_port(clk) will be replaced with the name of the clk signal (most likely just clk).

The port should also include all the indexing. This is where translation often differs from Lucid to the final name.

For example, acf_port(led[4]) will be replaced with the correct port name for the led[4] signal.