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

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