devlab-fpga 0.1.0__tar.gz

devlab_fpga-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mrju10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devlab_fpga-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

devlab_fpga-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: devlab-fpga
+Version: 0.1.0
+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.
+
+## 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
+```
+
+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
+```

devlab_fpga-0.1.0/README.md

@@ -0,0 +1,164 @@
+# 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.
+
+## 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
+```
+
+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
+```

devlab_fpga-0.1.0/devlab/__init__.py

@@ -0,0 +1,6 @@
+"""Python helpers for the devlab FPGA command line tools."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

devlab_fpga-0.1.0/devlab/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devlab_fpga-0.1.0/devlab/cli.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import argparse
+import platform
+from pathlib import Path
+
+from . import __version__
+from .errors import DevlabError
+from .platforms import current_platform
+from .project import build_project, create_project, detect_flash, doctor, flash_project
+from .toolchain import (
+    OSS_CAD_SUITE_RELEASE_URL,
+    archive_path,
+    devlab_home,
+    install_oss_cad_suite,
+    install_path,
+    select_asset,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devlab",
+        description="Install FPGA toolchains and run local FPGA build flows.",
+    )
+    parser.add_argument("--version", action="version", version=f"devlab {__version__}")
+
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    doctor_parser = commands.add_parser("doctor", help="Check local FPGA tools.")
+    doctor_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 when a tool is missing.",
+    )
+    doctor_parser.set_defaults(func=_doctor)
+
+    install_parser = commands.add_parser("install", help="Install OSS CAD Suite.")
+    install_parser.add_argument("--force", action="store_true", help="Re-download and reinstall.")
+    install_parser.add_argument(
+        "--run-installer",
+        action="store_true",
+        help="On Windows, execute the downloaded OSS CAD Suite installer.",
+    )
+    install_parser.set_defaults(func=_install)
+
+    new_parser = commands.add_parser("new", help="Create a new FPGA project.")
+    new_parser.add_argument("name", help="Project directory name.")
+    new_parser.add_argument("--dir", type=Path, help="Target directory. Defaults to NAME.")
+    new_parser.add_argument("--force", action="store_true", help="Overwrite template files.")
+    new_parser.add_argument(
+        "--hdl",
+        choices=("verilog", "vhdl"),
+        default="verilog",
+        help="Source template language. Defaults to verilog.",
+    )
+    new_parser.set_defaults(func=_new)
+
+    build = commands.add_parser("build", help="Build the current FPGA project.")
+    build.add_argument("-c", "--config", type=Path, help="Path to devlab.toml.")
+    build.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print commands without running them.",
+    )
+    build.set_defaults(func=_build)
+
+    flash = commands.add_parser("flash", help="Flash the built FPGA bitstream.")
+    flash.add_argument("-c", "--config", type=Path, help="Path to devlab.toml.")
+    flash.add_argument("--board", help="openFPGALoader board name.")
+    flash.add_argument("--artifact", type=Path, help="Bitstream path.")
+    flash.add_argument(
+        "--mode",
+        choices=("sram", "flash"),
+        help="Write target. sram is temporary; flash is persistent after reboot.",
+    )
+    flash.add_argument(
+        "--detect",
+        action="store_true",
+        help="Detect FPGA and flash support without writing a bitstream.",
+    )
+    flash.add_argument(
+        "--verify",
+        action="store_true",
+        help="Verify flash write when supported by the board/programming path.",
+    )
+    flash.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip flash verification when using --mode flash.",
+    )
+    flash.add_argument(
+        "--external-flash",
+        action="store_true",
+        help="Use external flash when the device has internal and external storage.",
+    )
+    flash.add_argument("--offset", help="Flash offset in bytes.")
+    flash.add_argument("--dry-run", action="store_true", help="Print command without running it.")
+    flash.set_defaults(func=_flash)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except DevlabError as exc:
+        parser.exit(2, f"devlab: error: {exc}\n")
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    platform_id = current_platform()
+    asset = select_asset(platform_id)
+    print(f"devlab: {__version__}")
+    print(f"python: {platform.python_version()} ({platform.python_implementation()})")
+    print(f"platform: {platform_id.key}")
+    print(f"home: {devlab_home()}")
+    print(f"release: {OSS_CAD_SUITE_RELEASE_URL}")
+    print(f"asset: {asset.name}")
+    print(f"archive: {archive_path(asset)}")
+    print(f"toolchain: {install_path(asset)}")
+    return doctor(strict=args.strict)
+
+
+def _install(args: argparse.Namespace) -> int:
+    destination = install_oss_cad_suite(
+        force=args.force,
+        run_windows_installer=args.run_installer,
+    )
+    print(f"OSS CAD Suite installed at {destination}")
+    return 0
+
+
+def _new(args: argparse.Namespace) -> int:
+    root = create_project(args.name, directory=args.dir, force=args.force, hdl=args.hdl)
+    print(f"Created FPGA project at {root}")
+    return 0
+
+
+def _build(args: argparse.Namespace) -> int:
+    artifact = build_project(config_path=args.config, dry_run=args.dry_run)
+    print(f"Build artifact: {artifact}")
+    return 0
+
+
+def _flash(args: argparse.Namespace) -> int:
+    if args.verify and args.no_verify:
+        raise DevlabError("--verify and --no-verify cannot be used together.")
+
+    if args.detect:
+        detect_flash(
+            config_path=args.config,
+            board=args.board,
+            dry_run=args.dry_run,
+        )
+        return 0
+
+    flash_project(
+        config_path=args.config,
+        board=args.board,
+        artifact=args.artifact,
+        mode=args.mode,
+        verify=True if args.verify else False if args.no_verify else None,
+        external_flash=True if args.external_flash else None,
+        offset=args.offset,
+        dry_run=args.dry_run,
+    )
+    return 0

devlab_fpga-0.1.0/devlab/errors.py

@@ -0,0 +1,3 @@
+class DevlabError(RuntimeError):
+    """User-facing error raised by devlab commands."""
+

devlab_fpga-0.1.0/devlab/platforms.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass
+
+from .errors import DevlabError
+
+
+@dataclass(frozen=True)
+class PlatformId:
+    os_name: str
+    arch: str
+
+    @property
+    def key(self) -> str:
+        return f"{self.os_name}-{self.arch}"
+
+
+def current_platform() -> PlatformId:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if system == "linux":
+        os_name = "linux"
+    elif system == "darwin":
+        os_name = "darwin"
+    elif system in {"windows", "msys", "cygwin"}:
+        os_name = "windows"
+    else:
+        raise DevlabError(f"Unsupported operating system: {platform.system()}")
+
+    if machine in {"x86_64", "amd64"}:
+        arch = "x64"
+    elif machine in {"aarch64", "arm64"}:
+        arch = "arm64"
+    else:
+        raise DevlabError(f"Unsupported CPU architecture: {platform.machine()}")
+
+    return PlatformId(os_name=os_name, arch=arch)
+