# Gf Pinmap

> Board-aware pin mapping. Generates FPGA constraint files (.xdc/.pcf/.lpf/.cst) with correct pin assignments, I/O standards, and drive strength for target boards. Example: "map SPI to PMOD JA on Arty A7", "generate constraints for my iCEBreaker"

- Skill: `codejunkie99/gf-pinmap` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codejunkie99/gf-pinmap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/gf-pinmap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codejunkie99/gf-pinmap

---


# GF-Pinmap — Board-Aware Pin Mapping

## Workflow

1. **Identify board** — Check `.gateflow/project.yaml` target.board or ask user
2. **Check curated database first**:
   ```bash
   ls ${CLAUDE_PLUGIN_ROOT}/boards/<board>/board.yaml 2>/dev/null
   ```
3. **If board found**: Read board.yaml, generate constraint file
4. **If board NOT found**: Web search as fallback, require user confirmation
5. **Cross-reference** generated constraints with RTL port list
6. **Output** constraint file in correct format for target FPGA

## Curated Board Flow

1. Read `boards/<board>/board.yaml` for pin data
2. Read `boards/<board>/constraints.*` for template
3. Map RTL ports → board pins based on user's peripheral selection
4. Generate complete constraint file with:
   - PACKAGE_PIN
   - IOSTANDARD (from board.yaml)
   - DRIVE strength (default 12mA for outputs)
   - SLEW rate (default SLOW)
   - PULLUP for active-low signals

## Web Search Fallback

Only when board is NOT in curated database:

1. Search: `"<board name>" constraint file site:github.com`
2. Search: `"<board name>" pinout .xdc OR .pcf OR .lpf`
3. Present findings to user with WARNING:
   ```
   Found constraint data for <board> via web search.
   Source: <url>

   WARNING: This pin data has NOT been verified against the official
   board documentation. Incorrect pin assignments can damage hardware.

   Please review before applying:
   [show pin assignments]

   Apply these constraints? [Y/n]
   ```
4. NEVER auto-apply web-searched data

## Safety

- Never guess pin assignments
- Always include IOSTANDARD (missing = synthesis error or hardware damage)
- Check voltage bank compatibility
- Warn if mixing I/O standards in the same bank
- Active-low signals get PULLUP

## GATEFLOW-RESULT Format

```
---GATEFLOW-RESULT---
STATUS: PASS | FAIL | ERROR
FORMAT: xdc | pcf | lpf | cst
BOARD: <board name>
PINS_MAPPED: <count>
PINS_UNMAPPED: <count>
FILE: <constraint file path>
DETAILS: <summary>
---END-GATEFLOW-RESULT---
```

## I/O Standard Reference

| IOSTANDARD | Voltage | Max Speed | Typical Use |
|---|---|---|---|
| LVCMOS33 | 3.3V | ~100 MHz | GPIO, LEDs, UART, SPI |
| LVCMOS25 | 2.5V | ~150 MHz | Mixed-voltage |
| LVCMOS18 | 1.8V | ~200 MHz | Modern peripherals |
| LVDS_25 | 2.5V diff | ~1 Gbps | High-speed serial |
| SSTL15 | 1.5V | ~800 MHz | DDR3 |
| TMDS_33 | 3.3V | ~750 Mbps | HDMI/DVI |

## Common Pin Mapping Mistakes

1. **Missing IOSTANDARD** -> Defaults may damage hardware. Always specify.
2. **Mixing I/O standards in same bank** -> All pins in a bank share VCCO.
3. **Floating inputs** -> Add PULLUP/PULLDOWN to unused inputs.
4. **No termination on high-speed** -> Use ODT for DDR, 100-ohm for LVDS.
5. **Wrong DRIVE strength** -> 4mA for LEDs, 8-12mA for SPI.
6. **Forgetting create_clock** -> No timing analysis without it.

## PMOD Mapping Patterns

Standard PMOD pinout: pins 1-4 (top row I/O), 5 (GND), 6 (VCC), 7-10 (bottom row I/O), 11 (GND), 12 (VCC).

| PMOD Type | Pin 1 | Pin 2 | Pin 3 | Pin 4 |
|---|---|---|---|---|
| Type 2 (SPI) | CS_N | MOSI | MISO | SCLK |
| Type 3 (UART) | CTS | TXD | RXD | RTS |
| Type 6 (I2C) | SCL | SDA | INT_N | RST_N |