Using emulators with cc65

Ullrich von Bassewitz


How to debug your code using the VICE and Oricutron emulators.

1. Overview

2. What is VICE?

3. How to prepare your programs

4. How to use the label file with VICE

5. How to use the label file with Oricutron


1. Overview

This document describes how to debug your programs using the cc65 development tools and the VICE or Oricutron emulator.

2. What is VICE?

VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS, Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information see the VICE home page:

http://vice-emu.sourceforge.net/.

VICE has a builtin machine language monitor that may be used for debugging your programs. Using an emulator for debugging has some advantages:

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:

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 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 -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 -Ln 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 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib
or
    ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.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 with VICE

Load your program, then enter the monitor and use the "ll" command to load your label file like this:

        ll "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 wherever 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).

If you start the emulator from the commandline, you can also load the labels directly using something like this:

        x64sc -moncommands hello.lbl hello.prg

5. How to use the label file with Oricutron

Load your program, then enter the monitor and use the "sl" command to load your label file like this:

        sl hello.sym

After loading the labels, they are used by Oricutron in the disassembler listing, and you may use them wherever you need to specify an address. Try

        d ._main

as an example.