amiga-debug Visual Studio Code Extension (Windows only)

One-stop Visual Studio Code Extention to compile, debug and profile Amiga C/C++ programs compiled by the bundled gcc 10.1 with the bundled WinUAE.

Overview

This fully self-contained extension will help you to quickly develop demos, intros, games, etc. for the Amiga 500, 1200, 4000. It supports C and C++, however no standard library is available. It comes with advanced productivity features like debug overlay, frame profiler and size profiler.

Quick-start

Install the extension from the Visual Studio Code Marketplace
Create a new empty project folder with File > Open Folder...
From the command palette Ctrl+Shift+P select Amiga: Init Project
Open .vscode/launch.json and point "kickstart" to your Kickstart 1.3 ROM
Hit F5 to build and run a minimal sample project
If you prefer C++ instead of C, just rename main.c to main.cpp

Features

No additional tools required. Everything is included (except Kickstart ROM 😒). Ready to go make your next Amiga 500 production!
State-of-the-art code generation by GCC with Link-Time-Optimizations (LTO) for increased performance and smaller code size
IntelliSense
Full source-level and assembly-level debugging with callstack, breakpoints, watches, registers, memory view with GDB-enabled WinUAE
Fully AmigaOS compatible via included .h files
INCBIN, INCBIN_CHIP support
Output to debug console from WinUAE
WinUAE warp-launch (turbo-boot)
WinUAE warp-mode control from your Amiga project (speed up precalc during development)
WinUAE debug overlay, full control from your Amiga project
Frame Profiler: function-level + DMA cycles profiling
Graphics Debugger: replay a captured frame cycle by cycle and watch your bitmaps change in real-time; Visualize all blitter operations, bitmap writes, copper list, custom registers
Size Profiler: profile the size of your executable by functions, data and references
Shrinkler executable cruncher with size profiling: profile the size of your compressed executable (open .shrinklerstats files)
Terminal window with access to the build tools
Extension automatically mounts executable's directory as dh1:, allowing for reading and writing files.

How-to-use

Amiga: View Memory, Amiga: Set Force Disassembly, Amiga: View Disassembly (Function) are available from the command palette Ctrl+Shift+P
Use the command Amiga: Open Terminal to open a shell with the environment set to use the included tools like elf2hunk, gcc, gnumake etc. (e.g. gnumake clean)
Frame Profiler: function-level + DMA profiling: during a debugging session, press the Profile button on the right of the debug toolbar, and 1 frame will be profiled.
Size Profiler: profile the size of your executable: right-click an ELF file in the Explorer, and select Amiga: Profile File Size
WinUAE debug overlay: see debug_* calls in template project's main.c
WinUAE:
- ^ = single step, Pause = pause/resume Page-up = warp mode
- all necessary options are already configured for Amiga 500, Kickstart 1.3 (for debugging), if you want to change some things (resolution, window size, etc.) just go into the Configurations tab, select default, and hit Save

Supported Amiga Models

Possible values of "config" in .vscode/launch.json:
- "a500": KS 1.3, ECS Agnus, 0.5MB Chip + 0.5MB Slow; needs Kickstart 1.3 ROM in "kickstart"
- "a1200": 68020, 2MB Chip; needs Kickstart 3.1 ROM in "kickstart"
- "a4000": 68030, 68882, 2MB Chip, 8MB FAST; needs Kickstart 3.1 ROM in "kickstart"

Credits

Code by Bartman/Abyss
Testing by Pink/Abyss

Already used in these productions

Coda by Abyss
Tiny Invaders by Abyss
Tiny Galaga by Abyss
AmigaKlang by Alcatraz & Haujobb

Acknowledgements

Debugger support is based in part on Marcel Ball's Cortex-Debug extension.

Copper Disassembly is based in part on prb28's vscode-amiga-assembly extension.

Some modifications of GCC are based on work by Stefan "Bebbo" Franke.

Profiler visualizer is based in part on Microsoft's vscode-js-profile-visualizer extension.

Amiga system-includes (NDK 3.9) copied from an installation of Bebbo's amiga-gcc and modified to work with GCC 8+. Originally downloaded from http://www.haage-partner.de/download/AmigaOS/NDK39.lha

Commodore Amiga Icon by Icons8.

P61.testmod - Module by Skylord/Sector 7

This extension contains binaries of:

modified GCC 10.1.0
- Copyright (C) 2020 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
modified GNU Binutils 2.34.50.20200508
- Copyright (C) 2020 Free Software Foundation, Inc.
- License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html
- This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
modified GNU gdb (GDB) 10.0.50.20200508-git
- Copyright (C) 2020 Free Software Foundation, Inc.
- This program is free software; you may redistribute it under the terms of the GNU General Public License version 3 or (at your option) any later version.
modified WinUAE 4.2.0
modified Shrinkler 4.6
- Copyright 1999-2015 Aske Simon Christensen
- Modified 2020, Bartman/Abyss
modified elf2hunk (source included)
- Copyright (c) 1995-2017, The AROS Development Team. All rights reserved.
- Modified 2018-2020, Bartman/Abyss
GNU Make 4.2.1
- Copyright (C) 1988-2016 Free Software Foundation, Inc.
- License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html
- This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
cd command replacement from AmigaPorts/amiga-cd

Caveats

sometimes when you're multiplying 2 WORDs together, gcc tries to use a (slow) 32-bit multiply. So if you have performance-critical multiplications, consider using the muluw and mulsw functions from gcc8_c_support.h

Porting

Currently this extension only works on Windows due to the included Windows-only binaries of gcc, gdb, elf2hunk and WinUAE. Compilation of gcc, gdb and elf2hunk on Linux should be trivial, as gcc and gdb only contain about 10 lines of code modifications. elf2hunk should work on Linux out-of-the-box. However, porting the GDB-server contained in WinUAE to FS-UAE could be a bit more work. 99% of WinUAE changes are contained in od-win32/barto_gdbserver.cpp|h.

Here are the command-lines used to compile the external tools:

MinGW on WSL (Ubuntu 18.04)

apt install build-essential flex bison expect dejagnu texinfo mingw-w64

Binutils

mkdir -p build-binutils-2.34
cd build-binutils-2.34
LDFLAGS="-static -static-libgcc -static-libstdc++" ../binutils-2.34/configure --disable-multilib --disable-nls --enable-lto --prefix=/opt/amiga/10.1.0 --target=m68k-amiga-elf --host=x86_64-w64-mingw32
make -j6
sudo make install

GDB

mkdir build-binutils-gdb
cd build-binutils-gdb
LDFLAGS="-static -static-libgcc -static-libstdc++" ../binutils-gdb/configure --prefix=/opt/amiga/10.1.0 --target=m68k-amiga-elf --disable-werror -enable-static --disable-shared --disable-interprocess-agent --disable-libcc --host=x86_64-w64-mingw32
make -j6
sudo make install
sudo strip /opt/amiga/10.1.0/bin/*.exe
sudo strip /opt/amiga/10.1.0/m68k-amiga-elf/bin/*.exe

GCC

cd gcc
./contrib/download_prerequisites
cd ..
mkdir -p build-gcc-10.1.0
cd build-gcc-10.1.0
LDFLAGS="-static -static-libgcc -static-libstdc++" ../gcc/configure \
  --target=m68k-amiga-elf \
  --disable-nls \
  --enable-languages=c,c++ \
  --enable-lto \
  --prefix=/opt/amiga/10.1.0 \
  --disable-libssp \
  --disable-gcov \
  --disable-multilib \
  --disable-threads \
  --with-cpu=68000 \
  --disable-libsanitizer \
  --disable-libada \
  --disable-libgomp \
  --disable-libvtv \
  --disable-nls \
  --disable-clocale \
  --host=x86_64-w64-mingw32 \
  --enable-static
make all-gcc -j6
sed 's/selftest # srcextra/# selftest srcextra/' gcc/Makefile >gcc/Makefile.tmp
mv gcc/Makefile.tmp gcc/Makefile
gcc/gcc-cross.exe -dumpspecs >gcc/specs
make all-gcc -j6
sudo make install-gcc
sudo strip /opt/amiga/10.1.0/bin/*.exe
sudo strip /opt/amiga/10.1.0/m68k-amiga-elf/bin/*.exe
sudo strip /opt/amiga/10.1.0/libexec/gcc/m68k-amiga-elf/10.1.0/*.exe

elf2hunk

LDFLAGS="-static -static-libgcc -static-libstdc++" x86_64-w64-mingw32-gcc -o elf2hunk -DDEBUG=0 elf2hunk.c -lws2_32

Known Issues/TODOs

Debugger: detect TRAP#7 (GCC undefined behavior), detect null-ptr access (GCC undefined behavior)
asm-singlestepping: sometimes doesn't find correct line
tooltips for blitter-rects?
.shrinklerstats profiler doesn't work
fix stray callstack in bobble (can't reproduce)
show compression ratio in .shrinklerstats profile visualizer
store assembly breakpoints in one "virtual" file in breakpointMap (how?!)
when stepping out of IRQ handler, stack frames are corrupt until next step
disassemble address always creates new disassembly even if just stepping. check title of current disassembly window if current PC is in range.
sometimes fail at start: Unable to open 'main.amigaasm': Cannot read property 'customRequest' of undefined.
restartRequest not implemented
vscode.debug.activeDebugSession is undefined when program is stopped on entry
not getting handleThreadSelected(), thread ID now set in class
sometimes Pause/Resume button doesn't correctly switch to "Pause" icon while amiga program is running
step out of kickstart: set fake breakpoint at 0xfffffff, WinUAE should enter TRACE_RANGE_PC mode (TODO: tighten range around loaded program), but keeps breaking later

gnilk / vscode-amiga-debug Goto Github PK

vscode-amiga-debug's Introduction