RTL Bench PRO
Open RTL Bench →

FPGA Pin Mapping Guide

Connect your synthesizable top-level RTL ports to board oscillators, push-buttons, LEDs, and external PMOD headers using physical constraint files.

Why Physical Constraints Matter

Synthesis translates Verilog and VHDL code into generic Look-Up Tables (LUTs) and flip-flops. However, the Place and Route tool (such as nextpnr) needs explicit instructions on which physical package pins correspond to your inputs and outputs. Without pin constraints, the tool randomly binds I/O signals, preventing your board peripherals from working.

Constraint File Formats

  • Gowin Physical Constraints (.cst): Used by Gowin LittleBee devices (Tang Nano 9K, Tang Nano 20K).
  • Lattice Physical Constraints (.pcf): Standard format for iCE40 FPGAs (iCE40UP5K breakout boards).
  • Logical Preference Files (.lpf): Standard syntax for Lattice ECP5 boards.

Example Gowin CST File (Tang Nano 9K)

The snippet below maps an active-low reset button, onboard 27 MHz clock, and dual output LEDs: 

// Tang Nano 9K Physical Constraints (tang_nano_9k.cst)
IO_LOC "sys_clk" 52;
IO_PORT "sys_clk" IO_TYPE=LVCMOS33 PULL_MODE=UP;

IO_LOC "rst_n" 4;
IO_PORT "rst_n" IO_TYPE=LVCMOS33 PULL_MODE=UP;

IO_LOC "led[0]" 10;
IO_PORT "led[0]" IO_TYPE=LVCMOS33 DRIVE=8;

IO_LOC "led[1]" 11;
IO_PORT "led[1]" IO_TYPE=LVCMOS33 DRIVE=8;
💡 Pull-Up Resistors: Always specify PULL_MODE=UP for mechanical push-buttons that switch to ground when pressed to prevent floating input pins.

Frequently asked questions

What is an FPGA pin mapping file?

A pin mapping constraint file binds top-level HDL port names (such as clk, led[0], btn) to specific physical ball/pin package identifiers on the FPGA chip (e.g., pin 38 or pin C4).

What happens if an output port is mapped to an incompatible pin?

Assigning an output to a dedicated input-only pin, an analog reference pin, or a pin with mismatched voltage bank levels will cause nextpnr place-and-route to fail with a design rule check (DRC) error.

How does RTL Bench safeguard against invalid pin assignments?

RTL Bench validates user pin constraints against known board package pinouts and automatically falls back to safe default pin configurations when illegal mappings are detected.

Next

Try it in the workbench →