From: cuz Date: Sun, 3 Dec 2000 18:48:23 +0000 (+0000) Subject: More SGML conversions X-Git-Tag: V2.12.0~3008 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=e5d3067d1d880b8731a71d34503212508cf4cd12;p=cc65 More SGML conversions git-svn-id: svn://svn.cc65.org/cc65/trunk@532 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- diff --git a/doc/Makefile b/doc/Makefile index 074901ec9..20babea17 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -10,6 +10,7 @@ SGML = ar65.sgml \ cc65.sgml \ cl65.sgml \ coding.sgml \ + debugging.sgml \ dio.sgml \ geos.sgml \ index.sgml \ diff --git a/doc/debugging.sgml b/doc/debugging.sgml new file mode 100644 index 000000000..0bfe1795c --- /dev/null +++ b/doc/debugging.sgml @@ -0,0 +1,168 @@ + + +
+ +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> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This document describes how to debug your programs using the cc65 development +tools and the VICE CBM emulator. + + + +<sect>What is VICE?<p> + +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<p> + +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/-L/ 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 -L 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<p> + +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"><p> + +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> + + + diff --git a/doc/debugging.txt b/doc/debugging.txt deleted file mode 100644 index a7a0eaf91..000000000 --- a/doc/debugging.txt +++ /dev/null @@ -1,151 +0,0 @@ - - - Debugging your code using VICE - - Ullrich von Bassewitz, March 1999 - - -Contents --------- - - 1. Overview - - 2. What is VICE? - - 3. How to prepare your sources - - 4. How to use the label file - - 5. Problems and workarounds - - - -1. Overview ------------ - -This document describes how to debug your programs using the cc65 -development tools and the VICE CBM emulator. - - - -2. 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: - - 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: - - - Since you're using a crossassembler/-compiler anyway, you don't need - to transfer the program to the real machine until it is done. - - - 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. - - - You may use the label file generated by the linker to make much more - use from the monitor. - -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 section 5 for -descriptions and some workarounds), but older versions had even more -problems and do NOT work correctly. - - - -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: - - - Use the -g switch on the assembler command line. - - - Use the - - .debuginfo + - - command in your source. - - - Use the -g switch when invoking the compiler. The compiler will then - put the .debuginfo command into the generated assembler source. - -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 +" 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 -L 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 -t c64 -L hello.lbl -m hello.map -o hello crt0 hello.o c64.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 ----------------------------- - -Load your program, then enter the monitor and use the "pb" command to load -your label file like this: - - pb "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 whereever 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). - - - -5. Problems and workarounds ---------------------------- - -Unfortunately, the VICE monitor has several problems with labels. However, -it is still tremendously useful, and I think that most problems are gone -in the next version. So, here is a list of the problems known to me as of -version 0.16.1: - - * The "ll" command does not work. Worse, it seems that internal memory - gets corrupted when using this command, so VICE will crash after use. - Be sure to use the "pb" command to load the label file. - - * 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:-) - - * Cheap labels, that is, labels starting with '@' or '?' are not - accepted. - - * The disassembly output is somewhat suboptimal. However, most things are - just cosmetical, e.g. labels appended to the right side of the - disassembled code. - diff --git a/doc/index.sgml b/doc/index.sgml index 1e4c44fee..7d6b7661e 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -37,7 +37,7 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="compile.txt" name="compile.txt"></tag> How to compile cc65 and the support tools. - <tag><htmlurl url="debugging.txt" name="debugging.txt"></tag> + <tag><htmlurl url="debugging.html" name="debugging.html"></tag> Debug programs using the VICE emulator. <tag><htmlurl url="dio.html" name="dio.html"></tag> diff --git a/doc/intro.sgml b/doc/intro.sgml index 14ec3ab46..bb38686da 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -4,7 +4,7 @@ <title>cc65 compiler intro <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>19.07.2000 +<date>03.12.2000 <abstract> How to use the cc65 C compiler - an introduction.