cc65.sgml \
cl65.sgml \
coding.sgml \
+ debugging.sgml \
dio.sgml \
geos.sgml \
index.sgml \
--- /dev/null
+<!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>
+
+
+
+++ /dev/null
-
-
- 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.
-
<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>
<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.
projects / cc65 / commitdiff