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>  <toc>  <sect>Overview This document describes how to debug your programs using the cc65 development tools and the VICE CBM emulator. <sect>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: <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 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 -t c64 -Ln 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 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"> 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>