mirror of
https://github.com/cc65/cc65.git
synced 2024-08-19 17:29:37 +00:00
152 lines
4.7 KiB
Plaintext
152 lines
4.7 KiB
Plaintext
|
|
||
|
|
||
|
Debugging your code using VICE
|
||
|
|
||
|
Ullrich von Bassewitz, March 1999
|
||
|
|
||
|
|
||
|
Contents
|
||
|
--------
|
||
|
|
||
|
1. Overview
|
||
|
|
||
|
2. What is VICE?
|
||
|
|
||
|
3. How to prepare your sources
|
||
|
|
||
|
4. How to use the label file
|
||
|
|
||
|
5. Problems and workarounds
|
||
|
|
||
|
|
||
|
|
||
|
1. Overview
|
||
|
-----------
|
||
|
|
||
|
This document describes how to debug your programs using the cc65
|
||
|
development tools and the VICE CBM emulator.
|
||
|
|
||
|
|
||
|
|
||
|
2. What is VICE?
|
||
|
----------------
|
||
|
|
||
|
VICE is an emulator for many of the CBM machines. It runs on Unix, DOS and
|
||
|
Windows 95. It emulates the Commodore 64, 128, VIC20, PET and the 600/700
|
||
|
machines. For more information see the VICE home page:
|
||
|
|
||
|
http://www.cs.cmu.edu/~dsladic/vice/vice.html
|
||
|
|
||
|
VICE has a builtin machine language monitor that may be used for debugging
|
||
|
your programs. Using an emulator for debugging has some advantages:
|
||
|
|
||
|
- Since you're using a crossassembler/-compiler anyway, you don't need
|
||
|
to transfer the program to the real machine until it is done.
|
||
|
|
||
|
- An emulator allows many things that are almost impossible one of the
|
||
|
original machines. You may set watchpoints (detect read or write
|
||
|
access to arbitary addresses), debug interrupt handlers and even debug
|
||
|
routines that run inside the 1541 floppy.
|
||
|
|
||
|
- You may use the label file generated by the linker to make much more
|
||
|
use from the monitor.
|
||
|
|
||
|
Please note that you need at least VICE version 0.16 for the label file
|
||
|
feature to work. This version has still some problems (see section 5 for
|
||
|
descriptions and some workarounds), but older versions had even more
|
||
|
problems and do NOT work correctly.
|
||
|
|
||
|
|
||
|
|
||
|
3. How to prepare your programs
|
||
|
-------------------------------
|
||
|
|
||
|
VICE support is mostly done via a label file that is generated by the
|
||
|
linker and that may be read by the VICE monitor, so it knows about your
|
||
|
program. Source level debugging is *not* available, you have to debug your
|
||
|
programs in the assembler view.
|
||
|
|
||
|
The first step is to generate object files that contain information about
|
||
|
ALL labels in your sources, not just the exported ones. This can be done
|
||
|
by several means:
|
||
|
|
||
|
- Use the -g switch on the assembler command line.
|
||
|
|
||
|
- Use the
|
||
|
|
||
|
.debuginfo +
|
||
|
|
||
|
command in your source.
|
||
|
|
||
|
- Use the -g switch when invoking the compiler. The compiler will then
|
||
|
put the .debuginfo command into the generated assembler source.
|
||
|
|
||
|
So, if you have just C code, all you need is to invoke the compiler with
|
||
|
-g. If you're using assembler code, you have to use -g for the assembler,
|
||
|
or add ".debuginfo +" to your source files. Since the generated debug info
|
||
|
is not appended to the generated executables, it is a good idea to always
|
||
|
use -g. It makes the object files and libraries slightly larger (~30%),
|
||
|
but this is usually not a problem.
|
||
|
|
||
|
The second step is to tell the linker that it should generate a VICE label
|
||
|
file. This is done by the -L switch followed by the name of the label file
|
||
|
(I'm usually using a .lbl extension for these files). An example for a
|
||
|
linker command line would be:
|
||
|
|
||
|
ld65 -t c64 -L hello.lbl -m hello.map -o hello crt0 hello.o c64.lib
|
||
|
|
||
|
This will generate a file named hello.lbl that contains all symbols used
|
||
|
in your program.
|
||
|
|
||
|
Note: The runtime libraries and startup files were generated with debug
|
||
|
info, so you don't have to care about this.
|
||
|
|
||
|
|
||
|
|
||
|
4. How to use the label file
|
||
|
----------------------------
|
||
|
|
||
|
Load your program, then enter the monitor and use the "pb" command to load
|
||
|
your label file like this:
|
||
|
|
||
|
pb "hello.lbl"
|
||
|
|
||
|
You will get lots of warnings and even a few errors. You may ignore safely
|
||
|
all these warnings and errors as long as they reference any problems VICE
|
||
|
thinks it has with the labels.
|
||
|
|
||
|
After loading the labels, they are used by VICE in the disassembler
|
||
|
listing, and you may use them whereever you need to specify an address.
|
||
|
Try
|
||
|
|
||
|
d ._main
|
||
|
|
||
|
as an example (note that VICE needs a leading dot before all labels, and
|
||
|
that the compiler prepends an underline under most named labels).
|
||
|
|
||
|
|
||
|
|
||
|
5. Problems and workarounds
|
||
|
---------------------------
|
||
|
|
||
|
Unfortunately, the VICE monitor has several problems with labels. However,
|
||
|
it is still tremendously useful, and I think that most problems are gone
|
||
|
in the next version. So, here is a list of the problems known to me as of
|
||
|
version 0.16.1:
|
||
|
|
||
|
* The "ll" command does not work. Worse, it seems that internal memory
|
||
|
gets corrupted when using this command, so VICE will crash after use.
|
||
|
Be sure to use the "pb" command to load the label file.
|
||
|
|
||
|
* VICE will crash if you use a label that is undefined. This is probably
|
||
|
the worst problem of all, since it needs just one typo to kill VICE.
|
||
|
So, watch your steps:-)
|
||
|
|
||
|
* Cheap labels, that is, labels starting with '@' or '?' are not
|
||
|
accepted.
|
||
|
|
||
|
* The disassembly output is somewhat suboptimal. However, most things are
|
||
|
just cosmetical, e.g. labels appended to the right side of the
|
||
|
disassembled code.
|
||
|
|