An assembler IDE for 8-bit home computers (currently KC85/3, KC85/4, C64 and Amstrad CPC) with integrated assembler and debugger.
Screenshots
Quickstart
- clone https://github.com/floooh/kcide-sample
- open VSCode in one of the following subdirectories:
kc854/: for the KC85/4 samplec64/: for the C64 samplecpc/: for the Amstrad CPC sample
- the extension should detect the
kcide.project.json file and activate itself
(a new tab should open with the embedded emulator)
- open the
src/main.asm file, and hit F7, you should see a message
Output written to ..., and a new subdirectory build/ should have been
created with the files out.hex, out.lst and out.map, and a system-specific
binary file (out.kcc, out.prg or out.bin)
- with the
src/main file loaded and active, press F5 to start a debug session
- explore additional features by opening the VSCode command palette and typing
kcide
Feature Overview
- build the project into a KCC or PRG file by pressing F7
- build and debug the project by pressing F5
- explore additional commands in the command palette by typing
kcide
- the assembler is a slightly extended ASMX compiled to WASI, the changes are tracked here
- the emulators are taken from the chips project compiled to WASM+WebGL, running in a VSCode tab
- original syntax highlighting https://github.com/mborik/z80-macroasm-vscode/blob/main/syntaxes/z80-macroasm.tmLanguage.json,
extended for 6502 assembler syntax and special ASMX keywords
- during a debug session, you can change into the 'raw' disassembly view at any time by running the palette command
Open Disassembly View, this also happens automatically when stepping into code
that's not part of the project (such as operating system code)
- you can inspect memory by hovering over a CPU register in the VSCode
Variables panel and clicking
the 'binary' icon with the tooltip View Binary Data, however note that the emulator's integrated
debugging UI has a much more powerful memory viewer and editor than what VSCode can provide through the Debug Adapter Protocol
Starting a new KC85 project
create a new project directory and cd into it
create a file project.kcide.json looking like this, tweak the attributes as needed (the extension provides a JSON schema to VSCode to provide completion and validation):
{
"emulator": {
"system": "KC85/4"
},
"assembler": {
"srcDir": "src",
"mainSourceFile": "main.asm",
"cpu": "Z80",
"outDir": "build",
"outBaseFilename": "hello",
"outFiletype": "KCC"
}
}
...also put the outDir value into your .gitignore
create a directory src/ and in it a file main.asm execution will start
at the label _start:
org 200h
_start:
ld a,5
ld b,6
add a,b
ret
test building by pressing F7 or running the palette command KCIDE: Build
test debugging by pressing F5 or running the palette command KCIDE: Debug
Starting a new C64 project
create a new project directory and cd into it
create a file project.kcide.json looking like this, tweak the attributes as needed (the extension provides a JSON schema to VSCode to provide completion and validation):
{
"emulator": {
"system": "C64"
},
"assembler": {
"cpu": "6502",
"srcDir": "src",
"mainSourceFile": "main.asm",
"outDir": "build",
"outBaseFilename": "out",
"outFiletype": "PRG"
}
}
...also put the outDir value into your .gitignore
create a directory src/ and in it a file main.asm execution will start
at the label _start
org $801
_start:
lda [#5](https://github.com/floooh/vscode-kcide/issues/5)
clc
adc [#6](https://github.com/floooh/vscode-kcide/issues/6)
rts
test building by pressing F7 or running the palette command KCIDE: Build
test debugging by pressing F5 or running the palette command KCIDE: Debug
for a more 'idiomatic' C64 PRG sample, check the example project here: https://github.com/floooh/kcide-sample/tree/main/c64
Starting a new Amstrad CPC project
create a new project directory and cd into it
create a file project.kcide.json looking like this, tweak the attributes as needed (the extension provides a JSON schema to VSCode to provide completion and validation):
{
"emulator": {
"system": "CPC6128"
},
"assembler": {
"cpu": "Z80",
"srcDir": "src",
"mainSourceFile": "main.asm",
"outDir": "build",
"outBaseFilename": "out",
"outFiletype": "AMSDOS_BIN"
}
}
...also put the outDir value into your .gitignore
create a directory src/ and in it a file main.asm execution will start
at the label _start
org 4000h
_start:
ld a,5
ld b,6
add a,b
ret
test building by pressing F7 or running the palette command KCIDE: Build
test debugging by pressing F5 or running the palette command KCIDE: Debug
for a more 'idiomatic' C64 PRG sample, check the example project here: https://github.com/floooh/kcide-sample/tree/main/c64
The integrated debugging UI
The emulator comes with an integrated debugging UI implemented with Dear ImGui which is much more powerful than what the VSCode debug adapter protocol can provide:
- the integrated CPU debugger allows to step in single clock cycles instead of full instructions
and displays the actual cycle count of executed instructions
- more powerful breakpoints:
- break on memory access
- break on IO access
- break on interrupts
- break on specific raster scanlines (C64 only)
- a much more powerful memory view/edit window
- an execution history window
- status windows for the CPU and system chips
- ...and more
Running in VSCode for Web
The extension has 'best effort' support for running in the VSCode browser version with the
following known issues:
- currently only the Insider version is supported (https://insiders.vscode.dev/)
- currently only working on local repositories is supported, directly opening
Github respositories doesn't work
- starting a debug session for the first time seems to take considerably longer
than on the desktop VSCode version
| |
