Metadata-Version: 2.4
Name: devlab-fpga
Version: 0.1.8
Summary: FPGA development helper for installing OSS CAD Suite and running build/flash flows.
Author-email: Mrju10 <name@email.com>
License: MIT
Project-URL: Homepage, https://github.com/unit-electronics/unit_devlab_lib
Project-URL: Source, https://github.com/unit-electronics/unit_devlab_lib
Keywords: fpga,yosys,oss-cad-suite,openfpgaloader,devlab,devlab-fpga
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: license-file

# devlab

`devlab` is a Python CLI package for FPGA development. It installs the
matching OSS CAD Suite build for the current operating system, creates a small
FPGA project, and runs build/flash commands from `devlab.toml`.

## Install

```bash
pip install devlab-fpga
```

For local development from this repository:

```bash
pip install -e .
```

## Commands

```bash
devlab doctor
devlab install
devlab new blink
devlab new blink-vhdl --hdl vhdl
cd blink
devlab build
devlab flash
```

`devlab install` downloads OSS CAD Suite release `2026-07-06` from
YosysHQ. The installer selects the correct asset for:

- Linux x64
- Linux arm64
- macOS x64
- macOS arm64
- Windows x64

The default install location is `~/.devlab`. Set `DEVLAB_HOME` to use a
different directory.

`devlab build`, `devlab flash`, and `devlab flash --detect` automatically run
OSS CAD Suite tools with the installed suite environment, including the
official `bin`, `py3bin`, `VIRTUAL_ENV`, `VERILATOR_ROOT`, and `GHDL_PREFIX`
settings. You do not need to manually source `environment` for those commands.
`devlab doctor` checks the tools required by the current platform.

On Windows, OSS CAD Suite may be distributed as a 7-Zip self-extracting `.exe`
archive. `devlab install` extracts it automatically into `~/.devlab/toolchains`
without opening an installer:

```powershell
devlab install
```

The installed tree keeps the official OSS CAD Suite layout:

```text
~/.devlab/toolchains/oss-cad-suite-2026-07-06-windows-x64/
  oss-cad-suite/
    bin/
    environment.bat
    environment.ps1
```

The Windows OSS CAD Suite package does not include GHDL. For VHDL projects on
Windows, install the standalone GHDL package separately:

```powershell
devlab install-ghdl
```

This downloads `ghdl-mcode-6.0.0-ucrt64.zip` and installs it under
`~/.devlab/toolchains`. Windows VHDL builds use `ghdl --synth --out=verilog`
to generate an intermediate Verilog file before running Yosys, so no
`yosys-ghdl` plugin is required on Windows.

## OSS CAD Suite Source

Default release:

https://github.com/YosysHQ/oss-cad-suite-build/releases/tag/2026-07-06

Example assets:

```text
https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-linux-arm64-20260706.tgz
https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-windows-x64-20260706.exe
```

Downloaded archives are verified with the SHA-256 digest published by the
GitHub release API.

## Project Format

`devlab new blink` creates:

```text
blink/
  devlab.toml
  pins.cst
  src/top.v
```

Use `--hdl vhdl` to create `src/top.vhd` instead:

```bash
devlab new blink-vhdl --hdl vhdl
```

Default `devlab.toml`:

```toml
[fpga]
family = "GW1N-9C"
device = "GW1NR-LV9QN88PC6/I5"
cst = "pins.cst"

[build]
top = "top"
sources = ["src/top.v"]
constraints = "pins.cst"
build_dir = "build"

[flash]
board = "tangnano9k"
mode = "sram"
verify = false
```

For Gowin, `family` is the FPGA series used by the packer and place-and-route
flow, for example `GW1N-9C`. `device` is the complete part number, for example
`GW1NR-LV9QN88PC6/I5`. `pins.cst` is the Gowin constraints file.

Update `pins.cst` and `[flash].board` for the real FPGA board before building
and flashing hardware.

## Build Flows

For Gowin `GW1N-9C` / `GW1NR-LV9QN88PC6/I5`, `devlab build` runs:

```bash
yosys
nextpnr-himbaechel
gowin_pack
```

The iCE40 and ECP5 flows are still available by setting `family = "ice40"` or
`family = "ecp5"` in `devlab.toml`.

For iCE40, it runs:

```bash
yosys
nextpnr-ice40
icepack
```

`devlab flash` uses `openFPGALoader`. By default it writes SRAM, so the FPGA
loses the design after power cycling. Use flash mode to write the bitstream to
non-volatile memory:

```bash
devlab flash --mode flash
```

Before writing flash on board variants where flash may or may not be populated,
run detection:

```bash
devlab flash --detect
devlab flash --detect --board tangnano9k
```

Persistent flash can also be configured in `devlab.toml`:

```toml
[flash]
board = "tangnano9k"
mode = "flash"
verify = false
# external_flash = true
# offset = "0"
```

For Tang Nano 9K/Gowin, flash write verification may print
`writing verification not supported` and fail the CRC check even when the flash
write completed. Keep `verify = false` unless the selected board/programming
path explicitly supports flash verification.

When sources end in `.vhd` or `.vhdl`, `devlab build` uses GHDL before FPGA
synthesis. On Linux and macOS it runs Yosys with the GHDL plugin from the
installed OSS CAD Suite tree. On Windows it uses the standalone GHDL package to
write `build/<top>_ghdl.v`, then runs the normal Yosys synthesis flow on that
generated Verilog file.

Use `--dry-run` to print the commands without executing them:

```bash
devlab build --dry-run
devlab flash --dry-run --board tangnano9k
devlab flash --dry-run --mode flash
```
