git.sur5r.net Git - cc65/blob - doc/debugging.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>Using VICE with cc65
   6 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
   7 <date>03.12.2000
   8
   9 <abstract>
  10 How to debug your code using the VICE emulator.
  11 </abstract>
  12
  13 <!-- Table of contents -->
  14 <toc>
  15
  16 <!-- Begin the document -->
  17
  18 <sect>Overview<p>
  19
  20 This document describes how to debug your programs using the cc65 development
  21 tools and the VICE CBM emulator.
  22
  23
  24
  25 <sect>What is VICE?<p>
  26
  27 VICE is an emulator for many of the CBM machines. It runs on Unix, DOS and
  28 Windows 95. It emulates the Commodore 64, 128, VIC20, PET and the 600/700
  29 machines. For more information see the VICE home page:
  30
  31 <htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
  32 name="http://www.cs.cmu.edu/~dsladic/vice/vice.html">
  33
  34 VICE has a builtin machine language monitor that may be used for debugging
  35 your programs. Using an emulator for debugging has some advantages:
  36
  37 <itemize>
  38
  39 <item>Since you're using a crossassembler/-compiler anyway, you don't need to
  40 transfer the program to the real machine until it is done.
  41
  42 <item>An emulator allows many things that are almost impossible one of the
  43 original machines. You may set watchpoints (detect read or write access to
  44 arbitary addresses), debug interrupt handlers and even debug routines that run
  45 inside the 1541 floppy.
  46
  47 <item>You may use the label file generated by the linker to make much more use
  48 from the monitor.
  49
  50 </itemize>
  51
  52 Please note that you need at least VICE version 0.16 for the label file
  53 feature to work. This version has still some problems (see <ref id="problems"
  54 name="Problems and workarounds">), but older versions had even more problems
  55 and do <em/not/ work correctly.
  56
  57
  58
  59 <sect>How to prepare your programs<p>
  60
  61 VICE support is mostly done via a label file that is generated by the linker
  62 and that may be read by the VICE monitor, so it knows about your program.
  63 Source level debugging is <tt/not/ available, you have to debug your programs
  64 in the assembler view.
  65
  66 The first step is to generate object files that contain information about
  67 <em/all/ labels in your sources, not just the exported ones. This can be done
  68 by several means:
  69
  70 <itemize>
  71
  72 <item>Use the -g switch on the assembler command line.
  73
  74 <item>Use the
  75 <tscreen><verb>
  76       .debuginfo +
  77 </verb></tscreen>
  78     command in your source.
  79
  80 <item>Use the <tt/-g/ switch when invoking the compiler. The compiler will
  81 then place a <tt/.debuginfo/ command into the generated assembler source.
  82
  83 </itemize>
  84
  85 So, if you have just C code, all you need is to invoke the compiler with
  86 <tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the
  87 assembler, or add "<tt/.debuginfo on/" to your source files. Since the
  88 generated debug info is not appended to the generated executables, it is a
  89 good idea to always use <tt/-g/. It makes the object files and libraries
  90 slightly larger (&tilde;30%), but this is usually not a problem.
  91
  92 The second step is to tell the linker that it should generate a VICE label
  93 file. This is done by the <tt/-Ln/ switch followed by the name of the label
  94 file (I'm usually using a <tt/.lbl/ extension for these files). An example for
  95 a linker command line would be:
  96
  97 <tscreen><verb>
  98     ld65 -t c64 -Ln hello.lbl -m hello.map -o hello crt0 hello.o c64.lib
  99 </verb></tscreen>
 100
 101 This will generate a file named hello.lbl that contains all symbols used in
 102 your program.
 103
 104 <bf>Note</bf>: The runtime libraries and startup files were generated with
 105 debug info, so you don't have to care about this.
 106
 107
 108
 109 <sect>How to use the label file<p>
 110
 111 Load your program, then enter the monitor and use the "<tt/ll/" command to
 112 load your label file like this:
 113
 114 <tscreen><verb>
 115         ll "hello.lbl"
 116 </verb></tscreen>
 117
 118 You will get lots of warnings and even a few errors. You may ignore safely all
 119 these warnings and errors as long as they reference any problems VICE thinks
 120 it has with the labels.
 121
 122 After loading the labels, they are used by VICE in the disassembler listing,
 123 and you may use them whereever you need to specify an address. Try
 124
 125 <tscreen><verb>
 126         d ._main
 127 </verb></tscreen>
 128
 129 as an example (note that VICE needs a leading dot before all labels, and that
 130 the compiler prepends an underline under most named labels).
 131
 132
 133
 134 <sect>Problems and workarounds<label id="problems"><p>
 135
 136 Older versions of VICE had several problems with labels. However, even those
 137 versions were still tremendously useful, and all known problems are gone in
 138 current versions. So, here is a list of the problems known to me as of version
 139 0.16.1:
 140
 141 <itemize>
 142
 143 <item>The "<tt/ll/" command does not work. Worse, it seems that internal
 144 memory gets corrupted when using this command, so VICE will crash after use.
 145 Use the "<tt/pb/" command to load the label file in this case.
 146
 147 <item>VICE will crash if you use a label that is undefined. This is probably
 148 the worst problem of all, since it needs just one typo to kill VICE. So, watch
 149 your steps:-)
 150
 151 <item>Cheap labels, that is, labels starting with '@' or '?' are not accepted.
 152
 153 <item>The disassembly output is somewhat suboptimal. However, most things are
 154 just cosmetical, e.g. labels appended to the right side of the disassembled
 155 code.
 156
 157 </itemize>
 158
 159 <bf>Note</bf>: All these problems are fixed in current (&gt;= 1.0) VICE
 160 versions. If you're really using such an old version, you should think about
 161 an upgrade.
 162
 163
 164
 165 </article>
 166
 167
 168