6502caEd

A C11 assembly development suite for 6502, 65C02 and 65816 projects, combining a command-line assembler, terminal and GTK editors, and an integrated hardware simulator.

All three interfaces share the same assembler core. The GTK editor's optional simulator lets you run and debug programs against a configurable virtual machine, including two VIA devices, an ACIA serial interface, an HD44780 LCD and an SPI SD card. Serial programs can communicate with an external terminal over TCP or a real/USB serial port.

Status

This is an early project release. Bug reports and small, focused contributions are welcome. Processor support and simulator behaviour should be checked against your target hardware; the presence of an instruction or device model does not imply complete hardware compatibility.

The simulator supports banked memory configurations. The assembler supports 65816 instructions and 24-bit operands, while each assembled binary currently covers a selectable range within a 64 KiB image.

Screenshots

Click any screenshot to open it at full resolution.

GTK editor

Source editing with syntax highlighting and embedded simulator profile settings.

Assembly output

Assembly listing with generated bytes, symbols and controls for saving the binary, viewing memory and launching emulation.

Memory viewer

Inspect assembled code and data in hexadecimal, binary and text form.

Hardware simulator

An HD44780 LCD test running alongside VIA1, VIA2 and ACIA panels, CPU registers, breakpoints and disassembly.

Interfaces

Executable	Description
6502ca-cli	Command-line assembler with binary, listing and symbol output
6502caEd	Terminal editor using ncurses on Linux or PDCurses on Windows
6502caEdGtk	Graphical editor using GTK 4 and GtkSourceView 5, with optional integrated simulator

Features

• 6502, 65C02 and 65816 instruction encoding, with optional undocumented 6502 opcodes.
• Labels, expressions, macros, includes and conditional assembly.
• Binary output, configurable assembly listings and symbol tables.
• Diagnostics with source locations and overwrite warnings.
• Syntax highlighting, code folding, find/replace and assembly diagnostics in the editors.
• Multiple tabs, an include manager and a memory viewer in the GTK editor.
• Integrated GTK simulator for testing assembly programs and peripheral interactions before moving to hardware.

See the user manual for the assembly language, editor features and simulator configuration.

Integrated hardware simulator

Build the GTK editor with ED_BUILD_SIM=ON to assemble, run and debug programs inside the application. The simulator combines CPU emulation with configurable memory and peripheral models, making it useful for developing and testing software for a 6502-based computer.

Devices and debugging

• Two VIA devices (VIA1 and VIA2): configurable I/O devices with port panels for inspecting peripheral interactions.
• HD44780-compatible LCD: test display routines with configurable VIA pin mappings, 4-bit or 8-bit transfers, and custom characters.
• SPI SD card: insert an image file and test SDSC or SDHC cards through configurable VIA-connected SPI signals. Create raw, FAT12, FAT16 or FAT32 images from the simulator.
• ACIA serial interface: communicate over TCP or a real/USB serial port, with connection settings and a Force Disconnect control.
• Execution controls: run, pause, single-step, reset and breakpoints, with register and disassembly views.
• Machine profiles: configure the memory map, device addresses and peripheral wiring; source comments can supply profile overrides.

Peripheral support is evolving, with more devices planned. See the simulator manual and LCD/VIA guide for configuration details and examples. Current limitations are listed below.

The term simulator describes the complete virtual hardware environment; emulation describes how its CPU and devices reproduce the behaviour of the real components.

Installers and release files

Release filenames use a consistent format:

6502caEd-{version}-{operating-system}-{architecture}-{type}.{extension}

Examples for version 1.03:

File	Contents
6502caEd-1.03-linux-x86_64-GTK.AppImage	Linux graphical editor and simulator
6502caEd-1.03-linux-amd64-GTK.deb	Debian/Ubuntu graphical editor and simulator
6502caEd-1.03-linux-amd64-TUI.deb	Debian/Ubuntu terminal editor
6502caEd-1.03-linux-amd64-CLI.deb	Debian/Ubuntu command-line assembler
6502caEd-1.03-windows-x86_64-ALL-setup.exe	Windows installer containing GTK, TUI and CLI interfaces

TUI means terminal user interface. Debian packages use Debian architecture names such as amd64; AppImage and Windows filenames use x86_64. The Windows installer currently bundles all three interfaces rather than producing separate installers.

Build scripts read component versions from versions.txt. A combined Windows installer requires matching component versions, or a common -Version override. To preview filenames without building:

bash build_Installers.sh --list

.\build_Windows.ps1 -List

Generated packages are written to installers/. Use the scripts' help options for build choices and version overrides.

SD-card support

The SPI card model supports single- and multi-block reads and writes, command/data CRC handling, erase operations and capacity reporting. SDSC uses byte addressing and supports configurable transfer lengths from 1 to 512 bytes; SDHC uses block addressing and 512-byte transfers. Image access supports offsets above 2 GiB.

Timing settings cover read delay, write busy time, erase busy time and maximum SPI clock, with a Defaults button. Strict timing uses simulated CPU cycles. These settings provide representative behaviour; they do not reproduce the performance of a particular physical card.

The image-creation dialog offers Raw Image, FAT12, FAT16 and FAT32. Creating a formatted image and accessing a filesystem from a 6502 program are separate operations: the supplied native assembly library supports FAT16.

Native 6502 libraries and examples

• Raw SD API: initialise a card, obtain capacity, and read or write 512-byte sectors without a filesystem.
• FAT16 library: mount a supported volume, enumerate root-directory entries, create a new file, and read/write/close a sequential file. VIA addresses, SPI pins, zero-page workspace and buffers are configurable.
• FAT16 round-trip demo: create a file, write a string, close it, clear the buffer, reopen it, read back and compare.
• Interactive FAT16 menu: format a card, create HELLO.TXT containing HELLO WORLD, check that it exists, and read back and verify its contents. Formatting requires confirmation and replaces existing filesystem/partition information. The formatter accepts cards from 16 MiB to 2 GiB.
• Serial examples: a configurable ACIA driver, an interactive serial demo and a visible demo that logs received/transmitted bytes in the simulator console. A Python TCP terminal is supplied for testing.

The native FAT16 library uses 512-byte sectors, short 8.3 filenames, root-directory files and one open file at a time. It does not currently provide subdirectories, long filenames, append/seek/delete operations or FAT12/FAT32 filesystem access. Raw sector access remains available independently.

The visible serial demo deliberately converts lowercase input to uppercase for its reply. Serial data normally appears in the connected terminal; the visible demo also mirrors activity to the simulator console. Opening a physical serial port reports the port as connected, but does not establish that another device is responding.

Build on Linux

Run these commands from the repository root, beside the top-level CMakeLists.txt.

Requirements are a C11 compiler and CMake 3.20 or newer. The terminal editor additionally needs curses; the graphical editor needs GTK 4, GtkSourceView 5 and pkg-config. Ninja is optional for the commands below.

Command-line assembler only

On Debian or Ubuntu:

sudo apt update
sudo apt install build-essential cmake

cmake -S . -B build-cli \
  -DCMAKE_BUILD_TYPE=Release \
  -DED_BUILD_TUI=OFF \
  -DED_BUILD_GTK=OFF \
  -DED_BUILD_SIM=OFF
cmake --build build-cli --parallel

The executable is build-cli/6502caEd/6502ca-cli.

Editors and simulator

On Debian or Ubuntu:

sudo apt install build-essential cmake pkg-config \
  libncurses-dev libgtk-4-dev libgtksourceview-5-dev

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DED_BUILD_TUI=ON \
  -DED_BUILD_GTK=ON \
  -DED_BUILD_SIM=ON
cmake --build build --parallel

The executables are in build/6502caEd/:

./build/6502caEd/6502caEd program.asm
./build/6502caEd/6502caEdGtk

CMake option	Default	Purpose
ED_BUILD_TUI	ON	Build the terminal editor
ED_BUILD_GTK	OFF	Build the graphical editor
ED_BUILD_SIM	OFF	Include the simulator; requires ED_BUILD_GTK=ON

The command-line assembler is always built. CMake presets are also supplied; their schema version 6 requires CMake 3.25 or newer and their builds use Ninja.

Build on Windows

The repository includes an MSYS2 UCRT64/MinGW build workflow, a PowerShell build script and an optional Inno Setup packaging path. Follow the Windows build guide for dependencies and setup.

From PowerShell in the repository root, after reviewing the script:

powershell -ExecutionPolicy Bypass -File .\build_Windows.ps1 -Help
powershell -ExecutionPolicy Bypass -File .\build_Windows.ps1

First program

Save this as hello.asm:

    .cpu 6502
    .org $0800

start:
    LDA #$01
    STA $00
    BRK

Assemble it using the CLI-only build:

./build-cli/6502caEd/6502ca-cli hello.asm -o hello.bin \
  --start '$0800' --end '$0804' \
  --listfile hello.lst --symfile hello.sym

This produces five bytes: A9 01 85 00 00. The output range is inclusive; without --start and --end, the CLI writes the full 65,536-byte image. The single quotes preserve the dollar signs in POSIX shells.

The applications start without a licence acceptance prompt. In the GTK editor, open Help → About → Licence to read the MIT licence, or Third-party notices for dependency information. The CLI prints its licence with --license.

Useful CLI options

Option	Purpose
--license	Print the MIT licence and exit
--cpu 6502, --cpu 65c02, --cpu 65816	Select the processor
--undoc	Enable undocumented 6502 opcodes
-I directory	Add an include search directory; repeat as needed
--start expression, --end expression	Select the binary output range
--listfile file.lst	Write an assembly listing
--nolist	Suppress the listing on standard output
--sym, --symfile file.sym	Print or save symbols
--symsort name, --symsort addr	Choose symbol ordering

Current CLI workaround: for 65816 programs, pass --cpu 65816 explicitly, even when the source contains .cpu 65816. The current CLI does not apply that source directive to its CPU selection.

Using the editors

Open or create an assembly file, then use the Assembly menu to check it or produce a binary. GTK File → Open and File → Save As share the last successfully used source folder for the current session. Common shortcuts include:

Shortcut	Action
Ctrl+O	Open a file
Ctrl+S	Save
F5	Check assembly
F9	Assemble with binary output
F10	Open the terminal editor's menu bar

When simulator support is enabled, the GTK editor provides Assembly → Assemble & Emulate. Simulator-window controls have their own shortcuts. Use the menus as the reference if a shortcut differs from the manual.

Documentation

• User manual
• HTML user manual — open locally in a browser
• HD44780 LCD and VIA guide
• Windows build guide

The repository also includes build_help.sh, build_Installers.sh and build_Windows.ps1 for documentation and packaging workflows.

Source layout

Directory	Contents
6502caEd/core/	Shared assembler, preprocessor, expressions, symbols and diagnostics
6502caEd/cli/	Command-line frontend
6502caEd/editor/	Terminal editor and shared editor utilities
6502caEd/gui/	GTK frontend
6502caEd/sim/	CPU, memory, peripherals and simulator interface
help/	Manual and hardware guides

Tests

The repository includes automated tests for the SPI SD-card model, filesystem integration and serial behaviour. Run tests from the repository root; test scripts need the accompanying source tree, not just an extracted patch directory.

bash tests/run_sd_tests.sh
bash tests/run_fatfs_tests.sh
python3 tests/test_acia_refresh.py

The SD suite covers SDSC/SDHC transfers, partial lengths, CRCs, boundaries, image preservation, no-card behaviour and a sparse 4 GiB image. Independent FatFs integration cases exercise FAT16/FAT32, partitioned and unpartitioned images, and both card types. These host-side FatFs tests are separate from the native 6502 FAT16 library.

For the serial transport suite, provide the path to a built CLI assembler:

ASSEMBLER=/absolute/path/to/6502ca-cli bash tests/run_acia_transport_tests.sh

Serial tests include TCP and Linux pseudo-terminal coverage. Real serial hardware and Windows COM-port behaviour also need validation on the target system.

Known limitations

• The CLI's .cpu 65816 handling needs the explicit flag described above.
• 65816 simulation is incomplete; do not assume full native-mode or cycle-accurate behaviour.
• SD support models SPI-mode behaviour; it is not a complete SD specification implementation and does not provide native SD-bus, SDIO or UHS operation.
• Physical serial-port support does not model every modem-control, break or line-error condition.
• Automated tests cover selected behaviours and do not establish complete hardware compatibility.

Reporting problems and contributing

Please open a GitHub issue with your operating system, compiler and dependency versions, build options, expected behaviour and actual result. For assembler problems, include the smallest source file that reproduces the issue, the exact command and its output. For simulator problems, include the CPU type and profile settings.

Keep pull requests focused and include a reproducible example or test for behaviour changes.

Licence

© 2026 MJD. The project's own code is released under the MIT License; see LICENSE.

GTK, GtkSourceView, curses, bundled runtime libraries and other external components retain their own licences. See third-party notices. The Windows packager includes the MSYS2 licence files and package versions; dependency source-distribution requirements must also be met when publishing binaries.