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

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>Using emulators with cc65
   6 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
   7 <date>2014-04-11
   8
   9 <abstract>
  10 How to debug your code using the VICE and Oricutron emulators.
  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, MS-DOS,
  28 Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates
  29 the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information
  30 see the VICE home page:
  31
  32 <url url="http://vice-emu.sourceforge.net/">.
  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
  53
  54 <sect>How to prepare your programs<p>
  55
  56 VICE support is mostly done via a label file that is generated by the linker
  57 and that may be read by the VICE monitor, so it knows about your program.
  58 Source level debugging is <tt/not/ available, you have to debug your programs
  59 in the assembler view.
  60
  61 The first step is to generate object files that contain information about
  62 <em/all/ labels in your sources, not just the exported ones. This can be done
  63 by several means:
  64
  65 <itemize>
  66
  67 <item>Use the -g switch on the assembler command line.
  68
  69 <item>Use the
  70 <tscreen><verb>
  71       .debuginfo +
  72 </verb></tscreen>
  73     command in your source.
  74
  75 <item>Use the <tt/-g/ switch when invoking the compiler. The compiler will
  76 then place a <tt/.debuginfo/ command into the generated assembler source.
  77
  78 </itemize>
  79
  80 So, if you have just C code, all you need is to invoke the compiler with
  81 <tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the
  82 assembler, or add "<tt/.debuginfo on/" to your source files. Since the
  83 generated debug info is not appended to the generated executables, it is a
  84 good idea to always use <tt/-g/. It makes the object files and libraries
  85 slightly larger (&tilde;30%), but this is usually not a problem.
  86
  87 The second step is to tell the linker that it should generate a VICE label
  88 file. This is done by the <tt/-Ln/ switch followed by the name of the label
  89 file (I'm usually using a <tt/.lbl/ extension for these files). An example for
  90 a linker command line would be:
  91
  92 <tscreen><verb>
  93     ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
  94 </verb></tscreen>
  95 or
  96 <tscreen><verb>
  97     ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib
  98 </verb></tscreen>
  99
 100 This will generate a file named hello.lbl that contains all symbols used in
 101 your program.
 102
 103 <bf>Note</bf>: The runtime libraries and startup files were generated with
 104 debug info, so you don't have to care about this.
 105
 106
 107
 108 <sect>How to use the label file with VICE<p>
 109
 110 Load your program, then enter the monitor and use the "<tt/ll/" command to
 111 load your label file like this:
 112
 113 <tscreen><verb>
 114         ll "hello.lbl"
 115 </verb></tscreen>
 116
 117 You will get lots of warnings and even a few errors. You may ignore safely all
 118 these warnings and errors as long as they reference any problems VICE thinks
 119 it has with the labels.
 120
 121 After loading the labels, they are used by VICE in the disassembler listing,
 122 and you may use them whereever you need to specify an address. Try
 123
 124 <tscreen><verb>
 125         d ._main
 126 </verb></tscreen>
 127
 128 as an example (note that VICE needs a leading dot before all labels, and that
 129 the compiler prepends an underline under most named labels).
 130
 131
 132
 133 <sect>How to use the label file with Oricutron<p>
 134
 135 Load your program, then enter the monitor and use the "<tt/sl/" command to
 136 load your label file like this:
 137
 138 <tscreen><verb>
 139         sl hello.sym
 140 </verb></tscreen>
 141
 142 After loading the labels, they are used by Oricutron in the disassembler listing,
 143 and you may use them whereever you need to specify an address. Try
 144
 145 <tscreen><verb>
 146         d ._main
 147 </verb></tscreen>
 148
 149 as an example (note that VICE needs a leading dot before all labels, and that
 150 the compiler prepends an underline under most named labels).
 151
 152
 153
 154 </article>