UAE Debug Adapter Protocol

Stand-aloneDebug Adapter for Amiga assembly development with FS-UAE or WinUAE.

This package was extracted from the vscode-amiga-assembly extension, to create stand-alone adapter for use with other editors that support Debug Adapter Protocol.

This library relies on patched binaries for FS-UAE and WinUAE with changes from @prb28 and @bartman to provide a remote GDB server. These are now bundled with the package for Windows, Mac and Debian Linux x64. Note that the FS-UAE implementation is now based on the current 4.x dev build, and as such has some limitations and missing features. It is totally usable though and is much closer to current WinUAE, allowing us to share common patches rather than maintaining two separate GDB implementations.

Tested with:

• NeoVim nvim-dap plugin. See example below.
• Emacs dap-mode. See emacs-m68k (currently using 0.x version).

Installation

Install the uae-dap npm package globally: npm i -g uae-dap

Usage

The Amiga binaries to be debugged must include SAS/C-compatible LINE DEBUG hunks. Use the -linedebug option is vasm and -hunkdebug in vbcc to include these.

Example configuration:

Here's a minimal example configuration for NeoVim with the Amiga Assembly example workspace.

dap.adapters.asm68k = {
  type = 'executable',
  command = 'uae-dap',
  options = { initialize_timeout_sec = 20 },
}

dap.configurations.asm68k = {
  {
    type = 'asm68k',
    request = 'launch',
    program = '${workspaceFolder}/uae/dh0/gencop',
    stopOnEntry = true,
    emulatorType = "fs-uae",
    emulatorArgs = {
      "--chip_memory=2048",
      "--amiga_model=A1200",
      "--automatic_input_grab=0",
      "--floppy_drive_0_sounds=off",
      "--hide_hud=1",
      "--window_resizable=1"
    }
  }
}

Configuration options:

Changes

1.0

• Changed configuration schema
• No longer supports the patched fs-uae 3.x implementation.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[1.1.5] - 2024-06-20

Fixed

• Default exception mask should only include error types
• Add line break after console output

[1.1.4] - 2024-02-03

Fixed

• WinUAE 5.1.0 hanging on remote debugger startup. Revert to 4.10.0 for now

[1.1.3] - 2024-02-02

Fixed

• Ensure npm build is called before publish!

[1.1.2] - 2024-02-02

Fixed

• Can't chain process.on()

[1.1.1] - 2024-02-02

Fixed

• Ignore VSIX files. Was accidentally being added to npm package.

[1.1.0] - 2024-02-02

Added

• Standalone vscode extension for testing/debugging

Changed

• Upgrade emulator to WinUAE 5.1.0 and FS-UAE fork based on this version

[1.0.7] - 2023-11-19

Fixed

• Prevent exception on step with WinUAE
• FS-UAE Mac/Linux returns correct exception codes. Windows binaries still to come.

[1.0.6] - 2023-11-17

Fixed

• Prevent exception with stopOnEntry

[1.0.5] - 2023-11-15

Fixed

• Force kill emulator if SIGKILL doesn't work
• Handle unsupported message types 'S' for stop codes and 'O' for output
• Special case to handle S05 as exception. Ideally the emulator would return appropriate codes for each exception type, but at least for now this prevents it being treated as a breakpoint.

[1.0.4] - 2023-11-09

Fixed

• wasm node 18 incompatibility issue

[1.0.3] - 2023-08-17

Fixed

• Use newer, more portable FS-UAE build for Mac/Linux

[1.0.2] - 2023-03-23

Fixed

• Source map addresses calculated incorrectly. Base offset shouldn't be added.

[1.0.1] - 2023-03-05

Fixed

• Revert to older FS-UAE build to avoid breakpoint issue on Windows.

[1.0.0] - 2022-10-07

Added

• Allow a access to UAE Console debug commands. These can now be executed in the debug console using a '$' prefix

Changed

• Improved help text in console. Now has compact summary with help per command.
• Update fs-uae

Fixed

• Error 'experimental fetch' error in wasm vasm with node 18
• Various issues in beta

[1.0.0-beta.0] - 2022-09-16

Changed

• Major rewrite with new patched FS-UAE 4.x
• Bundled binaries
• New config schema

[0.7.2] - 2022-06-13

Fixed

• Signed memory references were always negative!

[0.7.1] - 2022-06-13

Fixed

• Non-decimal numbers not supported in memory reference

[0.7.0] - 2022-06-12

Added

• Interrupt addresses in variables list
• Source constants in variable list
• Size/Sign fields for register variables

Changed

• Symbol names in stack trace
• Uses source references for disassembled sources, rather than writing to temp files
• Improved memory expressions - supports size and sign options
• Logpoint expressions formatted in hexadecimal for consistency
• Nicer syntax for expressions and commands, updated help text
• Better completions in REPL

Fixed

• Support memory read in logpoint expressions

[0.6.0] - 2022-06-06

Added

• Conditional breakpoints
• Logpoints

Fixed

• Better handling of stop on entry with WinUAE. Avoids race condition ands sends correct 'reason' property.
• Data breakpoint info request was broken.

[0.5.2] - 2022-06-04

Fixed

• Null coalesce for variable format
• Missing type export and variable formats
• Return formatted value for set variable

[0.5.1] - 2022-06-01

Fixed

• Support copper index in breakpoint source

[0.5.0] - 2022-05-31

Added

• Custom registers in scope
• Additional number formats

Fixed

• WinUAE support

[0.4.0] - 2022-05-28

Changed

• Pass memory format in launch arguments

[0.3.2] - 2022-05-27

Added

• Custom command for disassembled file contents

Fixed

• Expressions in dbgasm addresses
• CPU dbgasm formatting

[0.3.0] - 2022-05-27

Changed

• Abstract breakpoint storage. This will allow the vscode extension to make storage persistent
• Refactor for vscode hooks

Fixed

• Use correct variable format property name
• Prevent child process starting in inspect mode

[0.2.1] - 2022-05-25

Changed

• Add additional exports to index

Fixed

• Automatically detect wasm path
• Ignore .github dir
• Set correct main path

[0.2.0] - 2022-05-25

Changed

• Big refactor and cleanup
• Copper disassembly to temporary files

[0.1.0] - 2022-05-18

Added

• Tests migrated from VS Code extension

Changed

• Use wasm build of cstool to remove dependency on binary
• Refactor / cleanup

Fixed

• Expression parsing handles numeric literals
• NeoVim 'thread already stopped' issue on step events

[0.0.0] - 2022-05-13

Added

• Initial release