Metadata-Version: 2.4
Name: devlab-fpga
Version: 0.1.3
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.

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
```

## 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` runs Yosys with the
GHDL plugin before synthesis. OSS CAD Suite is expected to provide that plugin.

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
```
