kr580 1.0.0

Desktop KR580VM80 / Intel 8080 emulator.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

<p align="center">
  <img src="assets/brand/logo.svg" width="360" alt="KR580 logo" />
</p>

<p align="center">
  <a href="https://github.com/WhoSowSee/KR580/graphs/contributors"><img src="https://img.shields.io/github/contributors/WhoSowSee/KR580?style=for-the-badge&color=CBA6F7&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTkgMTFhNCA0IDAgMSAwIDAtOCA0IDQgMCAwIDAgMCA4Wm0wIDJjLTMuOSAwLTcgMi03IDQuNVYyMGgxNHYtMi41QzE2IDE1IDEyLjkgMTMgOSAxM1ptOC41LTEuNWEzLjI1IDMuMjUgMCAxIDAgMC02LjUgMy4yNSAzLjI1IDAgMCAwIDAgNi41Wm0wIDEuOGMtLjkgMC0xLjc1LjE1LTIuNS40MiAxLjcgMS4wNSAyLjcgMi40NSAyLjcgMy45OFYyMEgyMnYtMi4zYzAtMi40LTItNC40LTQuNS00LjRaIi8+PC9zdmc+" alt="CONTRIBUTORS"></a>
  <a href="https://github.com/WhoSowSee/KR580/forks"><img src="https://img.shields.io/github/forks/WhoSowSee/KR580?style=for-the-badge&color=89B4FA&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTIgMTIpIHNjYWxlKDEuMDgpIHRyYW5zbGF0ZSgtMTIgLTEyKSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTYgM2EzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZabTEyIDBhMyAzIDAgMSAwIDAgNiAzIDMgMCAwIDAgMC02Wk0xMiAxNWEzIDMgMCAxIDAgMCA2IDMgMyAwIDAgMCAwLTZaIi8%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTUgOGgydjIuNGMwIC4zMy4yNy42LjYuNmg4LjhjLjMzIDAgLjYtLjI3LjYtLjZWOGgydjIuNGEyLjYgMi42IDAgMCAxLTIuNiAyLjZIMTN2MmgtMnYtMkg3LjZBMi42IDIuNiAwIDAgMSA1IDEwLjRWOFoiLz48L2c%2BPC9zdmc%2B" alt="FORKS"></a>
  <a href="https://github.com/WhoSowSee/KR580/stargazers"><img src="https://img.shields.io/github/stars/WhoSowSee/KR580?style=for-the-badge&color=F9E2AF&labelColor=302D41&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMCAtMS42KSI%2BPHBhdGggZmlsbD0iI2NkZDZmNCIgZD0iTTEyIDIuNSAxNC45IDguNGw2LjUgMWEuOC44IDAgMCAxIC40NSAxLjM2bC00LjcgNC41OCAxLjEgNi40NWEuOC44IDAgMCAxLTEuMTYuODRMMTIgMTkuOTUgNi4yIDIyLjYzYS44LjggMCAwIDEtMS4xNi0uODRsMS4xLTYuNDUtNC43LTQuNThBLjguOCAwIDAgMSAxLjkgOS40bDYuNS0xTDEyIDIuNVoiLz48L2c%2BPC9zdmc%2B" alt="STARS"></a>
</p>

<p align="center">
  <a href="https://crates.io/crates/kr580"><img src="https://img.shields.io/crates/v/kr580?style=for-the-badge&color=FAB387&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="CRATES.IO"></a>
  <a href="https://crates.io/crates/kr580"><img src="https://img.shields.io/crates/d/kr580?style=for-the-badge&color=A6E3A1&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI%2BCjxwYXRoIGZpbGw9IiNjZGQ2ZjQiIGQ9Ik0xLjUgNi45ODRWMTFsNi41MDMgMy41TDE0LjUgMTFWM0wxMSAxLjVsLTYuNSAzdjF6Ii8%2BCjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzMwMkQ0MSIgc3Ryb2tlLXdpZHRoPSIuOSIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIj4KPHBhdGggZD0iTTEuNSA3TDggMTAuNUwxNC41IDdtLTEwLTIuNWwzLjUwMyAyTDE0LjQ5OCAzTTQuNSA1LjV2N20zLjUtNlYxNCIvPgo8cGF0aCBkPSJNOC4wMDMgM0wxMS41IDQuNXY4Ii8%2BCjwvZz4KPC9zdmc%2B&labelColor=302D41" alt="DOWNLOADS"></a>
</p>

<h2 align="center">Desktop KR580 emulator written in Rust</h2>

<p align="center">
  <img src="assets/screenshots/en/emulator.png" width="800" alt="KR580 emulator overview screenshot" />
</p>

> [!TIP]
> **Russian version:** [README.md](README.md)

KR580 is a modern desktop emulator for a KR580 / Intel 8080-style microprocessor system. It keeps the CPU core deterministic, models external devices through typed I/O ports, and presents the machine through a native multi-window GUI.

The project focuses on inspectable execution: edit RAM and registers, step by instruction or by tact, watch the control panels update live, open device windows, save snapshots, and export state without scraping UI widgets.

## Features

- Deterministic KR580 / Intel 8080 CPU state: registers, flags, `PC`, `SP`, 64 KiB RAM, interrupts, halt state, cycles, and tact phase.
- Documented 8080 opcode execution with tests for opcode families, flags, conditionals, stack operations, interrupts, and I/O routing.
- Instruction stepping, tact-level stepping, paced run, and burst run modes.
- Native iced desktop UI with RAM list, register editor, status register, machine-cycle view, control schematic, and localized Russian/English installer text.
- External device windows for monitor, floppy, HDD, network adapter, and printer.
- Versioned `.580` snapshots, raw `.krs` subprogram loading, direct `.txt` / `.xlsx` import and export, and printer PDF generation.
- Graphical installer, uninstaller, terminal launcher, optional `.580` file association, and portable or system install layouts.

## Screenshots

<p align="center"><strong>Monitor</strong> · <strong>Floppy</strong></p>
<p align="center">
  <img src="assets/screenshots/en/monitor.png" width="400" alt="Monitor window screenshot" />
  <img src="assets/screenshots/en/floppy.png" width="400" alt="Floppy window screenshot" />
</p>

<p align="center"><strong>HDD</strong> · <strong>Network adapter</strong></p>
<p align="center">
  <img src="assets/screenshots/en/hdd.png" width="400" alt="HDD window screenshot" />
  <img src="assets/screenshots/en/network.png" width="400" alt="Network adapter window screenshot" />
</p>

<p align="center"><strong>Printer</strong></p>
<p align="center">
  <img src="assets/screenshots/en/printer.png" width="520" alt="Printer window screenshot" />
</p>

## External devices

`IoBus` routes the low byte of I/O port addresses to five modeled devices:

| Port | Device | What it does |
|---:|---|---|
| `00h` | Monitor | 64×20 text framebuffer plus 256×256 graphics layer. |
| `01h` | Floppy | File-backed or debug-buffer storage window. |
| `02h` | HDD | Append-backed `hdd.kpd` storage with visible buffer inspection. |
| `03h` | Network adapter | TCP client/server worker with RX/TX counters and explicit connection state. |
| `04h` | Printer | CP866 spool, buffered output, and asynchronous A4 PDF export. |

Device operations return typed statuses and errors. The CPU core talks to them only through `IN` / `OUT`, so emulator state stays serializable and testable.

## Installation

### Requirements

- Rust `1.95.0` or newer.
- A desktop environment capable of running native iced windows.

### Install from crates.io

```bash
cargo install kr580
```

This path is for the published crates.io release. Until the package is published, use the source build or the standalone setup artifact.

### Install on NixOS

```bash
nix run github:WhoSowSee/KR580
nix profile install github:WhoSowSee/KR580
```

The NixOS package installs ready-to-run `k580` and `kr` binaries, the desktop entry, icons, and the `.580` MIME type directly through the Nix store. The standalone setup wizard is not used for this path.

### Run from source

```bash
git clone https://github.com/WhoSowSee/KR580.git
cd KR580
cargo run -p kr580 --bin k580
```

### Build the GUI binary

```bash
cargo build --release -p kr580 --bin k580
```

The built application is placed under `target/release/` as `k580` or `k580.exe`.

### Build the standalone setup artifact

Windows:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_installer.ps1
```

Unix/macOS:

```bash
bash scripts/build_installer.sh
```

The setup artifact is written to `dist/`.

## Usage

```bash
# Launch the emulator from source
cargo run -p kr580 --bin k580

# Open a snapshot through the launcher
cargo run -p kr580 --bin kr -- path/to/program.580

# Show launcher help
cargo run -p kr580 --bin kr -- --help
```

After installation, `kr` can open `.580` snapshots from the terminal and can register or remove the file association when the platform supports it.

## File formats

| Format | Purpose |
|---|---|
| `.580` | Versioned little-endian emulator snapshot with magic `K580`. |
| `.krs` | Raw subprogram bytes loaded at a caller-provided base address. |
| `.txt` | Plain-text register, flag, and memory exports; also importable. |
| `.xlsx` | Workbook export/import through `rust_xlsxwriter` and `calamine`. |
| `.pdf` | Printer output rendered as A4 text with bundled Roboto Mono. |

## Workspace layout

| Crate | Responsibility |
|---|---|
| `k580-core` | Public CPU core: state, opcode decode/execute, timing, interrupts, and `PortBus`. |
| `kr580` | Public installable crate: desktop UI, launcher, installer, uninstaller, platform shims, and internal `backend`, `devices`, and `persistence` modules. |

## Development

```bash
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

Useful reference docs:

- [Architecture](docs/architecture.md)
- [CPU core](docs/core.md)
- [Devices and IoBus](docs/devices.md)
- [Persistence](docs/persistence.md)
- [App and UI](docs/ui_app.md)
- [Installer](docs/installer.md)
- [Testing](docs/testing.md)
- [Assets](docs/assets.md)

## Star History

<p align="center">
  <a href="https://starchart.cc/WhoSowSee/KR580">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="https://starchart.cc/WhoSowSee/KR580.svg?variant=custom&background=%230d1117&axis=%238b949e&line=%232f81f7"
      />
      <source
        media="(prefers-color-scheme: light)"
        srcset="https://starchart.cc/WhoSowSee/KR580.svg?variant=custom&background=%23ffffff&axis=%2357606a&line=%230969da"
      />
      <img
        alt="KR580 star history"
        src="https://starchart.cc/WhoSowSee/KR580.svg?variant=custom&background=%23ffffff&axis=%2357606a&line=%230969da"
      />
    </picture>
  </a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true" alt="catppuccin" />
</p>

<p align="center">
  <i><code>&copy 2026-present <a href="https://github.com/WhoSowSee">WhoSowSee</a></code></i>
</p>

<div align="center">
  <a href="https://github.com/WhoSowSee/KR580/blob/main/LICENSE"><img src="https://img.shields.io/github/license/WhoSowSee/KR580?style=for-the-badge&color=CBA6F7&logoColor=cdd6f4&labelColor=302D41" alt="LICENSE"></a>
</div>