Pins, balls and the package
You will learn
How the signals of your design reach the outside world.
A chip sits in a package: on our AX7203 board the XC7A200T is in the 484-ball FBG484. The pin map draws the same die in the 676-ball FGG676 package of the Wukong board. Some balls carry power or configuration and only some are user IO, grouped into banks with their own voltage. A constraints file (XDC) says which ball each signal of your design uses. Put a signal on a ball that is not user IO and the build fails, or worse, the board does not do what you think.
Try it
Search for a ball name like E3, then colour by pin type and find a ball that is not user IO. The spec frame pins a small design to another package, the XC7A100T in CSG324: find the test that puts its clock on ball E3, and the one that counts its pins.

All 676 balls of the XC7A200T FGG676 by bank and type, with our board's pins on top. Paste or drop an XDC: it is linted in your browser and sent nowhere.
specs/boards/xc7a100t_minimal.t27
// SPDX-License-Identifier: Apache-2.0
// t27/specs/boards/xc7a100t_minimal.t27
// QMTECH XC7A100T-CSG324 Minimal Board Profile
// Heartbeat LED + UART loopback, prjxray-verified pins only
// phi^2 + 1/phi^2 = 3 | TRINITY
module BoardMinimalXC7A100T {
use base::types;
use base::ops;
const BOARD_NAME : &str = "QMTECH XC7A100T-CSG324";
const FPGA_FAMILY : &str = "artix7";
const FPGA_PART : &str = "xc7a100tcsg324-1";
const CLOCK_FREQ_HZ : u32 = 12_000_000;
const CLOCK_PERIOD_NS : u32 = 83;
const IO_STANDARD : &str = "LVCMOS33";
const CONFIG_VOLTAGE : &str = "3.3";
const NUM_LEDS : usize = 8;
const HAS_UART : bool = true;
const HAS_SPI : bool = false;
const HAS_MAC_DEBUG : bool = false;
struct PinAssignment {
port_name : &str,
package_pin : &str,
iostandard : &str,
is_clock : bool,
is_input : bool,
is_output : bool,
bank : u8,
}
struct ClockConstraint {
port_name : &str,
period_ns : u32,
waveform_high_ns : u32,
freq_hz : u32,
}
const PIN_CLK : PinAssignment = PinAssignment{
.port_name = "clk",
.package_pin = "E3",
.iostandard = "LVCMOS33",
.is_clock = true,
.is_input = true,
.is_output = false,
.bank = 0,
};
const PIN_RST_N : PinAssignment = PinAssignment{
.port_name = "rst_n",
.package_pin = "C18",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = true,
.is_output = false,
.bank = 0,
};
const PIN_UART_RX : PinAssignment = PinAssignment{
.port_name = "uart_rx",
.package_pin = "T14",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = true,
.is_output = false,
.bank = 0,
};
const PIN_UART_TX : PinAssignment = PinAssignment{
.port_name = "uart_tx",
.package_pin = "T15",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 0,
};
const PIN_LED_0 : PinAssignment = PinAssignment{
.port_name = "led[0]",
.package_pin = "H17",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_1 : PinAssignment = PinAssignment{
.port_name = "led[1]",
.package_pin = "K15",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_2 : PinAssignment = PinAssignment{
.port_name = "led[2]",
.package_pin = "J13",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_3 : PinAssignment = PinAssignment{
.port_name = "led[3]",
.package_pin = "N14",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_4 : PinAssignment = PinAssignment{
.port_name = "led[4]",
.package_pin = "R18",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_5 : PinAssignment = PinAssignment{
.port_name = "led[5]",
.package_pin = "U18",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_6 : PinAssignment = PinAssignment{
.port_name = "led[6]",
.package_pin = "T13",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const PIN_LED_7 : PinAssignment = PinAssignment{
.port_name = "led[7]",
.package_pin = "T11",
.iostandard = "LVCMOS33",
.is_clock = false,
.is_input = false,
.is_output = true,
.bank = 1,
};
const CLOCK_SYS : ClockConstraint = ClockConstraint{
.port_name = "clk",
.period_ns = 83,
.waveform_high_ns = 41,
.freq_hz = 12_000_000,
};
var all_pins : [12]PinAssignment = [
PIN_CLK, PIN_RST_N, PIN_UART_RX, PIN_UART_TX,
PIN_LED_0, PIN_LED_1, PIN_LED_2, PIN_LED_3,
PIN_LED_4, PIN_LED_5, PIN_LED_6, PIN_LED_7,
];
var clocks : [1]ClockConstraint = [CLOCK_SYS];
fn count_pins() -> usize {
return 12;
}
fn count_clocks() -> usize {
return 1;
}
fn count_leds() -> usize {
return 8;
}
fn has_uart() -> bool {
return HAS_UART;
}
fn has_spi() -> bool {
return HAS_SPI;
}
fn is_prjxray_verified(pin: PinAssignment) -> bool {
if (pin.package_pin == "E3") { return true; }
if (pin.package_pin == "C18") { return true; }
if (pin.package_pin == "T14") { return true; }
if (pin.package_pin == "T15") { return true; }
if (pin.package_pin == "H17") { return true; }
if (pin.package_pin == "K15") { return true; }
if (pin.package_pin == "J13") { return true; }
if (pin.package_pin == "N14") { return true; }
if (pin.package_pin == "R18") { return true; }
if (pin.package_pin == "U18") { return true; }
if (pin.package_pin == "T13") { return true; }
if (pin.package_pin == "T11") { return true; }
return false;
}
fn find_pin_by_port(name: &str) -> PinAssignment {
var i : usize = 0;
while (i < count_pins()) {
if (all_pins[i].port_name == name) {
return all_pins[i];
}
i = i + 1;
}
return PinAssignment{
.port_name = "",
.package_pin = "",
.iostandard = "",
.is_clock = false,
.is_input = false,
.is_output = false,
.bank = 0,
};
}
test board_name_set
given name = BOARD_NAME
then name == "QMTECH XC7A100T-CSG324"
test fpga_family_artix7
given family = FPGA_FAMILY
then family == "artix7"
test clock_freq_12mhz
given freq = CLOCK_FREQ_HZ
then freq == 12_000_000
test clock_period_83ns
given period = CLOCK_PERIOD_NS
then period == 83
test num_leds_is_8
given n = NUM_LEDS
then n == 8
test has_uart_true
given result = has_uart()
then result == true
test has_spi_false
given result = has_spi()
then result == false
test has_mac_debug_false
given result = HAS_MAC_DEBUG
then result == false
test count_pins_is_12
given n = count_pins()
then n == 12
test count_clocks_is_1
given n = count_clocks()
then n == 1
test pin_clk_is_e3
given pin = PIN_CLK
then pin.package_pin == "E3" and pin.is_clock == true and pin.is_input == true
test pin_rst_n_is_c18
given pin = PIN_RST_N
then pin.package_pin == "C18" and pin.is_input == true and pin.is_clock == false
test pin_uart_rx_is_t14
given pin = PIN_UART_RX
then pin.package_pin == "T14" and pin.is_input == true
test pin_uart_tx_is_t15
given pin = PIN_UART_TX
then pin.package_pin == "T15" and pin.is_output == true
test pin_led0_is_h17
given pin = PIN_LED_0
then pin.package_pin == "H17" and pin.is_output == true and pin.port_name == "led[0]"
test pin_led7_is_t11
given pin = PIN_LED_7
then pin.package_pin == "T11" and pin.port_name == "led[7]"
test clock_sys_period_matches_freq
given clk = CLOCK_SYS
then clk.freq_hz == 12_000_000 and clk.period_ns == 83 and clk.port_name == "clk"
test find_clk_pin
given pin = find_pin_by_port("clk")
then pin.package_pin == "E3"
test find_uart_tx_pin
given pin = find_pin_by_port("uart_tx")
then pin.package_pin == "T15"
test find_nonexistent_pin_returns_empty
given pin = find_pin_by_port("nonexistent")
then pin.package_pin == ""
test all_pins_prjxray_verified
given pin = PIN_CLK
and verified = is_prjxray_verified(pin)
then verified == true
test rst_n_pin_prjxray_verified
given pin = PIN_RST_N
and verified = is_prjxray_verified(pin)
then verified == true
test all_led_pins_prjxray_verified
given v0 = is_prjxray_verified(PIN_LED_0)
and v1 = is_prjxray_verified(PIN_LED_1)
and v2 = is_prjxray_verified(PIN_LED_2)
and v3 = is_prjxray_verified(PIN_LED_3)
and v4 = is_prjxray_verified(PIN_LED_4)
and v5 = is_prjxray_verified(PIN_LED_5)
and v6 = is_prjxray_verified(PIN_LED_6)
and v7 = is_prjxray_verified(PIN_LED_7)
then v0 and v1 and v2 and v3 and v4 and v5 and v6 and v7
invariant board_name_not_empty
assert BOARD_NAME != ""
invariant fpga_family_not_empty
assert FPGA_FAMILY != ""
invariant fpga_part_not_empty
assert FPGA_PART != ""
invariant clock_freq_positive
assert CLOCK_FREQ_HZ > 0
invariant clock_period_positive
assert CLOCK_PERIOD_NS > 0
invariant io_standard_is_lvcmos33
assert IO_STANDARD == "LVCMOS33"
invariant all_clocks_have_period
given clk = CLOCK_SYS
assert clk.period_ns > 0 and clk.freq_hz > 0
invariant minimal_no_spi
assert HAS_SPI == false
invariant minimal_no_mac_debug
assert HAS_MAC_DEBUG == false
invariant led_count_matches_pin_count
given n = count_leds()
assert n == NUM_LEDS and n == 8
invariant total_pin_count_consistent
given n = count_pins()
assert n == 4 + NUM_LEDS
invariant clk_is_clock_input
given pin = PIN_CLK
assert pin.is_clock == true and pin.is_input == true
invariant uart_direction_correct
given rx = PIN_UART_RX
and tx = PIN_UART_TX
assert rx.is_input == true and tx.is_output == true
invariant led_pins_are_output
given p0 = PIN_LED_0.is_output
and p7 = PIN_LED_7.is_output
assert p0 == true and p7 == true
invariant config_voltage_matches_iostandard
assert CONFIG_VOLTAGE == "3.3"
bench find_pin_latency
measure: nanoseconds to find_pin_by_port("uart_tx")
target: < 1000ns
bench prjxray_verify_latency
measure: nanoseconds to is_prjxray_verified(PIN_CLK)
target: < 100ns
}
All lessons
Module 1 · The chip
What an FPGA is, which chip we use, and how its pins meet the board.
Module 2 · Numbers in hardware
Bits, trits and number formats, and what arithmetic costs in logic.
Module 3 · Your t27 program
Write a spec, test it, and see why compiling is not the same as being right.
Module 4 · Inside t27c
How the compiler reads a spec and what it writes, including the native t27b.
Module 5 · From spec to hardware
The Verilog t27c writes, the cells it becomes, and what one LUT does.
Module 6 · Reading synthesis
What yosys reports about your design, and which warnings matter.
Module 7 · Place, route, timing
Where the cells land on the die, and whether the clock is met.
Module 8 · The bitstream
How a routed design becomes the bits the chip loads, with no Vivado.
Module 9 · On the board
Ask the chip who it is, load the bits, and check them.