pouët.net

C64Debugger v0.5 by Samar Productions

C64 Debugger by SLAJEREK/SAMAR
------------------------------

Vice (C) 1993-2016 The VICE Team


This is Commodore 64 code and memory debugger that works in real time.
It is quick prototyping tool where you can play with Commodore 64 machine
and its internals.

C64 Debugger utilises VICE v2.4 C64 emulation engine created by The VICE Team.


* Installation

On Windows you need to install Visual Studio C++ 2008 Redistributable package.
On Linux you need GTK3 libraries.


* Keyboard shortcuts

Global shortcuts:

Alt+Enter 
	Toggle fullscreen (MS Windows only)
Ctrl+F1
	Show only C64 screen
Ctrl+F2
	Show C64 disassembler, memory map and data dump
Ctrl+F3
	Show C64 disassembler with hex codes, memory map, data dump 
        and VIC state
Ctrl+F4
	Show C64 and 1541 disk disassembler and memory maps
Ctrl+F5
	Show states of chips
Ctrl+F6
	Show C64 disassembler and a big memory map
Ctrl+F7
	Show C64 and 1541 disk disassembler
Ctrl+F8
	Show Monitor console and debugging tools
TAB
	Change focus to next view
Shift+TAB
	Change focus to previous view
F9
	Show Main menu screen
Ctrl+B
	Show Breakpoints screen
Ctrl+Shift+S
	Show Snapshots screen
Ctrl+8
	Insert D64 file
Ctrl+O
	Load PRG file
Ctrl+L
	Reload PRG & Start
Ctrl+0
	Attach cartridge
Ctrl+F
	Cartridge freeze button
Ctrl+R
	Soft reset C64
Ctrl+Shift+R
	Hard reset C64
Ctrl+P
	Limit emulation speed On/Off (warp mode)
Ctrl+Y
	Use keyboard arrows as joystick On/Off, Right Alt to fire
F10
	Pause code or run to next instruction (step)
Ctrl+F10
	Step to next line (step over JSR)
Shift+F10
	Run one CPU cycle
F11
	Run/continue emulation
Ctrl+M
	Toggle data memory map/dump taken directly from RAM or as-is with
        I/O and ROMs selected by $0001
Ctrl+E
	Toggle show current raster beam position
Ctrl+S
	Store snapshot to a file
Ctrl+D
	Restore snapshot from a file
Shift+Ctrl+1, 2, 3, ..., 6
	Quick store snapshot to slot #1,#2,#3, ..., or #6
Ctrl+1, 2, 3, ..., 6
	Quick restore snapshot from slot #1,#2,#3, ..., or #6
Ctrl+U
	Dump C64's memory to file
Ctrl+Shift+U
	Dump 1541 Drive's memory to file


In Disassembly view:

Mouse Click on memory address
	Add/remove breakpoint
` (~ tilde key)
	Add/remove breakpoint
Arrow Up/Down
	Scroll code one instruction up/down
Page Up/Page Down or Shift+Arrow Up/Shift+Arrow Down
	Scroll code by $100 bytes up/down
Space
	Toggle tracking of code display by current PC
Enter
	Enter code editing mode (assemble)
Arrow Left/Right
	If not editing code: Scroll code one byte up/down
	If editing code and hex values visible: change edited hex value
CTRL+G <addr>  
        Move cursor to specific address (f.e. CTRL+G EA31)
CTRL+J
	JMP to current cursor's address (change CPU PC)


In Data dump view:

Mouse click on hex value
	Select hex value
Double mouse click on hex value
	Scroll disassemble view to selected address
Arrow keys
	Move editing cursor
Page Up/Page Down or Shift+Arrow Up/Shift+Arrow Down
	Scroll code by $100 bytes up/down
Enter or 0-9 or A-F
	Start editing value
Alt+Shift
	Change CBM charset
Ctrl+K
	Change colour mode on/off for sprites/characters
CTRL+G <addr>
	Move cursor to specific address (f.e. CTRL+G 0400)


In Memory map view:

Memory map shows current values of memory cells. Ctrl+M switches bank to
RAM. Each memory cell value is mapped into RGB or Gray or None. In RGB mode 
red are values from 0 to 85, green are values from 85 to 170 and blue are 
values from 170 to 255. In Gray mode all values are mapped into grayscale
colors.

Memory access:
  white shows current PC
  blue  marks read access
  red   marks write access

You can change colours to ICU-standard (read marked by green) in Settings.

You can click inside memory map to scroll data dump view to a clicked memory
address. You can double click to scroll disassemble view to a clicked memory
address.

You can zoom-in using mouse wheel and move around by holding right mouse click
(Windows, Linux, MacOS) or use mulitouch gestures such as pinch zoom and 
scroll using two fingers (MacOS only). You can select desired control behaviour 
in Settings.


In Breakpoints screen:

Arrow keys
	Move around
Enter or Spacebar
	Toggle value or start editing breakpoint


* Commodore 64 screen

All keys are mapped as original Commodore 64 keyboard. RUN+STOP is mapped to
` (tilde) key. Left Control key is not mapped and reserved for keyboard
shortcuts. Right Control is mapped into C64 Control key.

When joystick is turned on then you can control selected ports using arrow keys,
and right-alt as fire.


* SID state view

You can click waveforms to mute SID channels.


* Monitor screen

You can use these instructions in code monitor:

HELP
    shows help
DEVICE C / D / 8
    set current device (C64/Disk/Disk)
F <from address> <to address> <value>
    fill memory with value
C <from address> <to address> <destination address>
    compare memory with memory
H <from address> <to address> <value> [<value> ...]
    compare memory with values
T <from address> <to address> <destination address>
    copy memory
L <from address> [file name]
    load memory
S <from address> <to address> [file name]
    save memory
G <address>
    jmp to address


* Breakpoints screen

Breakpoint stops the execution of code depending on some state and situation.
In the Breakpoints screen (Ctrl + B) you can click using mouse, or Enter or
Space key to enable or disable monitoring of selected type of the breakpoint.
New value can be added by selecting "...." either by moving the cursor with the 
arrow keys or clicking using mouse. 

These are possibilities:
  VIC / CIA / NMI - stops when selected interruption occurs
  CPU PC - the code will stop as the processor will start to perform instruction 
           from selected address
  MEMORY - stops when there will be attempt to write to the memory of the set 
           value, for example: 4FFF <= 3F will stop code when there will be 
           attempt to write to the cells 4FFF value less or equal to 3F. To
           break at any write access you can use <= FF
  RASTER - stops when raster reaches the set line value

Breakpoints CPU type PC can also be set in the disassembler view by clicking
the mouse cursor on the address or by pressing the ` (tilde) key.

The same applies to 1541 Drive breakpoints on right side of the screen.


* Breakpoints file

Breakpoints file stores information about breakpoints, addresses and values.
Possible entries are:
  break xxxx - break when PC reaches address xxxx
               Example: break 3FFF
  breakraster xxx - break when raster reaches line number xxx
               Example: breakraster 40
  breakmem xxxx oo yy - break on memory write to address xxxx when
               expression oo yy is true. Possible operators oo are: 
               ==, !=, <, <=, >, >=
               Example: breakmem D018<=FF
  breakvic - break on VIC interrupt
  breakcia - break on CIA interrupt
  breaknmi - break on NMI interrupt

All entries are not case sensitive. Please check KickAssembler documentation, 
section 9.5: Writing to User Defined Files.


* Command line options

-help  show help
-layout <id> start with layout id <1-8>
-breakpoints <file>  load breakpoints from file
-wait <ms>   wait before performing tasks
-prg <file>  load PRG file into memory
-d64 <file>  insert D64 disk
-crt <file>  attach cartridge
-jmp <addr>  jmp to address on startup ($ signifies hex value),
             for example jmp $1000, jmp x1000 or jmp 4096
-snapshot <file>  load snapshot from file
-clearsettings    skip auto loading of settings stored in config

Other command line options are the same as selected emulation engine (thus
see Vice documentation for additional command line options).


* Other notes

Step over JSR works in a way that a temporary PC breakpoint is created in
next line. Code will be stopped when PC hits that breakpoint address, in
most situations just after returing from JSR. Note that if code never 
returns from JSR this breakpoint will still be "valid".


* Known bugs

Cartridge is sometimes not initialised properly after machine reset
(especially Action Replay), if AR goes to Basic instead the AR menu, then 
please just reset machine again. It just works sometimes.

When snapshot is loaded then selected settings are not updated in the Settings 
menu (such as SID type, C64 machine model, attached disks, etc).

Loading NTSC snapshot into PAL machine or vice-versa in some cases can crash 
debugger when machine model is changed.

It is not possible to zoom Drive 1541 memory map.

Clicking Drive 1541 memory map does not properly set selected value in memory 
dump view.

In command line help it's wrongly stated layout id options. Valid values of
layout id are from 1 to 8.


* To do

Add memory map zooming for Drive 1541.
Add more detailed VIC view and peek into graphics video RAM.
Add working on files directly instead of C64 memory (file adapter is ready),
to view/edit files directly.
Add custom layouts with layout editor.
Add custom keyboard shortcuts.
Add PAL CRT emulation.
Add Save Screenshot keyboard shortcut.


* Thanks for testing

Mr Wegi/Elysium - valuable suggestions and cartridge knowledge
ElfKaa/Avatar
Don Kichote/Samar
Isildur/Samar - MS Windows bug reports and suggestions


* Beer Donation

If you like this tool and you feel that you would like to share with me 
some beers, then you can use this link: http://tinyurl.com/C64Debugger-PayPal


* Contact

If you have ideas or found a bug feel free to contact me at slajerek@gmail.com


*
* License
*

C64 Debugger is (C) Marcin Skoczylas, aka Slajerek/Samar.

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  02111-1307  USA

The ROM files are Copyright (C) by Commodore Business Machines.


*
* Acknowledgements
*

Portions of this Software may utilize the following copyrighted material,
the use of which is hereby acknowledged:


* VICE License

 VICE, the Versatile Commodore Emulator

    Copyright C 1998-2008 Andreas Boose
    Copyright C 1998-2008 Dag Lem
    Copyright C 1998-2008 Tibor Biczo
    Copyright C 1999-2008 Andreas Matthies
    Copyright C 1999-2008 Martin Pottendorfer
    Copyright C 2000-2008 Spiro Trikaliotis
    Copyright C 2005-2008 Marco van den Heuvel
    Copyright C 2006-2008 Christian Vogelgsang
    Copyright C 2007-2008 Fabrizio Gennari
    Copyright C 1999-2007 Andreas Dehmel
    Copyright C 2003-2005 David Hansel
    Copyright C 2000-2004 Markus Brenner

    Copyright C 1999-2004 Thomas Bretz
    Copyright C 1997-2001 Daniel Sladic
    Copyright C 1996-1999 Ettore Perazzoli
    Copyright C 1996-1999 André Fachat
    Copyright C 1993-1994, 1997-1999 Teemu Rantanen
    Copyright C 1993-1996 Jouko Valta
    Copyright C 1993-1994 Jarkko Sonninen

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  02111-1307  USA

* Commodore ROMs

The ROM files embedded in the source code are Copyright C by Commodore
 Business Machines.

* Libraries

libjpeg 
	is a free software library written for JPEG image compression.
libjson 
	Copyright 2010 Jonathan Wallace. All rights reserved.
libpng version 1.5.2
	March 31, 2011 Copyright (c) 1998-2011 Glenn Randers-Pehrson
	(Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
 	(Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
LodePNG 
	version 20140801 Copyright (c) 2005-2014 Lode Vandevenne
minizip 
	Version 1.01e, February 12th, 2005 Copyright (C) 1998-2005 Gilles Vollant
mtrand
	// Coded by Takuji Nishimura and Makoto Matsumoto.
	// Ported to C++ by Jasper Bedaux 2003/1/1 (see http://www.bedaux.net/mtrand/).
	// The generators returning floating point numbers are based on
	// a version by Isaku Wada, 2002/01/09
	//
	// Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
	// All rights reserved.
utf8
	Copyright 2006 Nemanja Trifunovic
zlib
	Copyright (C) 1995-2006, 2010 Mark Adler
portaudio
	Copyright (c) 1999-2002 Ross Bencina and Phil Burk


*
* Change log
*

v0.5 (2016/06/04)
First public release at "Stary Piernik 11", Torun 2016

v0.41
PAL/NTSC machine model select
Fixed fullscreen problem on Windows

v0.4
Memory map zoom and better marking of code-execute.
Bug fixes.

v0.32
Bug fixes.

v0.31
Step over JSR (Ctrl+F10), thanks Mr Wegi/Elysium for suggestion.
Execute-aware code disassemble.
Quick store & restore snapshots ([Shift+] Ctrl+1,2,...)
UI tweaks suggested by Isildur.

v0.3
Mark code execution (thanks Mr Wegi/Elysium for suggestion)
Code monitor with basic commands DEVICE, F, C, H, T, L, S, G. (thanks DKT for
suggestion.

v0.22
Additional Settings: choose SID model and SID engine, ICU colours scheme, 
mute SID on pause, select joystick port, detach everything
Store: default folders per file type, last screen layout
Settings are stored and restored on startup
Linux tweaks
Bug fixes

v0.21 (2016/04/30)
Cartridge bank peek bug fixed, found by Mr Wegi/Elysium (thanks!)
SID state bug fixed and waveform views added
All data is now embedded into executable
Code optimizations

v0.2 (2016/04/23)
Cartridge support and memory peek
1541 drive breakpoints and debugging
Added to command line: 'wait', 'layout', 'cartridge'
Bug fixes (thanks Isildur)
Overall UI tweaks

v0.11 (2016/04/17)
VICE chips state is displayed (including sprites)
Some UX changes suggested by eLK/Avatar (thanks!)

v0.10 (2016/04/10)
First Vice integration preview

v0.03 (2016/03/30) aka "Samar meeting version"
Bug fixes.

v0.025 (2016/03/26)
Tweaked disassemble code functionality
Added: VIC/SID/CIA/Disk state screen
Added: assemble mnemonics is possible in code view by pressing ENTER key
Added: Linux GTK3 open/save dialogs

v0.024 (2016/03/19)
Cleaned engine. Code refactoring
Mangled keyboard shortcuts a bit
Added: mouse wheel scroll now works
Added: 1541 disk breakpoints

v0.023 (2016/03/12)
You can click inside memory map to scroll data dump view.
Added: reading breakpoints file
Added: command line options
Added: Ctrl+G for goto address in memory dump & disassemble
Added: in disassemble view: Ctrl+J make JMP to address shown by cursor

v0.022 (2016/03/05)
Traversing views in a main screen using TAB or Shift+TAB keys.
Added: Show current raster beam position (Ctrl+E)
Added: Snapshots menu. Store and restore full snapshots at any emulation cycle

v0.021 (2016/02/28)
Fixed mapping of some keys on Windows (thx DKT & Isildur)
ESC key returns, Alt+F4 closes app 
Added: Data dump view shows characters and sprites (Ctrl+K for colour mode)

v0.02 (2016/02/27)
Loading PRG automatically starts if SYS basic command is detected
Disassembled code can be scrolled using keyboard
Added: Data dump screen with hex editing
Added: Memory breakpoints

v0.01-test2 (2016/02/20)
Added: Breakpoints screen
Added: Settings screen

v0.01-test1 (2016/02/15)
First internal release


CIAO!