# ZScope

**Repository Path**: johnzchgrd/zscope

## Basic Information

- **Project Name**: ZScope
- **Description**: Lightweight JTAG logic analyzer and virtual I/O for FPGA debugging — SpinalHDL RTL plus Python CLI, from sim to hardware.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZScope

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

JTAG logic analyzer (LA) and virtual I/O (VIO) for FPGA designs. SpinalHDL RTL library plus Python host tools (`zscope` CLI, `hw_server`).

Repository: [gitee.com/johnzchgrd/zscope](https://gitee.com/johnzchgrd/zscope)

```
zscope CLI -> hw_server (:9900) -> JtagTcp (:7894) / remote_bitbang (:44853) -> simulation or FPGA
```

Supported JTAG bridges: **SoftTap** (simulation), **Xilinx BSCAN**, **Efinix BSCAN**.

## Architecture

```
zscope -> JTAG -> SystemDebugger mem bus -> ZScopeCsrHub
                                              |- LA ctrl  --CDC--> ZScopeLaCore
                                              |- VIO OUT   --CDC--> ZScopeVioCore -> design
                                              `- VIO IN    <---CDC-- ZScopeVioCore <- design
```

## Requirements

- JDK 8+
- [sbt](https://www.scala-sbt.org/) 1.10+
- [SpinalHDL](https://github.com/SpinalHDL/SpinalHDL) 1.13.x as a **sibling** checkout (`../SpinalHDL` relative to this repo)
- Python 3.9+ (host tools)
- [Verilator](https://www.veripool.org/verilator/) on `PATH` (for `ZScopeSim` only; Verilog generation does not need it)

```bash
git clone https://gitee.com/johnzchgrd/zscope.git
git clone https://github.com/SpinalHDL/SpinalHDL.git   # sibling directory
cd zscope
```

## Repository layout

```
lib/src/main/scala/ZScope/        RTL, Builder API, CSR
lib/src/main/scala/ZScope/bridge/ JTAG bridge implementations
lib/src/main/scala/EfxIf/         Efinix BSCAN interface helpers
tools/zscope/                     Python package (CLI + hw_server)
scripts/                          format-code, run-pytest
```

## Build (RTL)

```bash
sbt lib/compile
sbt "lib/runMain ZScope.ZScopeSim"                  # JtagTcp :7894 + remote_bitbang :44853
sbt "lib/runMain ZScope.ZScopeDemo_Verilog"         # SoftTap reference design + manifest
sbt "lib/runMain ZScope.ZScopeDemo_VerilogEfinix"   # Efinix BSCAN reference design
```

## Integrate into your design

Add ZScope as an sbt `ProjectRef` (or publish `lib` as a JAR):

```scala
lazy val zScopeLib = ProjectRef(file("path/to/zscope"), "lib")
// yourProject.dependsOn(..., zScopeLib)

import ZScope._

val params = ZScopeConfig(
  bridge = ZScopeJtagBridgeKind.EfinixBscan(),
  laDepth = 1024,
  manifestOut = Some("MyTop.zscope.yaml")
)
val dbgBuilder = ZScopeBuilder(params)

val core = new ClockingArea(sysCd) {
  val run = dbgBuilder.vioOut("run", Bool())
  dbgBuilder.vioIn("counter", counter)
  dbgBuilder.laProbe("counter", counter)
}
val dbg = dbgBuilder.build(sysCd, ZScopeBridgeIo.pack(params), "MyTop")
```

### JTAG bridges

| Kind | Use case |
|------|----------|
| `SoftTap` | Simulation / soft TAP |
| `XilinxBscan` | Xilinx USER BSCANE2 |
| `EfinixBscan` | Efinix embedded BSCAN |

CSR map: `lib/.../ZScopeRegs.scala` — mirrored in Python at `tools/zscope/zscope/registers.py`.

## Host tools (Python)

See [tools/zscope/README.md](tools/zscope/README.md).

```bash
pip install -e "tools/zscope[test]"
./scripts/run-pytest.sh
./scripts/format-code.sh

# terminal 1: sbt "lib/runMain ZScope.ZScopeSim"
# terminal 2:
zscope serve --manifest tools/zscope/examples/ZScopeDemo.zscope.yaml
zscope connect --adapter tcp --jtag-port 7894
zscope identify
```

Example one-click scripts: `tools/zscope/examples/zscope_demo_sim.*`, `zscope_demo_efinix.*`, `zscope_demo_t120.*`.

## Documentation

- [tools/zscope/README.md](tools/zscope/README.md) — CLI, adapters, manifest
- [tools/zscope/openocd/README.md](tools/zscope/openocd/README.md) — optional OpenOCD bring-up

## License

ZScope is released under the [MIT License](LICENSE).

This project depends on [SpinalHDL](https://github.com/SpinalHDL/SpinalHDL), which is licensed under LGPL-3.0. SpinalHDL is a separate dependency; comply with its license when distributing combined works.