mirror of
https://github.com/cc65/cc65.git
synced 2025-02-21 05:29:16 +00:00
More SGML conversions
git-svn-id: svn://svn.cc65.org/cc65/trunk@532 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz
parent
5d34df27c2
commit
e5d3067d1d
@ -10,6 +10,7 @@ SGML = ar65.sgml \
|
||||
cc65.sgml \
|
||||
cl65.sgml \
|
||||
coding.sgml \
|
||||
debugging.sgml \
|
||||
dio.sgml \
|
||||
geos.sgml \
|
||||
index.sgml \
|
||||
|
||||
168
doc/debugging.sgml
Normal file
168
doc/debugging.sgml
Normal file
@ -0,0 +1,168 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<article>
|
||||
|
||||
<title>Using VICE with cc65
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>03.12.2000
|
||||
|
||||
<abstract>
|
||||
How to debug your code using the VICE emulator.
|
||||
</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 CBM emulator.
|
||||
|
||||
|
||||
|
||||
<sect>What is VICE?<p>
|
||||
|
||||
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:
|
||||
|
||||
<htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
|
||||
name="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:
|
||||
|
||||
<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
|
||||
arbitary 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>
|
||||
|
||||
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 <ref id="problems"
|
||||
name="Problems and workarounds">), but older versions had even more problems
|
||||
and do <em/not/ work correctly.
|
||||
|
||||
|
||||
|
||||
<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/-L/ 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 -t c64 -L hello.lbl -m hello.map -o hello crt0 hello.o c64.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<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 whereever 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).
|
||||
|
||||
|
||||
|
||||
<sect>Problems and workarounds<label id="problems"><p>
|
||||
|
||||
Older versions of VICE had several problems with labels. However, even those
|
||||
versions were still tremendously useful, and all known problems are gone in
|
||||
current versions. So, here is a list of the problems known to me as of version
|
||||
0.16.1:
|
||||
|
||||
<itemize>
|
||||
|
||||
<item>The "<tt/ll/" command does not work. Worse, it seems that internal
|
||||
memory gets corrupted when using this command, so VICE will crash after use.
|
||||
Use the "<tt/pb/" command to load the label file in this case.
|
||||
|
||||
<item>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:-)
|
||||
|
||||
<item>Cheap labels, that is, labels starting with '@' or '?' are not accepted.
|
||||
|
||||
<item>The disassembly output is somewhat suboptimal. However, most things are
|
||||
just cosmetical, e.g. labels appended to the right side of the disassembled
|
||||
code.
|
||||
|
||||
</itemize>
|
||||
|
||||
<bf>Note</bf>: All these problems are fixed in current (>= 1.0) VICE
|
||||
versions. If you're really using such an old version, you should think about
|
||||
an upgrade.
|
||||
|
||||
|
||||
|
||||
</article>
|
||||
|
||||
|
||||
|
||||
@ -1,151 +0,0 @@
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@ -37,7 +37,7 @@ Main documentation page, contains links to other available stuff.
|
||||
<tag><htmlurl url="compile.txt" name="compile.txt"></tag>
|
||||
How to compile cc65 and the support tools.
|
||||
|
||||
<tag><htmlurl url="debugging.txt" name="debugging.txt"></tag>
|
||||
<tag><htmlurl url="debugging.html" name="debugging.html"></tag>
|
||||
Debug programs using the VICE emulator.
|
||||
|
||||
<tag><htmlurl url="dio.html" name="dio.html"></tag>
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
<title>cc65 compiler intro
|
||||
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
|
||||
<date>19.07.2000
|
||||
<date>03.12.2000
|
||||
|
||||
<abstract>
|
||||
How to use the cc65 C compiler - an introduction.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user