t27.aiРусский

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.

Open the interactive lesson →

Pin map: the XC7A200T FGG676 package ball by ball, with an XDC lint
Pin map: the XC7A200T FGG676 package ball by ball, with an XDC lint ↗

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
}

Open the lesson's spec in the player ↗

All lessons