Constraints: XDC, Clocks & I/O Planning

# --- 1. Primary clocks ------------------------------------------------
#     Nothing else can be written until the clocks exist.
create_clock -period 10.000 -name sys_clk [get_ports sys_clk_p]

# --- 2. Generated / derived clocks ------------------------------------
#     MMCM and PLL outputs are automatic. Only hand-written dividers,
#     forwarded clocks and gated clocks need an explicit statement.

# --- 3. Clock relationships -------------------------------------------
set_clock_groups -asynchronous \
  -group [get_clocks sys_clk] \
  -group [get_clocks eth_rx_clk]

# --- 4. I/O delays ----------------------------------------------------
set_input_delay  -clock sys_clk -max 4.2 [get_ports {data_in[*]}]
set_input_delay  -clock sys_clk -min 1.1 [get_ports {data_in[*]}]

# --- 5. Timing exceptions (last - they refine everything above) ------
set_false_path -from [get_cells cfg_reg_reg[*]]
set_multicycle_path 4 -setup -from [get_cells slow_acc_reg[*]]
set_multicycle_path 3 -hold  -from [get_cells slow_acc_reg[*]]

# WRONG - if the pattern misses, this line does nothing, forever.
set_false_path -from [get_cells u_cfg/mode_reg[*]]

# RIGHT - fail loudly at constraint-read time.
set cfg_cells [get_cells -quiet u_cfg/mode_reg[*]]
if {[llength $cfg_cells] == 0} {
  error "XDC: u_cfg/mode_reg[*] matched no cells - check hierarchy names"
}
set_false_path -from $cfg_cells

# Vivado also flags misses on its own if you ask it to:
#   set_msg_config -id {Vivado 12-180} -new_severity ERROR
# (12-180 is "No valid object(s) found for ...")

# A 100 MHz single-ended clock arriving on a pin.
create_clock -period 10.000 -name sys_clk [get_ports sys_clk]

# The same, but declaring a 60/40 duty cycle: rise at 0, fall at 6 ns.
create_clock -period 10.000 -waveform {0.000 6.000} -name skewed_clk \
             [get_ports skewed_clk]

# A 125 MHz clock arriving on a differential pair - constrain the P side
# only. The IBUFDS is a single cell; constraining both pins creates two
# clocks on one buffer.
create_clock -period 8.000 -name gt_refclk [get_ports gt_refclk_p]

# A VIRTUAL clock: no netlist object at all. Used as the reference for
# I/O delays when the external device is clocked by something the FPGA
# never sees.
create_clock -period 10.000 -name virt_sys_clk

# 1. Fabric divider. (Volume 01 argued against these - but if a legacy
#    block has one, it must be constrained or STA sees no clock at all.)
create_generated_clock -name clk_div2 \
  -source [get_pins clk_div_reg/C] -divide_by 2 [get_pins clk_div_reg/Q]

# 2. Forwarded clock leaving the chip through an ODDR. The generated
#    clock is what the DOWNSTREAM device sees, so output delay must
#    reference this, not sys_clk.
create_generated_clock -name spi_sclk_out \
  -source [get_pins oddr_sclk/C] -divide_by 1 [get_ports spi_sclk]

# 3. Gated clock through BUFGCE. Same period, but a distinct clock
#    object so you can constrain the enable path separately.
create_generated_clock -name clk_gated \
  -source [get_pins bufgce_i/I] -divide_by 1 [get_pins bufgce_i/O]

# ==== INPUT: an ADC driving 12 bits into the FPGA ====================
#   ADC Tco  : 5.0 ns max, 1.5 ns min
#   Data trace: 0.8 ns max, 0.5 ns min
#   Clock trace: 0.6 ns max, 0.4 ns min
set_input_delay -clock sys_clk -max 5.4 [get_ports {adc_d[*]}]
set_input_delay -clock sys_clk -min 1.4 [get_ports {adc_d[*]}]

# ==== OUTPUT: the FPGA driving a DAC ================================
#   DAC setup : 2.0 ns,  DAC hold : 0.5 ns
#   Data trace: 0.9 ns max, 0.6 ns min
#   Clock trace: 0.7 ns max, 0.5 ns min
#
#   output_delay(max) =  Tsu + Tdata(max) - Tclk(min) = 2.0 + 0.9 - 0.5 = 2.4
#   output_delay(min) = -Th  + Tdata(min) - Tclk(max) = -0.5 + 0.6 - 0.7 = -0.6
set_output_delay -clock sys_clk -max  2.4 [get_ports {dac_d[*]}]
set_output_delay -clock sys_clk -min -0.6 [get_ports {dac_d[*]}]

# ==== Genuinely asynchronous pins ===================================
# A push-button, an LED, a DIP switch. These have no timing relationship
# to any clock. Constraining them with a made-up number is worse than
# excluding them - but they must be EXCLUDED EXPLICITLY, so that
# check_timing does not list them as unconstrained.
set_false_path -from [get_ports {btn[*] dip[*]}]
set_false_path -to   [get_ports {led[*]}]

# ---- basic single-ended pin -------------------------------------------
set_property PACKAGE_PIN E3        [get_ports sys_clk]
set_property IOSTANDARD  LVCMOS33  [get_ports sys_clk]

# ---- an output that drives a long trace -------------------------------
# DRIVE is in mA; SLEW trades edge rate against ground bounce and EMI.
set_property PACKAGE_PIN H5        [get_ports {led[0]}]
set_property IOSTANDARD  LVCMOS33  [get_ports {led[0]}]
set_property DRIVE       12        [get_ports {led[0]}]
set_property SLEW        SLOW      [get_ports {led[0]}]

# ---- a button that needs a pull-up ------------------------------------
set_property PACKAGE_PIN D9        [get_ports btn_n]
set_property IOSTANDARD  LVCMOS33  [get_ports btn_n]
set_property PULLUP      true      [get_ports btn_n]

# ---- a differential input pair ----------------------------------------
# Constrain the P side; Vivado derives N from the package. DIFF_TERM
# enables the on-die 100 ohm termination - omit it and you need a
# resistor on the board instead.
set_property PACKAGE_PIN U4        [get_ports gt_refclk_p]
set_property IOSTANDARD  LVDS_25   [get_ports gt_refclk_p]
set_property DIFF_TERM   true      [get_ports gt_refclk_p]

# ---- board-level configuration ----------------------------------------
# Omitting CFGBVS/CONFIG_VOLTAGE is the classic "DRC failed after a
# 40-minute route" error on 7-series parts.
set_property CFGBVS       VCCO  [current_design]
set_property CONFIG_VOLTAGE 3.3  [current_design]

# Tie unused pins low rather than leaving them floating inputs.
set_property BITSTREAM.CONFIG.UNUSEDPIN PULLDOWN [current_design]