CPLD-FPGA Toolkit

A set of AI agent skills backed by a MegaMemory knowledge graph that teach your coding assistant (GitHub Copilot, Google Antigravity) how to design programmable logic circuits. Describe what you want in plain English — the AI generates, validates, compiles, and simulates the design.

The toolkit has three layers:

• .github/skills/ — agent skills with instructions, schemas, scripts, and idiom libraries
• .megamemory/knowledge.db — persistent knowledge graph (MegaMemory MCP) with 180+ verified facts about CPLD/FPGA architecture, device profiles, pinouts, and design patterns
• AGENTS.md — operational directives that guide the AI agent's behavior, evidence discipline, and toolchain usage

CPLD side — targets Atmel/Microchip ATF15xx and GAL/ATF families using WinCUPL (CUPL language). Generates .PLD source, compiles with the WinCUPL fitter, and runs CSIM simulation with test vectors.

FPGA side — targets iCE40, ECP5, and Gowin FPGAs using iCEstudio (Verilog). Generates .ice project files that can be opened directly in iCEstudio, synthesizes with yosys/nextpnr, and programs hardware.

Table of Contents

• CPLD-FPGA Toolkit
  • Table of Contents
  • Features
    • CPLD Design (WinCUPL/CUPL)
    • FPGA Design (iCEstudio/Verilog)
    • Cross-Domain
  • Supported Devices
    • CPLD (via WinCUPL)
    • FPGA (via iCEstudio/apio)
  • Compatibility
  • Project Structure
  • Quick Start
  • Installation
    • GitHub Copilot (VS Code)
    • MegaMemory Setup
    • Prerequisites
  • How It Works
    • CPLD Workflow
    • FPGA Workflow
  • Supported Workflows
  • Idiom Libraries
    • CUPL Idiom Library (17 idioms)
    • Verilog Idiom Library (121 idioms)
    • 74xx Reference (20 ICs)
  • Requirements
  • Troubleshooting
  • Limitations
  • Related Projects
  • Contributing
  • License
  • Support

Features

CPLD Design (WinCUPL/CUPL)

• Natural-language to CUPL — describe logic in plain English, get validated CUPL source
• Automatic pin validation — checks every pin against device pinouts (power/JTAG/ISP detection)
• ISP vs non-ISP awareness — JTAG pins locked on ISP variants, available as I/O on non-ISP
• 74xx glue logic consolidation — replace multiple discrete ICs with one CPLD
• Multi-component systems — generate and compile multi-file CUPL projects
• CSIM simulation — functional verification with test vectors
• 17 CUPL idioms — verified patterns for combinational, registered, sequenced, and memory-mapped logic
• 20 74xx IC references — truth tables and CUPL equivalents for common logic ICs

FPGA Design (iCEstudio/Verilog)

• Natural-language to Verilog — describe behavior, get synthesizable Verilog in .ice projects
• Component and project modes — generate reusable blocks (virtual ports, nested hierarchies) or board-level designs (physical pins)
• Hierarchical composition — generic blocks with recursive dependencies, collection imports, parameter overrides
• 121 Verilog idioms — across 13 categories (combinational, sequential, memory, CDC, FSM, CPU/ALU, protocols, anti-patterns)
• Communication protocols — SPI master/slave, UART TX/RX, I2C master/slave, PS/2, VGA, TMDS
• Utility patterns — debounce, LFSR, CRC-8, watchdog timer, round-robin arbiter
• Advanced patterns — AXI-Stream, generate-conditional variants, TMR register files, RISC-V register file
• Board rules auto-fill — automatic pin assignment from board definitions
• Visual components — generate reusable .ice blocks with SVG icons
• Synthesis/PnR — yosys → nextpnr-ice40/nextpnr-ecp5/nextpnr-gowin → bitstream pipeline
• Hardware programming — program FPGA boards directly (with attached hardware)

Cross-Domain

• Persistent knowledge graph — MegaMemory stores 180+ verified facts about device architectures, pinouts, design patterns, and toolchain behavior, used as reference when generating designs
• Shared design patterns — best practices that apply to both CPLD and FPGA design (FSM decomposition, bus ownership, capture/controller pipelines)
• Evidence-based verification — every design step reports its own pass/fail status; the toolkit never claims a design is "working" unless it passed the actual compiler/simulator
• Device architecture reference — detailed comparison of ATF1500A/1502/1504/1508/2500C families (macrocells, packages, extensions)
• Pinout database — 39 verified pin maps covering GAL, ATF750, ATF1500/1502/1504/1508, and ATF2500 families

Supported Devices

CPLD (via WinCUPL)

Family	Macrocells	Packages	Fitter
GAL16V8/ATF16V8	8	SOIC20, TSSOP20, PDIP20, PLCC20	built into WinCUPL
GAL22V10/ATF22V10	10	TSSOP24, DIP24, SOIC24, LCC28, PLCC28	built into WinCUPL
ATF750C	10	CerDIP24, PDIP24, SOIC24, TSSOP24, CLCC28, PLCC28	built into WinCUPL
ATF1500A	32	PLCC44, TQFP44	fit1500.exe
ATF1502	32	PLCC44, TQFP44	fit1502.exe
ATF1504	64	PLCC44, TQFP44, PLCC84, TQFP100	fit1504.exe
ATF1508	128	PLCC84, PQFP100, TQFP100, LQFP128	fit1508.exe
ATF2500C	24	DIP40, PLCC44	built into WinCUPL

All ATF15xx families support ISP (in-system programming) variants with JTAG.

FPGA (via iCEstudio/apio)

Family	Toolchain	Synthesis	PnR	Notes
iCE40 LP (1K/8K)	apio + oss-cad-suite	yosys	nextpnr-ice40	Low-power variant
iCE40 HX (1K/8K)	apio + oss-cad-suite	yosys	nextpnr-ice40	High-performance variant
iCE40 UP5K	apio + oss-cad-suite	yosys	nextpnr-ice40	Ultra-plus with SPRAM/DSP
iCE40 UL1K	apio + oss-cad-suite	yosys	nextpnr-ice40	Ultra-low power
iCE40 U4K	apio + oss-cad-suite	yosys	nextpnr-ice40	Ultra-low power
Lattice ECP5	apio + oss-cad-suite	yosys	nextpnr-ecp5	1.25K–85K LUTs, DDR3
Gowin GW1NR-9	apio + oss-cad-suite	yosys	nextpnr-gowin	Tang Nano 9K
Gowin GW1NZ-1K	apio + oss-cad-suite	yosys	nextpnr-gowin	Tang Nano 1K
Gowin GW2A-18	apio + oss-cad-suite	yosys	nextpnr-gowin	Tang Nano 20K
Gowin GW5A-25	apio + oss-cad-suite	yosys	nextpnr-gowin	Tang Nano 4K

91 board definitions from iCEstudio community catalog (with pinouts, constraints, and board rules).

Compatibility

The toolkit uses the open Agent Skills standard — a convention for teaching AI coding assistants new capabilities. Skills are self-contained folders with instructions, schemas, scripts, and examples that the AI coding assistant uses at runtime.

The knowledge layer uses MegaMemory — a persistent knowledge graph accessible to the AI coding assistant via MCP (Model Context Protocol). It provides device profiles, pinout data, design patterns, and verified facts used when generating designs.

Component	Purpose	Access
.github/skills/	Agent instructions, scripts, idiom libraries	File system (auto-detected)
.megamemory/knowledge.db	Verified CPLD/FPGA knowledge graph	MegaMemory MCP via proxy
AGENTS.md	Operational directives for the AI agent	File system (auto-detected)

AI Tool	Skill Path	Status
GitHub Copilot (VS Code)	.github/skills/	✅ Native support
Google Antigravity	.agents/skills/	✅ Native support

Project Structure

For developers and contributors — the skills are organized as follows:

.github/skills/
├── wincupl-cpld-generation/          # CPLD design skill
│   ├── SKILL.md                      # Main agent instructions
│   ├── schemas/                      # CUPL spec schemas
│   ├── examples/
│   │   ├── cupl_idiom_library.md     # 17 CUPL idioms
│   │   ├── 74xx_reference.md         # 20 74xx IC references
│   │   └── *.example.json            # Validation fixtures
│   ├── references/
│   │   ├── device_profiles.json      # 28 device profiles
│   │   ├── package_pinouts.json      # 39 pinout entries
│   │   └── *.md                      # CUPL language, timing, power refs
│   ├── scripts/
│   │   ├── generate_cupl.py          # JSON spec → CUPL .PLD
│   │   ├── build_cupl.py             # .PLD → compile → .abs
│   │   ├── simulate_cupl.py          # .PLD → CSIM simulation
│   │   └── validate_cupl_spec.py     # Spec validation + pin checking
│   └── evals/                        # Automated test fixtures
├── icestudio-fpga-generation/        # FPGA design skill
│   ├── SKILL.md
│   ├── examples/
│   │   └── verilog_idiom_library.md  # 121 Verilog idioms
│   ├── schemas/
│   └── scripts/
├── icestudio-fpga-analysis/          # FPGA analysis skill
├── programmable-logic-shared-knowledge/  # Cross-domain patterns
└── ...                               # Other skills

.megamemory/
└── knowledge.db                      # Persistent knowledge graph (180+ nodes)

AGENTS.md                             # Operational directives for the AI agent

Quick Start

Example 1 — CPLD (WinCUPL):

"Create a 4-bit binary counter with asynchronous reset for ATF1504 in TQFP44 package"

The AI generates a validated CUPL specification, compiles it with WinCUPL, and runs CSIM simulation — reporting pass/fail evidence at each step.

Example 2 — FPGA (iCEstudio):

"Make a PWM controller with 8-bit resolution for the iCE40-HX8K board"

The AI generates an iCEstudio .ice project with Verilog code, validates pin assignments against the board's real pinout, synthesizes with yosys/nextpnr, and optionally programs the FPGA.

Example 3 — 74xx replacement (CPLD):

"Replace 74HC161 + 74HC153 + 74HC74 with a single ATF1502"

The AI consolidates multiple discrete logic ICs into one CPLD design, preserving the original pin-compatible interface.

Installation

GitHub Copilot (VS Code)

1. Clone this repository into your project workspace — this gives you the complete system: skills, knowledge graph, and agent directives:

   git clone https://github.com/michpro/CPLD-FPGA_Toolkit.git

   Note: Copying only the .github/skills/ folder will work for basic CPLD/FPGA generation, but without AGENTS.md (operational directives) and .megamemory/knowledge.db (verified device profiles and design patterns) the toolkit will have significantly less knowledge and weaker evidence discipline.

2. The skills are automatically detected when you open the workspace in VS Code.

3. Install the MegaMemory MCP server to give the agent access to the knowledge graph. See MegaMemory setup below.

4. Start a chat with GitHub Copilot and describe what you want to build.

External tools (WinCUPL, iCEstudio, apio) are prompted for at runtime when needed.

MegaMemory Setup

MegaMemory is a persistent knowledge graph that stores verified CPLD/FPGA facts (device profiles, pinouts, design patterns). It is used as a reference when generating designs.

The problem: MegaMemory's default MCP server stores its database in the user's home directory (c:\Users\<you>\.megamemory\knowledge.db), not in the project workspace. This means each workspace should have its own knowledge base.

The solution: A proxy script intercepts the MCP initialize message, extracts the workspace path from the MCP protocol parameters, and redirects the database to <workspace>/.megamemory/knowledge.db. The proxy tries multiple strategies to find the workspace (MCP rootUri, workspaceFolders, environment variables, VS Code workspace storage) and falls back to the default location if none match.

Step 1 — Install MegaMemory globally:

npm install -g megamemory

Step 2 — Download the proxy script from this Gist and save it to c:\Users\<you>\AppData\Roaming\Code\User\megamemory_mcp_proxy.js (replace <you> with your Windows username).

Step 3 — Configure VS Code MCP in %APPDATA%\Code\User\mcp.json:

{
    "servers": {
        "megamemory": {
            "command": "node",
            "args": [
                "c:\\Users\\<you>\\AppData\\Roaming\\Code\\User\\megamemory_mcp_proxy.js"
            ],
            "env": {}
        }
    }
}

Replace <you> with your Windows username. If you already have other MCP servers configured, add the megamemory entry to the existing servers object.

Step 4 — Verify — open the CPLD-FPGA workspace in VS Code, start a Copilot chat, and ask "what do you know about ATF1504?". If MegaMemory is working, the response will reference device profiles from the knowledge graph.

Debugging — the proxy writes a log to c:\Users\<you>\.megamemory\proxy_debug.log showing which workspace resolution strategy was used and the final database path.

Prerequisites

For CPLD workflows (WinCUPL):

• WinCUPL II — native Windows application (Windows 10/11). Install it and note the installation path — you will be prompted for it when using CPLD features. See WinCUPL II on Microchip.com.-us/development-tool/wincupl).

For FPGA workflows (iCEstudio):

• iCEstudio — graphical IDE for iCE40/ECP5/Gowin FPGAs. The toolkit generates .ice project files (JSON 1.2 format) that can be opened directly in iCEstudio. Two generation modes are supported:
  • Component mode — reusable blocks with virtual ports, nested hierarchies, and generic dependencies. These can be imported into other iCEstudio projects as building blocks.
  • Project mode — board-level designs with physical pin assignments, ready for synthesis and programming. The iCEstudio installation path is needed to resolve board metadata (pinout.json, info.json, rules.json) for physical pin validation. See the iCEstudio project format documentation for details.

Python 3.9+ — required for FPGA synthesis scripts and toolchain management:

python -m venv .venv
# Windows:
.venv\Scripts\python.exe -m pip install apio pyarrow
# Linux/macOS:
.venv/bin/python3 -m pip install apio pyarrow

FPGA toolchain (for synthesis/PnR):

.venv\Scripts\python.exe -m apio packages install

How It Works

CPLD Workflow

You describe the logic → AI validates the design → AI generates CUPL source
    → WinCUPL compiles + fits → CSIM simulates → pass/fail evidence

1. Describe — tell the AI what logic you need (e.g. "4-bit counter with reset")
2. Validate — the toolkit checks pin assignments, device compatibility, and CUPL rules
3. Generate — produces a .PLD source file with pin declarations and logic equations
4. Compile — runs the WinCUPL compiler and ATF fitter (requires WinCUPL installed)
5. Simulate — runs CSIM with your test vectors to verify functional correctness
6. Evidence — each step reports its own status: valid, not_verified, or invalid

FPGA Workflow

You describe the behavior → AI validates the spec → AI generates .ice project
    → yosys synthesizes → nextpnr places & routes → bitstream ready

1. Describe — tell the AI what behavior you need (e.g. "SPI master, 10 MHz, mode 0")
2. Validate — the toolkit checks ports, board rules, and clock-domain crossings
3. Generate — produces an iCEstudio .ice project (component or project mode)
4. Synthesize — runs yosys + nextpnr for your target FPGA family
5. Program — uploads the bitstream to a connected FPGA board (optional)

Component mode generates reusable .ice blocks with virtual ports — these can be nested hierarchically and imported into other projects. Project mode generates board-level designs with physical pin assignments validated against the iCEstudio board catalog.

Supported Workflows

Workflow	CPLD	FPGA	Description
Combinational logic	✅	✅	Gates, muxes, decoders, adders
Sequential logic	✅	✅	Counters, registers, shift registers, FSMs
Memory	—	✅	RAM, ROM, FIFO (FPGA BRAM)
CDC synchronization	—	✅	2-FF sync, handshake, async FIFO
Communication protocols	—	✅	SPI, UART, I2C, PS/2, VGA, TMDS
74xx glue logic	✅	—	Consolidate discrete ICs into CPLD
Address decoding	✅	✅	Memory-mapped I/O, chip select
Bus ownership	✅	✅	OE control, turnaround, contention
Capture/controller	✅	✅	Frame buffer, sampled-data systems
Visual components	—	✅	Reusable .ice blocks with SVG

Idiom Libraries

The toolkit includes curated, tested code patterns ("idioms") that the AI uses as building blocks when generating designs. Each idiom is a complete, working example with known-good behavior.

CUPL Idiom Library (17 idioms)

Patterns for combinational logic, registered outputs, sequenced state machines, memory mappers, glue logic, and 74xx IC consolidation. All verified through WinCUPL compilation.

Verilog Idiom Library (121 idioms)

Category	Count	Examples
Combinational primitives	9	gates, buffers, tie-offs
Arithmetic units	14	adders, multipliers, subtractors
Sequential registers/counters	18	DFF, counters, shift registers, edge detectors
Combinational routing	14	muxes, encoders, decoders, comparators
Memory	6	RAM, ROM, FIFO
CDC/reset/datapath safety	10	synchronizers, reset, SIPO, Gray code
Advanced datapath	12	barrel shifter, popcount, PWM, arbiter
Communication protocols	10	SPI, UART, I2C, PS/2, VGA, TMDS
FSM	4	Moore, Mealy, one-hot, register-mapped
CPU/ALU	4	ALU, program counter, register file
Anti-patterns	11	latch inference, gated clock, blocking in clocked

74xx Reference (20 ICs)

Truth tables and CUPL equivalents for: 74HC00/04/08/32/86/74/138/139/151/153/157/161/163/164/165/193/283/244/245/595. Verified implementations for 74HC74, 74HC153, 74HC161, 74HC283.

Requirements

• AI coding assistant — GitHub Copilot in VS Code, or Google Antigravity (both support the Agent Skills standard)
• MegaMemory MCP (optional but recommended) — persistent knowledge graph with verified CPLD/FPGA facts; the agent works without it but with reduced knowledge. Requires Node.js and npm.
• Node.js (optional) — for MegaMemory MCP proxy script
• WinCUPL II (optional) — for CPLD compile/fit/simulate (Windows 10/11 only)
• iCEstudio (optional) — for FPGA board metadata and .ice project management
• Python 3.9+ — required for all toolkit scripts (CPLD validation/generation/simulation and FPGA synthesis)
• apio + oss-cad-suite (optional) — for FPGA synthesis/PnR (installed via pip)

Troubleshooting

Problem	Solution
WinCUPL not found	Install WinCUPL II and provide its installation path when prompted
Board pinout not found	Install iCEstudio and provide its installation path when prompted
Pin rejected as invalid	The toolkit validates pins against device pinouts — the pin may be a power, JTAG, or NC pin
ISP variant JTAG error	JTAG pins are locked on ISP variants — use non-ISP device or different pins
apio raw path errors on Windows	Use relative forward-slash paths (known apio bug with backslash paths)
STATUS_DLL_NOT_FOUND from FPGA tools	Don't call oss-cad-suite executables directly — the toolkit uses apio build internally
Agent doesn't know device profiles	Install MegaMemory and configure the proxy script — see MegaMemory Setup
MegaMemory database in wrong location	The proxy script redirects the database to <workspace>/.megamemory/ — verify mcp.json points to the proxy, not directly to megamemory

Limitations

• No timing closure guarantees — the toolkit verifies functional correctness (compile, simulate) but does not perform static timing analysis. Timing closure is the user's responsibility.
• No power analysis — the toolkit does not estimate or optimize power consumption.
• CPLD workflow is Windows-only — WinCUPL II runs natively on Windows 10/11. There is no Linux/macOS version.
• FPGA synthesis requires Python — the CPLD workflow is native Windows, but FPGA synthesis (yosys/nextpnr) requires Python 3.9+ and apio.
• Hardware programming requires physical access — the toolkit can generate bitstreams, but programming an actual FPGA board requires the board to be connected via USB.
• AI-generated code needs review — the toolkit generates validated designs, but human review is recommended for production use. The idiom libraries provide tested patterns, but novel designs may have edge cases.
• Board metadata is installation-specific — pin assignments and board rules come from the user's local iCEstudio installation, not from the toolkit itself.
• MegaMemory is optional — the toolkit works without the MegaMemory MCP server, but with less knowledge about device profiles, pinouts, and design patterns. Install MegaMemory for the best experience.

Related Projects

• iCEstudio — Visual editor for iCE40/ECP5/Gowin FPGAs; the toolkit generates .ice project files compatible with iCEstudio's project format (community GitHub)
• WinCUPL II — CUPL compiler for Atmel CPLDs (direct download) — runs on Windows 10 and 11
• apio — FPGA toolchain manager
• yosys — Open-source synthesis suite
• MegaMemory — Persistent knowledge graph for AI agents (MCP server)
• Agent Skills — Open standard for AI agent capabilities

Contributing

Bug reports and improvement suggestions are welcome. Create an issue on GitHub.

License

Copyright © 2026 Michal Protasowicki

This project is licensed under the MIT License.

Author: Michał Protasowicki

Support

If you find this project useful and would like to support my work: