mirror of https://github.com/cc65/cc65.git
158 lines
4.6 KiB
Plaintext
158 lines
4.6 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
<title>Using emulators with cc65
|
|
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
|
|
|
|
<abstract>
|
|
How to debug your code using the VICE and Oricutron emulators.
|
|
</abstract>
|
|
|
|
<!-- Table of contents -->
|
|
<toc>
|
|
|
|
<!-- Begin the document -->
|
|
|
|
<sect>Overview<p>
|
|
|
|
This document describes how to debug your programs using the cc65 development
|
|
tools and the VICE or Oricutron emulator.
|
|
|
|
|
|
|
|
<sect>What is VICE?<p>
|
|
|
|
VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS,
|
|
Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates
|
|
the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information
|
|
see the VICE home page:
|
|
|
|
<url url="http://vice-emu.sourceforge.net/">.
|
|
|
|
VICE has a builtin machine language monitor that may be used for debugging
|
|
your programs. Using an emulator for debugging has some advantages:
|
|
|
|
<itemize>
|
|
|
|
<item>Since you're using a crossassembler/-compiler anyway, you don't need to
|
|
transfer the program to the real machine until it is done.
|
|
|
|
<item>An emulator allows many things that are almost impossible one of the
|
|
original machines. You may set watchpoints (detect read or write access to
|
|
arbitrary addresses), debug interrupt handlers and even debug routines that run
|
|
inside the 1541 floppy.
|
|
|
|
<item>You may use the label file generated by the linker to make much more use
|
|
from the monitor.
|
|
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect>How to prepare your programs<p>
|
|
|
|
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 <tt/not/ available, you have to debug your programs
|
|
in the assembler view.
|
|
|
|
The first step is to generate object files that contain information about
|
|
<em/all/ labels in your sources, not just the exported ones. This can be done
|
|
by several means:
|
|
|
|
<itemize>
|
|
|
|
<item>Use the -g switch on the assembler command line.
|
|
|
|
<item>Use the
|
|
<tscreen><verb>
|
|
.debuginfo +
|
|
</verb></tscreen>
|
|
command in your source.
|
|
|
|
<item>Use the <tt/-g/ switch when invoking the compiler. The compiler will
|
|
then place a <tt/.debuginfo/ command into the generated assembler source.
|
|
|
|
</itemize>
|
|
|
|
So, if you have just C code, all you need is to invoke the compiler with
|
|
<tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the
|
|
assembler, or add "<tt/.debuginfo on/" to your source files. Since the
|
|
generated debug info is not appended to the generated executables, it is a
|
|
good idea to always use <tt/-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 <tt/-Ln/ switch followed by the name of the label
|
|
file (I'm usually using a <tt/.lbl/ extension for these files). An example for
|
|
a linker command line would be:
|
|
|
|
<tscreen><verb>
|
|
ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
|
|
</verb></tscreen>
|
|
or
|
|
<tscreen><verb>
|
|
ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib
|
|
</verb></tscreen>
|
|
|
|
This will generate a file named hello.lbl that contains all symbols used in
|
|
your program.
|
|
|
|
<bf>Note</bf>: The runtime libraries and startup files were generated with
|
|
debug info, so you don't have to care about this.
|
|
|
|
|
|
|
|
<sect>How to use the label file with VICE<p>
|
|
|
|
Load your program, then enter the monitor and use the "<tt/ll/" command to
|
|
load your label file like this:
|
|
|
|
<tscreen><verb>
|
|
ll "hello.lbl"
|
|
</verb></tscreen>
|
|
|
|
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 wherever you need to specify an address. Try
|
|
|
|
<tscreen><verb>
|
|
d ._main
|
|
</verb></tscreen>
|
|
|
|
as an example (note that VICE needs a leading dot before all labels, and that
|
|
the compiler prepends an underline under most named labels).
|
|
|
|
If you start the emulator from the commandline, you can also load the labels
|
|
directly using something like this:
|
|
|
|
<tscreen><verb>
|
|
x64sc -moncommands hello.lbl hello.prg
|
|
</verb></tscreen>
|
|
|
|
|
|
<sect>How to use the label file with Oricutron<p>
|
|
|
|
Load your program, then enter the monitor and use the "<tt/sl/" command to
|
|
load your label file like this:
|
|
|
|
<tscreen><verb>
|
|
sl hello.sym
|
|
</verb></tscreen>
|
|
|
|
After loading the labels, they are used by Oricutron in the disassembler listing,
|
|
and you may use them wherever you need to specify an address. Try
|
|
|
|
<tscreen><verb>
|
|
d ._main
|
|
</verb></tscreen>
|
|
|
|
as an example.
|
|
|
|
|
|
|
|
</article>
|