# TALOS-V2: microGPT in fixed-point Verilog on a DE1-SoC board

> TALOS-V2 is an Apache 2.0 licensed Verilog project that implements Karpathy's microGPT language model in RTL for the DE1-SoC Cyclone V FPGA, with fixed-point weight ROMs, a hardware sampler, JTAG driven inference and a ModelSim testbench. The judgement is that it is a complete hardware workflow rather than a paper implementation, and that its licensing splits cleanly between the original RTL and the third party artefacts the repository carries.

**Luthiraa/TALOS-V2** — hardware implementation of transformers running microgpt at 50k+ tkps

- Repository: https://github.com/Luthiraa/TALOS-V2
- Stars: 782 · Forks: 106
- Language: Verilog
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/luthiraa-talos-v2

## A language model that runs on the board rather than on a GPU

TALOS-V2 is an RTL implementation of Karpathy's microGPT language model for the DE1-SoC, which is a Cyclone V FPGA board. The repository description puts a number on it, microgpt at more than fifty thousand tokens per second, and that claim is about the RTL sampler on the board rather than about a machine learning framework.

What the project contains is a full workflow rather than a single module. There is a SystemVerilog inference core, a DE1-SoC top level with switch, LED, HEX display and JTAG or MMIO control, fixed-point model weights stored as ROM hex files, an RTL sampler for hardware token generation, a ModelSim testbench for deterministic core simulation, and Python tools for JTAG inference, reference runs and weight export.

The hardware arithmetic is the design decision that shapes everything else. The RTL follows the microGPT transformer structure, but it uses fixed-point arithmetic and an RTL friendly sampler, and outputs are deterministic for the same seed and configuration. That determinism is what makes the hardware comparable to a software reference, which is the only sane way to validate a model that runs on a board.

There are no GitHub releases for the project, and the last push was on 2026-05-14.

## The tree separates synthesizable RTL from generated ROMs and host tools

The repository layout is the fastest way to understand the project, and it is laid out in one block:

```text
rtl/src/           Synthesizable RTL
rtl/src/include/   RTL include fragments
rtl/generated/     Fixed-point model ROM hex files
rtl/microgpt/      Saved model weights and training dataset
rtl/python/        Python host and reference utilities
rtl/tcl/           System Console and Quartus TCL scripts
rtl/sim/           ModelSim testbenches
rtl/ip/            JTAG-to-Avalon bridge IP
rtl/docs/          Additional notes and archived writeups
```

Three distinctions inside that layout matter.

The first is between rtl/src, which holds the synthesizable RTL, and rtl/generated, which holds the fixed-point ROM hex files produced from the model. One is source you edit, the other is output, and keeping them apart is what makes it possible to regenerate the weights without touching the design.

The second is rtl/microgpt, which holds the saved model weights and the training dataset. The trained artefact is kept with the hardware, so a new board configuration can be built from the same model without a Python training environment.

The third is rtl/ip, which holds the JTAG-to-Avalon bridge IP. That is the piece that lets the outside world drive the core, and it is the reason the inference path can be scripted rather than being poked at by hand.

## Four batch files take you from source to a programmed board

The commands are Windows batch files at the repository root, and they are meant to be run from there. The sequence covers the four stages:

```bat
run_core_sim.bat
compile_only.bat
program_fpga.bat
run_de1soc.bat
```

run_core_sim.bat runs the RTL simulation, compile_only.bat builds the FPGA project, program_fpga.bat programs the DE1-SoC, and run_de1soc.bat does the build and the programming in one step.

The toolchain behind those files is specific. The requirements are Intel Quartus Prime 18.1 Lite or a compatible Cyclone V toolchain, ModelSim Intel FPGA Edition, Python 3, and the DE1-SoC board itself for hardware inference. There is one environment wrinkle: if Quartus is not installed in a standard location, the QUARTUS_ROOTDIR variable has to be set before the build or programming scripts are run, because the scripts have to find the toolchain to drive it.

That is the practical cost of the project. The simulation path needs only the simulator and Python, while everything else assumes the vendor toolchain is installed and licensed.

## Inference runs over JTAG with a sampler, a seed and a step count

Driving the model is a script, and its arguments are the interesting part:

```bat
run_inference.bat --sampler rtl --steps 15 --temperature 0.5 --seed 2 --stream
```

The sampler choice picks the RTL sampler for hardware token generation, the step count sets how many tokens to produce, the temperature sets the sampling distribution, the seed fixes it, and the stream flag asks for incremental output.

The software counterpart is one command away:

```bat
reference_microgpt.bat --count 20 --temperature 0.5
```

That reference implementation exists so the hardware can be checked against something. Since the outputs are deterministic for the same seed and configuration, the RTL sampler and the Python reference should agree for the same seed and temperature, and the difference between them is the useful signal when something is wrong.

The local validation path is short as well, a core simulation and a unit test of the equivalence:

```bat
run_core_sim.bat
cd rtl\python
python -m unittest test_reference_equivalence.py
```

For hardware validation the README gives the longer route, rebuild the Quartus project, program the board, and run the JTAG inference command.

## Two switches and eight LEDs describe the state of the core

There is no display protocol to learn, because the board itself reports the state.

The inputs are two switches. SW0 is enable, and SW1 is reset, where a high level resets and a low level runs. That is enough to start and stop generation from the physical board while a JTAG session stays connected.

The outputs are more informative. LEDR0 means ready, LEDR1 means busy, LEDR2 means generation done and LEDR3 means JTAG activity. LEDR4 shows the reset is deasserted, LEDR5 shows the enable state and LEDR6 blinks while busy. LEDR7 through LEDR9 carry the low bits of the last sampled token, which gives a quick visual read of whether the sampler is producing anything at all.

The two four digit HEX displays carry the wider values. HEX0 and HEX1 show the last sampled token id, HEX2 and HEX3 show how many tokens have been generated, HEX4 shows the top-level state and HEX5 shows the switch state.

Together they give a debugging channel that does not depend on the JTAG log being readable, which is the point on a board whose serial output is often the thing that is not working.

## Weights are Q4.12 fixed-point ROM files with an export script

The model does not live in the RTL. It lives in ROM files, and the bridge between the two is a Python script.

The RTL uses Q4.12 fixed-point ROM hex files in rtl/generated/. To regenerate them from the saved model weights, the README gives one command:

```bat
cd rtl
python python\export_weights.py --weights microgpt\weights_only.npy --outdir generated
```

The inputs and outputs are both visible in that line. The source is a weights-only NumPy file from the microgpt directory, and the destination is the generated directory that the RTL reads at synthesis time.

Q4.12 is a fixed-point format with four integer bits and twelve fractional bits, which is the whole reason the design is deterministic: there is no floating-point rounding behaviour to reproduce, so the same weights file always produces the same ROM contents and therefore the same hardware behaviour. The tradeoff is that the arithmetic is not floating point, so the hardware model is not bit-identical to a float model, and the reference implementation and the equivalence test exist to measure how far apart they are.

For anyone extending the project, this is the seam where a different model or a different quantisation would be introduced.

## Apache 2.0 for the code, separate terms for the artefacts

The licensing section is more careful than most, and the split deserves reading before you copy anything.

The original TALOS-V2 source code, the RTL, the scripts, the configuration and the documentation are licensed under the Apache License, Version 2.0, with the LICENSE and NOTICE files in the repository.

The repository also contains files that are not covered by that grant. Third-party reference material, Intel and Altera FPGA IP or generated tool outputs, and model or dataset artefacts all carry separate ownership or licensing terms, and the README points at THIRD_PARTY_NOTICES.md, which is the file to read before redistributing the whole repository or using those artefacts outside local development and validation.

That distinction matters for two audiences. A hardware engineer reading the RTL is fine under the Apache grant. A company that wants to ship a board with the model ROMs and the dataset embedded has to clear the second set of terms, and the repository is explicit that the first grant does not cover it.

The root directory also holds a few loose ends, an info.md file, a main.c, a compile_monitor.log and a prebuilt microgpt_bos_start.exe, alongside the batch scripts and the rtl directory.

## Conclusion

TALOS-V2 fits an FPGA engineer who wants to see a small language model running on a board and needs the whole path from trained weights to a blinking LED, because the repository carries the RTL, the fixed-point weight export, the simulation testbench, the board scripts and a Python reference implementation to compare against. It is the wrong choice for anything larger than the demonstration it is, since the model is microGPT and the arithmetic is fixed-point Q4.12, and it is the wrong choice if you cannot obtain a DE1-SoC board, a Quartus Prime 18.1 toolchain and ModelSim, since the simulation path is the only part that runs without hardware. Before you use the artefacts, read THIRD_PARTY_NOTICES.md, because the repository states that the Intel and Altera FPGA IP, the generated tool outputs and the model and dataset files carry separate ownership, and check the deterministic behaviour with a fixed seed before you compare the hardware output against the Python reference.

## FAQ

### What is TALOS-V2?

It is an RTL implementation of Karpathy's microGPT language model for the DE1-SoC, a Cyclone V FPGA board. The project includes a SystemVerilog inference core, a DE1-SoC top level, fixed-point weight ROMs, an RTL sampler, a ModelSim testbench and Python host tools for JTAG inference, reference runs and weight export.

### What do I need to run TALOS-V2?

Intel Quartus Prime 18.1 Lite or a compatible Cyclone V toolchain, ModelSim Intel FPGA Edition, Python 3, and a DE1-SoC board for hardware inference. If Quartus is not installed in a standard location, set QUARTUS_ROOTDIR before running the build or programming scripts.

### How are the model weights stored?

As Q4.12 fixed-point ROM hex files in rtl/generated/. They can be regenerated from the saved model weights with python python\export_weights.py --weights microgpt\weights_only.npy --outdir generated, run from the rtl directory.

### Can I use TALOS-V2 without the FPGA board?

The simulation path works without hardware, through run_core_sim.bat, and the Python reference implementation and its equivalence unit test run separately under rtl\python. Everything else, the compile, the programming and the JTAG inference, needs the board.

## Sources

- [Issues](https://github.com/Luthiraa/TALOS-V2/issues)
- [License: Apache-2.0](https://github.com/Luthiraa/TALOS-V2/blob/main/LICENSE)
- [Luthiraa/TALOS-V2 on GitHub](https://github.com/Luthiraa/TALOS-V2)
- [README](https://github.com/Luthiraa/TALOS-V2/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/luthiraa-talos-v2