floooh / vscode-kcide

Retro assembly IDE for VSCode

An assembler IDE for 8-bit home computers (currently KC85/3, KC85/4, C64 and Amstrad CPC) with integrated assembler and debugger.

Installation

Please make sure to install the pre-release version!

This is currently required because the dependency extension ms-vscode.wasm-wasi-core only exists as pre-release.

Screenshots

Quickstart

With the pre-release version of the extension installed:

• clone https://github.com/floooh/kcide-sample
• open VSCode in one of the following subdirectories:
  • kc854/: for the KC85/4 sample
  • c64/: for the C64 sample
  • cpc/: 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
        clc
        adc #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

vscode-kcide's Issues

implement call stack (also in embedded debugger)

Nice to have! This would involve tracking subroutine call instructions in the embedded debugger and tracking their call targets.

And then:

• add a new window to the embedded debugger with the callstack (clicking on the callstack should move the debug window there so that it's possible to set a breakpoint
• add callstack support to the emulator's webapi
• ...and implement the call stack for the vscode debug adapter.

unable to compile with org 0000h

I'm working in my z80 kernel and I can compile and run my software when org is > 0.

I got an error when org is 0. I think it should be linked to curAddr in file assembler.ts that it returns error when curAddr = 0

I suppose it should be linked to line 191.
if (curSymbol && curAddr) {

[Enhancement] Possibility to write the texts into the memory

Hello,

In CPC6128 emulator (I suppose that it should be the same for 2 other emulators), it is only possible to write the hex values into the memory.

It should be great if there would be the possibility to write also the text as WinAPE is allowing.

this feature is useful as I'm writing from scratch a new BASIC on Z80 and it is helpful for the debugging to write the basic commands into the memory

Support for a code-vs-data map in assembler and emulator

This would allow to automatically step over inline data after call instructions.

The assembler would need to add the information to the map file whether that line and address is code or data.

The emulator and emulator webapi would need to accept a new binary file format which for every address in the 16-bit address space has the information whether this address contains code or data.

The debugger 'heatmap' would be initialized with this information.

The step-over debugger feature would need to learn to step over inline data.

breakpoint is deactivated in the asm file subfolder

There is an annoying bug in the debugger that it deactivates the breakpoint in the files that are in the subfolders

As you can see in the picture, by running the debugger, the breakpoint is deactivated for the reason "unverified breakpoint".

Maybe it is my fault and something is missing in my configuration file

1.0 TODO

• pre-release readme
• emulator imgui: using the memory editor address field blocks further input => this is because the Emscripten backend is sending focused/unfocused events for some reason when a text input field is activated (fixed by removing all that hacky mobile keyboard code from the sokol_app.h emscripten backend)
• web extension problems:
  • transfer of KCC ArrayBuffer doesn't work: the size is 191 bytes (should be 182), and the header (or all content?) seems to be zero => this seems to be a difference/bug of VSCode when transferring ArrayBuffer objects. Works in the native version, breaks on the web. Fixed by explicitly sending the data as base64 encoded string.
• disable F5 and F7 key bindings unless the extension is active => changed to .asm file loaded
• failing to build must be more obvious
• add back extensionDependency on vscode-wasm (the missing piece was to publish the KC IDE extension also as a pre-release version, this will then automatically install pre-release versions for the dependencies too)
• allow to click on emulator canvas to activate tab (need to pass through mouse clicks?)
• emulator and vscode are fighting over function keys (e.g. try to debug in emulator) (hmm... consuming the events in the emulator doesn't appear to help) => partly sovled by disabling function keys in package.json when emulator webview panel is active.
• input problem: when debugging in emulator, the emulator sends a stopped event, which in turn causes the text editor to become active, which in turn activates function keys again :/ => ideally the vscode side would update, but not focus the text editor panel => this is possible by setting the .body.preserveFocusHint on the StoppedMessage, NOTE doesn't make sense to set preserveFocusHint when emulator panel is active, this breaks when clicking on the UI debug controls. Instead the emulator would need to send information with the stopped-event whether the internal debugger was used. Messy. NOTE: conditionally disabling the function keys in package.json when the webview panel is active also doesn't work reliably => fixed by binding a function to those keys which focuses the emulator tab again when VSCode steals the focus
• when starting a debug session via F5, the code isn't rebuilt (since it will directly start a debug session without going through the Debug command => fix this with a prelaunch-task in launch.json? this would be the "standard way" fixed by removing launch.json support and directly binding F5 key to the debug command)
• debug adapter
  • implement memory views (read-only for now)
  • in the chips debugger, prefix detection when scanning backwards also needs to check for double-prefixes ddcb and fdcb (no separate code path is actually needed for this, since CB is the regular opcode byte in this case)
  • setting source breakpoints on Windows is broken again
  • waiting for the emulator to be ready seems to be broken again :/
  • fix run-state in call stack panel (stop-reason)
  • print the current address in call stack panel
  • fix breakpoint names
  • setting breakpoints doesn't work on Windows (most likely converting source file paths to workspace local paths)
  • restart debug session currently doesn't work
  • in the variable view, add a visual Flags: --Z-C---' line line
  • implement register view
  • code cleanup (merge DebugRuntime class into DebugSession)
  • debug adapter should properly wait for emulator to become ready (by polling a new "webapi_ready()" call)
  • implement batch update and deleting of breakpoints
  • figure out a way to automatically stop debug session
  • somehow deal with stepping out of source code into operating system code (investigate debug adapter "DisassembleRequest" and "Instruction Breakpoints")
  • when pressing F5 for the first time and the debug provider drop down shows up, nothing happens when selecting the KCIDE debug provider (or does it just take a while???)
  • debugger doesn't connect in the browser version, communicating breakpoints works, but that's it...
• language server too much work for little in return
• allow emulator to go into sleep/freeze mode to preserve battery
• extension icon
• remove blinking audio icon
• extension doesn't find commands unless there's a kcide.project.json (doesn't activate properly when just invoking a command?)
• asmx: add debug-map output (map addresses to source+line-nr)
• asmx: add an include-root argument
• figure out how to make debug adapter work in web extension (@vscode/debugadapter has node.js dependencies) => fixed by using browser polyfills for url and process when building for web
• what's up with the weird stuttering in the emulator webpanel... maybe related to passing through input events now? (hadn't noticed that before). PS: on Windows it looks fine. (seems to happen only when Spotify is also open - spooky action at a distance?)

Cannot debug nor compile

I installed the sample example and created the new project on CPC folder.

I can see the emulator on the right but I cannot debug and even compile. I got the error message when I'm pushing on F5 "You don't have an extension for debugging 'Assembler file'.

Nothing happened when I push on F7.

Filesystem related issues on Windows in VSCode ~~web version~~ working on local project.

See https://twitter.com/l_vanek/status/1734544371695903185

(not just the web version as expected first)

Web platform: working directly on Github repos doesn't work

Trying to build results in Unable to resolve nonexistent file 'vscode-vfs://github/floooh/kcide-sample/build', also trying to manually create a build subdirectory in the outliner fails, so it's probably a general problem and not directly related to the vscode extension.