From 3334082abfe1881591ccb67520b4f3a3b77109fb Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Thu, 30 Jan 2014 13:02:01 +0100 Subject: [PATCH 01/36] Avoid include subdirs on install cmdline. --- libsrc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libsrc/Makefile b/libsrc/Makefile index cbc778f11..3d8277ae5 100644 --- a/libsrc/Makefile +++ b/libsrc/Makefile @@ -82,7 +82,7 @@ define INSTALL_recipe $(if $(prefix),,$(error variable `prefix' must be set)) $(INSTALL) -d $(subst ..,$(DESTDIR)$(datadir),$(dir)) -$(INSTALL) -m644 $(dir)/* $(subst ..,$(DESTDIR)$(datadir),$(dir)) +$(INSTALL) -m644 $(dir)/*.* $(subst ..,$(DESTDIR)$(datadir),$(dir)) endef From c5309e96cad5f2e1d64bf5caf9b98409f9893c41 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Fri, 31 Jan 2014 14:22:47 +0100 Subject: [PATCH 02/36] First test with LinuxDoc. --- .travis.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index ffec9e605..b4f6394a5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,2 +1,6 @@ -language: c -script: make +language: +- c +before_script: +- sudo apt-get install linuxdoc-tools +script: +- make From 56ef96a3bdcb82299832a1b14668f5db8b8851d2 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Fri, 31 Jan 2014 16:37:01 +0100 Subject: [PATCH 03/36] Added secured GH_TOKEN env var. --- .travis.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index b4f6394a5..6a96d7fca 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,9 @@ language: -- c -before_script: -- sudo apt-get install linuxdoc-tools + - c +install: + - sudo apt-get install linuxdoc-tools script: -- make + - make +env: + global: + - secure: "h+hoQdEHGPLNwaqGKmSaM8NBRDLc2X+W05VsnNG2Feq/wPv/AiBjONNlzN7jRf6D6f3aoPXaQ2Lc3bYWdxGvFRCmwiofdxkJI9n5L8HPHLZ2lf37MQsXmGJzoTFOvjPLj73H6HlbI9Ux0El3zO6hvalxiXj6TfoZ41dbhNyvpYk=" From 9aa17b4c537f77fc01d49ab7167b1b3c179c7b97 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Fri, 31 Jan 2014 22:27:07 +0100 Subject: [PATCH 04/36] Moved ca65html out of the src directory. - A HTML generator isn't really the core of a C/asm toolchain. - A Perl script isn't actually as portable as one might think. --- {src/ca65html => util}/ca65html | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {src/ca65html => util}/ca65html (100%) mode change 100755 => 100644 diff --git a/src/ca65html/ca65html b/util/ca65html old mode 100755 new mode 100644 similarity index 100% rename from src/ca65html/ca65html rename to util/ca65html From 4e83ff8d591839f61a4f558e318ec8032425cac3 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Tue, 4 Feb 2014 18:33:37 +0100 Subject: [PATCH 05/36] First test of gh-pages push. --- .travis.yml | 1 + doc/Makefile | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 doc/Makefile diff --git a/.travis.yml b/.travis.yml index 6a96d7fca..79e1a619f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,6 +4,7 @@ install: - sudo apt-get install linuxdoc-tools script: - make + - make -C doc gh-pages env: global: - secure: "h+hoQdEHGPLNwaqGKmSaM8NBRDLc2X+W05VsnNG2Feq/wPv/AiBjONNlzN7jRf6D6f3aoPXaQ2Lc3bYWdxGvFRCmwiofdxkJI9n5L8HPHLZ2lf37MQsXmGJzoTFOvjPLj73H6HlbI9Ux0El3zO6hvalxiXj6TfoZ41dbhNyvpYk=" diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..66969920d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,9 @@ +gh-pages: + git clone --branch=gh-pages https://${GH_TOKEN}@github.com/oliverschmidt/cc65.git ../gh-pages + cd ../gh-pages + git config user.name "Oliver Schmidt" + git config user.email "ol.sc@web.de" + echo date > testfile.txt + git add -A + git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." + git push From b8eb1c779463583354c5ca18603a254921539bda Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Tue, 4 Feb 2014 21:31:35 +0100 Subject: [PATCH 06/36] Avoid 'cd' in Makefile. --- doc/Makefile | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 66969920d..d4860ca40 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,9 +1,10 @@ +GH_PAGES = ../../gh-pages + gh-pages: - git clone --branch=gh-pages https://${GH_TOKEN}@github.com/oliverschmidt/cc65.git ../gh-pages - cd ../gh-pages - git config user.name "Oliver Schmidt" - git config user.email "ol.sc@web.de" - echo date > testfile.txt - git add -A - git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." - git push + git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES) + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" + echo date > $(GH_PAGES)/testfile.txt + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From aa7561ec45fd8f7dbd7ae723b8d9275b48412428 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt Date: Tue, 4 Feb 2014 22:18:58 +0100 Subject: [PATCH 07/36] Revert "No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh-pages'." This reverts commit fcea8951f1dc51cce28cabfc9cfec760a341118a. Conflicts: doc/Makefile --- doc/apple2.sgml | 544 +++ doc/apple2enh.sgml | 550 ++++ doc/ar65.sgml | 156 + doc/atari.sgml | 590 ++++ doc/atmos.sgml | 260 ++ doc/c128.sgml | 356 ++ doc/c16.sgml | 274 ++ doc/c64.sgml | 405 +++ doc/ca65.sgml | 4786 +++++++++++++++++++++++++++ doc/ca65html.sgml | 289 ++ doc/cbm510.sgml | 301 ++ doc/cbm610.sgml | 300 ++ doc/cc65.sgml | 1386 ++++++++ doc/cl65.sgml | 316 ++ doc/co65.sgml | 353 ++ doc/coding.sgml | 308 ++ doc/customizing.sgml | 730 +++++ doc/da65.sgml | 694 ++++ doc/debugging.sgml | 154 + doc/dio.sgml | 134 + doc/funcref.sgml | 7439 ++++++++++++++++++++++++++++++++++++++++++ doc/geos.sgml | 1662 ++++++++++ doc/grc65.sgml | 392 +++ doc/index.sgml | 179 + doc/internal.txt | 207 ++ doc/intro.sgml | 527 +++ doc/ld65.sgml | 1114 +++++++ doc/library.sgml | 251 ++ doc/lynx.sgml | 360 ++ doc/nes.sgml | 197 ++ doc/od65.sgml | 224 ++ doc/pet.sgml | 261 ++ doc/plus4.sgml | 270 ++ doc/smc.sgml | 596 ++++ doc/sp65.sgml | 424 +++ doc/supervision.sgml | 179 + doc/using-make.sgml | 156 + doc/vic20.sgml | 269 ++ 38 files changed, 27593 insertions(+) create mode 100644 doc/apple2.sgml create mode 100644 doc/apple2enh.sgml create mode 100644 doc/ar65.sgml create mode 100644 doc/atari.sgml create mode 100644 doc/atmos.sgml create mode 100644 doc/c128.sgml create mode 100644 doc/c16.sgml create mode 100644 doc/c64.sgml create mode 100644 doc/ca65.sgml create mode 100644 doc/ca65html.sgml create mode 100644 doc/cbm510.sgml create mode 100644 doc/cbm610.sgml create mode 100644 doc/cc65.sgml create mode 100644 doc/cl65.sgml create mode 100644 doc/co65.sgml create mode 100644 doc/coding.sgml create mode 100644 doc/customizing.sgml create mode 100644 doc/da65.sgml create mode 100644 doc/debugging.sgml create mode 100644 doc/dio.sgml create mode 100644 doc/funcref.sgml create mode 100644 doc/geos.sgml create mode 100644 doc/grc65.sgml create mode 100644 doc/index.sgml create mode 100644 doc/internal.txt create mode 100644 doc/intro.sgml create mode 100644 doc/ld65.sgml create mode 100644 doc/library.sgml create mode 100644 doc/lynx.sgml create mode 100644 doc/nes.sgml create mode 100644 doc/od65.sgml create mode 100644 doc/pet.sgml create mode 100644 doc/plus4.sgml create mode 100644 doc/smc.sgml create mode 100644 doc/sp65.sgml create mode 100644 doc/supervision.sgml create mode 100644 doc/using-make.sgml create mode 100644 doc/vic20.sgml diff --git a/doc/apple2.sgml b/doc/apple2.sgml new file mode 100644 index 000000000..fb6dda7fe --- /dev/null +++ b/doc/apple2.sgml @@ -0,0 +1,544 @@ + + +
+ +Apple ][ specific information for cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-10-07 + +<abstract> +An overview over the Apple ][ runtime system as it is +implemented for the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Apple ][ runtime system +as it comes with the cc65 C compiler. It describes the memory layout, +Apple ][ specific header files, available drivers, and any +pitfalls specific to that platform. + +Please note that Apple ][ specific functions are just mentioned +here, they are described in detail in the separate <htmlurl url="funcref.html" +name="function reference">. Even functions marked as "platform dependent" may +be available on more than one platform. Please see the function reference for +more information. + + + +<sect>Binary format<p> + +The standard binary file format generated by the linker for the +Apple ][ target is a binary program with a 4 byte DOS 3.3 header +containing the load address and load length. The default load address is +$803. + +<bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ +that allows to put binary files with a DOS 3.3 header onto disk images +containing DOS 3.3 as well as ProDOS 8. + +For ProDOS 8 system programs the load address is fixed to $2000 so there +is no need for a header. Thus the linker configuration +<htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> for those programs +omits the DOS 3.3 header. The right AppleCommander option to put system files +without a header on a ProDOS 8 disk image is <tt/-p/. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$803 to $95FF, so 35.5 KB of RAM are available. + +Special locations: + +<descrip> + + <tag/Stack/ + The C runtime stack is located at HIMEM and grows downwards, regardless of + how your linker config file is setup. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + +While running <tt/main()/ the Language Card bank 2 is enabled for read access. +However while running module constructors/destructors the Language Card is disabled. + +Enabling the Language Card allows to use it as additional memory for cc65 +generated code. However code is never automatically placed there. Rather code +needs to be explicitly placed in the Language Card either per file by compiling +with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma +code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the +cc65 runtime system takes care of actually moving the code into the Language +Card. + +The amount of memory available in the Language Card for generated code depends +on the chosen <htmlurl url="apple2-4.html" name="linker configuration">. + + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the Apple ][, +which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/). +The apple2 package comes with additional secondary linker config files, which +are used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +Default configuration optimized for a binary program running on ProDOS 8 with +BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card +bank 2 memory from $D400 to $DFFF. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-dos33.cfg/<p> + +Configuration optimized for a binary program running on DOS 3.3. A plain +vanilla DOS 3.3 doesn't make use of the Language Card at all. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $FFFF (12 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-system.cfg/<p> + +Configuration for a system program running on ProDOS 8. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $2000 to $BEFF (39.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Fixed ($2000) + + <tag><tt/HEADER:/ Binary file header</tag> + None + +</descrip><p> + + +<sect1><tt/apple2-loader.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/, which is available +in the cc65 User Contributions section. + +A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but +isn't tied to the start address $2000. Thus with the default start +address $800 the main memory area is increased by 6 KB. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-reboot.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together +with the function <tt/rebootafterexit()/. + +If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather +reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of +the Language Card bank 2 at all. + +This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $DFFF (4 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + + +<sect>ProDOS 8 system programs<p> + +ProDOS 8 system programs are always loaded to the start address $2000. +For cc65 programs this means that the 6 KB from $800 to $2000 are +by default unused. There are however several options to make use of that memory +range. + + +<sect1>LOADER.SYSTEM<p> + +The easiest (and for really large programs in fact the only) way to have a cc65 +program use the memory from $800 to $2000 is to link it as binary +(as opposed to system) program using the linker configuration +<htmlurl url="apple2-4.html#ss4.4" name="apple2-loader.cfg"> with start address +$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ +ProDOS 8 loader for cc65 programs/. The program then works like a system program +(i.e. quits to the ProDOS dispatcher). + +Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the +program to load under name <program>.SYSTEM as a system program. For +example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. + + +<sect1>Heap<p> + +If the cc65 program can be successfully linked as system program using the linker +configuration <htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> but +uses the heap either explicitly or implicitly (i.e. by loading a driver) then +the memory from $800 to $2000 can be added to the heap by calling +<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. + + +<sect1>ProDOS 8 I/O buffers<p> + +ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default +these buffers are allocated by the cc65 runtime system on the heap using +<tt/posix_memalign()/. While this is generally the best solution it means quite +some overhead for (especially rather small) cc65 programs which do open files +but don't make use of the heap otherwise. + +The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation +module <tt/apple2-iobuf-0800.o/ which uses the memory between $800 and +the program start address for the 1 KB I/O buffers. For system programs (with +start address $2000) this results in up to 6 I/O buffers and thus up to 6 +concurrently open files. + +While using <tt/_heapadd()/ as described in the section above together with the +default I/O buffer allocation basically yields the same placement of I/O buffers +in memory the primary benefit of <tt/apple2-iobuf-0800.o/ is a reduction in code +size - and thus program file size - of more than 1400 bytes. + +Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o +</verb></tscreen> + + + +<sect>Platform specific header files<p> + +Programs containing Apple ][ specific code may use the +<tt/apple2.h/ header file. + + +<sect1>Apple ][ specific functions<p> + +The functions listed below are special for the Apple ][. See +the <htmlurl url="funcref.html" name="function reference"> for declaration and +usage. + +<itemize> +<item>_auxtype +<item>_dos_type +<item>_filetype +<item>get_ostype +<item>rebootafterexit +<item>ser_apple2_slot +<item>tgi_apple2_mix +</itemize> + + +<sect1>Hardware access<p> + +There's currently no support for direct hardware access. This does not mean +you cannot do it, it just means that there's no help. + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag> + This driver features a resolution of 40×48 with 16 colors. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function clears the corresponding area at the bottom of the screen. + + <tag><tt/a2.hi.tgi (apple2_280_192_8)/</tag> + This driver features a resolution of 280×192 with 8 colors and two + hires pages. Note that programs using this driver will have to be linked + with <tt/--start-addr $4000/ to reserve the first hires page or with + <tt/--start-addr $6000/ to reserve both hires pages. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function doesn't clear the corresponding area at the bottom of the screen. + + In memory constrained situations the memory from $803 to $1FFF + can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ + at the beginning of <tt/main()/. Doing so is beneficial even if the program + doesn't use the the heap explicitly because loading the driver (and in fact + already opening the driver file) uses the heap implicitly. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/a2.auxmem.emd (apple2_auxmem)/</tag> + Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended + 80-Column Text Card. + + Note that this driver doesn't check for the actual existence of the memory + and that it doesn't check for ProDOS 8 RAM disk content! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/a2.stdjoy.joy (apple2_stdjoy)/</tag> + Supports up to two standard analog joysticks connected to the game port of + the Apple ][. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag> + Driver for the AppleMouse II Card. Searches all Apple II slots + for an AppleMouse II Card compatible firmware. The default bounding + box is [0..279,0..191]. + + Programs using this driver will have to be linked with <tt/--start-addr $4000/ + to reserve the first hires page if they are intended to run on an + Apple ][ (in contrast to an Apple //e) because the + AppleMouse II Card firmware writes to the hires page when initializing + on that machine. + + Note that the Apple ][ default mouse callbacks support text + mode only. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/a2.ssc.ser (apple2_ssc)/</tag> + Driver for the Apple II Super Serial Card. Supports up to 19200 baud, + hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to + <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ + succeeds for all Apple II slots, but <tt/ser_open()/ fails with + <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. + +</descrip><p> + + + +<sect>Limitations<p> + + +<sect1>DOS 3.3<p> + +Although the standard binaries generated by the linker for the Apple ][ +generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with +BASIC.SYSTEM) there are some limitations for DOS 3.3: + +<descrip> + + <tag>Disk File I/O</tag> + There's no disk file I/O support. Any attempt to use it yields an error with + <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers + are in general not functional as they depend on disk file I/O. However they + may be converted to statically linked drivers using the co65 object-file + converter. + + <tag/Interrupts/ + There's no <tt/interruptor/ support. Any attempt to use it yields the message + 'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that + <tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on + interrupts. + +</descrip><p> + + +<sect1>Direct console I/O<p> + +<descrip> + + <tag/Color/ + The Apple ][ has no color text mode. Therefore the functions + <htmlurl url="funcref-205.html" name="textcolor()">, + <htmlurl url="funcref-68.html" name="bgcolor()"> and + <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + + <tag/Cursor/ + The Apple ][ has no hardware cursor. Therefore the function + <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + +</descrip><p> + + + +<sect>Other hints<p> + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> +]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Apple ][ uses routines marked as +<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be +written as simple machine language subroutines and will be called +automatically by the interrupt handler code when they are linked into a +program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl +url="ca65.html" name="assembler manual">. + + +<sect1>DIO<p> + +<descrip> + + <tag/Drive ID/ + The function <htmlurl url="dio-1.html" name="dio_open()"> has the single + parameter <tt/device/ to identify the device to be opened. Therefore an + Apple II slot and drive pair is mapped to that <tt/device/ according + to the formula + + <tscreen> + device = slot + (drive - 1) * 8 + </tscreen> + + so that for example slot 6 drive 2 is mapped to <tt/device/ 14. + + <tag/Sector count/ + The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns + the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 + disk it simply always returns 280 (which is only correct for a 140 KB disk). + This condition is indicated by the <tt/_oserror/ value 82. + +</descrip><p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml new file mode 100644 index 000000000..667ae9ec7 --- /dev/null +++ b/doc/apple2enh.sgml @@ -0,0 +1,550 @@ +<!doctype linuxdoc system> + +<article> + +<title>Enhanced Apple //e specific information for cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-10-07 + +<abstract> +An overview over the enhanced Apple //e runtime system as it is +implemented for the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the enhanced Apple //e runtime system +as it comes with the cc65 C compiler. It describes the memory layout, +enhanced Apple //e specific header files, available drivers, and any +pitfalls specific to that platform. + +Please note that enhanced Apple //e specific functions are just mentioned +here, they are described in detail in the separate <htmlurl url="funcref.html" +name="function reference">. Even functions marked as "platform dependent" may +be available on more than one platform. Please see the function reference for +more information. + + + +<sect>Binary format<p> + +The standard binary file format generated by the linker for the +enhanced Apple //e target is a binary program with a 4 byte DOS 3.3 header +containing the load address and load length. The default load address is +$803. + +<bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ +that allows to put binary files with a DOS 3.3 header onto disk images +containing DOS 3.3 as well as ProDOS 8. + +For ProDOS 8 system programs the load address is fixed to $2000 so there +is no need for a header. Thus the linker configuration +<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> for those programs +omits the DOS 3.3 header. The right AppleCommander option to put system files +without a header on a ProDOS 8 disk image is <tt/-p/. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$803 to $95FF, so 35.5 KB of RAM are available. + +Special locations: + +<descrip> + + <tag/Stack/ + The C runtime stack is located at HIMEM and grows downwards, regardless of + how your linker config file is setup. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + +While running <tt/main()/ the Language Card bank 2 is enabled for read access. +However while running module constructors/destructors the Language Card is disabled. + +Enabling the Language Card allows to use it as additional memory for cc65 +generated code. However code is never automatically placed there. Rather code +needs to be explicitly placed in the Language Card either per file by compiling +with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma +code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the +cc65 runtime system takes care of actually moving the code into the Language +Card. + +The amount of memory available in the Language Card for generated code depends +on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. + + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the enhanced Apple //e, +which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/). +The apple2enh package comes with additional secondary linker config files, which +are used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +Default configuration optimized for a binary program running on ProDOS 8 with +BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card +bank 2 memory from $D400 to $DFFF. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-dos33.cfg/<p> + +Configuration optimized for a binary program running on DOS 3.3. A plain +vanilla DOS 3.3 doesn't make use of the Language Card at all. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $FFFF (12 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-system.cfg/<p> + +Configuration for a system program running on ProDOS 8. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $2000 to $BEFF (39.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Fixed ($2000) + + <tag><tt/HEADER:/ Binary file header</tag> + None + +</descrip><p> + + +<sect1><tt/apple2enh-loader.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/, which is available +in the cc65 User Contributions section. + +A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but +isn't tied to the start address $2000. Thus with the default start +address $800 the main memory area is increased by 6 KB. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-reboot.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together +with the function <tt/rebootafterexit()/. + +If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather +reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of +the Language Card bank 2 at all. + +This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $DFFF (4 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + + +<sect>ProDOS 8 system programs<p> + +ProDOS 8 system programs are always loaded to the start address $2000. +For cc65 programs this means that the 6 KB from $800 to $2000 are +by default unused. There are however several options to make use of that memory +range. + + +<sect1>LOADER.SYSTEM<p> + +The easiest (and for really large programs in fact the only) way to have a cc65 +program use the memory from $800 to $2000 is to link it as binary +(as opposed to system) program using the linker configuration +<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address +$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ +ProDOS 8 loader for cc65 programs/. The program then works like a system program +(i.e. quits to the ProDOS dispatcher). + +Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the +program to load under name <program>.SYSTEM as a system program. For +example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. + + +<sect1>Heap<p> + +If the cc65 program can be successfully linked as system program using the linker +configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but +uses the heap either explicitly or implicitly (i.e. by loading a driver) then +the memory from $800 to $2000 can be added to the heap by calling +<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. + + +<sect1>ProDOS 8 I/O buffers<p> + +ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default +these buffers are allocated by the cc65 runtime system on the heap using +<tt/posix_memalign()/. While this is generally the best solution it means quite +some overhead for (especially rather small) cc65 programs which do open files +but don't make use of the heap otherwise. + +The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation +module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and +the program start address for the 1 KB I/O buffers. For system programs (with +start address $2000) this results in up to 6 I/O buffers and thus up to 6 +concurrently open files. + +While using <tt/_heapadd()/ as described in the section above together with the +default I/O buffer allocation basically yields the same placement of I/O buffers +in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code +size - and thus program file size - of more than 1400 bytes. + +Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o +</verb></tscreen> + + + +<sect>Platform specific header files<p> + +Programs containing enhanced Apple //e specific code may use the +<tt/apple2enh.h/ header file. + + +<sect1>Enhanced Apple //e specific functions<p> + +The functions listed below are special for the enhanced Apple //e. See +the <htmlurl url="funcref.html" name="function reference"> for declaration and +usage. + +<itemize> +<item>_auxtype +<item>_dos_type +<item>_filetype +<item>get_ostype +<item>rebootafterexit +<item>ser_apple2_slot +<item>textframe +<item>textframexy +<item>tgi_apple2_mix +<item>videomode +</itemize> + + +<sect1>Hardware access<p> + +There's currently no support for direct hardware access. This does not mean +you cannot do it, it just means that there's no help. + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/a2e.lo.tgi (apple2_40_48_16)/</tag> + This driver features a resolution of 40×48 with 16 colors. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function clears the corresponding area at the bottom of the screen. + + <tag><tt/a2e.hi.tgi (apple2_280_192_8)/</tag> + This driver features a resolution of 280×192 with 8 colors and two + hires pages. Note that programs using this driver will have to be linked + with <tt/--start-addr $4000/ to reserve the first hires page or with + <tt/--start-addr $6000/ to reserve both hires pages. + + Note that the second hires page is only available if the text display is not in + 80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/ + before installing the driver. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function doesn't clear the corresponding area at the bottom of the screen. + + In memory constrained situations the memory from $803 to $1FFF + can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ + at the beginning of <tt/main()/. Doing so is beneficial even if the program + doesn't use the the heap explicitly because loading the driver (and in fact + already opening the driver file) uses the heap implicitly. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/a2e.auxmem.emd (apple2_auxmem)/</tag> + Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended + 80-Column Text Card. + + Note that this driver doesn't check for the actual existence of the memory + and that it doesn't check for ProDOS 8 RAM disk content! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/a2e.stdjoy.joy (apple2_stdjoy)/</tag> + Supports up to two standard analog joysticks connected to the game port of + the enhanced Apple //e. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag> + Driver for the AppleMouse II Card. Searches all Apple II slots + for an AppleMouse II Card compatible firmware. The default bounding + box is [0..279,0..191]. + + Note that the enhanced Apple //e default mouse callbacks support + text mode only. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/a2e.ssc.ser (apple2_ssc)/</tag> + Driver for the Apple II Super Serial Card. Supports up to 19200 baud, + hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to + <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ + succeeds for all Apple II slots, but <tt/ser_open()/ fails with + <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. + +</descrip><p> + + + +<sect>Limitations<p> + + +<sect1>DOS 3.3<p> + +Although the standard binaries generated by the linker for the enhanced Apple //e +generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with +BASIC.SYSTEM) there are some limitations for DOS 3.3: + +<descrip> + + <tag>Disk File I/O</tag> + There's no disk file I/O support. Any attempt to use it yields an error with + <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers + are in general not functional as they depend on disk file I/O. However they + may be converted to statically linked drivers using the co65 object-file + converter. + + <tag/Interrupts/ + There's no <tt/interruptor/ support. Any attempt to use it yields the message + 'Failed to alloc interrupt' on program startup. This implicitly means that + <tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on + interrupts. + +</descrip><p> + + +<sect1>Direct console I/O<p> + +<descrip> + + <tag/Color/ + The enhanced Apple //e has no color text mode. Therefore the functions + <htmlurl url="funcref-205.html" name="textcolor()">, + <htmlurl url="funcref-68.html" name="bgcolor()"> and + <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + + <tag/Cursor/ + The enhanced Apple //e has no hardware cursor. Therefore the function + <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + +</descrip><p> + + + +<sect>Other hints<p> + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> +]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Function keys<p> + +These are defined to be OpenApple + number key. + + +<sect1>Interrupts<p> + +The runtime for the enhanced Apple //e uses routines marked as +<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be +written as simple machine language subroutines and will be called +automatically by the interrupt handler code when they are linked into a +program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl +url="ca65.html" name="assembler manual">. + + +<sect1>DIO<p> + +<descrip> + + <tag/Drive ID/ + The function <htmlurl url="dio-1.html" name="dio_open()"> has the single + parameter <tt/device/ to identify the device to be opened. Therefore an + Apple II slot and drive pair is mapped to that <tt/drive_id/ according + to the formula + + <tscreen> + device = slot + (drive - 1) * 8 + </tscreen> + + so that for example slot 6 drive 2 is mapped to <tt/device/ 14. + + <tag/Sector count/ + The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns + the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 + disk it simply always returns 280 (which is only correct for a 140 KB disk). + This condition is indicated by the <tt/_oserror/ value 82. + +</descrip><p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/ar65.sgml b/doc/ar65.sgml new file mode 100644 index 000000000..d4e19a5c5 --- /dev/null +++ b/doc/ar65.sgml @@ -0,0 +1,156 @@ +<!doctype linuxdoc system> + +<article> + +<title>ar65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>19.07.2000 + +<abstract> +ar65 is an archiver for object files generated by ca65. It allows to create +archives, add or remove modules from archives, and to extract modules from +existing archives. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + + +ar65 is a replacement for the libr65 archiver that was part of the cc65 C +compiler suite developed by John R. Dunning. libr65 had some problems and +the copyright does not permit some things which I wanted to be possible, +so I decided to write a completely new assembler/linker/archiver suite +for the cc65 compiler. ar65 is part of this suite. + +<sect>Usage<p> + + +The archiver is called as follows: + +<tscreen><verb> + Usage: ar65 <operation> lib file|module ... + Operation is one of: + a Add modules + d Delete modules + l List library contents + x Extract modules + V Print the archiver version +</verb></tscreen> + +You may add modules to a library using the `a' command. If the library +does not exist, it is created (and a warning message is printed which you +may ignore if creation of the library was your intention). You may +specify any number of modules on the command line following the library. + +If a module with the same name exists in the library, it is replaced by +the new one. The archiver prints a warning, if the module in the library +has a newer timestamp than the one to add. + +Here's an example: + +<tscreen><verb> + ar65 a mysubs.lib sub1.o sub2.o +</verb></tscreen> + +This will add two modules to the library `mysubs.lib' creating the +library if necessary. If the library contains modules named sub1.o or +sub2.o, they are replaced by the new ones. + +Modules names in the library are stored without the path, so, using + +<tscreen><verb> + ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o +</verb></tscreen> + +will add two modules named `sub1.o' and `sub2.o' to the library. + +Deleting modules from a library is done with the `d' command. You may not +give a path when naming the modules. + +Example: + +<tscreen><verb> + ar65 d mysubs.lib sub1.o +</verb></tscreen> + +This will delete the module named `sub1.o' from the library, printing an +error if the library does not contain that module. + + +The `l' command prints a list of all modules in the library. Any module +names on the command line are ignored. + +Example: + +<tscreen><verb> + ar65 l mysubs.lib +</verb></tscreen> + + +Using the `x' command, you may extract modules from the library. The +modules named on the command line are extracted from the library and put +into the current directory. + +Note: Because of the indexing done by the archiver, the modules may have +a changed binary layout, that is, a binary compare with the old module +(before importing it into the library) may yield differences. The +extracted modules are accepted by the linker and archiver, however, so +this is not a problem. + +Example for extracting a module from the library: + +<tscreen><verb> + ar65 x mysubs.lib sub1.o +</verb></tscreen> + + +The `V' command prints the version number of the assembler. If you send +any suggestions or bugfixes, please include your version number. + +In addition to these operations, the archiver will check for, and warn +about duplicate external symbols in the library, every time when an +operation does update the library. This is only a warning, the linker +will ignore one of the duplicate symbols (which one is unspecified). + + +<sect>Bugs/Feedback<p> + +If you have problems using the archiver, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following conditions +do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/atari.sgml b/doc/atari.sgml new file mode 100644 index 000000000..9fe75ec2a --- /dev/null +++ b/doc/atari.sgml @@ -0,0 +1,590 @@ +<!doctype linuxdoc system> + +<article> + +<title>Atari specific information for cc65 +<author>Shawn Jefferson, <htmlurl +url="mailto:shawnjefferson@24fightingchickens.com" +name="shawnjefferson@24fightingchickens.com"> and +Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> +<date>03-Jan-2006 + +<abstract> +An overview over the Atari runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atari runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Atari specific +header files, available drivers, and any pitfalls specific to that +platform. + +Please note that Atari specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the +Atari target is a machine language program with a standard executable +header (FF FF <2 byte start address> <2 bytes end address> +[program bytes]). These values are calculated in the crt0.s +file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep +this in mind if you create a custom linker config file and start +moving segments around (see section +<ref name="Reserving a memory area inside the program" id="memhole">). +You can override this behaviour by creating your own crt0.s file and +linking it into your program. A run vector is added to the end of the +file ($02E0 <run vector>) and is calculated using +__STARTUP_LOAD__ in crt0.s. + + +<sect>Memory layout<p> + +The default linker script assumes that the BASIC ROM is disabled (or +the BASIC cartridge unplugged). This gives a usable memory range from +$2E00 - $BC1F. The library startup code examines the +current memory configuration, which depends on the size of the +installed memory and cartridges present, by inspecting the value in +the MEMTOP ($2E5) variable. Then the initial stack pointer, +which indicates the upper bound of memory used, is adjusted. The +default load address of $2E00 was chosen to accommodate having +a DOS loaded and a driver that resides in low memory such as the 850 +R: handler. You can override this behaviour by creating a custom +linker config file or by using the "--start-addr" cl65 command line +argument or the "--start-addr" or "-S" ld65 command line arguments. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen depends on the installed memory size and cartridges + and can be obtained from the SAVMSC variable ($58). + + <tag/Stack/ + The C runtime stack is located at MEMTOP and grows downwards, + regardless of how your linker config file is setup. This + accommodates the different memory configurations of the Atari + machines, as well as having a cartridge installed. You can override + this behaviour by writing your own crt0.s file and linking it to + your program (see also <ref name="Final note" + id="memhole_final_note">). + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Atari specific code may use the <tt/atari.h/ +header file. + + +<sect1>Atari specific functions<p> + +The functions and global variable listed below are special for the Atari. +See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +<item>get_tv +<item>_dos_type +<item>_gtia_mkcolor +<item>_getcolor +<item>_getdefdev +<item>_graphics +<item>_rest_vecs +<item>_save_vecs +<item>_scroll +<item>_setcolor +<item>_setcolor_low +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/atari.h/ header +file do allow access to hardware located in the address space. Some +variables are structures, accessing the struct fields will access the +chip registers. + +<descrip> + + <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag> + The <tt/GTIA_READ/ structure allows read access to the GTIA. The + <tt/GTIA_WRITE/ structure allows write access to the GTIA. + See the <tt/_gtia.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag> + The <tt/POKEY_READ/ structure allows read access to the POKEY. The + <tt/POKEY_WRITE/ structure allows write access to the POKEY. + See the <tt/_pokey.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/ANTIC/</tag> + The <tt/ANTIC/ structure allows read access to the ANTIC. + See the <tt/_antic.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/PIA/</tag> + The <tt/PIA/ structure allows read access to the PIA 6520. + See the <tt/_pia.h/ header file located in the include directory + for the declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/atari10.tgi (atari_10)/</tag> + + <tag><tt/atr10p2.tgi (atari_10p2)/</tag> + + <tag><tt/atari11.tgi (atari_11)/</tag> + + <tag><tt/atari14.tgi (atari_14)/</tag> + + <tag><tt/atari15.tgi (atari_15)/</tag> + + <tag><tt/atr15p2.tgi (atari_15p2)/</tag> + + <tag><tt/atari3.tgi (atari_3)/</tag> + + <tag><tt/atari4.tgi (atari_4)/</tag> + + <tag><tt/atari5.tgi (atari_5)/</tag> + + <tag><tt/atari6.tgi (atari_6)/</tag> + + <tag><tt/atari7.tgi (atari_7)/</tag> + + <tag><tt/atari8.tgi (atari_8)/</tag> + + <tag><tt/atr8p2.tgi (atari_8p2)/</tag> + + <tag><tt/atari9.tgi (atari_9)/</tag> + + <tag><tt/atr9p2.tgi (atari_9p2)/</tag> + +</descrip><p> + +Many graphics modes require more memory than the text screen which is +in effect when the program starts up. Therefore the programmer has to +tell the program beforehand the memory requirements of the graphics +modes the program intends to use. +This can be done by using the __RESERVED_MEMORY__ linker config +variable. The number specified there describes the number of bytes to +subtract from the top of available memory as seen from the runtime +library. This memory is then used by the screen buffer. + +The numbers for the different graphics modes presented below should +only be seen as a rule of thumb. Since the screen buffer memory needs +to start at specific boundaries, the numbers depend on the current top +of available memory. +The following numbers were determined by a BASIC program. + +<table> +<tabular ca="rr"> +graphics mode|reserved memory@<hline> +0|1@ +1|1@ +2|1@ +3|1@ +4|1@ +5|182@ +6|1182@ +7|3198@ +8|7120@ +9|7146@ +10|7146@ +11|7146@ +12|162@ +13|1@ +14|3278@ +15|7120@ +16|1@ +17|1@ +18|1@ +19|1@ +20|1@ +21|184@ +22|1192@ +23|3208@ +24|7146@ +25|7146@ +26|7146@ +27|7146@ +28|162@ +29|1@ +30|3304@ +31|7146 +</tabular> +<caption>reserved memory required for different graphics modes +</table> + +The values of "1" are needed because the graphics command crashes if +it doesn't have at least one byte available. This seems to be a bug of +the Atari ROM code. + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/atr130xe.emd (atari_130xe)/</tag> + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/ataristd.joy (atari_stdjoy)/</tag> + Supports up to four standard joysticks connected to the joystick ports of + the Atari. + + <tag><tt/atarim8.joy (atari_multijoy)/</tag> + Supports up to eight standard joysticks connected to a MultiJoy adapter. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). There is a static driver you can use. + + +<sect1>RS232 device drivers<p> + +Currently there are no RS232 loadable drivers available for the Atari +platform. There is a static driver you can use. + + +<sect>Limitations<p> + + +<sect>DIO implementation<label id="dio"><p> + +The Atari supports disk drives with either 128 or 256 byte sectors. +The first three sectors of any disk are always 128 bytes long though. This is +because the system can only boot from 128 bytes sectors. + +Therefore the DIO read and write functions transfer only 128 bytes +for sectors 1 to 3, regardless of the type of diskette. + + +<sect>CONIO implementation<label id="conio"><p> + +The console I/O is speed optimized therefore support for XEP80 hardware +or f80.com software is missing. Of course you may use stdio.h functions. + + +<sect>Other hints<p> + + +<sect1>Function keys<p> + +Function keys are mapped to Atari + number key. + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ when DOS supports it. + +<enum> +<item>Arguments are separated by spaces. +<item>Leading and trailing spaces around an argument are ignored. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 16 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the VBI handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + +<sect1>Reserving a memory area inside a program<label id="memhole"><p> + +The Atari 130XE maps its additional memory into CPU memory in 16K +chunks at address $4000 to $7FFF. One might want to +prevent this memory area from being used by cc65. Other reasons to +prevent the use of some memory area could be to reserve space for the +buffers for display lists and screen memory. +<p> +The Atari executable format allows holes inside a program, e.g. one +part loads into $2E00 to $3FFF, going below the reserved +memory area (assuming a reserved area from $4000 to +$7FFF), and another part loads into $8000 to +$BC1F. +<p> +Each load chunk of the executable starts with a 4 byte header which +defines its load address and size. In the following linker scripts +these headers are named HEADER and SECHDR (for the MEMORY layout), and +accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout). +<p> +<sect2>Low code and high data example<p> +Goal: Create an executable with 2 load chunks which doesn't use the +memory area from $4000 to $7FFF. The CODE segment of +the program should go below $4000 and the DATA and RODATA +segments should go above $7FFF. +<p> +The main problem is that the EXE header generated by the cc65 runtime +lib is wrong. It defines a single load chunk with the sizes/addresses +of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user +program). +<p> +The contents of the EXE header come from the EXEHDR segment, which is +defined in crt0.s. This cannot be changed without modifying and +recompiling the cc65 atari runtime lib. Therefore the original EXE +header must be discarded. It will be replaced by a user created +one. The discarding is done by assigning the EXEHDR segment to the +BANK memory area. The BANK memory area is discarded in the new linker +script (written to file ""). +<p> +The user needs to create a customized linker config file which adds +new memory areas and segments to hold the new EXE header and the +header data for the second load chunk. Also an assembly source file +needs to be created which defines the contents of the new EXE header +and the second load chunk header. +<p> +<p> +This is an example of a modified cc65 Atari linker configuration file +(split.cfg): +<tscreen><verb> +SYMBOLS { + __STACKSIZE__ = $800; # 2K stack + __RESERVED_MEMORY__: value = $0000, weak = yes; +} +FEATURES { + STARTADDRESS: default = $2E00; +} +MEMORY { + ZP: start = $82, size = $7E, type = rw, define = yes; + + HEADER: start = $0000, size = $6, file = %O; # first load chunk + RAMLO: start = %S, size = $4000 - %S, file = %O; + + BANK: start = $4000, size = $4000, file = ""; + + SECHDR: start = $0000, size = $4, file = %O; # second load chunk + RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F +} +SEGMENTS { + EXEHDR: load = BANK, type = ro; + + NEXEHDR: load = HEADER, type = ro; # first load chunk + STARTUP: load = RAMLO, type = ro, define = yes; + LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes; + INIT: load = RAMLO, type = ro, optional = yes; + CODE: load = RAMLO, type = ro, define = yes; + + CHKHDR: load = SECHDR, type = ro; # second load chunk + RODATA: load = RAM, type = ro, define = yes; + DATA: load = RAM, type = rw, define = yes; + BSS: load = RAM, type = bss, define = yes; + ZPSAVE: load = RAM, type = bss, define = yes; + + ZEROPAGE: load = ZP, type = zp; + AUTOSTRT: load = RAM, type = ro; # defines program entry point +} +FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = RODATA, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} +</verb></tscreen> +<p> + +A new memory area BANK was added which describes the reserved area. +It gets loaded with the contents of the old EXEHDR segment. But the +memory area isn't written to the output file. This way the contents of +the EXEHDR segment get discarded. +<p> +The newly added NEXEHDR segment defines the correct EXE header. It +puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the +segments containing only code, into load chunk #1 (RAMLO memory area). +<p> +The header for the second load chunk comes from the new CHKHDR +segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load +chunk #2 (RAM memory area). +<p> +<p> +The contents of the new NEXEHDR and CHKHDR segments come from this +file (split.s): +<tscreen><verb> + .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__ + .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__ + + .segment "NEXEHDR" + .word $FFFF + .word __STARTUP_LOAD__ + .word __CODE_LOAD__ + __CODE_SIZE__ - 1 + + .segment "CHKHDR" + .word __RODATA_LOAD__ + .word __BSS_LOAD__ - 1 +</verb></tscreen> +<p> +Compile with +<tscreen><verb> +cl65 -t atari -C split.cfg -o prog.com prog.c split.s +</verb></tscreen> + +<sect2>Low data and high code example<p> + + +Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT, +CODE, BSS, ZPSAVE into high memory (split2.cfg): + +<tscreen><verb> +SYMBOLS { + __STACKSIZE__ = $800; # 2K stack + __RESERVED_MEMORY__: value = $0000, weak = yes; +} +FEATURES { + STARTADDRESS: default = $2E00; +} +MEMORY { + ZP: start = $82, size = $7E, type = rw, define = yes; + + HEADER: start = $0000, size = $6, file = %O; # first load chunk + RAMLO: start = %S, size = $4000 - %S, file = %O; + + BANK: start = $4000, size = $4000, file = ""; + + SECHDR: start = $0000, size = $4, file = %O; # second load chunk + RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F +} +SEGMENTS { + EXEHDR: load = BANK, type = ro; # discarded old EXE header + + NEXEHDR: load = HEADER, type = ro; # first load chunk + RODATA: load = RAMLO, type = ro, define = yes; + DATA: load = RAMLO, type = rw, define = yes; + + CHKHDR: load = SECHDR, type = ro; # second load chunk + STARTUP: load = RAM, type = ro, define = yes; + INIT: load = RAM, type = ro, optional = yes; + CODE: load = RAM, type = ro, define = yes; + ZPSAVE: load = RAM, type = bss, define = yes; + BSS: load = RAM, type = bss, define = yes; + + ZEROPAGE: load = ZP, type = zp; + AUTOSTRT: load = RAM, type = ro; # defines program entry point +} +FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = RODATA, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} +</verb></tscreen> + +New contents for NEXEHDR and CHKHDR are needed (split2.s): +<tscreen><verb> + .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__ + .import __DATA_LOAD__, __RODATA_LOAD__ + + .segment "NEXEHDR" + .word $FFFF + .word __RODATA_LOAD__ + .word __DATA_LOAD__ + __DATA_SIZE__ - 1 + + .segment "CHKHDR" + .word __STARTUP_LOAD__ + .word __ZPSAVE_LOAD__ - 1 +</verb></tscreen> + +Compile with +<tscreen><verb> +cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s +</verb></tscreen> + +<sect2>Final note<label id="memhole_final_note"><p> + +There are two other memory areas which don't appear directly in the +linker script. They are the stack and the heap. + +The cc65 runtime lib places the stack location at the end of available +memory. This is dynamically set from the MEMTOP system variable at +startup. The heap is located in the area between the end of the BSS +segment and the top of the stack as defined by __STACKSIZE__. + +If BSS and/or the stack shouldn't stay at the end of the program, +some parts of the cc65 runtime lib need to be replaced/modified. + +common/_heap.s defines the location of the heap and atari/crt0.s +defines the location of the stack by initializing sp. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org"> or <htmlurl url="mailto:chris@groessler.org" +name="chris@groessler.org"> ). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/atmos.sgml b/doc/atmos.sgml new file mode 100644 index 000000000..8e24c92a1 --- /dev/null +++ b/doc/atmos.sgml @@ -0,0 +1,260 @@ +<!doctype linuxdoc system> + +<article> + +<title>Oric Atmos specific information for cc65 +<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline> +Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> +<date>2013-01-08 + +<abstract> +An overview over the Atmos runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atmos runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Atmos specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that Atmos specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Atmos target +is a machine language program with a 17 byte tape header including a cc65 tag. +The standard load and autostart address is $500. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$500 to $9800, so nearly 37K of memory (including the stack) is +available. ROM calls are possible without further precautions. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $97FF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Atmos specific code may use the <tt/atmos.h/ header file. + + +<sect1>Atmos specific functions<p> + +The functions listed below are special for the Atmos. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>atmos_load +<item>atmos_save +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/atmos.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIA/</tag> + Access to the VIA (versatile interface adapter) chip is available via the + <tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<em>Note:</em> Since the Atmos doesn't have working disk I/O +(see <ref id="limitations" name="section "Limitations"">), the +available drivers cannot be loaded at runtime (so the term "loadable drivers" +is somewhat misleading). Instead, the drivers have to be statically linked. While +this may seem overhead, it has two advantages: + +<enum> +<item>The interface is identical to the one used for other platforms + and to the one for the Atmos once it has disk I/O. +<item>Once disk I/O is available, existing code can be changed to load drivers + at runtime with almost no effort. +</enum> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3)/</tag> + This driver was written by Greg King and Stefan Haubenthal. + It features a resolution of 228×200 with a palette of two colors that + can be chosen from the Atmos's eight colors. The driver supports a third + palette-"color" that actually "flips" the pixel (it becomes the other color) + that is on the screen under the graphics cursor. + + <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag> + This driver was written by Stefan Haubenthal and Greg King. + It features a resolution of 240×200 with black and white colors. + It is the default graphics driver for the Atmos. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Atmos. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/atmos-pase.joy (atmos_pase)/</tag> + Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Atmos. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/atmos-acia.ser (atmos_acia)/</tag> + Driver for the Telestrat integrated serial controller and the Atmos with a + serial add-on. + Note that because of the peculiarities of the 6551 chip together with the + use of the NMI, transmits are not interrupt driven, and the transceiver + blocks if the receiver asserts flow control because of a full buffer. + +</descrip><p> + + + +<sect>Limitations<label id="limitations"><p> + +<sect1>Disk I/O<p> + +The existing library for the Atmos doesn't implement C file +I/O. There is one hack for the <tt/write()/ routine in +place, which will make functions work that write to <tt/stdout/ +(like <tt/printf()/). However, this function has some shortcomings which +won't be fixed, because it's going to be replaced anyway. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + +<sect1>Function keys<p> + +These are defined to be FUNCT + number key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + CALL#500:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/c128.sgml b/doc/c128.sgml new file mode 100644 index 000000000..37cdd25f8 --- /dev/null +++ b/doc/c128.sgml @@ -0,0 +1,356 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 128 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-14 + +<abstract> +An overview over the C128 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C128 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C128 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C128 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C128 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal ROM enabled. Note that this is a non standard memory layout, and that +there is no "memory configuration index" for this layout. This means that +special care has to be taken when changing the configuration, or calling any +code that does this. The memory configuration register at $FF00 should +be saved and restored instead of relying on the memory configuration index +stored in the zero page. + +The setup gives a usable memory range of $1C00 - $BFFF. Having +just the kernal ROM mapped in means, that kernal entry points may be called +directly, but using the BASIC ROM is not possible without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $400 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $BFFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c128.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C128 specific functions<p> + +The functions listed below are special for the C128. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>videomode +<item>c64mode +<item>fast +<item>slow +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c128.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/VDC/</tag> + The <tt/VDC/ structure allows access to the VDC (the video display + controller). See the <tt/_vdc.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/CIA1, CIA2/</tag> + Access to the two CIA (complex interface adapter) chips is available via + the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables + is explained in <tt/_6526.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C128 at $D800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +Note: The graphics drivers for the VDC are incompatible with the extended +memory drivers using the VDC memory! + +<descrip> + <tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag> + This driver was written by Maciej Witkowiak. It uses the 80 column display + and features a resolution of 640*200 with two colors and an adjustable + palette (that means that the two colors can be chosen out of the 16 VDC + colors). + + <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag> + This driver was written by Maciej Witkowiak. This driver uses the 80 column + display and features a resolution of 640*480 with two colors and an + adjustable palette (that means that the two colors can be chosen out of the + 16 VDC colors). The driver requires 64KB VDC RAM. +</descrip><p> + +Note: The colors are translated from definitions in headers to correct VDC values +so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are +missing on VDC and are translated to the two colors missing from VIC palette. + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c128-georam.emd (c128_georam)/</tag> + A driver for the GeoRam cartridge. The driver will always assume 2048 pages + of 256 bytes each. There are no checks, so if your program knows better, + just go ahead. + + <tag><tt/c128-ram.emd (c128_ram)/</tag> + An extended memory driver for the RAM in page 1. The common memory area is + excluded, so this driver supports 251 pages of 256 bytes each. + + <tag><tt/c128-ram2.emd (c128_ram2)/</tag> + + An extended memory driver for the RAM in pages 1-3. The common memory area + is excluded, so this driver supports up to 731 pages of 256 bytes each. The + driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM + in pages 2+3 is autodetected, but it's larger and there are not many + machines with RAM in banks 2+3, so it has been made a separate driver. The + additional code was contributed by Marco van den Heuvel. + + <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag> + A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. + Will test the hardware for the available RAM. + + <tag><tt/c128-reu.emd (c128_reu)/</tag> + A driver for the CBM REUs. The driver will determine from the connected REU + if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, + but since there are no range checks, the application can use more memory if + it has better knowledge about the hardware than the driver. + + <tag><tt/c128-vdc.emd (c128_vdc)/</tag> + A driver for the VDC memory of the C128 written and contributed by Maciej + Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers + 64 or 256 pages of 256 bytes each. Note: This driver is incompatible with + any of the graphics drivers using the VDC! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter originally written by Groepaz + for the C64 and converted for the C128 by me. See <htmlurl + url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to four joysticks are supported. + + <tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the C128. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/c128-1351.mou (c128_1351)/</tag> + Supports a standard mouse connected to port #0 of the C128. + + <tag><tt/c128-joy.mou (c128_joymouse)/</tag> + Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port + #1 of the C128. + + <tag><tt/c128-pot.mou (c128_potmouse)/</tag> + Supports a potentiometer device e.g. Koala Pad connected to port #1 of + the C128. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/c128-swlink.ser (c128_swlink)/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver uses the RS232 variables and buffers of the kernal (buffers at + $C00 and $D00). + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C128 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/c16.sgml b/doc/c16.sgml new file mode 100644 index 000000000..110082a19 --- /dev/null +++ b/doc/c16.sgml @@ -0,0 +1,274 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 16/116 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-15 + +<abstract> +An overview over the C16 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C16 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C16/116 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that C16 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +Since the C16/C116 and the Commodore Plus/4 are almost identical (the former +don't have the 6551 ACIA and only 16KB of memory), the <htmlurl +url="plus4.html" name="Plus/4 documentation"> is also worth a look. The +difference between both cc65 targets is that the Plus/4 runtime uses banking +to support full 64K RAM, while the C16 does not use banking and supports up to +32K RAM. Because banking is not needed, most C16 programs will be somewhat +smaller than the same program compiled for the Plus/4. However, programs C16 +will always run on the Plus/4, while the reverse is not necessarily true. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C16/116 +target is a machine language program with a one line BASIC stub which, calls +the machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the kernal and basic +banked in. This gives a usable memory range of $1000 - $4000 +(or $8000 if the machine is equipped with 32K RAM or more). Having the +kernal and basic ROMs banked in means, that ROM entry points may be called +directly from user code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $C00 (as in the standard setup). + + <tag/Color RAM/ + The color RAM is located at $800 (standard location). + + <tag/Stack/ + The C runtime stack is located at $3FFF ($7FFF in case of a + machine with 32K of memory or more) and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing C16 specific code may use the <tt/c16.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c16.h/ and declares several functions +common to all CBM platforms. + +Please note that most of the header file declarations from the <tt/c16.h/ +header file are shared between the C16 and Plus/4 configurations. For this +reason, most of it is located in a common header file named <tt/cbm264.h/. + + + +<sect1>C16/C116 specific functions<p> + +There are currently no special C16/C116 functions. + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c16.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/TED/</tag> + The <tt/TED/ structure allows access to the TED chip. See the + <tt/_ted.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C16 at $0800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the C16/C116. + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c16-ram.emd (c16_ram)/</tag> + A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125 + pages with 256 bytes each if the machine is equipped with 64K of memory + (a Plus/4 or a memory extended C16/116). + +</descrip><p> + + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the Commodore 16/116. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +The Commodore 16 does not have a builtin ACIA and no RS232 extensions are +known. For this reason, there are no RS232 drivers available. Please note that +the standard Plus/4 driver will <em>not</em> run together with the C16 +library, because the latter does not support interrupts needed by the driver. + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C16 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + + diff --git a/doc/c64.sgml b/doc/c64.sgml new file mode 100644 index 000000000..2e6a37e77 --- /dev/null +++ b/doc/c64.sgml @@ -0,0 +1,405 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 64 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-09-23 + +<abstract> +An overview over the C64 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C64 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C64 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C64 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C64 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal ROM enabled (memory under the kernal may be used for graphics or as +extended memory - see the sections about graphics and extended memory +drivers). The BASIC ROM is disabled, which gives a usable memory range of +$0800 - $CFFF. This means that kernal entry points may be called +directly, but using the BASIC ROM is not possible without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $400 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $CFFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the Commodore 64, +which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The +c64 package comes with additional secondary linker config files, which are +used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +The builtin configuration is tailored to C programs. It supplies the load +address and a small BASIC stub that starts the compiled program using a SYS +command. + + +<sect1><tt/c64-asm.cfg/<p> + +This configuration is made for assembler programmers who don't need a special +setup. The default start address is $801. It can be changed with the +linker command line option <tt/--start-addr/. All standard segments with the +exception of <tt/zeropage/ are written to the output file and a two byte load +address is prepended. + +To use this config file, assemble with <tt/-t c64/ and link with <tt/-C +c64-asm.cfg/. The former will make sure that correct character translation is +in effect, while the latter supplies the actual config. When using <tt/cl65/, +use both command line options. + +Sample command line for <tt/cl65/: + +<tscreen><verb> +cl65 -o file.prg -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +To generate code that loads to $C000: + +<tscreen><verb> +cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +It is also possible to add a small BASIC header to the program, that uses SYS +to jump to the program entry point (which is the start of the code segment). +The advantage is that the program can be started using RUN. + +To generate a program with a BASIC SYS header, use + +<tscreen><verb> +cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +Please note that in this case a changed start address doesn't make sense, +since the program must be loaded to the BASIC start address. + + +<sect>Platform specific header files<p> + +Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c64.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C64 specific functions<p> + +The functions listed below are special for the C64. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c64.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/CIA1, CIA2/</tag> + Access to the two CIA (complex interface adapter) chips is available via + the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables + is explained in <tt/_6526.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C64 at $D800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<em>Note:</em> All available graphics drivers for the TGI interface will use +the space below the I/O area and kernal ROM, so you can have hires graphics in +the standard setup without any memory loss or need for a changed +configuration. + +<descrip> + <tag><tt/c64-hi.tgi (c64_320_200_2)/</tag> + This driver features a resolution of 320*200 with two colors and an + adjustable palette (that means that the two colors can be chosen out of a + palette of the 16 C64 colors). +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c64-c256k.emd (c64_c256k)/</tag> + A driver for the C64 256K memory expansion. This driver offers 768 pages of + 256 bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-dqbb.emd (c64_dqbb)/</tag> + A driver for the Double Quick Brown Box cartridge. This driver offers + 64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-georam.emd (c64_georam)/</tag> + A driver for the Berkeley Softworks GeoRam cartridge. The driver will + determine the available RAM from the connected cartridge. It supports 64KB + up to 2048KB of RAM. + + <tag><tt/c64-isepic.emd (c64_isepic)/</tag> + A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256 + bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-ram.emd (c64_ram)/</tag> + A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 + 256 byte pages. Please note that this driver is incompatible with any of the + graphics drivers! + + <tag><tt/c64-ramcart.emd (c64_ramcart)/</tag> + A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. + Will test the hardware for the available RAM. + + <tag><tt/c64-reu.emd (c64_reu)/</tag> + A driver for the CBM REUs. The driver will determine from the connected REU + if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, + but since there are no range checks, the application can use more memory if + it has better knowledge about the hardware than the driver. + + <tag><tt/c64-vdc.emd (c64_vdc)/</tag> + A driver for the VDC memory of the C128. Written and contributed by Maciej + Witkowiak. Can be used if the program is running in C64 mode of the C128. + Autodetects the amount of memory available (16 or 64K) and offers 64 or 256 + pages of 256 bytes each. + + <tag><tt/dtv-himem.emd (dtv_himem)/</tag> + A driver for the C64 D2TV (the second or PAL version). This driver offers + indeed 7680 pages of 256 bytes each. + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag> + Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See + <htmlurl url="http://www.digitalexcess.de/downloads/productions.php" + name="http://www.digitalexcess.de/downloads/productions.php"> on + instructions how to build one. Up to four joysticks are supported. + + <tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to four joysticks are supported. + + <tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag> + Supports up to two standard joysticks connected to the joysticks port of + the C64. + + <tag><tt/c64-numpad.joy (c64_numpad)/</tag> + Supports one joystick emulated by the numberpad of the C128 in C64 mode, + the firebutton is labeled &dquot;5&dquot; and ENTER. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/c64-1351.mou (c64_1351)/</tag> + Supports a standard mouse connected to port #0 of the C64. + + <tag><tt/c64-joy.mou (c64_joymouse)/</tag> + Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port + #1 of the C64. + + <tag><tt/c64-pot.mou (c64_potmouse)/</tag> + Supports a potentiometer device e.g. Koala Pad connected to port #1 of + the C64. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/c64-swlink.ser (c64_swlink)/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Escape code<p> + +For an Esc press CTRL and [ key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/ca65.sgml b/doc/ca65.sgml new file mode 100644 index 000000000..00d72db56 --- /dev/null +++ b/doc/ca65.sgml @@ -0,0 +1,4786 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>ca65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-07-19, 2000-11-29, 2001-10-02, 2005-09-08 + +<abstract> +ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is +used as a companion assembler for the cc65 crosscompiler, but it may also be +used as a standalone product. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +ca65 is a replacement for the ra65 assembler that was part of the cc65 C +compiler, originally developed by John R. Dunning. I had some problems with +ra65 and the copyright does not permit some things which I wanted to be +possible, so I decided to write a completely new assembler/linker/archiver +suite for the cc65 compiler. ca65 is part of this suite. + +Some parts of the assembler (code generation and some routines for symbol +table handling) are taken from an older crossassembler named a816 written +by me a long time ago. + + +<sect1>Design criteria<p> + +Here's a list of the design criteria, that I considered important for the +development: + +<itemize> + +<item> The assembler must support macros. Macros are not essential, but they + make some things easier, especially when you use the assembler in the + backend of a compiler. +<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been + thinking about a 65816 backend for the C compiler, and even my old + a816 assembler had support for these CPUs, so this wasn't really a + problem. +<item> The assembler must produce relocatable code. This is necessary for the + compiler support, and it is more convenient. +<item> Conditional assembly must be supported. This is a must for bigger + projects written in assembler (like Elite128). +<item> The assembler must support segments, and it must support more than + three segments (this is the count, most other assemblers support). + Having more than one code segments helps developing code for systems + with a divided ROM area (like the C64). +<item> The linker must be able to resolve arbitrary expressions. It should + be able to get things like +<tscreen><verb> + .import S1, S2 + .export Special + Special = 2*S1 + S2/7 +</verb></tscreen> + right. +<item> True lexical nesting for symbols. This is very convenient for larger + assembly projects. +<item> "Cheap" local symbols without lexical nesting for those quick, late + night hacks. +<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I + introduced the concept into the object file format use by the new cc65 + binutils. +<item> The assembler will be a one pass assembler. There was no real need for + this decision, but I've written several multipass assemblers, and it + started to get boring. A one pass assembler needs much more elaborated + data structures, and because of that it's much more fun:-) +<item> Non-GPLed code that may be used in any project without restrictions or + fear of "GPL infecting" other code. +</itemize> +<p> + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The assembler accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ca65 [options] file +Short options: + -D name[=value] Define a symbol + -I dir Set an include directory search path + -U Mark unresolved symbols as import + -V Print the assembler version + -W n Set warning level n + -d Debug mode + -g Add debug info to object file + -h Help (this text) + -i Ignore case of symbols + -l name Create a listing file if assembly was ok + -mm model Set the memory model + -o name Name the output file + -s Enable smart mode + -t sys Set the target system + -v Increase verbosity + +Long options: + --auto-import Mark unresolved symbols as import + --bin-include-dir dir Set a search path for binary includes + --cpu type Set cpu type + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --debug Debug mode + --debug-info Add debug info to object file + --feature name Set an emulation feature + --forget-inc-paths Forget include search paths + --help Help (this text) + --ignore-case Ignore case of symbols + --include-dir dir Set an include directory search path + --large-alignment Don't warn about large alignments + --listing name Create a listing file if assembly was ok + --list-bytes n Maximum number of bytes per listing line + --macpack-dir dir Set a macro package directory + --memory-model model Set the memory model + --pagelength n Set the page length for the listing + --relax-checks Relax some checks (see docs) + --smart Enable smart mode + --target sys Set the target system + --verbose Increase verbosity + --version Print the assembler version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--bin-include-dir"> + <tag><tt>--bin-include-dir dir</tt></tag> + + Name a directory which is searched for binary include files. The option + may be used more than once to specify more than one directory to search. The + current directory is always searched first before considering any + additional directories. See also the section about <ref id="search-paths" + name="search paths">. + + + <label id="option--cpu"> + <tag><tt>--cpu type</tt></tag> + + Set the default for the CPU type. The option takes a parameter, which + may be one of + + 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280 + + The sunplus cpu is not available in the freeware version, because the + instruction set is "proprietary and confidential". + + + <label id="option-create-dep"> + <tag><tt>--create-dep name</tt></tag> + + Tells the assembler to generate a file containing the dependency list for + the assembled module in makefile syntax. The output is written to a file + with the given name. The output does not include files passed via debug + information to the assembler. + + + <label id="option-create-full-dep"> + <tag><tt>--create-full-dep name</tt></tag> + + Tells the assembler to generate a file containing the dependency list for + the assembled module in makefile syntax. The output is written to a file + with the given name. The output does include files passed via debug + information to the assembler. + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere + mortals:-) + + + <label id="option--feature"> + <tag><tt>--feature name</tt></tag> + + Enable an emulation feature. This is identical as using <tt/.FEATURE/ + in the source with two exceptions: Feature names must be lower case, and + each feature must be specified by using an extra <tt/--feature/ option, + comma separated lists are not allowed. + + See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt> + command for a list of emulation features. + + + <label id="option--forget-inc-paths"> + <tag><tt>--forget-inc-paths</tt></tag> + + Forget the builtin include paths. This is most useful when building + customized assembler modules, in which case the standard header files should + be ignored. + + + <label id="option-g"> + <tag><tt>-g, --debug-info</tt></tag> + + When this option (or the equivalent control command <tt/.DEBUGINFO/) is + used, the assembler will add a section to the object file that contains + all symbols (including local ones) together with the symbol values and + source file positions. The linker will put these additional symbols into + the VICE label file, so even local symbols can be seen in the VICE + monitor. + + + <label id="option-h"> + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-i"> + <tag><tt>-i, --ignore-case</tt></tag> + + This option makes the assembler case insensitive on identifiers and labels. + This option will override the default, but may itself be overridden by the + <tt><ref id=".CASE" name=".CASE"></tt> control command. + + + <label id="option-l"> + <tag><tt>-l name, --listing name</tt></tag> + + Generate an assembler listing with the given name. A listing file will + never be generated in case of assembly errors. + + + <label id="option--large-alignment"> + <tag><tt>--large-alignment</tt></tag> + + Disable warnings about a large combined alignment. See the discussion of the + <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for futher information. + + + <label id="option--list-bytes"> + <tag><tt>--list-bytes n</tt></tag> + + Set the maximum number of bytes printed in the listing for one line of + input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive + for more information. The value zero can be used to encode an unlimited + number of printed bytes. + + + <label id="option--macpack-dir"> + <tag><tt>--macpack-dir dir</tt></tag> + + This options allows to specify a directory containing macro files that are + used instead of the builtin images when a <tt><ref id=".MACPACK" + name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt> + was specified, a <tt>.mac</tt> extension is added to the package name and + the resulting file is loaded from the given directory. This is most useful + when debugging the builtin macro packages. + + + <label id="option-mm"> + <tag><tt>-mm model, --memory-model model</tt></tag> + + Define the default memory model. Possible model specifiers are near, far and + huge. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + The default output name is the name of the input file with the extension + replaced by ".o". If you don't like that, you may give another name with + the -o option. The output file will be placed in the same directory as + the source file, or, if -o is given, the full path in this name is used. + + + <label id="option--pagelength"> + <tag><tt>--pagelength n</tt></tag> + + sets the length of a listing page in lines. See the <tt><ref + id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information. + + + <label id="option--relax-checks"> + <tag><tt>--relax-checks</tt></tag> + + Relax some checks done by the assembler. This will allow code that is an + error in most cases and flagged as such by the assembler, but can be valid + in special situations. + + Examples are: +<itemize> +<item>Short branches between two different segments. +<item>Byte sized address loads where the address is not a zeropage address. +</itemize> + + + <label id="option-s"> + <tag><tt>-s, --smart-mode</tt></tag> + + In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt> + pseudo instruction) the assembler will track usage of the <tt/REP/ and + <tt/SEP/ instructions in 65816 mode and update the operand sizes + accordingly. If the operand of such an instruction cannot be evaluated by + the assembler (for example, because the operand is an imported symbol), a + warning is issued. + + Beware: Since the assembler cannot trace the execution flow this may + lead to false results in some cases. If in doubt, use the .ixx and .axx + instructions to tell the assembler about the current settings. Smart + mode is off by default. + + + <label id="option-t"> + <tag><tt>-t sys, --target sys</tt></tag> + + Set the target system. This will enable translation of character strings and + character constants into the character set of the target platform. The + default for the target system is "none", which means that no translation + will take place. The assembler supports the same target systems as the + compiler, see there for a list. + + Depending on the target, the default CPU type is also set. This can be + overriden by using the <tt/<ref id="option--cpu" name="--cpu">/ option. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Increase the assembler verbosity. Usually only needed for debugging + purposes. You may use this option more than one time for even more + verbose output. + + + <label id="option-D"> + <tag><tt>-D</tt></tag> + + This option allows you to define symbols on the command line. Without a + value, the symbol is defined with the value zero. When giving a value, + you may use the '$' prefix for hexadecimal symbols. Please note + that for some operating systems, '$' has a special meaning, so + you may have to quote the expression. + + + <label id="option-I"> + <tag><tt>-I dir, --include-dir dir</tt></tag> + + Name a directory which is searched for include files. The option may be + used more than once to specify more than one directory to search. The + current directory is always searched first before considering any + additional directories. See also the section about <ref id="search-paths" + name="search paths">. + + + <label id="option-U"> + <tag><tt>-U, --auto-import</tt></tag> + + Mark symbols that are not defined in the sources as imported symbols. This + should be used with care since it delays error messages about typos and such + until the linker is run. The compiler uses the equivalent of this switch + (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported + symbols for the runtime library. However, the compiler is supposed to + generate code that runs through the assembler without problems, something + which is not always true for assembler programmers. + + + <label id="option-V"> + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions + or bugfixes, please include the version number. + + + <label id="option-W"> + <tag><tt>-Wn</tt></tag> + + Set the warning level for the assembler. Using -W2 the assembler will + even warn about such things like unused imported symbols. The default + warning level is 1, and it would probably be silly to set it to + something lower. + +</descrip> +<p> + + + +<sect>Search paths<label id="search-paths"><p> + +Normal include files are searched in the following places: + +<enum> +<item>The current directory. +<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt> + on Linux systems. +<item>The value of the environment variable <tt/CA65_INC/ if it is defined. +<item>A subdirectory named <tt/asminc/ of the directory defined in the + environment variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option +on the command line. +</enum> + +Binary include files are searched in the following places: + +<enum> +<item>The current directory. +<item>Any directory added with the <tt/<ref id="option--bin-include-dir" +name="--bin-include-dir">/ option on the command line. +</enum> + + + +<sect>Input format<p> + +<sect1>Assembler syntax<p> + +The assembler accepts the standard 6502/65816 assembler syntax. One line may +contain a label (which is identified by a colon), and, in addition to the +label, an assembler mnemonic, a macro, or a control command (see section <ref +id="control-commands" name="Control Commands"> for supported control +commands). Alternatively, the line may contain a symbol definition using +the '=' token. Everything after a semicolon is handled as a comment (that is, +it is ignored). + +Here are some examples for valid input lines: + +<tscreen><verb> + Label: ; A label and a comment + lda #$20 ; A 6502 instruction plus comment + L1: ldx #$20 ; Same with label + L2: .byte "Hello world" ; Label plus control command + mymac $20 ; Macro expansion + MySym = 3*L1 ; Symbol definition + MaSym = Label ; Another symbol +</verb></tscreen> + +The assembler accepts + +<itemize> +<item>all valid 6502 mnemonics when in 6502 mode (the default or after the + <tt><ref id=".P02" name=".P02"></tt> command was given). +<item>all valid 6502 mnemonics plus a set of illegal instructions when in + <ref id="6502X-mode" name="6502X mode">. +<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the + <tt><ref id=".PSC02" name=".PSC02"></tt> command was given). +<item>all valid 65C02 mnemonics when in 65C02 mode (after the + <tt><ref id=".PC02" name=".PC02"></tt> command was given). +<item>all valid 65618 mnemonics when in 65816 mode (after the + <tt><ref id=".P816" name=".P816"></tt> command was given). +<item>all valid SunPlus mnemonics when in SunPlus mode (after the + <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given). +</itemize> + + +<sect1>65816 mode<p> + +In 65816 mode several aliases are accepted in addition to the official +mnemonics: + +<tscreen><verb> + BGE is an alias for BCS + BLT is an alias for BCC + CPA is an alias for CMP + DEA is an alias for DEC A + INA is an alias for INC A + SWA is an alias for XBA + TAD is an alias for TCD + TAS is an alias for TCS + TDA is an alias for TDC + TSA is an alias for TSC +</verb></tscreen> + + + +<sect1>6502X mode<label id="6502X-mode"><p> + +6502X mode is an extension to the normal 6502 mode. In this mode, several +mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since +these instructions are illegal, there are no official mnemonics for them. The +unofficial ones are taken from <htmlurl +url="http://www.oxyron.de/html/opcodes02.html" +name="http://www.oxyron.de/html/opcodes02.html">. Please note that only the +ones marked as "stable" are supported. The following table uses information +from the mentioned web page, for more information, see there. + +<itemize> +<item><tt>ALR: A:=(A and #{imm})/2;</tt> +<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B. +<item><tt>ARR: A:=(A and #{imm})/2;</tt> +<item><tt>AXS: X:=A and X-#{imm};</tt> +<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt> +<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt> +<item><tt>LAS: A,X,S:={adr} and S;</tt> +<item><tt>LAX: A,X:={adr};</tt> +<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt> +<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt> +<item><tt>SAX: {adr}:=A and X;</tt> +<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt> +<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt> +</itemize> + + + +<sect1>sweet16 mode<label id="sweet16-mode"><p> + +SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak +for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can +generate code for this pseudo CPU when switched into sweet16 mode. The +following is special in sweet16 mode: + +<itemize> + +<item>The '@' character denotes indirect addressing and is no longer available +for cheap local labels. If you need cheap local labels, you will have to +switch to another lead character using the <tt/<ref id=".LOCALCHAR" +name=".LOCALCHAR">/ command. + +<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode, +these identifiers are reserved words. + +</itemize> + +Please note that the assembler does neither supply the interpreter needed for +SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers, +nor does it call the interpreter. All this must be done by your program. Apple +][ programmers do probably know how to use sweet16 mode. + +For more information about SWEET 16, see +<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm" +name="http://www.6502.org/source/interpreters/sweet16.htm">. + + +<sect1>Number format<p> + +For literal values, the assembler accepts the widely used number formats: A +preceding '$' or a trailing 'h' denotes a hex value, a preceding '%' +denotes a binary value, and a bare number is interpreted as a decimal. There +are currently no octal values and no floats. + + +<sect1>Conditional assembly<p> + +Please note that when using the conditional directives (<tt/.IF/ and friends), +the input must consist of valid assembler tokens, even in <tt/.IF/ branches +that are not assembled. The reason for this behaviour is that the assembler +must still be able to detect the ending tokens (like <tt/.ENDIF/), so +conversion of the input stream into tokens still takes place. As a consequence +conditional assembly directives may <bf/not/ be used to prevent normal text +(used as a comment or similar) from being assembled. <p> + + +<sect>Expressions<p> + + +<sect1>Expression evaluation<p> + +All expressions are evaluated with (at least) 32 bit precision. An +expression may contain constant values and any combination of internal and +external symbols. Expressions that cannot be evaluated at assembly time +are stored inside the object file for evaluation by the linker. +Expressions referencing imported symbols must always be evaluated by the +linker. + + +<sect1>Size of an expression result<p> + +Sometimes, the assembler must know about the size of the value that is the +result of an expression. This is usually the case, if a decision has to be +made, to generate a zero page or an absolute memory references. In this +case, the assembler has to make some assumptions about the result of an +expression: + +<itemize> +<item> If the result of an expression is constant, the actual value is + checked to see if it's a byte sized expression or not. +<item> If the expression is explicitly casted to a byte sized expression by + one of the '>', '<' or '^' operators, it is a byte expression. +<item> If this is not the case, and the expression contains a symbol, + explicitly declared as zero page symbol (by one of the .importzp or + .exportzp instructions), then the whole expression is assumed to be + byte sized. +<item> If the expression contains symbols that are not defined, and these + symbols are local symbols, the enclosing scopes are searched for a + symbol with the same name. If one exists and this symbol is defined, + its attributes are used to determine the result size. +<item> In all other cases the expression is assumed to be word sized. +</itemize> + +Note: If the assembler is not able to evaluate the expression at assembly +time, the linker will evaluate it and check for range errors as soon as +the result is known. + + +<sect1>Boolean expressions<p> + +In the context of a boolean expression, any non zero value is evaluated as +true, any other value to false. The result of a boolean expression is 1 if +it's true, and zero if it's false. There are boolean operators with extreme +low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/ +operators are shortcut operators. That is, if the result of the expression is +already known, after evaluating the left hand side, the right hand side is +not evaluated. + + +<sect1>Constant expressions<p> + +Sometimes an expression must evaluate to a constant without looking at any +further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command +that decides if parts of the code are assembled or not. An expression used in +the <tt/.IF/ command cannot reference a symbol defined later, because the +decision about the <tt/.IF/ must be made at the point when it is read. If the +expression used in such a context contains only constant numerical values, +there is no problem. When unresolvable symbols are involved it may get harder +for the assembler to determine if the expression is actually constant, and it +is even possible to create expressions that aren't recognized as constant. +Simplifying the expressions will often help. + +In cases where the result of the expression is not needed immediately, the +assembler will delay evaluation until all input is read, at which point all +symbols are known. So using arbitrary complex constant expressions is no +problem in most cases. + + + +<sect1>Available operators<label id="operators"><p> + +<table> +<tabular ca="clc"> +<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline> +| Built-in string functions| 0@ +||~@ +| Built-in pseudo-variables| 1@ +| Built-in pseudo-functions| 1@ ++| Unary positive| 1@ +-| Unary negative| 1@ +˜<newline> +.BITNOT| Unary bitwise not| 1@ +<<newline> +.LOBYTE| Unary low-byte operator| 1@ +><newline> +.HIBYTE| Unary high-byte operator| 1@ +^<newline> +.BANKBYTE| Unary bank-byte operator| 1@ +||~@ +*| Multiplication| 2@ +/| Division| 2@ +.MOD| Modulo operator| 2@ +&<newline> +.BITAND| Bitwise and| 2@ +^<newline> +.BITXOR| Binary bitwise xor| 2@ +<<<newline> +.SHL| Shift-left operator| 2@ +>><newline> +.SHR| Shift-right operator| 2@ +||~@ ++| Binary addition| 3@ +-| Binary subtraction| 3@ +|<newline> +.BITOR| Bitwise or| 3@ +||~@ += | Compare operator (equal)| 4@ +<>| Compare operator (not equal)| 4@ +<| Compare operator (less)| 4@ +>| Compare operator (greater)| 4@ +<=| Compare operator (less or equal)| 4@ +>=| Compare operator (greater or equal)| 4@ +||~@ +&&<newline> +.AND| Boolean and| 5@ +.XOR| Boolean xor| 5@ +||~@ +||<newline> +.OR| Boolean or| 6@ +||~@ +!<newline> +.NOT| Boolean not| 7@<hline> +</tabular> +<caption>Available operators, sorted by precedence +</table> + +To force a specific order of evaluation, parentheses may be used, as usual. + + + +<sect>Symbols and labels<p> + +A symbol or label is an identifier that starts with a letter and is followed +by letters and digits. Depending on some features enabled (see +<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>, +<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and +<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>) +other characters may be present. Use of identifiers consisting of a single +character will not work in all cases, because some of these identifiers are +reserved keywords (for example "A" is not a valid identifier for a label, +because it is the keyword for the accumulator). + +The assembler allows you to use symbols instead of naked values to make +the source more readable. There are a lot of different ways to define and +use symbols and labels, giving a lot of flexibility. + +<sect1>Numeric constants<p> + +Numeric constants are defined using the equal sign or the label assignment +operator. After doing + +<tscreen><verb> + two = 2 +</verb></tscreen> + +may use the symbol "two" in every place where a number is expected, and it is +evaluated to the value 2 in this context. The label assignment operator is +almost identical, but causes the symbol to be marked as a label, so it may be +handled differently in a debugger: + +<tscreen><verb> + io := $d000 +</verb></tscreen> + +The right side can of course be an expression: + +<tscreen><verb> + four = two * two +</verb></tscreen> + + +<label id="variables"> +<sect1>Numeric variables<p> + +Within macros and other control structures (<tt><ref id=".REPEAT" +name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of +variable. This can be achieved by the <tt>.SET</tt> operator. It creates a +symbol that may get assigned a different value later: + +<tscreen><verb> + four .set 4 + lda #four ; Loads 4 into A + four .set 3 + lda #four ; Loads 3 into A +</verb></tscreen> + +Since the value of the symbol can change later, it must be possible to +evaluate it when used (no delayed evaluation as with normal symbols). So the +expression used as the value must be constant. + +Following is an example for a macro that generates a different label each time +it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function +and a numeric variable named <tt>lcount</tt>. + +<tscreen><verb> + .lcount .set 0 ; Initialize the counter + + .macro genlab + .ident (.sprintf ("L%04X", lcount)): + lcount .set lcount + 1 + .endmacro +</verb></tscreen> + + +<sect1>Standard labels<p> + +A label is defined by writing the name of the label at the start of the line +(before any instruction mnemonic, macro or pseudo directive), followed by a +colon. This will declare a symbol with the given name and the value of the +current program counter. + + +<sect1>Local labels and symbols<p> + +Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to +create regions of code where the names of labels and symbols are local to this +region. They are not known outside of this region and cannot be accessed from +there. Such regions may be nested like PROCEDUREs in Pascal. + +See the description of the <tt><ref id=".PROC" name=".PROC"></tt> +directive for more information. + + +<sect1>Cheap local labels<p> + +Cheap local labels are defined like standard labels, but the name of the +label must begin with a special symbol (usually '@', but this can be +changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt> +directive). + +Cheap local labels are visible only between two non cheap labels. As soon as a +standard symbol is encountered (this may also be a local symbol if inside a +region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the +cheap local symbol goes out of scope. + +You may use cheap local labels as an easy way to reuse common label +names like "Loop". Here is an example: + +<tscreen><verb> + Clear: lda #$00 ; Global label + ldy #$20 + @Loop: sta Mem,y ; Local label + dey + bne @Loop ; Ok + rts + Sub: ... ; New global label + bne @Loop ; ERROR: Unknown identifier! +</verb></tscreen> + +<sect1>Unnamed labels<p> + +If you really want to write messy code, there are also unnamed labels. These +labels do not have a name (you guessed that already, didn't you?). A colon is +used to mark the absence of the name. + +Unnamed labels may be accessed by using the colon plus several minus or plus +characters as a label designator. Using the '-' characters will create a back +reference (use the n'th label backwards), using '+' will create a forward +reference (use the n'th label in forward direction). An example will help to +understand this: + +<tscreen><verb> + : lda (ptr1),y ; #1 + cmp (ptr2),y + bne :+ ; -> #2 + tax + beq :+++ ; -> #4 + iny + bne :- ; -> #1 + inc ptr1+1 + inc ptr2+1 + bne :- ; -> #1 + + : bcs :+ ; #2 -> #3 + ldx #$FF + rts + + : ldx #$01 ; #3 + : rts ; #4 +</verb></tscreen> + +As you can see from the example, unnamed labels will make even short +sections of code hard to understand, because you have to count labels +to find branch targets (this is the reason why I for my part do +prefer the "cheap" local labels). Nevertheless, unnamed labels are +convenient in some situations, so it's your decision. + +<bf/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not +unnamed ones, so scopes don't have an effect on unnamed labels. + + + +<sect1>Using macros to define labels and constants<p> + +While there are drawbacks with this approach, it may be handy in a few rare +situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible +to define symbols or constants that may be used elsewhere. One of the +advantages is that you can use it to define string constants (this is not +possible with the other symbol types). + +Please note: <tt/.DEFINE/ style macros do token replacements on a low level, +so the names do not adhere to scoping, diagnostics may be misleading, there +are no symbols to look up in the map file, and there is no debug info. +Especially the first problem in the list can lead to very nasty programming +errors. Because of these problems, the general advice is, <bf/NOT/ do use +<tt/.DEFINE/ if you don't have to. + +Example: + +<tscreen><verb> + .DEFINE two 2 + .DEFINE version "SOS V2.3" + + four = two * two ; Ok + .byte version ; Ok + + .PROC ; Start local scope + two = 3 ; Will give "2 = 3" - invalid! + .ENDPROC +</verb></tscreen> + + +<sect1>Symbols and <tt>.DEBUGINFO</tt><p> + +If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref +id="option-g" name="-g"> is given on the command line), global, local and +cheap local labels are written to the object file and will be available in the +symbol file via the linker. Unnamed labels are not written to the object file, +because they don't have a name which would allow to access them. + + + +<sect>Scopes<label id="scopes"><p> + +ca65 implements several sorts of scopes for symbols. + +<sect1>Global scope<p> + +All (non cheap local) symbols that are declared outside of any nested scopes +are in global scope. + + +<sect1>Cheap locals<p> + +A special scope is the scope for cheap local symbols. It lasts from one non +local symbol to the next one, without any provisions made by the programmer. +All other scopes differ in usage but use the same concept internally. + + +<sect1>Generic nested scopes<p> + +A nested scoped for generic use is started with <tt/<ref id=".SCOPE" +name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/. +The scope can have a name, in which case it is accessible from the outside by +using <ref id="scopesyntax" name="explicit scopes">. If the scope does not +have a name, all symbols created within the scope are local to the scope, and +aren't accessible from the outside. + +A nested scope can access symbols from the local or from enclosing scopes by +name without using explicit scope names. In some cases there may be +ambiguities, for example if there is a reference to a local symbol that is not +yet defined, but a symbol with the same name exists in outer scopes: + +<tscreen><verb> + .scope outer + foo = 2 + .scope inner + lda #foo + foo = 3 + .endscope + .endscope +</verb></tscreen> + +In the example above, the <tt/lda/ instruction will load the value 3 into the +accumulator, because <tt/foo/ is redefined in the scope. However: + +<tscreen><verb> + .scope outer + foo = $1234 + .scope inner + lda foo,x + foo = $12 + .endscope + .endscope +</verb></tscreen> + +Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the +assembler that <tt/foo/ is a zeropage symbol when translating the instruction, +absolute mode is used instead. In fact, the assembler will not use absolute +mode by default, but it will search through the enclosing scopes for a symbol +with the given name. If one is found, the address size of this symbol is used. +This may lead to errors: + +<tscreen><verb> + .scope outer + foo = $12 + .scope inner + lda foo,x + foo = $1234 + .endscope + .endscope +</verb></tscreen> + +In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/ +instruction, it will search for an already defined symbol <tt/foo/. It will +find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a +zeropage symbol. So the assembler will use zeropage addressing mode. If +<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change +the address in the <tt/lda/ instruction already translated, but since the new +value needs absolute addressing mode, this fails, and an error message "Range +error" is output. + +Of course the most simple solution for the problem is to move the definition +of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be +rare cases when this cannot be done. In these cases, you can use one of the +address size override operators: + +<tscreen><verb> + .scope outer + foo = $12 + .scope inner + lda a:foo,x + foo = $1234 + .endscope + .endscope +</verb></tscreen> + +This will cause the <tt/lda/ instruction to be translated using absolute +addressing mode, which means changing the symbol reference later does not +cause any errors. + + +<sect1>Nested procedures<p> + +A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It +differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a +name, and a it will introduce a symbol with this name in the enclosing scope. +So + +<tscreen><verb> + .proc foo + ... + .endproc +</verb></tscreen> + +is actually the same as + +<tscreen><verb> + foo: + .scope foo + ... + .endscope +</verb></tscreen> + +This is the reason why a procedure must have a name. If you want a scope +without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/. + +<bf/Note:/ As you can see from the example above, scopes and symbols live in +different namespaces. There can be a symbol named <tt/foo/ and a scope named +<tt/foo/ without any conflicts (but see the section titled <ref +id="scopesearch" name=""Scope search order"">). + + +<sect1>Structs, unions and enums<p> + +Structs, unions and enums are explained in a <ref id="structs" name="separate +section">, I do only cover them here, because if they are declared with a +name, they open a nested scope, similar to <tt/<ref id=".SCOPE" +name=".SCOPE">/. However, when no name is specified, the behaviour is +different: In this case, no new scope will be opened, symbols declared within +a struct, union, or enum declaration will then be added to the enclosing scope +instead. + + +<sect1>Explicit scope specification<label id="scopesyntax"><p> + +Accessing symbols from other scopes is possible by using an explicit scope +specification, provided that the scope where the symbol lives in has a name. +The namespace token (<tt/::/) is used to access other scopes: + +<tscreen><verb> + .scope foo + bar: .word 0 + .endscope + + ... + lda foo::bar ; Access foo in scope bar +</verb></tscreen> + +The only way to deny access to a scope from the outside is to declare a scope +without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command). + +A special syntax is used to specify the global scope: If a symbol or scope is +preceded by the namespace token, the global scope is searched: + +<tscreen><verb> + bar = 3 + + .scope foo + bar = 2 + lda #::bar ; Access the global bar (which is 3) + .endscope +</verb></tscreen> + + +<sect1>Scope search order<label id="scopesearch"><p> + +The assembler searches for a scope in a similar way as for a symbol. First, it +looks in the current scope, and then it walks up the enclosing scopes until +the scope is found. + +However, one important thing to note when using explicit scope syntax is, that +a symbol may be accessed before it is defined, but a scope may <bf/not/ be +used without a preceding definition. This means that in the following +example: + +<tscreen><verb> + .scope foo + bar = 3 + .endscope + + .scope outer + lda #foo::bar ; Will load 3, not 2! + .scope foo + bar = 2 + .endscope + .endscope +</verb></tscreen> + +the reference to the scope <tt/foo/ will use the global scope, and not the +local one, because the local one is not visible at the point where it is +referenced. + +Things get more complex if a complete chain of scopes is specified: + +<tscreen><verb> + .scope foo + .scope outer + .scope inner + bar = 1 + .endscope + .endscope + .scope another + .scope nested + lda #outer::inner::bar ; 1 + .endscope + .endscope + .endscope + + .scope outer + .scope inner + bar = 2 + .endscope + .endscope +</verb></tscreen> + +When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the +assembler will first search in the local scope for a scope named <tt/outer/. +Since none is found, the enclosing scope (<tt/another/) is checked. There is +still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally +scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in +this scope, the assembler looks for a symbol named <tt/bar/. + +Please note that once the anchor scope is found, all following scopes +(<tt/inner/ in this case) are expected to be found exactly in this scope. The +assembler will search the scope tree only for the first scope (if it is not +anchored in the root scope). Starting from there on, there is no flexibility, +so if the scope named <tt/outer/ found by the assembler does not contain a +scope named <tt/inner/, this would be an error, even if such a pair does exist +(one level up in global scope). + +Ambiguities that may be introduced by this search algorithm may be removed by +anchoring the scope specification in the global scope. In the example above, +if you want to access the "other" symbol <tt/bar/, you would have to write: + +<tscreen><verb> + .scope foo + .scope outer + .scope inner + bar = 1 + .endscope + .endscope + .scope another + .scope nested + lda #::outer::inner::bar ; 2 + .endscope + .endscope + .endscope + + .scope outer + .scope inner + bar = 2 + .endscope + .endscope +</verb></tscreen> + + +<sect>Address sizes and memory models<label id="address-sizes"><p> + +<sect1>Address sizes<p> + +ca65 assigns each segment and each symbol an address size. This is true, even +if the symbol is not used as an address. You may also think of a value range +of the symbol instead of an address size. + +Possible address sizes are: + +<itemize> +<item>Zeropage or direct (8 bits) +<item>Absolute (16 bits) +<item>Far (24 bits) +<item>Long (32 bits) +</itemize> + +Since the assembler uses default address sizes for the segments and symbols, +it is usually not necessary to override the default behaviour. In cases, where +it is necessary, the following keywords may be used to specify address sizes: + +<itemize> +<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits). +<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits). +<item>FAR for far addressing (24 bits). +<item>LONG or DWORD for long addressing (32 bits). +</itemize> + + +<sect1>Address sizes of segments<p> + +The assembler assigns an address size to each segment. Since the +representation of a label within this segment is "segment start + offset", +labels will inherit the address size of the segment they are declared in. + +The address size of a segment may be changed, by using an optional address +size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for +an explanation on how this is done. + + +<sect1>Address sizes of symbols<p> + + + + +<sect1>Memory models<p> + +The default address size of a segment depends on the memory model used. Since +labels inherit the address size from the segment they are declared in, +changing the memory model is an easy way to change the address size of many +symbols at once. + + + + +<sect>Pseudo variables<label id="pseudo-variables"><p> + +Pseudo variables are readable in all cases, and in some special cases also +writable. + +<sect1><tt>*</tt><p> + + Reading this pseudo variable will return the program counter at the start + of the current input line. + + Assignment to this variable is possible when <tt/<ref id=".FEATURE" + name=".FEATURE pc_assignment">/ is used. Note: You should not use + assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead. + + +<sect1><tt>.CPU</tt><label id=".CPU"><p> + + Reading this pseudo variable will give a constant integer value that + tells which CPU is currently enabled. It can also tell which instruction + set the CPU is able to translate. The value read from the pseudo variable + should be further examined by using one of the constants defined by the + "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/). + + It may be used to replace the .IFPxx pseudo instructions or to construct + even more complex expressions. + + Example: + + <tscreen><verb> + .macpack cpu + .if (.cpu .bitand CPU_ISET_65816) + phx + phy + .else + txa + pha + tya + pha + .endif + </verb></tscreen> + + +<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p> + + This builtin pseudo variable is only available in macros. It is replaced by + the actual number of parameters that were given in the macro invocation. + + Example: + + <tscreen><verb> + .macro foo arg1, arg2, arg3 + .if .paramcount <> 3 + .error "Too few parameters for macro foo" + .endif + ... + .endmacro + </verb></tscreen> + + See section <ref id="macros" name="Macros">. + + +<sect1><tt>.TIME</tt><label id=".TIME"><p> + + Reading this pseudo variable will give a constant integer value that + represents the current time in POSIX standard (as seconds since the + Epoch). + + It may be used to encode the time of translation somewhere in the created + code. + + Example: + + <tscreen><verb> + .dword .time ; Place time here + </verb></tscreen> + + +<sect1><tt>.VERSION</tt><label id=".VERSION"><p> + + Reading this pseudo variable will give the assembler version according to + the following formula: + + VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH + + It may be used to encode the assembler version or check the assembler for + special features not available with older versions. + + Example: + + Version 2.11.1 of the assembler will return $2B1 as numerical constant when + reading the pseudo variable <tt/.VERSION/. + + + +<sect>Pseudo functions<label id="pseudo-functions"><p> + +Pseudo functions expect their arguments in parenthesis, and they have a result, +either a string or an expression. + + +<sect1><tt>.BANK</tt><label id=".BANK"><p> + + The <tt/.BANK/ function is used to support systems with banked memory. The + argument is an expression with exactly one segment reference - usually a + label. The function result is the value of the <tt/bank/ attribute assigned + to the run memory area of the segment. Please see the linker documentation + for more information about memory areas and their attributes. + + The value of <tt/.BANK/ can be used to switch memory so that a memory bank + containing specific data is available. + + The <tt/bank/ attribute is a 32 bit integer and so is the result of the + <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE" + name=".LOBYTE"></tt> or similar functions to address just part of it. + + Please note that <tt/.BANK/ will always get evaluated in the link stage, so + an expression containing <tt/.BANK/ can never be used where a constant known + result is expected (for example with <tt/.RES/). + + Example: + + <tscreen><verb> + .segment "BANK1" + .proc banked_func_1 + ... + .endproc + + .segment "BANK2" + .proc banked_func_2 + ... + .endproc + + .proc bank_table + .addr banked_func_1 + .byte <.BANK (banked_func_1) + + .addr banked_func_2 + .byte <.BANK (banked_func_2) + .endproc + </verb></tscreen> + + + +<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p> + + The function returns the bank byte (that is, bits 16-23) of its argument. + It works identical to the '^' operator. + + See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, + <tt><ref id=".LOBYTE" name=".LOBYTE"></tt> + + +<sect1><tt>.BLANK</tt><label id=".BLANK"><p> + + Builtin function. The function evaluates its argument in braces and yields + "false" if the argument is non blank (there is an argument), and "true" if + there is no argument. The token list that makes up the function argument + may optionally be enclosed in curly braces. This allows the inclusion of + tokens that would otherwise terminate the list (the closing right + parenthesis). The curly braces are not considered part of the list, a list + just consisting of curly braces is considered to be empty. + + As an example, the <tt/.IFBLANK/ statement may be replaced by + + <tscreen><verb> + .if .blank({arg}) + </verb></tscreen> + + + +<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p> + + Builtin string function. The function allows to concatenate a list of string + constants separated by commas. The result is a string constant that is the + concatenation of all arguments. This function is most useful in macros and + when used together with the <tt/.STRING/ builtin function. The function may + be used in any case where a string constant is expected. + + Example: + + <tscreen><verb> + .include .concat ("myheader", ".", "inc") + </verb></tscreen> + + This is the same as the command + + <tscreen><verb> + .include "myheader.inc" + </verb></tscreen> + + +<sect1><tt>.CONST</tt><label id=".CONST"><p> + + Builtin function. The function evaluates its argument in braces and + yields "true" if the argument is a constant expression (that is, an + expression that yields a constant value at assembly time) and "false" + otherwise. As an example, the .IFCONST statement may be replaced by + + <tscreen><verb> + .if .const(a + 3) + </verb></tscreen> + + +<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p> + + The function returns the high byte (that is, bits 8-15) of its argument. + It works identical to the '>' operator. + + See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>, + <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> + + +<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p> + + The function returns the high word (that is, bits 16-31) of its argument. + + See: <tt><ref id=".LOWORD" name=".LOWORD"></tt> + + +<sect1><tt>.IDENT</tt><label id=".IDENT"><p> + + The function expects a string as its argument, and converts this argument + into an identifier. If the string starts with the current <tt/<ref + id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local + identifier, otherwise it will be converted into a normal identifier. + + Example: + + <tscreen><verb> + .macro makelabel arg1, arg2 + .ident (.concat (arg1, arg2)): + .endmacro + + makelabel "foo", "bar" + + .word foobar ; Valid label + </verb></tscreen> + + +<sect1><tt>.LEFT</tt><label id=".LEFT"><p> + + Builtin function. Extracts the left part of a given token list. + + Syntax: + + <tscreen><verb> + .LEFT (<int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the number of tokens to extract from + the token list. The second argument is the token list itself. The token + list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). + + Example: + + To check in a macro if the given argument has a '#' as first token + (immediate addressing mode), use something like this: + + <tscreen><verb> + .macro ldax arg + ... + .if (.match (.left (1, {arg}), #)) + + ; ldax called with immediate operand + ... + + .endif + ... + .endmacro + </verb></tscreen> + + See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT" + name=".RIGHT"></tt> builtin functions. + + +<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p> + + The function returns the low byte (that is, bits 0-7) of its argument. + It works identical to the '<' operator. + + See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, + <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> + + +<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p> + + The function returns the low word (that is, bits 0-15) of its argument. + + See: <tt><ref id=".HIWORD" name=".HIWORD"></tt> + + +<sect1><tt>.MATCH</tt><label id=".MATCH"><p> + + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + <tscreen><verb> + .MATCH(<token list #1>, <token list #2>) + </verb></tscreen> + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + <itemize> + <item>end-of-line + <item>end-of-file + </itemize> + + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. + + Please note that the function does only compare tokens, not token + attributes. So any number is equal to any other number, regardless of the + actual value. The same is true for strings. If you need to compare tokens + <em/and/ token attributes, use the <tt><ref id=".XMATCH" + name=".XMATCH"></tt> function. + + Example: + + Assume the macro <tt/ASR/, that will shift right the accumulator by one, + while honoring the sign bit. The builtin processor instructions will allow + an optional "A" for accu addressing for instructions like <tt/ROL/ and + <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function + to check for this and print and error for invalid calls. + + <tscreen><verb> + .macro asr arg + + .if (.not .blank(arg)) .and (.not .match ({arg}, a)) + .error "Syntax error" + .endif + + cmp #$80 ; Bit 7 into carry + lsr a ; Shift carry into bit 7 + + .endmacro + </verb></tscreen> + + The macro will only accept no arguments, or one argument that must be the + reserved keyword "A". + + See: <tt><ref id=".XMATCH" name=".XMATCH"></tt> + + +<sect1><tt>.MAX</tt><label id=".MAX"><p> + + Builtin function. The result is the larger of two values. + + The syntax is + + <tscreen><verb> + .MAX (<value #1>, <value #2>) + </verb></tscreen> + + Example: + + <tscreen><verb> + ; Reserve space for the larger of two data blocks + savearea: .max (.sizeof (foo), .sizeof (bar)) + </verb></tscreen> + + See: <tt><ref id=".MIN" name=".MIN"></tt> + + +<sect1><tt>.MID</tt><label id=".MID"><p> + + Builtin function. Takes a starting index, a count and a token list as + arguments. Will return part of the token list. + + Syntax: + + <tscreen><verb> + .MID (<int expr>, <int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the starting token in the list (the first + token has index 0). The second integer expression gives the number of tokens + to extract from the token list. The third argument is the token list itself. + The token list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). + + Example: + + To check in a macro if the given argument has a '<tt/#/' as first token + (immediate addressing mode), use something like this: + + <tscreen><verb> + .macro ldax arg + ... + .if (.match (.mid (0, 1, {arg}), #)) + + ; ldax called with immediate operand + ... + + .endif + ... + .endmacro + </verb></tscreen> + + See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT" + name=".RIGHT"></tt> builtin functions. + + +<sect1><tt>.MIN</tt><label id=".MIN"><p> + + Builtin function. The result is the smaller of two values. + + The syntax is + + <tscreen><verb> + .MIN (<value #1>, <value #2>) + </verb></tscreen> + + Example: + + <tscreen><verb> + ; Reserve space for some data, but 256 bytes minimum + savearea: .min (.sizeof (foo), 256) + </verb></tscreen> + + See: <tt><ref id=".MAX" name=".MAX"></tt> + + +<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p> + + Builtin function. The function expects an identifier as argument in braces. + The argument is evaluated, and the function yields "true" if the identifier + is a symbol that has already been referenced somewhere in the source file up + to the current position. Otherwise the function yields false. As an example, + the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by + + <tscreen><verb> + .if .referenced(a) + </verb></tscreen> + + See: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p> + + Builtin function. Extracts the right part of a given token list. + + Syntax: + + <tscreen><verb> + .RIGHT (<int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the number of tokens to extract from the + token list. The second argument is the token list itself. The token list + may optionally be enclosed into curly braces. This allows the inclusion of + tokens that would otherwise terminate the list (the closing right paren in + the given case). + + See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID" + name=".MID"></tt> builtin functions. + + +<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p> + + <tt/.SIZEOF/ is a pseudo function that returns the size of its argument. The + argument can be a struct/union, a struct member, a procedure, or a label. In + case of a procedure or label, its size is defined by the amount of data + placed in the segment where the label is relative to. If a line of code + switches segments (for example in a macro) data placed in other segments + does not count for the size. + + Please note that a symbol or scope must exist, before it is used together with + <tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes). + A scope has preference over a symbol with the same name, so if the last part + of a name represents both, a scope and a symbol, the scope is chosen over the + symbol. + + After the following code: + + <tscreen><verb> + .struct Point ; Struct size = 4 + xcoord .word + ycoord .word + .endstruct + + P: .tag Point ; Declare a point + @P: .tag Point ; Declare another point + + .code + .proc Code + nop + .proc Inner + nop + .endproc + nop + .endproc + + .proc Data + .data ; Segment switch!!! + .res 4 + .endproc + </verb></tscreen> + + <descrip> + <tag><tt/.sizeof(Point)/</tag> + will have the value 4, because this is the size of struct <tt/Point/. + + <tag><tt/.sizeof(Point::xcoord)/</tag> + will have the value 2, because this is the size of the member <tt/xcoord/ + in struct <tt/Point/. + + <tag><tt/.sizeof(P)/</tag> + will have the value 4, this is the size of the data declared on the same + source line as the label <tt/P/, which is in the same segment that <tt/P/ + is relative to. + + <tag><tt/.sizeof(@P)/</tag> + will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/ + does also work for cheap local symbols. + + <tag><tt/.sizeof(Code)/</tag> + will have the value 3, since this is amount of data emitted into the code + segment, the segment that was active when <tt/Code/ was entered. Note that + this value includes the amount of data emitted in child scopes (in this + case <tt/Code::Inner/). + + <tag><tt/.sizeof(Code::Inner)/</tag> + will have the value 1 as expected. + + <tag><tt/.sizeof(Data)/</tag> + will have the value 0. Data is emitted within the scope <tt/Data/, but since + the segment is switched after entry, this data is emitted into another + segment. + </descrip> + + +<sect1><tt>.STRAT</tt><label id=".STRAT"><p> + + Builtin function. The function accepts a string and an index as + arguments and returns the value of the character at the given position + as an integer value. The index is zero based. + + Example: + + <tscreen><verb> + .macro M Arg + ; Check if the argument string starts with '#' + .if (.strat (Arg, 0) = '#') + ... + .endif + .endmacro + </verb></tscreen> + + +<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p> + + Builtin function. It expects a format string as first argument. The number + and type of the following arguments depend on the format string. The format + string is similar to the one of the C <tt/printf/ function. Missing things + are: Length modifiers, variable width. + + The result of the function is a string. + + Example: + + <tscreen><verb> + num = 3 + + ; Generate an identifier: + .ident (.sprintf ("%s%03d", "label", num)): + </verb></tscreen> + + +<sect1><tt>.STRING</tt><label id=".STRING"><p> + + Builtin function. The function accepts an argument in braces and converts + this argument into a string constant. The argument may be an identifier, or + a constant numeric value. + + Since you can use a string in the first place, the use of the function may + not be obvious. However, it is useful in macros, or more complex setups. + + Example: + + <tscreen><verb> + ; Emulate other assemblers: + .macro section name + .segment .string(name) + .endmacro + </verb></tscreen> + + +<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p> + + Builtin function. The function accepts a string argument in braces and + evaluates to the length of the string. + + Example: + + The following macro encodes a string as a pascal style string with + a leading length byte. + + <tscreen><verb> + .macro PString Arg + .byte .strlen(Arg), Arg + .endmacro + </verb></tscreen> + + +<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p> + + Builtin function. The function accepts a token list in braces. The function + result is the number of tokens given as argument. The token list may + optionally be enclosed into curly braces which are not considered part of + the list and not counted. Enclosement in curly braces allows the inclusion + of tokens that would otherwise terminate the list (the closing right paren + in the given case). + + Example: + + The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as + with the normal 6502 instructions). To translate it into two separate 8 bit + load instructions, the '#' token has to get stripped from the argument: + + <tscreen><verb> + .macro ldax arg + .if (.match (.mid (0, 1, {arg}), #)) + ; ldax called with immediate operand + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ... + .endif + .endmacro + </verb></tscreen> + + +<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p> + + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + <tscreen><verb> + .XMATCH(<token list #1>, <token list #2>) + </verb></tscreen> + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + <itemize> + <item>end-of-line + <item>end-of-file + </itemize> + + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. + + The function compares tokens <em/and/ token values. If you need a function + that just compares the type of tokens, have a look at the <tt><ref + id=".MATCH" name=".MATCH"></tt> function. + + See: <tt><ref id=".MATCH" name=".MATCH"></tt> + + + +<sect>Control commands<label id="control-commands"><p> + +Here's a list of all control commands and a description, what they do: + + +<sect1><tt>.A16</tt><label id=".A16"><p> + + Valid only in 65816 mode. Switch the accumulator to 16 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 16 bit operands for immediate accumulator addressing mode. + + See also: <tt><ref id=".SMART" name=".SMART"></tt> + + +<sect1><tt>.A8</tt><label id=".A8"><p> + + Valid only in 65816 mode. Switch the accumulator to 8 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 8 bit operands for immediate accu addressing mode. + + See also: <tt><ref id=".SMART" name=".SMART"></tt> + + +<sect1><tt>.ADDR</tt><label id=".ADDR"><p> + + Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and + may be used for better readability if the data words are address values. In + 65816 mode, the address is forced to be 16 bit wide to fit into the current + segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command + must be followed by a sequence of (not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .addr $0D00, $AF13, _Clear + </verb></tscreen> + + See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD" + name=".WORD"></tt> + + +<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p> + + Align data to a given boundary. The command expects a constant integer + argument in the range 1 ... 65536, plus an optional second argument + in byte range. If there is a second argument, it is used as fill value, + otherwise the value defined in the linker configuration file is used + (the default for this value is zero). + + <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of + the final address of the segment. <tt/.ALIGN/ cannot insert a variable + number of bytes, since that would break address calculations within the + module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple + of the alignment, because that allows the number of fill bytes to be + calculated in advance by the assembler. You are therefore required to + specify a matching alignment for the segment in the linker config. The + linker will output a warning if the alignment of the segment is less than + what is necessary to have a correct alignment in the object file. + + Example: + + <tscreen><verb> + .align 256 + </verb></tscreen> + + Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/ + commands with different arguments. To allow the assembler to calculate the + number of fill bytes in advance, the alignment of the segment must be a + multiple of each of the alignment factors. This may result in unexpectedly + large alignments for the segment within the module. + + Example: + + <tscreen><verb> + .align 15 + .byte 15 + .align 18 + .byte 18 + </verb></tscreen> + + For the assembler to be able to align correctly, the segment must be aligned + to the least common multiple of 15 and 18 which is 90. The assembler will + calculate this automatically and will mark the segment with this value. + + Unfortunately, the combined alignment may get rather large without the user + knowing about it, wasting space in the final executable. If we add another + alignment to the example above + + <tscreen><verb> + .align 15 + .byte 15 + .align 18 + .byte 18 + .align 251 + .byte 0 + </verb></tscreen> + + the assembler will force a segment alignment to the least common multiple of + 15, 18 and 251 - which is 22590. To protect the user against errors, the + assembler will issue a warning when the combined alignment exceeds 256. The + command line option <tt><ref id="option--large-alignment" + name="--large-alignment"></tt> will disable this warning. + + Please note that with alignments that are a power of two (which were the + only alignments possible in older versions of the assembler), the problem is + less severe, because the least common multiple of powers to the same base is + always the larger one. + + + +<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p> + + Define a string with a trailing zero. + + Example: + + <tscreen><verb> + Msg: .asciiz "Hello world" + </verb></tscreen> + + This will put the string "Hello world" followed by a binary zero into + the current segment. There may be more strings separated by commas, but + the binary zero is only appended once (after the last one). + + +<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p> + + Add an assertion. The command is followed by an expression, an action + specifier, and an optional message that is output in case the assertion + fails. If no message was given, the string "Assertion failed" is used. The + action specifier may be one of <tt/warning/, <tt/error/, <tt/ldwarning/ or + <tt/lderror/. In the former two cases, the assertion is evaluated by the + assembler if possible, and in any case, it's also passed to the linker in + the object file (if one is generated). The linker will then evaluate the + expression when segment placement has been done. + + Example: + + <tscreen><verb> + .assert * = $8000, error, "Code not at $8000" + </verb></tscreen> + + The example assertion will check that the current location is at $8000, + when the output file is written, and abort with an error if this is not + the case. More complex expressions are possible. The action specifier + <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs + an error message. In the latter case, generation of the output file is + suppressed in both the assembler and linker. + + +<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p> + + Is followed by a plus or a minus character. When switched on (using a + +), undefined symbols are automatically marked as import instead of + giving errors. When switched off (which is the default so this does not + make much sense), this does not happen and an error message is + displayed. The state of the autoimport flag is evaluated when the + complete source was translated, before outputting actual code, so it is + <em/not/ possible to switch this feature on or off for separate sections + of code. The last setting is used for all symbols. + + You should probably not use this switch because it delays error + messages about undefined symbols until the link stage. The cc65 + compiler (which is supposed to produce correct assembler code in all + circumstances, something which is not true for most assembler + programmers) will insert this command to avoid importing each and every + routine from the runtime library. + + Example: + + <tscreen><verb> + .autoimport + ; Switch on auto import + </verb></tscreen> + +<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p> + + Define byte sized data by extracting only the bank byte (that is, bits 16-23) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '^' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + TableLookupBank: .bankbytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, + <tt><ref id=".LOBYTES" name=".LOBYTES"></tt> + + +<sect1><tt>.BSS</tt><label id=".BSS"><p> + + Switch to the BSS segment. The name of the BSS segment is always "BSS", + so this is a shortcut for + + <tscreen><verb> + .segment "BSS" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p> + + Define byte sized data. Must be followed by a sequence of (byte ranged) + expressions or strings. + + Example: + + <tscreen><verb> + .byte "Hello " + .byt "world", $0D, $00 + </verb></tscreen> + + +<sect1><tt>.CASE</tt><label id=".CASE"><p> + + Switch on or off case sensitivity on identifiers. The default is off + (that is, identifiers are case sensitive), but may be changed by the + -i switch on the command line. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .case - ; Identifiers are not case sensitive + </verb></tscreen> + + +<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p> + + Apply a custom mapping for characters. The command is followed by two + numbers. The first one is the index of the source character (range 1..255), + the second one is the mapping (range 0..255). The mapping applies to all + character and string constants when they generate output, and overrides a + mapping table specified with the <tt><ref id="option-t" name="-t"></tt> + command line switch. + + Example: + + <tscreen><verb> + .charmap $41, $61 ; Map 'A' to 'a' + </verb></tscreen> + + +<sect1><tt>.CODE</tt><label id=".CODE"><p> + + Switch to the CODE segment. The name of the CODE segment is always + "CODE", so this is a shortcut for + + <tscreen><verb> + .segment "CODE" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.CONDES</tt><label id=".CONDES"><p> + + Export a symbol and mark it in a special way. The linker is able to build + tables of all such symbols. This may be used to automatically create a list + of functions needed to initialize linked library modules. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol with + <tt/.CONDES/ does nothing by itself. + + All symbols are exported as an absolute (16 bit) symbol. You don't need to + use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this + is implied by <tt/.CONDES/. + + <tt/.CONDES/ is followed by the type, which may be <tt/constructor/, + <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as + specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/). + The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" + name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/ + with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/. + + After the type, an optional priority may be specified. Higher numeric values + mean higher priority. If no priority is given, the default priority of 7 is + used. Be careful when assigning priorities to your own module constructors + so they won't interfere with the ones in the cc65 library. + + Example: + + <tscreen><verb> + .condes ModuleInit, constructor + .condes ModInit, 0, 16 + </verb></tscreen> + + See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" + name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes" + name="Module constructors/destructors"> explaining the feature in more + detail. + + +<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p> + + Export a symbol and mark it as a module constructor. This may be used + together with the linker to build a table of constructor subroutines that + are called by the startup code. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + constructor does nothing by itself. + + A constructor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.constructor/. It may have an optional priority that is separated by a + comma. Higher numeric values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module constructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .constructor ModuleInit + .constructor ModInit, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section + <ref id="condes" name="Module constructors/destructors"> explaining the + feature in more detail. + + +<sect1><tt>.DATA</tt><label id=".DATA"><p> + + Switch to the DATA segment. The name of the DATA segment is always + "DATA", so this is a shortcut for + + <tscreen><verb> + .segment "DATA" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.DBYT</tt><label id=".DBYT"><p> + + Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to + create word sized data in native 65XX format). Must be followed by a + sequence of (word ranged) expressions. + + Example: + + <tscreen><verb> + .dbyt $1234, $4512 + </verb></tscreen> + + This will emit the bytes + + <tscreen><verb> + $12 $34 $45 $12 + </verb></tscreen> + + into the current segment in that order. + + +<sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p> + + Switch on or off debug info generation. The default is off (that is, + the object file will not contain debug infos), but may be changed by the + -g switch on the command line. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .debuginfo + ; Generate debug info + </verb></tscreen> + + +<sect1><tt>.DEFINE</tt><label id=".DEFINE"><p> + + Start a define style macro definition. The command is followed by an + identifier (the macro name) and optionally by a list of formal arguments + in braces. + + Please note that <tt/.DEFINE/ shares most disadvantages with its C + counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you + don't have to. + + See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and + section <ref id="macros" name="Macros">. + + +<sect1><tt>.DELMAC, .DELMACRO</tt><label id=".DELMACRO"><p> + + Delete a classic macro (defined with <tt><ref id=".MACRO" + name=".MACRO"></tt>) . The command is followed by the name of an + existing macro. Its definition will be deleted together with the name. + If necessary, another macro with this name may be defined later. + + See: <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p> + + Builtin function. The function expects an identifier as argument in braces. + The argument is evaluated, and the function yields "true" if the identifier + is a symbol that is already defined somewhere in the source file up to the + current position. Otherwise the function yields false. As an example, the + <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by + + <tscreen><verb> + .if .defined(a) + </verb></tscreen> + + +<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p> + + Export a symbol and mark it as a module destructor. This may be used + together with the linker to build a table of destructor subroutines that + are called by the startup code. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + constructor does nothing by itself. + + A destructor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.destructor/. It may have an optional priority that is separated by a + comma. Higher numerical values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module destructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .destructor ModuleDone + .destructor ModDone, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref + id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate + section <ref id="condes" name="Module constructors/destructors"> explaining + the feature in more detail. + + +<sect1><tt>.DWORD</tt><label id=".DWORD"><p> + + Define dword sized data (4 bytes) Must be followed by a sequence of + expressions. + + Example: + + <tscreen><verb> + .dword $12344512, $12FA489 + </verb></tscreen> + + +<sect1><tt>.ELSE</tt><label id=".ELSE"><p> + + Conditional assembly: Reverse the current condition. + + +<sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p> + + Conditional assembly: Reverse current condition and test a new one. + + +<sect1><tt>.END</tt><label id=".END"><p> + + Forced end of assembly. Assembly stops at this point, even if the command + is read from an include file. + + +<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p> + + End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration. + + +<sect1><tt>.ENDIF</tt><label id=".ENDIF"><p> + + Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or + <tt><ref id=".ELSE" name=".ELSE"></tt> branch. + + +<sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p> + + Marks the end of a macro definition. + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p> + + End of local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>). + + +<sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p> + + End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block. + + +<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p> + + End of local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/). + + +<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p> + + Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/ + command and the separate section named <ref id="structs" name=""Structs + and unions"">. + + +<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p> + + Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/ + command and the separate section named <ref id="structs" name=""Structs + and unions"">. + + +<sect1><tt>.ENUM</tt><label id=".ENUM"><p> + + Start an enumeration. This directive is very similar to the C <tt/enum/ + keyword. If a name is given, a new scope is created for the enumeration, + otherwise the enumeration members are placed in the enclosing scope. + + In the enumeration body, symbols are declared. The first symbol has a value + of zero, and each following symbol will get the value of the preceding plus + one. This behaviour may be overridden by an explicit assignment. Two symbols + may have the same value. + + Example: + + <tscreen><verb> + .enum errorcodes + no_error + file_error + parse_error + .endenum + </verb></tscreen> + + Above example will create a new scope named <tt/errorcodes/ with three + symbols in it that get the values 0, 1 and 2 respectively. Another way + to write this would have been: + + <tscreen><verb> + .scope errorcodes + no_error = 0 + file_error = 1 + parse_error = 2 + .endscope + </verb></tscreen> + + Please note that explicit scoping must be used to access the identifiers: + + <tscreen><verb> + .word errorcodes::no_error + </verb></tscreen> + + A more complex example: + + <tscreen><verb> + .enum + EUNKNOWN = -1 + EOK + EFILE + EBUSY + EAGAIN + EWOULDBLOCK = EAGAIN + .endenum + </verb></tscreen> + + In this example, the enumeration does not have a name, which means that the + members will be visible in the enclosing scope and can be used in this scope + without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1. + The value for the following members is incremented by one, so <tt/EOK/ would + be zero and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EGAIN/, so it has an + override for the value using an already defined symbol. + + +<sect1><tt>.ERROR</tt><label id=".ERROR"><p> + + Force an assembly error. The assembler will output an error message + preceded by "User error". Assembly is continued but no object file will + generated. + + This command may be used to check for initial conditions that must be + set before assembling a source file. + + Example: + + <tscreen><verb> + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .error "Must define foo or bar!" + .endif + </verb></tscreen> + + See also: <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p> + + Abort a macro expansion immediately. This command is often useful in + recursive macros. + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p> + + Make symbols accessible from other modules. Must be followed by a comma + separated list of symbols to export, with each one optionally followed by an + address specification and (also optional) an assignment. Using an additional + assignment in the export statement allows to define and export a symbol in + one statement. The default is to export the symbol with the address size it + actually has. The assembler will issue a warning, if the symbol is exported + with an address size smaller than the actual address size. + + Examples: + + <tscreen><verb> + .export foo + .export bar: far + .export foobar: far = foo * bar + .export baz := foobar, zap: far = baz - bar + </verb></tscreen> + + As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the + symbols as a label. + + See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt> + + +<sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p> + + Make symbols accessible from other modules. Must be followed by a comma + separated list of symbols to export. The exported symbols are explicitly + marked as zero page symbols. An assignment may be included in the + <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one + statement. + + Examples: + + <tscreen><verb> + .exportzp foo, bar + .exportzp baz := $02 + </verb></tscreen> + + See: <tt><ref id=".EXPORT" name=".EXPORT"></tt> + + +<sect1><tt>.FARADDR</tt><label id=".FARADDR"><p> + + Define far (24 bit) address data. The command must be followed by a + sequence of (not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .faraddr DrawCircle, DrawRectangle, DrawHexagon + </verb></tscreen> + + See: <tt><ref id=".ADDR" name=".ADDR"></tt> + + +<sect1><tt>.FATAL</tt><label id=".FATAL"><p> + + Force an assembly error and terminate assembly. The assembler will output an + error message preceded by "User error" and will terminate assembly + immediately. + + This command may be used to check for initial conditions that must be + set before assembling a source file. + + Example: + + <tscreen><verb> + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .fatal "Must define foo or bar!" + .endif + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.FEATURE</tt><label id=".FEATURE"><p> + + This directive may be used to enable one or more compatibility features + of the assembler. While the use of <tt/.FEATURE/ should be avoided when + possible, it may be useful when porting sources written for other + assemblers. There is no way to switch a feature off, once you have + enabled it, so using + + <tscreen><verb> + .FEATURE xxx + </verb></tscreen> + + will enable the feature until end of assembly is reached. + + The following features are available: + + <descrip> + + <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> + + Accept the at character (`@') as a valid character in identifiers. The + at character is not allowed to start an identifier, even with this + feature enabled. + + <tag><tt>c_comments</tt><label id="c_comments"></tag> + + Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right + comment terminators. Note that C comments may not be nested. There's also a + pitfall when using C like comments: All statements must be terminated by + "end-of-line". Using C like comments, it is possible to hide the newline, + which results in error messages. See the following non working example: + + <tscreen><verb> + lda #$00 /* This comment hides the newline +*/ sta $82 + </verb></tscreen> + + <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> + + Accept the dollar sign (`$') as a valid character in identifiers. The + dollar character is not allowed to start an identifier, even with this + feature enabled. + + <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> + + The dollar sign may be used as an alias for the star (`*'), which + gives the value of the current PC in expressions. + Note: Assignment to the pseudo variable is not allowed. + + <tag><tt>force_range</tt><label id="force_range"></tag> + + Force expressions into their valid range for immediate addressing and + storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and + <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one, + since it will completely disable error checks. + + <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag> + + Allow labels without a trailing colon. These labels are only accepted, + if they start at the beginning of a line (no leading white space). + + <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> + + Accept the dot (`.') as the first character of an identifier. This may be + used for example to create macro names that start with a dot emulating + control directives of other assemblers. Note however, that none of the + reserved keywords built into the assembler, that starts with a dot, may be + overridden. When using this feature, you may also get into trouble if + later versions of the assembler define new keywords starting with a dot. + + <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag> + + Accept single quotes as well as double quotes as terminators for char + constants. + + <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag> + + Accept single quotes as well as double quotes as terminators for string + constants. + + <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag> + + Accept single quoted character constants where the terminating quote is + missing. + <tscreen><verb> + lda #'a + </verb></tscreen> + <bf/Note:/ This does not work in conjunction with <tt/.FEATURE + loose_string_term/, since in this case the input would be ambiguous. + + <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag> + + This feature makes relocatable/absolute mode local to the current segment. + Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in + effect will only enable absolute mode for the current segment. Dito for + <tt><ref id=".RELOC" name=".RELOC"></tt>. + + <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> + + Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/ + is enabled). Such an assignment is handled identical to the <tt><ref + id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just + removing the lines with the assignments may also be an option when porting + code written for older assemblers). + + <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag> + + Allow the use of instructions names as names for macros and symbols. This + makes it possible to "overload" instructions by defining a macro with the + same name. This does also make it possible to introduce hard to find errors + in your code, so be careful! + + <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag> + + Allow underlines within numeric constants. These may be used for grouping + the digits of numbers for easier reading. + Example: + <tscreen><verb> + .feature underline_in_numbers + .word %1100001110100101 + .word %1100_0011_1010_0101 ; Identical but easier to read + </verb></tscreen> + + </descrip> + + It is also possible to specify features on the command line using the + <tt><ref id="option--feature" name="--feature"></tt> command line option. + This is useful when translating sources written for older assemblers, when + you don't want to change the source code. + + As an example, to translate sources written for Andre Fachats xa65 + assembler, the features + + <verb> + labels_without_colons, pc_assignment, loose_char_term + </verb> + + may be helpful. They do not make ca65 completely compatible, so you may not + be able to translate the sources without changes, even when enabling these + features. However, I have found several sources that translate without + problems when enabling these features on the command line. + + +<sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p> + + Insert an option string into the object file. There are two forms of + this command, one specifies the option by a keyword, the second + specifies it as a number. Since usage of the second one needs knowledge + of the internal encoding, its use is not recommended and I will only + describe the first form here. + + The command is followed by one of the keywords + + <tscreen><verb> + author + comment + compiler + </verb></tscreen> + + a comma and a string. The option is written into the object file + together with the string value. This is currently unidirectional and + there is no way to actually use these options once they are in the + object file. + + Examples: + + <tscreen><verb> + .fileopt comment, "Code stolen from my brother" + .fileopt compiler, "BASIC 2.0" + .fopt author, "J. R. User" + </verb></tscreen> + + +<sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p> + + Import an absolute symbol from another module. The command is followed by a + comma separated list of symbols to import. The command is similar to <tt> + <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always + written to the generated object file, even if the symbol is never referenced + (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import + references for unused symbols). + + Example: + + <tscreen><verb> + .forceimport needthisone, needthistoo + </verb></tscreen> + + See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> + + +<sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p> + + Declare symbols as global. Must be followed by a comma separated list of + symbols to declare. Symbols from the list, that are defined somewhere in the + source, are exported, all others are imported. Additional <tt><ref + id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT" + name=".EXPORT"></tt> commands for the same symbol are allowed. + + Example: + + <tscreen><verb> + .global foo, bar + </verb></tscreen> + + +<sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p> + + Declare symbols as global. Must be followed by a comma separated list of + symbols to declare. Symbols from the list, that are defined somewhere in the + source, are exported, all others are imported. Additional <tt><ref + id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP" + name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols + in the list are explicitly marked as zero page symbols. + + Example: + + <tscreen><verb> + .globalzp foo, bar + </verb></tscreen> + +<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p> + + Define byte sized data by extracting only the high byte (that is, bits 8-15) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '>' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .lobytes $1234, $2345, $3456, $4567 + .hibytes $fedc, $edcb, $dcba, $cba9 + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + .byte $34, $45, $56, $67 + .byte $fe, $ed, $dc, $cb + </verb></tscreen> + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>, + <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> + + +<sect1><tt>.I16</tt><label id=".I16"><p> + + Valid only in 65816 mode. Switch the index registers to 16 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 16 bit operands for immediate operands. + + See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART" + name=".SMART"></tt> commands. + + +<sect1><tt>.I8</tt><label id=".I8"><p> + + Valid only in 65816 mode. Switch the index registers to 8 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 8 bit operands for immediate operands. + + See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART" + name=".SMART"></tt> commands. + + +<sect1><tt>.IF</tt><label id=".IF"><p> + + Conditional assembly: Evaluate an expression and switch assembler output + on or off depending on the expression. The expression must be a constant + expression, that is, all operands must be defined. + + A expression value of zero evaluates to FALSE, any other value evaluates + to TRUE. + + +<sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p> + + Conditional assembly: Check if there are any remaining tokens in this line, + and evaluate to FALSE if this is the case, and to TRUE otherwise. If the + condition is not true, further lines are not assembled until an <tt><ref + id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or + <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. + + This command is often used to check if a macro parameter was given. Since an + empty macro parameter will evaluate to nothing, the condition will evaluate + to TRUE if an empty parameter was given. + + Example: + + <tscreen><verb> + .macro arg1, arg2 + .ifblank arg2 + lda #arg1 + .else + lda #arg2 + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".BLANK" name=".BLANK"></tt> + + +<sect1><tt>.IFCONST</tt><label id=".IFCONST"><p> + + Conditional assembly: Evaluate an expression and switch assembler output + on or off depending on the constness of the expression. + + A const expression evaluates to to TRUE, a non const expression (one + containing an imported or currently undefined symbol) evaluates to + FALSE. + + See also: <tt><ref id=".CONST" name=".CONST"></tt> + + +<sect1><tt>.IFDEF</tt><label id=".IFDEF"><p> + + Conditional assembly: Check if a symbol is defined. Must be followed by + a symbol name. The condition is true if the the given symbol is already + defined, and false otherwise. + + See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p> + + Conditional assembly: Check if there are any remaining tokens in this line, + and evaluate to TRUE if this is the case, and to FALSE otherwise. If the + condition is not true, further lines are not assembled until an <tt><ref + id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or + <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. + + This command is often used to check if a macro parameter was given. + Since an empty macro parameter will evaluate to nothing, the condition + will evaluate to FALSE if an empty parameter was given. + + Example: + + <tscreen><verb> + .macro arg1, arg2 + lda #arg1 + .ifnblank arg2 + lda #arg2 + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".BLANK" name=".BLANK"></tt> + + +<sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p> + + Conditional assembly: Check if a symbol is defined. Must be followed by + a symbol name. The condition is true if the the given symbol is not + defined, and false otherwise. + + See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.IFNREF</tt><label id=".IFNREF"><p> + + Conditional assembly: Check if a symbol is referenced. Must be followed + by a symbol name. The condition is true if if the the given symbol was + not referenced before, and false otherwise. + + See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> + + +<sect1><tt>.IFP02</tt><label id=".IFP02"><p> + + Conditional assembly: Check if the assembler is currently in 6502 mode + (see <tt><ref id=".P02" name=".P02"></tt> command). + + +<sect1><tt>.IFP816</tt><label id=".IFP816"><p> + + Conditional assembly: Check if the assembler is currently in 65816 mode + (see <tt><ref id=".P816" name=".P816"></tt> command). + + +<sect1><tt>.IFPC02</tt><label id=".IFPC02"><p> + + Conditional assembly: Check if the assembler is currently in 65C02 mode + (see <tt><ref id=".PC02" name=".PC02"></tt> command). + + +<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p> + + Conditional assembly: Check if the assembler is currently in 65SC02 mode + (see <tt><ref id=".PSC02" name=".PSC02"></tt> command). + + +<sect1><tt>.IFREF</tt><label id=".IFREF"><p> + + Conditional assembly: Check if a symbol is referenced. Must be followed + by a symbol name. The condition is true if if the the given symbol was + referenced before, and false otherwise. + + This command may be used to build subroutine libraries in include files + (you may use separate object modules for this purpose too). + + Example: + + <tscreen><verb> + .ifref ToHex ; If someone used this subroutine + ToHex: tay ; Define subroutine + lda HexTab,y + rts + .endif + </verb></tscreen> + + See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> + + +<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p> + + Import a symbol from another module. The command is followed by a comma + separated list of symbols to import, with each one optionally followed by + an address specification. + + Example: + + <tscreen><verb> + .import foo + .import bar: zeropage + </verb></tscreen> + + See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt> + + +<sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p> + + Import a symbol from another module. The command is followed by a comma + separated list of symbols to import. The symbols are explicitly imported + as zero page symbols (that is, symbols with values in byte range). + + Example: + + <tscreen><verb> + .importzp foo, bar + </verb></tscreen> + + See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> + + +<sect1><tt>.INCBIN</tt><label id=".INCBIN"><p> + + Include a file as binary data. The command expects a string argument + that is the name of a file to include literally in the current segment. + In addition to that, a start offset and a size value may be specified, + separated by commas. If no size is specified, all of the file from the + start offset to end-of-file is used. If no start position is specified + either, zero is assumed (which means that the whole file is inserted). + + Example: + + <tscreen><verb> + ; Include whole file + .incbin "sprites.dat" + + ; Include file starting at offset 256 + .incbin "music.dat", $100 + + ; Read 100 bytes starting at offset 200 + .incbin "graphics.dat", 200, 100 + </verb></tscreen> + + +<sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p> + + Include another file. Include files may be nested up to a depth of 16. + + Example: + + <tscreen><verb> + .include "subs.inc" + </verb></tscreen> + + +<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p> + + Export a symbol and mark it as an interruptor. This may be used together + with the linker to build a table of interruptor subroutines that are called + in an interrupt. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + interruptor does nothing by itself. + + An interruptor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.interruptor/. It may have an optional priority that is separated by a + comma. Higher numeric values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module constructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .interruptor IrqHandler + .interruptor Handler, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate + section <ref id="condes" name="Module constructors/destructors"> explaining + the feature in more detail. + + +<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p> + + Switch on or off line continuations using the backslash character + before a newline. The option is off by default. + Note: Line continuations do not work in a comment. A backslash at the + end of a comment is treated as part of the comment and does not trigger + line continuation. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .linecont + ; Allow line continuations + + lda \ + #$20 ; This is legal now + </verb></tscreen> + + +<sect1><tt>.LIST</tt><label id=".LIST"><p> + + Enable output to the listing. The command must be followed by a boolean + switch ("on", "off", "+" or "-") and will enable or disable listing + output. + The option has no effect if the listing is not enabled by the command line + switch -l. If -l is used, an internal counter is set to 1. Lines are output + to the listing file, if the counter is greater than zero, and suppressed if + the counter is zero. Each use of <tt/.LIST/ will increment or decrement the + counter. + + Example: + + <tscreen><verb> + .list on ; Enable listing output + </verb></tscreen> + + +<sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p> + + Set, how many bytes are shown in the listing for one source line. The + default is 12, so the listing will show only the first 12 bytes for any + source line that generates more than 12 bytes of code or data. + The directive needs an argument, which is either "unlimited", or an + integer constant in the range 4..255. + + Examples: + + <tscreen><verb> + .listbytes unlimited ; List all bytes + .listbytes 12 ; List the first 12 bytes + .incbin "data.bin" ; Include large binary file + </verb></tscreen> + + +<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p> + + Define byte sized data by extracting only the low byte (that is, bits 0-7) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '<' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .lobytes $1234, $2345, $3456, $4567 + .hibytes $fedc, $edcb, $dcba, $cba9 + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + .byte $34, $45, $56, $67 + .byte $fe, $ed, $dc, $cb + </verb></tscreen> + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, + <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> + + +<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p> + + This command may only be used inside a macro definition. It declares a + list of identifiers as local to the macro expansion. + + A problem when using macros are labels: Since they don't change their name, + you get a "duplicate symbol" error if the macro is expanded the second time. + Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their + name mapped to an internal unique name (<tt/___ABCD__/) with each macro + invocation. + + Some other assemblers start a new lexical block inside a macro expansion. + This has some drawbacks however, since that will not allow <em/any/ symbol + to be visible outside a macro, a feature that is sometimes useful. The + <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way + to address the problem. + + You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside + a macro. + + +<sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p> + + Defines the character that start "cheap" local labels. You may use one + of '@' and '?' as start character. The default is '@'. + + Cheap local labels are labels that are visible only between two non + cheap labels. This way you can reuse identifiers like "<tt/loop/" without + using explicit lexical nesting. + + Example: + + <tscreen><verb> + .localchar '?' + + Clear: lda #$00 ; Global label + ?Loop: sta Mem,y ; Local label + dey + bne ?Loop ; Ok + rts + Sub: ... ; New global label + bne ?Loop ; ERROR: Unknown identifier! + </verb></tscreen> + + +<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p> + + Insert a predefined macro package. The command is followed by an + identifier specifying the macro package to insert. Available macro + packages are: + + <tscreen><verb> + atari Defines the scrcode macro. + cbm Defines the scrcode macro. + cpu Defines constants for the .CPU variable. + generic Defines generic macros like add and sub. + longbranch Defines conditional long jump macros. + </verb></tscreen> + + Including a macro package twice, or including a macro package that + redefines already existing macros will lead to an error. + + Example: + + <tscreen><verb> + .macpack longbranch ; Include macro package + + cmp #$20 ; Set condition codes + jne Label ; Jump long on condition + </verb></tscreen> + + Macro packages are explained in more detail in section <ref + id="macropackages" name="Macro packages">. + + +<sect1><tt>.MAC, .MACRO</tt><label id=".MACRO"><p> + + Start a classic macro definition. The command is followed by an identifier + (the macro name) and optionally by a comma separated list of identifiers + that are macro parameters. A macro definition is terminated by <tt><ref + id=".ENDMACRO" name=".ENDMACRO"></tt>. + + Example: + + <tscreen><verb> + .macro ldax arg ; Define macro ldax + lda arg + ldx arg+1 + </verb></tscreen> + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.ORG</tt><label id=".ORG"><p> + + Start a section of absolute code. The command is followed by a constant + expression that gives the new PC counter location for which the code is + assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to + relocatable code. + + By default, absolute/relocatable mode is global (valid even when switching + segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt> + it can be made segment local. + + Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing + code at a specific address is the job of the linker, not the assembler, so + there is usually no reason to assemble code to a specific address. + + Example: + + <tscreen><verb> + .org $7FF ; Emit code starting at $7FF + </verb></tscreen> + + +<sect1><tt>.OUT</tt><label id=".OUT"><p> + + Output a string to the console without producing an error. This command + is similar to <tt/.ERROR/, however, it does not force an assembler error + that prevents the creation of an object file. + + Example: + + <tscreen><verb> + .out "This code was written by the codebuster(tm)" + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.P02</tt><label id=".P02"><p> + + Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816 + instructions. This is the default if not overridden by the + <tt><ref id="option--cpu" name="--cpu"></tt> command line option. + + See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.P816</tt><label id=".P816"><p> + + Enable the 65816 instruction set. This is a superset of the 65SC02 and + 6502 instruction sets. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt> + + +<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p> + + Set the page length for the listing. Must be followed by an integer + constant. The value may be "unlimited", or in the range 32 to 127. The + statement has no effect if no listing is generated. The default value is -1 + (unlimited) but may be overridden by the <tt/--pagelength/ command line + option. Beware: Since ca65 is a one pass assembler, the listing is generated + after assembly is complete, you cannot use multiple line lengths with one + source. Instead, the value set with the last <tt/.PAGELENGTH/ is used. + + Examples: + + <tscreen><verb> + .pagelength 66 ; Use 66 lines per listing page + + .pagelength unlimited ; Unlimited page length + </verb></tscreen> + + +<sect1><tt>.PC02</tt><label id=".PC02"><p> + + Enable the 65C02 instructions set. This instruction set includes all + 6502 and 65SC02 instructions. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p> + + Pop the last CPU setting from the stack, and activate it. + + This command will switch back to the CPU that was last pushed onto the CPU + stack using the <tt><ref id=".PUSHCPU" name=".PUSHCPU"></tt> command, and + remove this entry from the stack. + + The assembler will print an error message if the CPU stack is empty when + this command is issued. + + See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".PUSHCPU" + name=".PUSHCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> + + +<sect1><tt>.POPSEG</tt><label id=".POPSEG"><p> + + Pop the last pushed segment from the stack, and set it. + + This command will switch back to the segment that was last pushed onto the + segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> + command, and remove this entry from the stack. + + The assembler will print an error message if the segment stack is empty + when this command is issued. + + See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> + + +<sect1><tt>.PROC</tt><label id=".PROC"><p> + + Start a nested lexical level with the given name and adds a symbol with this + name to the enclosing scope. All new symbols from now on are in the local + lexical level and are accessible from outside only via <ref id="scopesyntax" + name="explicit scope specification">. Symbols defined outside this local + level may be accessed as long as their names are not used for new symbols + inside the level. Symbols names in other lexical levels do not clash, so you + may use the same names for identifiers. The lexical level ends when the + <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels + may be nested up to a depth of 16 (this is an artificial limit to protect + against errors in the source). + + Note: Macro names are always in the global level and in a separate name + space. There is no special reason for this, it's just that I've never + had any need for local macro definitions. + + Example: + + <tscreen><verb> + .proc Clear ; Define Clear subroutine, start new level + lda #$00 + L1: sta Mem,y ; L1 is local and does not cause a + ; duplicate symbol error if used in other + ; places + dey + bne L1 ; Reference local symbol + rts + .endproc ; Leave lexical level + </verb></tscreen> + + See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE" + name=".SCOPE">/ + + +<sect1><tt>.PSC02</tt><label id=".PSC02"><p> + + Enable the 65SC02 instructions set. This instruction set includes all + 6502 instructions. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02" + name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p> + + Push the currently active CPU onto a stack. The stack has a size of 8 + entries. + + <tt/.PUSHCPU/ allows together with <tt><ref id=".POPCPU" + name=".POPCPU"></tt> to switch to another CPU and to restore the old CPU + later, without knowledge of the current CPU setting. + + The assembler will print an error message if the CPU stack is already full, + when this command is issued. + + See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".POPCPU" + name=".POPCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> + + +<sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p> + + Push the currently active segment onto a stack. The entries on the stack + include the name of the segment and the segment type. The stack has a size + of 16 entries. + + <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt> + to switch to another segment and to restore the old segment later, without + even knowing the name and type of the current segment. + + The assembler will print an error message if the segment stack is already + full, when this command is issued. + + See: <tt><ref id=".POPSEG" name=".POPSEG"></tt> + + +<sect1><tt>.RELOC</tt><label id=".RELOC"><p> + + Switch back to relocatable mode. See the <tt><ref id=".ORG" + name=".ORG"></tt> command. + + +<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p> + + Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT" + name=".ENDREPEAT"></tt> constant number of times. The command is followed by + a constant expression that tells how many times the commands in the body + should get repeated. Optionally, a comma and an identifier may be specified. + If this identifier is found in the body of the repeat statement, it is + replaced by the current repeat count (starting with zero for the first time + the body is repeated). + + <tt/.REPEAT/ statements may be nested. If you use the same repeat count + identifier for a nested <tt/.REPEAT/ statement, the one from the inner + level will be used, not the one from the outer level. + + Example: + + The following macro will emit a string that is "encrypted" in that all + characters of the string are XORed by the value $55. + + <tscreen><verb> + .macro Crypt Arg + .repeat .strlen(Arg), I + .byte .strat(Arg, I) ^ $55 + .endrep + .endmacro + </verb></tscreen> + + See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt> + + +<sect1><tt>.RES</tt><label id=".RES"><p> + + Reserve storage. The command is followed by one or two constant + expressions. The first one is mandatory and defines, how many bytes of + storage should be defined. The second, optional expression must by a + constant byte value that will be used as value of the data. If there + is no fill value given, the linker will use the value defined in the + linker configuration file (default: zero). + + Example: + + <tscreen><verb> + ; Reserve 12 bytes of memory with value $AA + .res 12, $AA + </verb></tscreen> + + +<sect1><tt>.RODATA</tt><label id=".RODATA"><p> + + Switch to the RODATA segment. The name of the RODATA segment is always + "RODATA", so this is a shortcut for + + <tscreen><verb> + .segment "RODATA" + </verb></tscreen> + + The RODATA segment is a segment that is used by the compiler for + readonly data like string constants. + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p> + + Start a nested lexical level with the given name. All new symbols from now + on are in the local lexical level and are accessible from outside only via + <ref id="scopesyntax" name="explicit scope specification">. Symbols defined + outside this local level may be accessed as long as their names are not used + for new symbols inside the level. Symbols names in other lexical levels do + not clash, so you may use the same names for identifiers. The lexical level + ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is + read. Lexical levels may be nested up to a depth of 16 (this is an + artificial limit to protect against errors in the source). + + Note: Macro names are always in the global level and in a separate name + space. There is no special reason for this, it's just that I've never + had any need for local macro definitions. + + Example: + + <tscreen><verb> + .scope Error ; Start new scope named Error + None = 0 ; No error + File = 1 ; File error + Parse = 2 ; Parse error + .endscope ; Close lexical level + + ... + lda #Error::File ; Use symbol from scope Error + </verb></tscreen> + + See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC" + name=".PROC">/ + + +<sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p> + + Switch to another segment. Code and data is always emitted into a + segment, that is, a named section of data. The default segment is + "CODE". There may be up to 254 different segments per object file + (and up to 65534 per executable). There are shortcut commands for + the most common segments ("CODE", "DATA" and "BSS"). + + The command is followed by a string containing the segment name (there are + some constraints for the name - as a rule of thumb use only those segment + names that would also be valid identifiers). There may also be an optional + address size separated by a colon. See the section covering <tt/<ref + id="address-sizes" name="address sizes">/ for more information. + + The default address size for a segment depends on the memory model specified + on the command line. The default is "absolute", which means that you don't + have to use an address size modifier in most cases. + + "absolute" means that the is a segment with 16 bit (absolute) addressing. + That is, the segment will reside somewhere in core memory outside the zero + page. "zeropage" (8 bit) means that the segment will be placed in the zero + page and direct (short) addressing is possible for data in this segment. + + Beware: Only labels in a segment with the zeropage attribute are marked + as reachable by short addressing. The `*' (PC counter) operator will + work as in other segments and will create absolute variable values. + + Please note that a segment cannot have two different address sizes. A + segment specified as zeropage cannot be declared as being absolute later. + + Examples: + + <tscreen><verb> + .segment "ROM2" ; Switch to ROM2 segment + .segment "ZP2": zeropage ; New direct segment + .segment "ZP2" ; Ok, will use last attribute + .segment "ZP2": absolute ; Error, redecl mismatch + </verb></tscreen> + + See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE" + name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref + id=".RODATA" name=".RODATA"></tt> + + +<sect1><tt>.SET</tt><label id=".SET"><p> + + <tt/.SET/ is used to assign a value to a variable. See <ref id="variables" + name="Numeric variables"> for a full description. + + +<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p> + + Switch the CPU instruction set. The command is followed by a string that + specifies the CPU. Possible values are those that can also be supplied to + the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, + namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please + note that support for the sunplus CPU is not available in the freeware + version, because the instruction set of the sunplus CPU is "proprietary + and confidential". + + See: <tt><ref id=".CPU" name=".CPU"></tt>, + <tt><ref id=".IFP02" name=".IFP02"></tt>, + <tt><ref id=".IFP816" name=".IFP816"></tt>, + <tt><ref id=".IFPC02" name=".IFPC02"></tt>, + <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>, + <tt><ref id=".P02" name=".P02"></tt>, + <tt><ref id=".P816" name=".P816"></tt>, + <tt><ref id=".PC02" name=".PC02"></tt>, + <tt><ref id=".PSC02" name=".PSC02"></tt> + + +<sect1><tt>.SMART</tt><label id=".SMART"><p> + + Switch on or off smart mode. The command must be followed by a '+' or '-' + character to switch the option on or off respectively. The default is off + (that is, the assembler doesn't try to be smart), but this default may be + changed by the -s switch on the command line. + + In smart mode the assembler will do the following: + + <itemize> + <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode + and update the operand sizes accordingly. If the operand of such an + instruction cannot be evaluated by the assembler (for example, because + the operand is an imported symbol), a warning is issued. Beware: Since + the assembler cannot trace the execution flow this may lead to false + results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/ + instructions to tell the assembler about the current settings. + <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is + used within a procedure declared as <tt/far/, or if the procedure has + no explicit address specification, but it is <tt/far/ because of the + memory model used. + </itemize> + + Example: + + <tscreen><verb> + .smart ; Be smart + .smart - ; Stop being smart + </verb></tscreen> + + See: <tt><ref id=".A16" name=".A16"></tt>, + <tt><ref id=".A8" name=".A8"></tt>, + <tt><ref id=".I16" name=".I16"></tt>, + <tt><ref id=".I8" name=".I8"></tt> + + +<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p> + + Starts a struct definition. Structs are covered in a separate section named + <ref id="structs" name=""Structs and unions"">. + + See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, + <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, + <tt><ref id=".UNION" name=".UNION"></tt> + + +<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p> + + Enable the SunPlus instructions set. This command will not work in the + freeware version of the assembler, because the instruction set is + "proprietary and confidential". + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and + <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.TAG</tt><label id=".TAG"><p> + + Allocate space for a struct or union. + + Example: + + <tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct + + .bss + .tag Point ; Allocate 4 bytes + </verb></tscreen> + + +<sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p> + + Delete a define style macro definition. The command is followed by an + identifier which specifies the name of the macro to delete. Macro + replacement is switched of when reading the token following the command + (otherwise the macro name would be replaced by its replacement list). + + See also the <tt><ref id=".DEFINE" name=".DEFINE"></tt> command and + section <ref id="macros" name="Macros">. + + +<sect1><tt>.UNION</tt><label id=".UNION"><p> + + Starts a union definition. Unions are covered in a separate section named + <ref id="structs" name=""Structs and unions"">. + + See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, + <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, + <tt><ref id=".STRUCT" name=".STRUCT"></tt> + + +<sect1><tt>.WARNING</tt><label id=".WARNING"><p> + + Force an assembly warning. The assembler will output a warning message + preceded by "User warning". This warning will always be output, even if + other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt> + command line option. + + This command may be used to output possible problems when assembling + the source file. + + Example: + + <tscreen><verb> + .macro jne target + .local L1 + .ifndef target + .warning "Forward jump in jne, cannot optimize!" + beq L1 + jmp target + L1: + .else + ... + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt> + + +<sect1><tt>.WORD</tt><label id=".WORD"><p> + + Define word sized data. Must be followed by a sequence of (word ranged, + but not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .word $0D00, $AF13, _Clear + </verb></tscreen> + + +<sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p> + + Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment. + The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a + shortcut for + + <tscreen><verb> + .segment "ZEROPAGE", zeropage + </verb></tscreen> + + Because of the "zeropage" attribute, labels declared in this segment are + addressed using direct addressing mode if possible. You <em/must/ instruct + the linker to place this segment somewhere in the address range 0..$FF + otherwise you will get errors. + + See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> + + + +<sect>Macros<label id="macros"><p> + + +<sect1>Introduction<p> + +Macros may be thought of as "parametrized super instructions". Macros are +sequences of tokens that have a name. If that name is used in the source +file, the macro is "expanded", that is, it is replaced by the tokens that +were specified when the macro was defined. + + +<sect1>Macros without parameters<p> + +In its simplest form, a macro does not have parameters. Here's an +example: + +<tscreen><verb> + .macro asr ; Arithmetic shift right + cmp #$80 ; Put bit 7 into carry + ror ; Rotate right with carry + .endmacro +</verb></tscreen> + +The macro above consists of two real instructions, that are inserted into +the code, whenever the macro is expanded. Macro expansion is simply done +by using the name, like this: + +<tscreen><verb> + lda $2010 + asr + sta $2010 +</verb></tscreen> + + +<sect1>Parametrized macros<p> + +When using macro parameters, macros can be even more useful: + +<tscreen><verb> + .macro inc16 addr + clc + lda addr + adc #$01 + sta addr + lda addr+1 + adc #$00 + sta addr+1 + .endmacro +</verb></tscreen> + +When calling the macro, you may give a parameter, and each occurrence of +the name "addr" in the macro definition will be replaced by the given +parameter. So + +<tscreen><verb> + inc16 $1000 +</verb></tscreen> + +will be expanded to + +<tscreen><verb> + clc + lda $1000 + adc #$01 + sta $1000 + lda $1000+1 + adc #$00 + sta $1000+1 +</verb></tscreen> + +A macro may have more than one parameter, in this case, the parameters +are separated by commas. You are free to give less parameters than the +macro actually takes in the definition. You may also leave intermediate +parameters empty. Empty parameters are replaced by empty space (that is, +they are removed when the macro is expanded). If you have a look at our +macro definition above, you will see, that replacing the "addr" parameter +by nothing will lead to wrong code in most lines. To help you, writing +macros with a variable parameter list, there are some control commands: + +<tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and +returns true, if there are any tokens on the remainder of the line. Since +empty parameters are replaced by nothing, this may be used to test if a given +parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the +opposite. + +Look at this example: + +<tscreen><verb> + .macro ldaxy a, x, y + .ifnblank a + lda #a + .endif + .ifnblank x + ldx #x + .endif + .ifnblank y + ldy #y + .endif + .endmacro +</verb></tscreen> + +This macro may be called as follows: + +<tscreen><verb> + ldaxy 1, 2, 3 ; Load all three registers + + ldaxy 1, , 3 ; Load only a and y + + ldaxy , , 3 ; Load y only +</verb></tscreen> + +There's another helper command for determining, which macro parameters are +valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is +replaced by the parameter count given, <em/including/ intermediate empty macro +parameters: + +<tscreen><verb> + ldaxy 1 ; .PARAMCOUNT = 1 + ldaxy 1,,3 ; .PARAMCOUNT = 3 + ldaxy 1,2 ; .PARAMCOUNT = 2 + ldaxy 1, ; .PARAMCOUNT = 2 + ldaxy 1,2,3 ; .PARAMCOUNT = 3 +</verb></tscreen> + +Macro parameters may optionally be enclosed into curly braces. This allows the +inclusion of tokens that would otherwise terminate the parameter (the comma in +case of a macro parameter). + +<tscreen><verb> + .macro foo arg1, arg2 + ... + .endmacro + + foo ($00,x) ; Two parameters passed + foo {($00,x)} ; One parameter passed +</verb></tscreen> + +In the first case, the macro is called with two parameters: '<tt/($00/' +and 'x)'. The comma is not passed to the macro, since it is part of the +calling sequence, not the parameters. + +In the second case, '($00,x)' is passed to the macro, this time +including the comma. + + +<sect1>Detecting parameter types<p> + +Sometimes it is nice to write a macro that acts differently depending on the +type of the argument supplied. An example would be a macro that loads a 16 bit +value from either an immediate operand, or from memory. The <tt/<ref +id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/ +functions will allow you to do exactly this: + +<tscreen><verb> + .macro ldax arg + .if (.match (.left (1, {arg}), #)) + ; immediate mode + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ; assume absolute or zero page + lda arg + ldx 1+(arg) + .endif + .endmacro +</verb></tscreen> + +Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to +check if its argument begins with a hash mark. If so, two immediate loads are +emitted, Otherwise a load from an absolute zero page memory location is +assumed. Please note how the curly braces are used to enclose parameters to +pseudo functions handling token lists. This is necessary, because the token +lists may include commas or parens, which would be treated by the assembler +as end-of-list. + +The macro can be used as + +<tscreen><verb> + foo: .word $5678 + ... + ldax #$1234 ; X=$12, A=$34 + ... + ldax foo ; X=$56, A=$78 +</verb></tscreen> + + +<sect1>Recursive macros<p> + +Macros may be used recursively: + +<tscreen><verb> + .macro push r1, r2, r3 + lda r1 + pha + .if .paramcount > 1 + push r2, r3 + .endif + .endmacro +</verb></tscreen> + +There's also a special macro to help writing recursive macros: <tt><ref +id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion +immediately: + +<tscreen><verb> + .macro push r1, r2, r3, r4, r5, r6, r7 + .ifblank r1 + ; First parameter is empty + .exitmacro + .else + lda r1 + pha + .endif + push r2, r3, r4, r5, r6, r7 + .endmacro +</verb></tscreen> + +When expanding this macro, the expansion will push all given parameters +until an empty one is encountered. The macro may be called like this: + +<tscreen><verb> + push $20, $21, $32 ; Push 3 ZP locations + push $21 ; Push one ZP location +</verb></tscreen> + + +<sect1>Local symbols inside macros<p> + +Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and +<tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need? +Have a look at the inc16 macro above. Here is it again: + +<tscreen><verb> + .macro inc16 addr + clc + lda addr + adc #$01 + sta addr + lda addr+1 + adc #$00 + sta addr+1 + .endmacro +</verb></tscreen> + +If you have a closer look at the code, you will notice, that it could be +written more efficiently, like this: + +<tscreen><verb> + .macro inc16 addr + inc addr + bne Skip + inc addr+1 + Skip: + .endmacro +</verb></tscreen> + +But imagine what happens, if you use this macro twice? Since the label "Skip" +has the same name both times, you get a "duplicate symbol" error. Without a +way to circumvent this problem, macros are not as useful, as they could be. +One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>. +It declares one or more symbols as local to the macro expansion. The names of +local variables are replaced by a unique name in each separate macro +expansion. So we can solve the problem above by using <tt/.LOCAL/: + +<tscreen><verb> + .macro inc16 addr + .local Skip ; Make Skip a local symbol + inc addr + bne Skip + inc addr+1 + Skip: ; Not visible outside + .endmacro +</verb></tscreen> + +Another solution is of course to start a new lexical block inside the macro +that hides any labels: + +<tscreen><verb> + .macro inc16 addr + .proc + inc addr + bne Skip + inc addr+1 + Skip: + .endproc + .endmacro +</verb></tscreen> + + +<sect1>C style macros<p> + +Starting with version 2.5 of the assembler, there is a second macro type +available: C style macros using the <tt/.DEFINE/ directive. These macros are +similar to the classic macro type described above, but behaviour is sometimes +different: + +<itemize> + +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not + span more than a line. You may use line continuation (see <tt><ref + id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over + more than one line for increased readability, but the macro itself + may not contain an end-of-line token. + +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share + the name space with classic macros, but they are detected and replaced + at the scanner level. While classic macros may be used in every place, + where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" + name=".DEFINE"></tt> style macros are allowed anywhere in a line. So + they are more versatile in some situations. + +<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take + parameters. While classic macros may have empty parameters, this is + not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. + For this macro type, the number of actual parameters must match + exactly the number of formal parameters. + + To make this possible, formal parameters are enclosed in braces when + defining the macro. If there are no parameters, the empty braces may + be omitted. + +<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not + contain end-of-line tokens, there are things that cannot be done. They + may not contain several processor instructions for example. So, while + some things may be done with both macro types, each type has special + usages. The types complement each other. + +</itemize> + +Let's look at a few examples to make the advantages and disadvantages +clear. + +To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the +following <tt/.DEFINE/: + +<tscreen><verb> + .define EQU = + + foo EQU $1234 ; This is accepted now +</verb></tscreen> + +You may use the directive to define string constants used elsewhere: + +<tscreen><verb> + ; Define the version number + .define VERSION "12.3a" + + ; ... and use it + .asciiz VERSION +</verb></tscreen> + +Macros with parameters may also be useful: + +<tscreen><verb> + .define DEBUG(message) .out message + + DEBUG "Assembling include file #3" +</verb></tscreen> + +Note that, while formal parameters have to be placed in braces, this is +not true for the actual parameters. Beware: Since the assembler cannot +detect the end of one parameter, only the first token is used. If you +don't like that, use classic macros instead: + +<tscreen><verb> + .macro DEBUG message + .out message + .endmacro +</verb></tscreen> + +(This is an example where a problem can be solved with both macro types). + + +<sect1>Characters in macros<p> + +When using the <ref id="option-t" name="-t"> option, characters are translated +into the target character set of the specific machine. However, this happens +as late as possible. This means that strings are translated if they are part +of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ" +name=".ASCIIZ"></tt> command. Characters are translated as soon as they are +used as part of an expression. + +This behaviour is very intuitive outside of macros but may be confusing when +doing more complex macros. If you compare characters against numeric values, +be sure to take the translation into account. + + +<sect1>Deleting macros<p> + +Macros can be deleted. This will not work if the macro that should be deleted +is currently expanded as in the following non working example: + +<tscreen><verb> + .macro notworking + .delmacro notworking + .endmacro + + notworking ; Will not work +</verb></tscreen> + +The commands to delete classic and define style macros differ. Classic macros +can be deleted by use of <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, while +for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref +id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example: + +<tscreen><verb> + .define value 1 + .macro mac + .byte 2 + .endmacro + + .byte value ; Emit one byte with value 1 + mac ; Emit another byte with value 2 + + .undefine value + .delmacro mac + + .byte value ; Error: Unknown identifier + mac ; Error: Missing ":" +</verb></tscreen> + +A separate command for <tt>.DEFINE</tt> style macros was necessary, because +the name of such a macro is replaced by its replacement list on a very low +level. To get the actual name, macro replacement has to be switched off when +reading the argument to <tt>.UNDEFINE</tt>. This does also mean that the +argument to <tt>.UNDEFINE</tt> is not allowed to come from another +<tt>.DEFINE</tt>. All this is not necessary for classic macros, so having two +different commands increases flexibility. + + +<sect>Macro packages<label id="macropackages"><p> + +Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined +macro packages may be included with just one command. Available macro packages +are: + + +<sect1><tt>.MACPACK generic</tt><p> + +This macro package defines macros that are useful in almost any program. +Currently defined macros are: + +<tscreen><verb> + .macro add Arg + clc + adc Arg + .endmacro + + .macro sub Arg + sec + sbc Arg + .endmacro + + .macro bge Arg + bcs Arg + .endmacro + + .macro blt Arg + bcc Arg + .endmacro + + .macro bgt Arg + .local L + beq L + bcs Arg + L: + .endmacro + + .macro ble Arg + beq Arg + bcc Arg + .endmacro +</verb></tscreen> + + +<sect1><tt>.MACPACK longbranch</tt><p> + +This macro package defines long conditional jumps. They are named like the +short counterpart but with the 'b' replaced by a 'j'. Here is a sample +definition for the "<tt/jeq/" macro, the other macros are built using the same +scheme: + +<tscreen><verb> + .macro jeq Target + .if .def(Target) .and ((*+2)-(Target) <= 127) + beq Target + .else + bne *+5 + jmp Target + .endif + .endmacro +</verb></tscreen> + +All macros expand to a short branch, if the label is already defined (back +jump) and is reachable with a short jump. Otherwise the macro expands to a +conditional branch with the branch condition inverted, followed by an absolute +jump to the actual branch target. + +The package defines the following macros: + +<tscreen><verb> + jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc +</verb></tscreen> + + + +<sect1><tt>.MACPACK atari</tt><p> + +The atari macro package will define a macro named <tt/scrcode/. It takes a +string as argument and places this string into memory translated into screen +codes. + + +<sect1><tt>.MACPACK cbm</tt><p> + +The cbm macro package will define a macro named <tt/scrcode/. It takes a +string as argument and places this string into memory translated into screen +codes. + + +<sect1><tt>.MACPACK cpu</tt><p> + +This macro package does not define any macros but constants used to examine +the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For +each supported CPU a constant similar to + +<tscreen><verb> + CPU_6502 + CPU_65SC02 + CPU_65C02 + CPU_65816 + CPU_SUNPLUS + CPU_SWEET16 + CPU_HUC6280 +</verb></tscreen> + +is defined. These constants may be used to determine the exact type of the +currently enabled CPU. In addition to that, for each CPU instruction set, +another constant is defined: + +<tscreen><verb> + CPU_ISET_6502 + CPU_ISET_65SC02 + CPU_ISET_65C02 + CPU_ISET_65816 + CPU_ISET_SUNPLUS + CPU_ISET_SWEET16 + CPU_ISET_HUC6280 +</verb></tscreen> + +The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may +be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the +currently enabled CPU supports a specific instruction set. For example the +65C02 supports all instructions of the 65SC02 CPU, so it has the +<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/ +bit. Using + +<tscreen><verb> + .if (.cpu .bitand CPU_ISET_65SC02) + lda (sp) + .else + ldy #$00 + lda (sp),y + .endif +</verb></tscreen> + +it is possible to determine if the + +<tscreen><verb> + lda (sp) +</verb></tscreen> + +instruction is supported, which is the case for the 65SC02, 65C02 and 65816 +CPUs (the latter two are upwards compatible to the 65SC02). + + + +<sect>Predefined constants<label id="predefined-constants"><p> + +For better orthogonality, the assembler defines similar symbols as the +compiler, depending on the target system selected: + +<itemize> +<item><tt/__APPLE2__/ - Target system is <tt/apple2/ +<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ +<item><tt/__ATARI__/ - Target system is <tt/atari/ +<item><tt/__ATMOS__/ - Target system is <tt/atmos/ +<item><tt/__BBC__/ - Target system is <tt/bbc/ +<item><tt/__C128__/ - Target system is <tt/c128/ +<item><tt/__C16__/ - Target system is <tt/c16/ +<item><tt/__C64__/ - Target system is <tt/c64/ +<item><tt/__CBM__/ - Target is a Commodore system +<item><tt/__CBM510__/ - Target system is <tt/cbm510/ +<item><tt/__CBM610__/ - Target system is <tt/cbm610/ +<item><tt/__GEOS__/ - Target system is <tt/geos/ +<item><tt/__LUNIX__/ - Target system is <tt/lunix/ +<item><tt/__NES__/ - Target system is <tt/nes/ +<item><tt/__PET__/ - Target system is <tt/pet/ +<item><tt/__PLUS4__/ - Target system is <tt/plus4/ +<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/ +<item><tt/__VIC20__/ - Target system is <tt/vic20/ +</itemize> + + +<sect>Structs and unions<label id="structs"><p> + +<sect1>Structs and unions Overview<p> + +Structs and unions are special forms of <ref id="scopes" name="scopes">. They +are to some degree comparable to their C counterparts. Both have a list of +members. Each member allocates storage and may optionally have a name, which, +in case of a struct, is the offset from the beginning and, in case of a union, +is always zero. + + +<sect1>Declaration<p> + +Here is an example for a very simple struct with two members and a total size +of 4 bytes: + +<tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct +</verb></tscreen> + +A union shares the total space between all its members, its size is the same +as that of the largest member. The offset of all members relative to the union +is zero. + +<tscreen><verb> + .union Entry + index .word + ptr .addr + .endunion +</verb></tscreen> + +A struct or union must not necessarily have a name. If it is anonymous, no +local scope is opened, the identifiers used to name the members are placed +into the current scope instead. + +A struct may contain unnamed members and definitions of local structs. The +storage allocators may contain a multiplier, as in the example below: + +<tscreen><verb> + .struct Circle + .struct Point + .word 2 ; Allocate two words + .endstruct + Radius .word + .endstruct +</verb></tscreen> + + +<sect1>The <tt/.TAG/ keyword<p> + +Using the <ref id=".TAG" name=".TAG"> keyword, it is possible to reserve space +for an already defined struct or unions within another struct: + +<tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct + + .struct Circle + Origin .tag Point + Radius .byte + .endstruct +</verb></tscreen> + +Space for a struct or union may be allocated using the <ref id=".TAG" +name=".TAG"> directive. + +<tscreen><verb> + C: .tag Circle +</verb></tscreen> + +Currently, members are just offsets from the start of the struct or union. To +access a field of a struct, the member offset has to be added to the address +of the struct itself: + +<tscreen><verb> + lda C+Circle::Radius ; Load circle radius into A +</verb></tscreen> + +This may change in a future version of the assembler. + + +<sect1>Limitations<p> + +Structs and unions are currently implemented as nested symbol tables (in fact, +they were a by-product of the improved scoping rules). Currently, the +assembler has no idea of types. This means that the <ref id=".TAG" +name=".TAG"> keyword will only allocate space. You won't be able to initialize +variables declared with <ref id=".TAG" name=".TAG">, and adding an embedded +structure to another structure with <ref id=".TAG" name=".TAG"> will not make +this structure accessible by using the '::' operator. + + + +<sect>Module constructors/destructors<label id="condes"><p> + +<em>Note:</em> This section applies mostly to C programs, so the explanation +below uses examples from the C libraries. However, the feature may also be +useful for assembler programs. + + +<sect1>Module constructors/destructors Overview<p> + +Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref +id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" +name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a +special way. The linker is able to generate tables with all functions of a +specific type. Such a table will <em>only</em> include symbols from object +files that are linked into a specific executable. This may be used to add +initialization and cleanup code for library modules, or a table of interrupt +handler functions. + +The C heap functions are an example where module initialization code is used. +All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few +variables that contain the start and the end of the heap, pointers to the free +list and so on. Since the end of the heap depends on the size and start of the +stack, it must be initialized at runtime. However, initializing these +variables for programs that do not use the heap are a waste of time and +memory. + +So the central module defines a function that contains initialization code and +exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if) +this module is added to an executable by the linker, the initialization +function will be placed into the table of constructors by the linker. The C +startup code will call all constructors before <tt/main/ and all destructors +after <tt/main/, so without any further work, the heap initialization code is +called once the module is linked in. + +While it would be possible to add explicit calls to initialization functions +in the startup code, the new approach has several advantages: + +<enum> +<item> +If a module is not included, the initialization code is not linked in and not +called. So you don't pay for things you don't need. + +<item> +Adding another library that needs initialization does not mean that the +startup code has to be changed. Before we had module constructors and +destructors, the startup code for all systems had to be adjusted to call the +new initialization code. + +<item> +The feature saves memory: Each additional initialization function needs just +two bytes in the table (a pointer to the function). + +</enum> + + +<sect1>Calling order<p> + +The symbols are sorted in increasing priority order by the linker when using +one of the builtin linker configurations, so the functions with lower +priorities come first and are followed by those with higher priorities. The C +library runtime subroutine that walks over the function tables calls the +functions starting from the top of the table - which means that functions with +a high priority are called first. + +So when using the C runtime, functions are called with high priority functions +first, followed by low priority functions. + + +<sect1>Pitfalls<p> + +When using these special symbols, please take care of the following: + +<itemize> + +<item> +The linker will only generate function tables, it will not generate code to +call these functions. If you're using the feature in some other than the +existing C environments, you have to write code to call all functions in a +linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules +in the C runtime for an example on how to do this. + +<item> +The linker will only add addresses of functions that are in modules linked to +the executable. This means that you have to be careful where to place the +condes functions. If initialization or an irq handler is needed for a group of +functions, be sure to place the function into a module that is linked in +regardless of which function is called by the user. + +<item> +The linker will generate the tables only when requested to do so by the +<tt/FEATURE CONDES/ statement in the linker config file. Each table has to +be requested separately. + +<item> +Constructors and destructors may have priorities. These priorities determine +the order of the functions in the table. If your initialization or cleanup code +does depend on other initialization or cleanup code, you have to choose the +priority for the functions accordingly. + +<item> +Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref +id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" +name=".INTERRUPTOR"></tt> statements, there is also a more generic command: +<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an +additional type. Predefined types are 0 (constructor), 1 (destructor) and 2 +(interruptor). The linker generates a separate table for each type on request. + +</itemize> + + +<sect>Porting sources from other assemblers<p> + +Sometimes it is necessary to port code written for older assemblers to ca65. +In some cases, this can be done without any changes to the source code by +using the emulation features of ca65 (see <tt><ref id=".FEATURE" +name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the +source code. + +Probably the biggest difference is the handling of the <tt><ref id=".ORG" +name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is +done by the linker. Most other assemblers generate absolute code, placement is +done within the assembler and there is no external linker. + +In general it is not a good idea to write new code using the emulation +features of the assembler, but there may be situations where even this rule is +not valid. + +<sect1>TASS<p> + +You need to use some of the ca65 emulation features to simulate the behaviour +of such simple assemblers. + +<enum> +<item>Prepare your sourcecode like this: + +<tscreen><verb> + ; if you want TASS style labels without colons + .feature labels_without_colons + + ; if you want TASS style character constants + ; ("a" instead of the default 'a') + .feature loose_char_term + + .word *+2 ; the cbm load address + + [yourcode here] +</verb></tscreen> + +notice that the two emulation features are mostly useful for porting +sources originally written in/for TASS, they are not needed for the +actual "simple assembler operation" and are not recommended if you are +writing new code from scratch. + +<item>Replace all program counter assignments (which are not possible in ca65 +by default, and the respective emulation feature works different from what +you'd expect) by another way to skip to memory locations, for example the +<tt><ref id=".RES" name=".RES"></tt> directive. + +<tscreen><verb> + ; *=$2000 + .res $2000-* ; reserve memory up to $2000 +</verb></tscreen> + +Please note that other than the original TASS, ca65 can never move the program +counter backwards - think of it as if you are assembling to disk with TASS. + +<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be +rewritten to match ca65 syntax. Most importantly notice that due to the lack +of <tt/.goto/, everything involving loops must be replaced by +<tt><ref id=".REPEAT" name=".REPEAT"></tt>. + +<item>To assemble code to a different address than it is executed at, use the +<tt><ref id=".ORG" name=".ORG"></tt> directive instead of +<tt/.offs/-constructs. + +<tscreen><verb> + .org $1800 + + [floppy code here] + + .reloc ; back to normal +</verb></tscreen> + +<item>Then assemble like this: + +<tscreen><verb> + cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg +</verb></tscreen> + +Note that you need to use the actual start address minus two, since two bytes +are used for the cbm load address. + +</enum> + + +<sect>Bugs/Feedback<p> + +If you have problems using the assembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to +hear from you. Feel free to contact me by email +(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml new file mode 100644 index 000000000..8b26be44c --- /dev/null +++ b/doc/ca65html.sgml @@ -0,0 +1,289 @@ +<!doctype linuxdoc system> + +<article> +<title>ca65html Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2007-10-2 + +<abstract> +ca65html is an assembly-source-to-HTML converter. It is very useful if you +want to publish your assembler sources in the web. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +ca65html converts assembly source files written for use with the <tt/<url +url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone +tool written in PERL; and as such, it does not understand the structure of +assembler sources in the same depth as ca65 does, so it may fail in very rare +cases. In all other cases, it generates very nice output. + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The HTML converter accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ca65html [options] file ... +Options: + --bgcolor c Use background color c instead of #FFFFFF + --colorize Add color highlights to the output + --commentcolor c Use color c for comments instead of #B22222 + --crefs Generate references to the C source file(s) + --ctrlcolor c Use color c for directives instead of #228B22 + --cvttabs Convert tabs to spaces in the output + --help This text + --htmldir dir Specify directory for HTML files + --indexcols n Use n columns on index page (default 6) + --indexname file Use file for the index file instead of index.html + --indexpage Create an index page + --indextitle title Use title as the index title instead of Index + --keywordcolor c Use color c for keywords instead of #A020F0 + --linelabels Generate a linexxx HTML label for each line + --linenumbers Add line numbers to the output + --linkstyle style Use the given link style + --replaceext Replace source extension instead of appending .html + --textcolor c Use text color c instead of #000000 + --verbose Be more verbose +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--bgcolor c</tt></tag> + + Set the background color. The argument c must be a valid HTML color, usually + given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the + respective red, green, and blue parts as two-digit hex values. The default is + <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the + generated HTML output. + + + <tag><tt>--colorize</tt></tag> + + Colorize the output. The converter outputs processor instructions, assembler + control commands, and comments in different colors. + + + <tag><tt>--commentcolor c</tt></tag> + + Set the color used for comments. The argument c must be a valid HTML color, + usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are + the respective red, green, and blue parts as two-digit hex values. The + default is <tt/#B22222/ (red). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + + <tag><tt>--crefs</tt></tag> + + Generate references to the C file, when a <tt/.dbg/ command is found with a + file name. The converter assumes that the C source was also converted into + HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and + lives in the same directory as the assembler file. If the <tt/.dbg/ + directive specifies a line, a link to the correct line in the C file is + generated, using a label in the form <tt/linexxx/, as it is created by + <tt/c2html/ by use of the <tt/-n/ option. + + + <tag><tt>--commentcolor c</tt></tag> + + Set the color used for assembler control commands. The argument c must be a + valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, + where r, g, and b are the respective red, green, and blue parts as two-digit + hex values. The default is <tt/#228B22/ (green). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + + <tag><tt>--cvttabs</tt></tag> + + Convert tabs in the input into spaces in the output, assuming the standard + tab width of 8. This is useful if the <tt/--linenumbers/ option is used to + retain the indentation. + + + <tag><tt>--help</tt></tag> + + Print the command line option summary shown above. + + + <tag><tt>--htmldir dir</tt></tag> + + Specify an output directory for the generated HTML files. + + + <tag><tt>--indexcols n</tt></tag> + + Use n columns on the index page. This option has no effect if used without + <tt/--indexpage/. + + + <tag><tt>--indexname name</tt></tag> + + Use another index file name instead of <tt/index.html/. This option has no + effect if used without <tt/--indexpage/. + + + <tag><tt>--indexpage</tt></tag> + + Causes the converter to generate an index page listing file names, and all + exports found in the converted files. + + + <tag><tt>--indextitle title</tt></tag> + + Use "title" as the title of the index page. This option has no effect if + used without <tt/--indexpage/. + + + <tag><tt>--keywordcolor c</tt></tag> + + Set the color used for processor instructions. The argument c must be a + valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, + where r, g, and b are the respective red, green, and blue parts as two-digit + hex values. The default is <tt/#A020F0/ (purple). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + <tag><tt>--linelabels</tt></tag> + + Generate a label for each line using the name <tt/linexxx/ where xxx is the + number of the line. + + Note: The converter will not make use of this label. Use this option if you + have other HTML pages referencing the converted assembler file. + + + <tag><tt>--linenumbers</tt></tag> + + Generate line numbers on the left side of the output. + + + <tag><tt>--linkstyle n</tt></tag> + + Influences the style used when generating links for imports. If n is zero + (the default), the converter creates a link to the actual symbol if it is + defined somewhere in the input files. If not, it creates a link to the + <tt/.import/ statement. If n is one, the converter will always generate a + HTML link to the <tt/.import/ statement. + + + <tag><tt>--replaceext</tt></tag> + + Replace the file extension of the input file instead of appending <tt/.html/ + when generating the output file name. + + + <tag><tt>--textcolor c</tt></tag> + + Set the color for normal text. The argument c must be a valid HTML color, + usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are + the respective red, green, and blue parts as two-digit hex values. The + default is <tt/#000000/ (black). This color is used in the <tt/<body>/ + of the generated HTML output. + + + <tag><tt>--verbose</tt></tag> + + Increase the converter verbosity. Without this option, ca65html is quiet + when working. If you have a slow machine and lots of files to convert, you + might like a little bit more progress information. + +</descrip> +<p> + + +<sect>Peculiarities<p> + +<sect1>Cross links<p> + +Since ca65html is able to generate links between modules, the best way to use +it is to supply all modules to it in one run, instead of running each file +separately through it. + + +<sect1>Include files<p> + +For now, ca65html will not read files included with <tt/.include/. Specifying +the include files as normal input files on the command line works in many +cases. + + +<sect1>Conversion errors<p> + +Since ca65html does not really parse the input, but does most of its work +applying text patterns, it doesn't know anything about scoping and advanced +features of the assembler. This means that it might miss a label. And, it +might choose the wrong color for an item, in rare cases. Because it's just a +tool for displaying sources in a nice form, I think that's OK. Anyway, if you +find a conversion problem, you can send me a short piece of example input code. +If possible, I will fix it. + + +<sect1>Colorization<p> + +While having colors in the output looks really nice, it has one drawback: + +<enum> + +<item>Because lots of <tt/<span>/ tags are created in the output, +the size of the output file literally will explode. It seems to be the price +that you have to pay for color. + +</enum> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the assembler, I would be glad to hear from +you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the +following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml new file mode 100644 index 000000000..0dc842bc1 --- /dev/null +++ b/doc/cbm510.sgml @@ -0,0 +1,301 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 510 (aka P500) specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2006-05-22 + +<abstract> +An overview over the Commodore 510 runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the CBM 510 runtime system as it comes with +the cc65 C compiler. It describes the memory layout, CBM 510 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that CBM 510 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +In addition to the Commodore 510 (named P128 in the U.S.), no other +machines are supported by this cc65 target. + + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Commodore +510 target is a machine language program with a one line BASIC stub, which +transfers control to the machine language running in bank 0. This means that a +program can be loaded as BASIC program and started with RUN. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + + + +<sect>Memory layout<p> + +cc65 generated programs for the Commodore 510 run in bank 0, the memory bank +reserved for BASIC programs. Since there are no ROMs in this memory bank, +kernal subroutines are either emulated or called by bank switching, which has +the disadvantage of being slow compared to a direct call. + +The default memory configuration for the CBM 510 allocates all memory between +$0002 and $FFF0 in bank 0 for the compiled program. Some space +in low memory is lost, because a separate hardware stack is set up in page 1, +and the kernal replacement functions need some more memory locations. A few +more pages are lost in high memory, because the runtime sets up a copy of the +character ROM, a text screen and a CBM compatible jump table at $FF81. +The main startup code is located at $0400, so about 54K of the complete +bank are actually usable for applications. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $FF81 and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or +<tt/cbm.h/ header files. Using the later may be an option when writing code +for more than one CBM platform, since it includes <tt/cbm510.h/ and declares +several functions common to all CBM platforms. + +<sect1>CBM 510 specific functions<p> + +The functions listed below are special for the CBM 510. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>peekbsys +<item>peekwsys +<item>pokebsys +<item>pokewsys +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/cbm510.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can +therefore not be accessed like on other platforms. Please use one of the +<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to +access the I/O chips. Direct reads and writes to the structures named below +will <em>not</em> work! + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/ACIA/</tag> + Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. + See the <tt/_6551.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/CIA/</tag> + Access to the CIA chip is available via the <tt/CIA/ variable. See the + <tt/_6526.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/TPI1, TPI2/</tag> + The two 6525 triport chips may be accessed by using this variable. See the + <tt/_6525.h/ header file located in the include directory for the + declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Commodore 510. + + +<sect1>Extended memory drivers<p> + +<descrip> + <tag><tt/cbm510-ram.emd (cbm510_ram)/</tag> + A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes + each. +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag> + Supports up to two standard joysticks connected to the joysticks port of + the Commodore 510. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Commodore 510. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/cbm510-std.ser (cbm510_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to + 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. + Note that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + +</descrip><p> + + +<sect>Limitations<label id="limitations"><p> + + +<sect1>Kernal and hardware access<p> + +Since the program runs in bank 0, and the kernal and all I/O chips are located +in bank 15, calling ROM routines or accessing hardware needs special code. The +cc65 runtime implements wrappers for all functions in the kernal jump table. +While this simplifies things, it should be noted that the wrappers do have +quite an impact on performance: A cross bank call has an extra 300µs +penalty added by the wrapper. + +<sect1>Interrupts<p> + +Compiled programs contain an interrupt handler that runs in the program bank. +This has several advantages, one of them being performance (see cross bank +call overhead mentioned above). However, this introduces one problem: +Interrupts are lost while the CPU executes code in the kernal bank. As a +result, the clock may go wrong and (worse) serial interrupts may get lost. + +Since the cc65 runtime does only call the kernal for disk I/O, this means that +a program should not do file I/O while it depends on interrupts. + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the Commodore +510. + + +<sect1>Program return code<p> + +The program return code (signed char) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupt handlers<p> + +The runtime for the Commodore 510 uses routines marked as <tt/.INTERRUPTOR/ +for interrupt handlers. Such routines must be written as simple machine +language subroutines and will be called automatically by the interrupt handler +code when they are linked into a program. See the discussion of the +<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml new file mode 100644 index 000000000..5acb38a1a --- /dev/null +++ b/doc/cbm610.sgml @@ -0,0 +1,300 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 610 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-16 + +<abstract> +An overview over the Commodore 610 runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the CBM 610 runtime system as it comes with +the cc65 C compiler. It describes the memory layout, CBM 610 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that CBM 610 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +In addition to the Commodore 610 (named B40 in the U.S.), several other +machines are supported by this cc65 target, since they have identical +hardware: The Commodore 620 and 630 (more memory, additional coprocessor +card), and the Commodore 710, 720 and 730 (same hardware in another case with +a builtin monitor). + + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Commodore +610 target is a machine language program with a one line BASIC stub, which +transfers control to the machine language running in bank 1. This means that a +program can be loaded as BASIC program and started with RUN. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + + +<sect>Memory layout<p> + +cc65 generated programs for the Commodore 610 run in bank 1, the memory bank +reserved for BASIC programs. Since there are no ROMs in this memory bank, +kernal subroutines are either emulated or called by bank switching, which has +the disadvantage of being slow compared to a direct call. + +The default memory configuration for the CBM 610 allocates all memory between +$0002 and $FFF0 in bank 1 for the compiled program. Some space +in low memory is lost, because a separate hardware stack is set up in page 1, +and the kernal replacement functions need some more memory locations. A few +more bytes are lost in high memory, because the runtime sets up a CBM +compatible jump table at $FF81. The main startup code is located at +$0400, so about 63K of the complete bank are actually usable for +applications. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $FF81 and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing CBM 610 specific code may use the <tt/cbm610.h/ or +<tt/cbm.h/ header files. Using the later may be an option when writing code +for more than one CBM platform, since it includes <tt/cbm610.h/ and declares +several functions common to all CBM platforms. + +<sect1>CBM 610 specific functions<p> + +The functions listed below are special for the CBM 610. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>peekbsys +<item>peekwsys +<item>pokebsys +<item>pokewsys +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/cbm610.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can +therefore not be accessed like on other platforms. Please use one of the +<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to +access the I/O chips. Direct reads and writes to the structures named below +will <em>not</em> work! + +<descrip> + + <tag><tt/CRTC/</tag> + The <tt/CRTC/ structure allows access to the CRTC (the video controller). + See the <tt/_6545.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/SID/</tag> The <tt/SID/ structure allows access to the SID (the + sound interface device). See the <tt/_sid.h/ header file located in the + include directory for the declaration of the structure. + + <tag><tt/ACIA/</tag> + Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. + See the <tt/_6551.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/CIA/</tag> + Access to the CIA chip is available via the <tt/CIA/ variable. See the + <tt/_6526.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/TPI1, TPI2/</tag> + The two 6525 triport chips may be accessed by using this variable. See the + <tt/_6525.h/ header file located in the include directory for the + declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Commodore 610 (and since +the machine has no graphics capabilities, chances for a graphics driver aren't +really good:-). + + +<sect1>Extended memory drivers<p> + +<descrip> + <tag><tt/cbm610-ram.emd (cbm610_ram)/</tag> + A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes + each. +</descrip><p> + + +<sect1>Joystick drivers<p> + +The Commodore 610 is a business machine and doesn't have joystick ports. There +are no drivers for the non existing ports available. + + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/cbm610-std.ser (cbm610_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to + 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. + Note that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + +</descrip><p> + + +<sect>Limitations<label id="limitations"><p> + + +<sect1>Kernal and hardware access<p> + +Since the program runs in bank 1, and the kernal and all I/O chips are located +in bank 15, calling ROM routines or accessing hardware needs special code. The +cc65 runtime implements wrappers for all functions in the kernal jump table. +While this simplifies things, it should be noted that the wrappers do have +quite an impact on performance: A cross bank call has an extra 300µs +penalty added by the wrapper. + +<sect1>Interrupts<p> + +Compiled programs contain an interrupt handler that runs in the program bank. +This has several advantages, one of them being performance (see cross bank +call overhead mentioned above). However, this introduces one problem: +Interrupts are lost while the CPU executes code in the kernal bank. As a +result, the clock may go wrong and (worse) serial interrupts may get lost. + +Since the cc65 runtime does only call the kernal for disk I/O, this means that +a program should not do file I/O while it depends on interrupts. + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the Commodore +610. + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupt handlers<p> + +The runtime for the Commodore 610 uses routines marked as <tt/.INTERRUPTOR/ +for interrupt handlers. Such routines must be written as simple machine +language subroutines and will be called automatically by the interrupt handler +code when they are linked into a program. See the discussion of the +<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/cc65.sgml b/doc/cc65.sgml new file mode 100644 index 000000000..bb1303909 --- /dev/null +++ b/doc/cc65.sgml @@ -0,0 +1,1386 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-09-03, 2001-10-02, 2005-08-01 + +<abstract> +cc65 is a C compiler for 6502 targets. It supports several 6502 based home +computers like the Commodore and Atari machines, but it is easily retargetable. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +cc65 was originally a C compiler for the Atari 8-bit machines written by +John R. Dunning. In prior releases I've described the compiler by listing +up the changes made by me. I have made many more changes in the meantime +(and rewritten major parts of the compiler), so I will no longer do that, +since the list would be too large and of no use to anyone. Instead I will +describe the compiler in respect to the ANSI/ISO C standard. + +There are separate documents named <url url="library.html"> and <url +url="funcref.html"> that cover the library that is available for the compiler. +If you know C, and are interested in doing actual programming, the library +documentation is probably of much more use than this document. + +If you need some hints for getting the best code out of the compiler, you +may have a look at <url url="coding.html"> which covers some code generation +issues. + + + +<sect>Usage<p> + +The compiler translates C files into files containing assembly code that +may be translated by the ca65 macroassembler (for more information about +the assembler, have a look at <url url="ca65.html">). + + +<sect1>Command line option overview<p> + +The compiler may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: cc65 [options] file +Short options: + -Cl Make local variables static + -Dsym[=defn] Define a symbol + -E Stop after the preprocessing stage + -I dir Set an include directory search path + -O Optimize code + -Oi Optimize code, inline more code + -Or Enable register variables + -Os Inline some known functions + -T Include source as comment + -V Print the compiler version number + -W warning[,...] Suppress warnings + -d Debug mode + -g Add debug info to object file + -h Help (this text) + -j Default characters are signed + -mm model Set the memory model + -o name Name the output file + -r Enable register variables + -t sys Set the target system + -v Increase verbosity + +Long options: + --add-source Include source as comment + --bss-name seg Set the name of the BSS segment + --check-stack Generate stack overflow checks + --code-name seg Set the name of the CODE segment + --codesize x Accept larger code by factor x + --cpu type Set cpu type (6502, 65c02) + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --data-name seg Set the name of the DATA segment + --debug Debug mode + --debug-info Add debug info to object file + --debug-opt name Debug optimization steps + --dep-target target Use this dependency target + --disable-opt name Disable an optimization step + --enable-opt name Enable an optimization step + --forget-inc-paths Forget include search paths + --help Help (this text) + --include-dir dir Set an include directory search path + --list-opt-steps List all optimizer steps and exit + --list-warnings List available warning types for -W + --local-strings Emit string literals immediately + --memory-model model Set the memory model + --register-space b Set space available for register variables + --register-vars Enable register variables + --rodata-name seg Set the name of the RODATA segment + --signed-chars Default characters are signed + --standard std Language standard (c89, c99, cc65) + --static-locals Make local variables static + --target sys Set the target system + --verbose Increase verbosity + --version Print the compiler version number + --writable-strings Make string literals writable +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option-bss-name"> + <tag><tt>--bss-name seg</tt></tag> + + Set the name of the bss segment. See also <tt/<ref id="pragma-bss-name" + name="#pragma bss-name">/. + + + <label id="option-check-stack"> + <tag><tt>--check-stack</tt></tag> + + Tells the compiler to generate code that checks for stack overflows. See + <tt/<ref id="pragma-check-stack" name="#pragma check-stack">/ for an + explanation of this feature. + + + <label id="option-code-name"> + <tag><tt>--code-name seg</tt></tag> + + Set the name of the code segment. See also <tt/<ref id="pragma-code-name" + name="#pragma code-name">/ + + + <label id="option-codesize"> + <tag><tt>--codesize x</tt></tag> + + This options allows finer control about speed vs. size decisions in the code + generation and optimization phases. It gives the allowed size increase + factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when + using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/-O --codesize 200/). + + + <label id="option--cpu"> + <tag><tt>--cpu CPU</tt></tag> + + Set the CPU, the compiler generates code for. You may specify "6502" or + "65C02" as the CPU. The default depends on the selected target (see option + <tt/<ref id="option-t" name="-t">/). It is the 6502 CPU for most targets or + if no target has been set. Specifying 65C02 will use a few 65C02 + instructions when generating code. Don't expect too much from this option: + In most cases the difference in size and speed is just 1-2%. + + + <label id="option-create-dep"> + <tag><tt>--create-dep name</tt></tag> + + Tells the compiler to generate a file containing the dependency list for the + compiled module in makefile syntax. The output is written to a file with the + given name. The output does not include system include files (in angle + brackets). + + + <label id="option-create-full-dep"> + <tag><tt>--create-full-dep name</tt></tag> + + Tells the compiler to generate a file containing the dependency list for the + compiled module in makefile syntax. The output is written to a file with the + given name. The output does include system include files (in angle + brackets). + + + <label id="option-data-name"> + <tag><tt>--data-name seg</tt></tag> + + Set the name of the data segment. See also <tt/<ref id="pragma-data-name" + name="#pragma data-name">/ + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere + mortals:-) + + + <label id="option-dep-target"> + <tag><tt>--dep-target target</tt></tag> + + When generating a dependency file, don't use the actual output file as the + target of the dependency, but the file specified with this option. The + option has no effect if neither <tt/<ref id="option-create-dep" + name="--create-dep">/ nor <tt/<ref id="option-create-full-dep" + name="--create-full-dep">/ is specified. + + + <tag><tt>-D sym[=definition]</tt></tag> + + Define a macro on the command line. If no definition is given, the macro + is defined to the value "1". + + + <tag><tt>--forget-inc-paths</tt></tag> + + Forget the builtin include paths. This is most useful when building + customized C or runtime libraries, in which case the standard header + files should be ignored. + + + <tag><tt>-g, --debug-info</tt></tag> + + This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the + generated assembler code. This will cause the assembler to include all + symbols in a special section in the object file. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-list-warnings"> + <tag><tt>--list-warnings</tt></tag> + + List the names of warning types available for use with <tt><ref + id="option-W" name="-W"></tt>. + + + <label id="option-local-strings"> + <tag><tt>--local-strings</tt></tag> + + Emit string literals into the rodata segment as soon as they're encountered + in the source (even if you do nothing but get the sizeof those strings). The + default is to keep string literals until end of assembly, merge read only + literals if possible, and then output the literals into the data or rodata + segment that is active at that point. Use of this option prevents merging of + duplicate strings, but the options that change the name of one of the data + segments will work. + + You can also use <tt><ref id="pragma-local-strings" + name="#pragma local-strings"></tt> for fine grained control. + + + <tag><tt>-o name</tt></tag> + + Specify the name of the output file. If you don't specify a name, the + name of the C input file is used, with the extension replaced by ".s". + + + <label id="option-register-vars"> + <tag><tt>-r, --register-vars</tt></tag> + + <tt/-r/ will make the compiler honor the <tt/register/ keyword. Local + variables may be placed in registers (which are actually zero page + locations). There is some overhead involved with register variables, since + the old contents of the registers must be saved and restored. Since register + variables are of limited use without the optimizer, there is also a combined + switch: <tt/-Or/ will enable both, the optimizer and register variables. + + For more information about register variables see <ref id="register-vars" + name="register variables">. + + The compiler setting can also be changed within the source file by using + <tt/<ref id="pragma-register-vars" name="#pragma register-vars">/. + + + <label id="option-register-space"> + <tag><tt>--register-space</tt></tag> + + This option takes a numeric parameter and is used to specify, how much + zero page register space is available. Please note that just giving this + option will not increase or decrease by itself, it will just tell the + compiler about the available space. You will have to allocate that space + yourself using an assembler module with the necessary allocations, and a + linker configuration that matches the assembler module. The default value + for this option is 6 (bytes). + + If you don't know what all this means, please don't use this option. + + + <label id="option-rodata-name"> + <tag><tt>--rodata-name seg</tt></tag> + + Set the name of the rodata segment (the segment used for readonly data). + See also <tt/<ref id="pragma-rodata-name" name="#pragma rodata-name">/ + + <label id="option-signed-chars"> + <tag><tt>-j, --signed-chars</tt></tag> + + Using this option, you can make the default characters signed. Since the + 6502 has no provisions for sign extending characters (which is needed on + almost any load operation), this will make the code larger and slower. A + better way is to declare characters explicitly as "signed" if needed. You + can also use <tt><ref id="pragma-signed-chars" + name="#pragma signed-chars"></tt> for better control of this option. + + + <label id="option--standard"> + <tag><tt>--standard std</tt></tag> + + This option allows to set the language standard supported. The argument is + one of + <descrip> + <tag/c89/ + This disables anything that is illegal in C89/C90. Among those things + are <tt>//</tt> comments and the non-standard keywords without + underscores. Please note that cc65 is not a fully C89 compliant compiler + despite this option. A few more things (like floats) are missing. + + <tag/c99/ + This enables a few features from the C99 standard. With this option, + <tt>//</tt> comments are allowed. It will also cause warnings and even + errors in a few situations that are allowed with <tt/--standard c89/. + For example, a call to a function without a prototype is an error in + this mode. + + <tag/cc65/ + This is the default mode. It is like c99 mode, but additional features + are enabled. Among these are "void data", non-standard keywords without + the underlines, unnamed function parameters and the requirement for + main() to return an int. + </descrip> + + Please note that the compiler does not support the C99 standard and never + will. c99 mode is actually c89 mode with a few selected C99 extensions. + + + <label id="option-t"> + <tag><tt>-t target, --target target</tt></tag> + + This option is used to set the target system. The target system determines + the character set that is used for strings and character constants and the + default CPU. The CPU setting can be overriden by use of the <tt/<ref + id="option--cpu" name="--cpu">/ option. + + The following target systems are supported: + + <itemize> + <item>none + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with memory up to 32K) + <item>c64 + <item>c128 + <item>cbm510 (CBM-II series with 40 column video) + <item>cbm610 (all CBM-II II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>lunix + <item>lynx + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>plus4 + <item>supervision + <item>vic20 + </itemize> + + <tag><tt>-v, --verbose</tt></tag> + + Using this option, the compiler will be somewhat more verbose if errors + or warnings are encountered. + + + <label id="option-writable-strings"> + <tag><tt>--writable-strings</tt></tag> + + Make string literals writable by placing them into the data segment instead + of the rodata segment. You can also use <tt><ref id="pragma-writable-strings" + name="#pragma writable-strings"></tt> to control this option from within + the source file. + + + <label id="option-static-locals"> + <tag><tt>-Cl, --static-locals</tt></tag> + + Use static storage for local variables instead of storage on the stack. + Since the stack is emulated in software, this gives shorter and usually + faster code, but the code is no longer reentrant. The difference between + <tt/-Cl/ and declaring local variables as static yourself is, that + initializer code is executed each time, the function is entered. So when + using + + <tscreen><verb> + void f (void) + { + unsigned a = 1; + ... + } + </verb></tscreen> + + the variable <tt/a/ will always have the value <tt/1/ when entering the + function and using <tt/-Cl/, while in + + <tscreen><verb> + void f (void) + { + static unsigned a = 1; + .... + } + </verb></tscreen> + + the variable <tt/a/ will have the value <tt/1/ only the first time that the + function is entered, and will keep the old value from one call of the + function to the next. + + You may also use <tt><ref id="pragma-static-locals" + name="#pragma static-locals"></tt> to change this setting in your + sources. + + + <label id="option-include-dir"> + <tag><tt>-I dir, --include-dir dir</tt></tag> + + Set a directory where the compiler searches for include files. You may + use this option multiple times to add more than one directory to the + search list. + + + <label id="option-O"> + <tag><tt>-O, -Oi, -Or, -Os</tt></tag> + + Enable an optimizer run over the produced code. + + Using <tt/-Oi/, the code generator will inline some code where otherwise a + runtime functions would have been called, even if the generated code is + larger. This will not only remove the overhead for a function call, but will + make the code visible for the optimizer. <tt/-Oi/ is an alias for + <tt/-O --codesize 200/. + + <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local + variables may be placed in registers (which are actually zero page + locations). See also the <tt/<ref id="option-register-vars" + name="--register-vars">/ command line option, and the <ref + id="register-vars" name="discussion of register variables"> below. + + Using <tt/-Os/ will force the compiler to inline some known functions from + the C library like strlen. Note: This has two consequences: + <p> + <itemize> + <item>You may not use names of standard C functions in your own code. If you + do that, your program is not standard compliant anyway, but using + <tt/-Os/ will actually break things. + <p> + <item>The inlined string and memory functions will not handle strings or + memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/ + functions will not work with values outside the char. range (such as + <tt/EOF/). + <p> + </itemize> + <p> + It is possible to concatenate the modifiers for <tt/-O/. For example, to + enable register variables and inlining of known functions, you may use + <tt/-Ors/. + + + <tag><tt>-T, --add-source</tt></tag> + + This include the source code as comments in the generated code. This is + normally not needed. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. + + + <label id="option-W"> + <tag><tt>-W name[,name]</tt></tag> + + This option allows to control warnings generated by the compiler. It is + followed by a comma separated list of warnings that should be enabled or + disabled. To disable a warning, its name is prefixed by a minus sign. If + no such prefix exists, or the name is prefixed by a plus sign, the warning + is enabled. + + The following warning names are currently recognized: + <descrip> + <tag><tt/const-comparison/</tag> + Warn if the result of a comparison is constant. + <tag><tt/error/</tag> + Treat all warnings as errors. + <tag><tt/no-effect/</tag> + Warn about statements that don't have an effect. + <tag><tt/struct-param/</tag> + Warn when passing structs by value. + <tag><tt/unknown-pragma/</tag> + Warn about known #pragmas. + <tag><tt/unused-label/</tag> + Warn about unused labels. + <tag><tt/unused-param/</tag> + Warn about unused function parameters. + <tag><tt/unused-var/</tag> + Warn about unused variables. + </descrip> + + The full list of available warning names may be retrieved by using the + option <tt><ref id="option-list-warnings" name="--list-warnings"></tt>. + + You may also use <tt><ref id="pragma-warn" name="#pragma warn"></tt> to + control this setting for smaller pieces of code from within your code. + +</descrip><p> + + +<sect>Input and output<p> + +The compiler will accept one C file per invocation and create a file with +the same base name, but with the extension replaced by ".s". The output +file contains assembler code suitable for the use with the ca65 macro +assembler. + +Include files in single quotes are searched in the following places: +<enum> +<item>The current directory. +<item>The value of the environment variable <tt/CC65_INC/ if it is defined. +<item>Any directory added with the <tt/-I/ option on the command line. +</enum> + +Include files in angle brackets are searched in the following places: +<enum> +<item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on + Linux systems. +<item>The value of the environment variable <tt/CC65_INC/ if it is defined. +<item>A subdirectory named <tt/include/ of the directory defined in the + environment variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt/-I/ option on the command line. +</enum> + + + +<sect>Differences to the ISO standard<p> + +Apart from the things listed below, the compiler does support additional +keywords, has several functions in the standard headers with names outside the +reserved namespace and a few syntax extensions. All these can be disabled with +the <tt><ref id="option--standard" name="--standard"></tt> command line +option. Its use for maximum standards compatibility is advised. + +Here is a list of differences between the language, the compiler accepts, +and the one defined by the ISO standard: + +<itemize> + +<item> The datatypes "float" and "double" are not available. + <p> +<item> C Functions may not return structs (or unions), and structs may not + be passed as parameters by value. However, struct assignment *is* + possible. + <p> +<item> Part of the C library is available only with fastcall calling + conventions (see below). It means that you must not mix pointers to + those functions with pointers to user-written, not-fastcall functions. + <p> +<item> The <tt/volatile/ keyword doesn't have an effect. This is not as bad + as it sounds, since the 6502 has so few registers that it isn't + possible to keep values in registers anyway. + <p> +</itemize> + +There may be some more minor differences I'm currently not aware of. The +biggest problem is the missing float data type. With this limitation in +mind, you should be able to write fairly portable code. + + + +<sect>Extensions<p> + +This cc65 version has some extensions to the ISO C standard. + +<itemize> + +<item> The compiler allows to insert assembler statements into the output + file. The syntax is + + <tscreen><verb> + asm (<string literal>[, optional parameters]) ; + </verb></tscreen> + or + <tscreen><verb> + __asm__ (<string literal>[, optional parameters]) ; + </verb></tscreen> + + The first form is in the user namespace and is disabled if the <tt/-A/ + switch is given. + + There is a whole section covering inline assembler statements, + <ref id="inline-asm" name="see there">. + <p> + +<item> There is a special calling convention named "fastcall". + The syntax for a function declaration using fastcall is + + <tscreen><verb> + <return type> fastcall <function name> (<parameter list>) + </verb></tscreen> + or + <tscreen><verb> + <return type> __fastcall__ <function name> (<parameter list>) + </verb></tscreen> + An example would be + <tscreen><verb> + void __fastcall__ f (unsigned char c) + </verb></tscreen> + The first form of the fastcall keyword is in the user namespace and can + therefore be disabled with the <tt><ref id="option--standard" + name="--standard"></tt> command line option. + + For functions declared as <tt/fastcall/, the rightmost parameter is not + pushed on the stack but left in the primary register when the function + is called. This will reduce the cost when calling assembler functions + significantly, especially when the function itself is rather small. + <p> + +<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/. + Both refer to the primary register that is used by the compiler to + evaluate expressions or return function results. <tt/__AX__/ is of + type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/ + respectively. The pseudo variables may be used as lvalue and rvalue as + every other variable. They are most useful together with short + sequences of assembler code. For example, the macro + + <tscreen><verb> + #define hi(x) \ + (__AX__ = (x), \ + asm ("txa"), \ + asm ("ldx #$00"), \ + __AX__) + </verb></tscreen> + + will give the high byte of any unsigned value. + <p> + +<item> Inside a function, the identifier <tt/__func__/ gives the name of the + current function as a string. Outside of functions, <tt/__func__/ is + undefined. + Example: + + <tscreen><verb> + #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s); + </verb></tscreen> + + The macro will print the name of the current function plus a given + string. + <p> + +<item> cc65 allows the initialization of <tt/void/ variables. This may be + used to create variable structures that are more compatible with + interfaces written for assembler languages. Here is an example: + + <tscreen><verb> + void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 }; + </verb></tscreen> + + This will be translated as follows: + + <tscreen><verb> + _GCmd: + .byte 3 + .word $2000 + .word $3000 + </verb></tscreen> + + Since the variable is of type <tt/void/ you may not use it as is. + However, taking the address of the variable results in a <tt/void*/ + which may be passed to any function expecting a pointer. + + See the <url url="geos.html" name="GEOS library document"> for examples + on how to use this feature. + <p> + +<item> cc65 implements flexible array struct members as defined in the C99 ISO + standard. As an extension, these fields may be initialized. There are + several exceptions, however (which is probably the reason why the + standard does not define this feature, because it is highly + unorthogonal). Flexible array members cannot be initialized ... + + <itemize> + <item>... when defining an array of structs with flexible + members. + <item>... if such a struct is a member field of another struct + which is not the last field. + <item>... if the struct which contains a flexible array member is + declared as <tt/register/, and the size and compiler settings + do allow the compiler actually to place the struct into the + register bank in the zero page. + </itemize> + + Please note that -- as defined in the ISO C standard -- the <tt/sizeof/ + operator returns the struct size with the flexible array member having + size zero, even if it is initialized. + <p> + +</itemize> +<p> + + +<sect>Predefined macros<p> + +The compiler defines several macros at startup: + +<descrip> + <tag><tt>__APPLE2__</tt></tag> + + This macro is defined if the target is the Apple ][ (-t apple2). + + <tag><tt>__APPLE2ENH__</tt></tag> + + This macro is defined if the target is the enhanced Apple //e (-t apple2enh). + + <tag><tt>__ATARI__</tt></tag> + + This macro is defined if the target is one of the Atari computers + (400/800/130XL/800XL). + + <tag><tt>__ATMOS__</tt></tag> + + This macro is defined if the target is the Oric Atmos (-t atmos). + + <tag><tt>__C128__</tt></tag> + + This macro is defined if the target is the c128 (-t c128). + + <tag><tt>__C16__</tt></tag> + + This macro is defined if the target is the c16 (-t c16). + + <tag><tt>__C64__</tt></tag> + + This macro is defined if the target is the c64 (-t c64). + + <tag><tt>__CBM__</tt></tag> + + This macro is defined if the target system is one of the CBM targets. + + <tag><tt>__CBM510__</tt></tag> + + This macro is defined if the target is the CBM 500 series of computers. + + <tag><tt>__CBM610__</tt></tag> + + This macro is defined if the target is one of the CBM 600/700 family of + computers (called B series in the US). + + <tag><tt>__CC65__</tt></tag> + + This macro is always defined. Its value is the version number of the + compiler in hex. For example, version 2.10.1 of the compiler has this macro + defined as <tt/0x02A1/. + + <tag><tt>__CC65_STD__</tt></tag> + + This macro is defined to one of the following depending on the <tt><ref + id="option--standard" name="--standard"></tt> command line option: + <itemize> + <item><tt/__CC65_STD_C89__/ + <item><tt/__CC65_STD_C99__/ + <item><tt/__CC65_STD_CC65__/ + </itemize> + + <tag><tt>__DATE__</tt></tag> + + This macro expands to the date of translation of the preprocessing + translation unit in the form "Mmm dd yyyy". + + <tag><tt>__FILE__</tt></tag> + + This macro expands to a string containing the name of the C source file. + + <tag><tt>__GEOS__</tt></tag> + + This macro is defined if you are compiling for the GEOS system (-t geos). + + <tag><tt>__LINE__</tt></tag> + + This macro expands to the current line number. + + <tag><tt>__LUNIX__</tt></tag> + + This macro is defined if you are compiling for the LUnix system (-t lunix). + + <tag><tt>__LYNX__</tt></tag> + + This macro is defined if the target is the Atari Lynx (-t lynx). + + <tag><tt>__NES__</tt></tag> + + This macro is defined if the target is the NES (-t nes). + + <tag><tt>__OPT__</tt></tag> + + Is defined if the compiler was called with the <tt/-O/ command line option. + + <tag><tt>__OPT_i__</tt></tag> + + Is defined if the compiler was called with the <tt/-Oi/ command line option. + + <tag><tt>__OPT_r__</tt></tag> + + Is defined if the compiler was called with the <tt/-Or/ command line option. + + <tag><tt>__OPT_s__</tt></tag> + + Is defined if the compiler was called with the <tt/-Os/ command line option. + + <tag><tt>__PET__</tt></tag> + + This macro is defined if the target is the PET family of computers (-t pet). + + <tag><tt>__PLUS4__</tt></tag> + + This macro is defined if the target is the plus/4 (-t plus4). + + <tag><tt>__STDC_HOSTED__</tt></tag> + + This macro is expands to the integer constant 1. + + <tag><tt>__SUPERVISION__</tt></tag> + + This macro is defined if the target is the supervision (-t supervision). + + <tag><tt>__TIME__</tt></tag> + + This macro expands to the time of translation of the preprocessing + translation unit in the form "hh:mm:ss". + + <tag><tt>__VIC20__</tt></tag> + + This macro is defined if the target is the vic20 (-t vic20). +</descrip> + + +<sect>#pragmas<label id="pragmas"><p> + +The compiler understands some pragmas that may be used to change code +generation and other stuff. Some of these pragmas understand a special form: +If the first parameter is <tt/push/, the old value is saved onto a stack +before changing it. The value may later be restored by using the <tt/pop/ +parameter with the <tt/#pragma/. + +<sect1><tt>#pragma bss-name ([push,] <name>)</tt><label id="pragma-bss-name"><p> + + This pragma changes the name used for the BSS segment (the BSS segment + is used to store uninitialized data). The argument is a string enclosed + in double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + Beware: The startup code will zero only the default BSS segment. If you + use another BSS segment, you have to do that yourself, otherwise + uninitialized variables do not have the value zero. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma bss-name ("MyBSS") + </verb></tscreen> + + +<sect1><tt>#pragma charmap (<index>, <code>)</tt><label id="pragma-charmap"><p> + + Each literal string and each literal character in the source is translated + by use of a translation table. This translation table is preset when the + compiler is started depending on the target system, for example to map + ISO-8859-1 characters into PETSCII if the target is a commodore machine. + + This pragma allows to change entries in the translation table, so the + translation for individual characters, or even the complete table may be + adjusted. + + Both arguments are assumed to be unsigned characters with a valid range of + 1-255. + + Beware of two pitfalls: + + <itemize> + <item>The character index is actually the code of the character in the + C source, so character mappings do always depend on the source + character set. This means that <tt/#pragma charmap/ is not + portable -- it depends on the build environment. + <item>While it is possible to use character literals as indices, the + result may be somewhat unexpected, since character literals are + itself translated. For this reason I would suggest to avoid + character literals and use numeric character codes instead. + </itemize> + + Example: + <tscreen><verb> + /* Use a space wherever an 'a' occurs in ISO-8859-1 source */ + #pragma charmap (0x61, 0x20); + </verb></tscreen> + + +<sect1><tt>#pragma check-stack ([push,] on|off)</tt><label id="pragma-check-stack"><p> + + Tells the compiler to insert calls to a stack checking subroutine to detect + stack overflows. The stack checking code will lead to somewhat larger and + slower programs, so you may want to use this pragma when debugging your + program and switch it off for the release version. If a stack overflow is + detected, the program is aborted. + + If the argument is "off", stack checks are disabled (the default), otherwise + they're enabled. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + +<sect1><tt>#pragma code-name ([push,] <name>)</tt><label id="pragma-code-name"><p> + + This pragma changes the name used for the CODE segment (the CODE segment + is used to store executable code). The argument is a string enclosed in + double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma code-name ("MyCODE") + </verb></tscreen> + + +<sect1><tt>#pragma codesize ([push,] <int>)</tt><label id="pragma-codesize"><p> + + This pragma allows finer control about speed vs. size decisions in the code + generation and optimization phase. It gives the allowed size increase factor + (in percent). The default is can be changed by use of the <tt/<ref + id="option-codesize" name="--codesize">/ compiler option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma data-name ([push,] <name>)</tt><label id="pragma-data-name"><p> + + This pragma changes the name used for the DATA segment (the DATA segment + is used to store initialized data). The argument is a string enclosed in + double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma data-name ("MyDATA") + </verb></tscreen> + + +<sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p> + + When "on", emit string literals to the data segment when they're encountered + in the source. The default ("off") is to keep string literals until end of + assembly, merge read only literals if possible, and then output the literals + into the data or rodata segment that is active at that point. + + Using this <tt/#pragma/ it is possible to control the behaviour from within + the source. When <tt/#pragma local-strings/ is active, string literals are + output immediately, which means that they go into the currently active data + or rodata segment, but cannot be merged. When inactive, string literals are + remembered and output as a whole when translation is finished. + + +<sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p> + + Switch optimization on or off. If the argument is "off", optimization is + disabled, otherwise it is enabled. Please note that this pragma only effects + whole functions. The setting in effect when the function is encountered will + determine if the generated code is optimized or not. + + Optimization and code generation is also controlled by the <ref + id="pragma-codesize" name="codesize pragma">. + + The default is "off", but may be changed with the <tt/<ref name="-O" + id="option-O">/ compiler option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma rodata-name ([push,] <name>)</tt><label id="pragma-rodata-name"><p> + + This pragma changes the name used for the RODATA segment (the RODATA + segment is used to store readonly data). The argument is a string + enclosed in double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma rodata-name ("MyRODATA") + </verb></tscreen> + + +<sect1><tt>#pragma regvaraddr ([push,] on|off)</tt><label id="pragma-regvaraddr"><p> + + The compiler does not allow to take the address of register variables. + The regvaraddr pragma changes this. Taking the address of a register + variable is allowed after using this pragma with "on" as argument. + Using "off" as an argument switches back to the default behaviour. + + Beware: The C standard does not allow taking the address of a variable + declared as register. So your programs become non-portable if you use + this pragma. In addition, your program may not work. This is usually the + case if a subroutine is called with the address of a register variable, + and this subroutine (or a subroutine called from there) uses + register variables. So be careful with this #pragma. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma regvaraddr(on) /* Allow taking the address + * of register variables + */ + </verb></tscreen> + + +<sect1><tt>#pragma register-vars ([push,] on|off)</tt><label id="pragma-register-vars"><p> + + Enables or disables use of register variables. If register variables are + disabled (the default), the <tt/register/ keyword is ignored. Register + variables are explained in more detail in <ref id="register-vars" name="a separate + chapter">. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma signed-chars ([push,] on|off)</tt><label id="pragma-signed-chars"><p> + + Changes the signedness of the default character type. If the argument is + "on", default characters are signed, otherwise characters are unsigned. The + compiler default is to make characters unsigned since this creates a lot + better code. This default may be overridden by the <tt/<ref + name="--signed-chars" id="option-signed-chars">/ command line option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma static-locals ([push,] on|off)</tt><label id="pragma-static-locals"<p> + + Use variables in the bss segment instead of variables on the stack. This + pragma changes the default set by the compiler option <tt/<ref + name="--static-locals" id="option-static-locals">/. If the argument is "on", + local variables are allocated in the BSS segment, leading to shorter and in + most cases faster, but non-reentrant code. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma warn (name, [push,] on|off)</tt><label id="pragma-warn"><p> + + Switch compiler warnings on or off. "name" is the name of a warning (see the + <tt/<ref name="-W" id="option-W">/ compiler option for a list). The name is + either followed by "pop", which restores the last pushed state, or by "on" or + "off", optionally preceeded by "push" to push the current state before + changing it. + + Example: + <tscreen><verb> + /* Don't warn about the unused parameter in function func */ + #pragma warn (unused-param, push, off) + static int func (int unused) + { + return 0; + } + #pragma warn (unused-param, pop) + </verb></tscreen> + +<sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p> + + Changes the storage location of string literals. For historical reasons, + the C standard defines that string literals are of type "char[]", but + writing to such a literal causes undefined behaviour. Most compilers + (including cc65) place string literals in the read-only data segment, which + may cause problems with old C code that writes to string literals. + + Using this pragma (or the corresponding command line option <tt/<ref + name="--writable-strings" id="option-writable-strings">/) causes the + literals to be placed in the data segment so they can be written to without + worry. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma zpsym (<name>)</tt><p> + + Tell the compiler that the -- previously as external declared -- symbol with + the given name is a zero page symbol (usually from an assembler file). + The compiler will create a matching import declaration for the assembler. + + Example: + <tscreen><verb> + extern int foo; + #pragma zpsym ("foo"); /* foo is in the zeropage */ + </verb></tscreen> + + + + +<sect>Register variables<label id="register-vars"><p> + +The runtime for all supported platforms has 6 bytes of zero page space +available for register variables (this could be increased, but I think it's a +good value). So you can declare register variables up to a total size of 6 per +function. The compiler will allocate register space on a "first come, first +served" base and convert any <tt/register/ declarations that exceed the +available register space silently to <tt/auto/. Parameters can also be +declared as <tt/register/, this will in fact give slightly shorter code than +using a register variable. + +Since a function must save the current values of the registers on entry and +restore them on exit, there is an overhead associated with register variables, +and this overhead is quite high (about 20 bytes per variable). This means that +just declaring anything as <tt/register/ is not a good idea. + +The best use for register variables are pointers, especially those that point +to structures. The magic number here is about 3 uses of a struct field: If the +function contains this number or even more, the generated code will be usually +shorter and faster when using a register variable for the struct pointer. The +reason for this is that the register variable can in many cases be used as a +pointer directly. Having a pointer in an auto variable means that this pointer +must first be copied into a zero page location, before it can be dereferenced. + +Second best use for register variables are counters. However, there is not +much difference in the code generated for counters, so you will need at least +100 operations on this variable (for example in a loop) to make it worth the +trouble. The only savings you get here are by the use of a zero page variable +instead of one on the stack or in the data segment. + +Register variables must be explicitly enabled, either by using <tt/<ref +name="-Or" id="option-O">/ or <tt/<ref name="--register-vars" +id="option-register-vars">/ on the command line or by use of <tt/<ref +name="#pragma register-vars" id="pragma-register-vars">/. Register variables +are only accepted on function top level, register variables declared in +interior blocks are silently converted to <tt/auto/. With register variables +disabled, all variables declared as <tt/register/ are actually auto variables. + +Please take care when using register variables: While they are helpful and can +lead to a tremendous speedup when used correctly, improper usage will cause +bloated code and a slowdown. + + + +<sect>Inline assembler<label id="inline-asm"><p> + +The compiler allows to insert assembler statements into the output file. The +syntax is + +<tscreen><verb> + asm (<string literal>[, optional parameters]) ; +</verb></tscreen> +or +<tscreen><verb> + __asm__ (<string literal>[, optional parameters]) ; +</verb></tscreen> +<p> + +The first form is in the user namespace and is disabled by <tt><ref +id="option--standard" name="--standard"></tt> if the argument is not <tt/cc65/. + +The asm statement may be used inside a function and on global file level. An +inline assembler statement is a primary expression, so it may also be used as +part of an expression. Please note however that the result of an expression +containing just an inline assembler statement is always of type <tt/void/. + +The contents of the string literal are preparsed by the compiler and inserted +into the generated assembly output, so that the can be further processed by +the backend and especially the optimizer. For this reason, the compiler does +only allow regular 6502 opcodes to be used with the inline assembler. Pseudo +instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed, +even if the ca65 assembler (which is used to translate the generated assembler +code) would accept them. The builtin inline assembler is not a replacement for +the full blown macro assembler which comes with the compiler. + +Note: Inline assembler statements are subject to all optimizations done by the +compiler. There is currently no way to protect an inline assembler statement +from being moved or removed completely by the optimizer. If in doubt, check +the generated assembler output, or disable optimizations. + +The string literal may contain format specifiers from the following list. For +each format specifier, an argument is expected which is inserted instead of +the format specifier before passing the assembly code line to the backend. + +<itemize> + <item><tt/%b/ - Numerical 8-bit value + <item><tt/%w/ - Numerical 16-bit value + <item><tt/%l/ - Numerical 32-bit value + <item><tt/%v/ - Assembler name of a global variable or function + <item><tt/%o/ - Stack offset of a local variable + <item><tt/%g/ - Assembler name of a C label + <item><tt/%s/ - The argument is converted to a string + <item><tt/%%/ - The % sign itself +</itemize><p> + +Using these format specifiers, you can access C <tt/#defines/, variables or +similar stuff from the inline assembler. For example, to load the value of +a C <tt/#define/ into the Y register, one would use + +<tscreen><verb> + #define OFFS 23 + __asm__ ("ldy #%b", OFFS); +</verb></tscreen> + +Or, to access a struct member of a static variable: + +<tscreen><verb> + typedef struct { + unsigned char x; + unsigned char y; + unsigned char color; + } pixel_t; + static pixel_t pixel; + __asm__ ("ldy #%b", offsetof(pixel_t, color)); + __asm__ ("lda %v,y", pixel); +</verb></tscreen> +<p> +The next example shows how to use global variables to exchange data between C +an assembler and how to handle assembler jumps: + +<tscreen><verb> + unsigned char globalSubA, globalSubB, globalSubResult; + + /* return a-b, return 255 if b>a */ + unsigned char sub (unsigned char a, unsigned char b) + { + globalSubA = a; + globalSubB = b; + __asm__ ("sec"); + __asm__ ("lda %v", globalSubA); + __asm__ ("sbc %v", globalSubB); + __asm__ ("bcs %g", jumpSubNoError); + __asm__ ("lda #$FF"); + jumpSubNoError: + __asm__ ("sta %v", globalSubResult); + return globalSubResult; + } +</verb></tscreen> +<p> + +Arrays can also be accessed: + +<tscreen><verb> + unsigned char globalSquareTable[] = { + 0, 1, 4, 9, 16, 25, 36, 49, 64, 81, + 100, 121, 144, 169, 196, 225 + }; + unsigned char globalSquareA, globalSquareResult; + + /* return a*a for a<16, else 255 */ + unsigned char square (unsigned char a) + { + if (a>15){ + return 255; + } + globalSquareA = a; + __asm__ ("ldx %v", globalSquareA); + __asm__ ("lda %v,x", globalSquareTable); + __asm__ ("sta %v", globalSquareResult); + return globalSquareResult; + } +</verb></tscreen> +<p> + +Note: Do not embed the assembler labels that are used as names of global +variables or functions into your asm statements. Code like this + +<tscreen><verb> + int foo; + int bar () { return 1; } + __asm__ ("lda _foo"); /* DON'T DO THAT! */ + ... + __asm__ ("jsr _bar"); /* DON'T DO THAT EITHER! */ +</verb></tscreen> +<p> + +may stop working if the way, the compiler generates these names is changed in +a future version. Instead use the format specifiers from the table above: + +<tscreen><verb> + __asm__ ("lda %v", foo); /* OK */ + ... + __asm__ ("jsr %v", bar); /* OK */ +</verb></tscreen> +<p> + + +<sect>Implementation-defined behavior<p> + +This section describes the behavior of cc65 when the standard describes the +behavior as implementation-defined. + +(to be done) + +<sect>Bugs/Feedback<p> + +If you have problems using the compiler, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +This is the original compiler copyright: + +<tscreen><verb> +-------------------------------------------------------------------------- + -*- Mode: Text -*- + + This is the copyright notice for RA65, LINK65, LIBR65, and other + Atari 8-bit programs. Said programs are Copyright 1989, by John R. + Dunning. All rights reserved, with the following exceptions: + + Anyone may copy or redistribute these programs, provided that: + + 1: You don't charge anything for the copy. It is permissable to + charge a nominal fee for media, etc. + + 2: All source code and documentation for the programs is made + available as part of the distribution. + + 3: This copyright notice is preserved verbatim, and included in + the distribution. + + You are allowed to modify these programs, and redistribute the + modified versions, provided that the modifications are clearly noted. + + There is NO WARRANTY with this software, it comes as is, and is + distributed in the hope that it may be useful. + + This copyright notice applies to any program which contains + this text, or the refers to this file. + + This copyright notice is based on the one published by the Free + Software Foundation, sometimes known as the GNU project. The idea + is the same as theirs, ie the software is free, and is intended to + stay that way. Everybody has the right to copy, modify, and re- + distribute this software. Nobody has the right to prevent anyone + else from copying, modifying or redistributing it. + +-------------------------------------------------------------------------- +</verb></tscreen> + +Small parts of the compiler (parts of the preprocessor and main parser) are +still covered by this copyright. The main portion is covered by the usual +cc65 license, which reads: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/cl65.sgml b/doc/cl65.sgml new file mode 100644 index 000000000..a574049cc --- /dev/null +++ b/doc/cl65.sgml @@ -0,0 +1,316 @@ +<!doctype linuxdoc system> + +<article> +<title>cl65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>01.08.2000, 27.11.2000, 02.10.2001 + +<abstract> +cl65 is the compile & link utility for cc65, the 6502 C compiler. It was +designed as a smart frontend for the C compiler (cc65), the assembler (ca65), +the object file converter (co65), and the linker (ld65). +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the +full power of the tools when calling them through cl65, most features are +available, and the use of cl65 is much simpler. + + +<sect>Basic Usage<p> + +The cl65 compile and link utility may be used to convert, compile, assemble +and link files. While the separate tools do just one step, cl65 knows how to +build object files from C files (by calling the compiler, then the assembler) +and other things. + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: cl65 [options] file [...] +Short options: + -c Compile and assemble but don't link + -d Debug mode + -g Add debug info + -h Help (this text) + -l name Create an assembler listing file + -m name Create a map file + -mm model Set the memory model + -o name Name the output file + -r Enable register variables + -t sys Set the target system + -u sym Force an import of symbol `sym' + -v Verbose mode + -vm Verbose map file + -C name Use linker config file + -Cl Make local variables static + -D sym[=defn] Define a preprocessor symbol + -I dir Set a compiler include directory path + -L path Specify a library search path + -Ln name Create a VICE label file + -O Optimize code + -Oi Optimize code, inline functions + -Or Optimize code, honour the register keyword + -Os Optimize code, inline known C funtions + -S Compile but don't assemble and link + -T Include source as comment + -V Print the version number + -W name[,...] Supress compiler warnings + -Wa options Pass options to the assembler + -Wl options Pass options to the linker + +Long options: + --add-source Include source as comment + --asm-args options Pass options to the assembler + --asm-define sym[=v] Define an assembler symbol + --asm-include-dir dir Set an assembler include directory + --bin-include-dir dir Set an assembler binary include directory + --bss-label name Define and export a BSS segment label + --bss-name seg Set the name of the BSS segment + --cc-args options Pass options to the compiler + --cfg-path path Specify a config file search path + --check-stack Generate stack overflow checks + --code-label name Define and export a CODE segment label + --code-name seg Set the name of the CODE segment + --codesize x Accept larger code by factor x + --config name Use linker config file + --cpu type Set cpu type + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --data-label name Define and export a DATA segment label + --data-name seg Set the name of the DATA segment + --debug Debug mode + --debug-info Add debug info + --feature name Set an emulation feature + --force-import sym Force an import of symbol `sym' + --forget-inc-paths Forget include search paths (compiler) + --help Help (this text) + --include-dir dir Set a compiler include directory path + --ld-args options Pass options to the linker + --lib file Link this library + --lib-path path Specify a library search path + --list-targets List all available targets + --listing name Create an assembler listing file + --list-bytes n Number of bytes per assembler listing line + --mapfile name Create a map file + --memory-model model Set the memory model + --module Link as a module + --module-id id Specify a module id for the linker + --o65-model model Override the o65 model + --obj file Link this object file + --obj-path path Specify an object file search path + --register-space b Set space available for register variables + --register-vars Enable register variables + --rodata-name seg Set the name of the RODATA segment + --signed-chars Default characters are signed + --standard std Language standard (c89, c99, cc65) + --start-addr addr Set the default start address + --static-locals Make local variables static + --target sys Set the target system + --version Print the version number + --verbose Verbose mode + --zeropage-label name Define and export a ZEROPAGE segment label + --zeropage-name seg Set the name of the ZEROPAGE segment +--------------------------------------------------------------------------- +</verb></tscreen> + +Most of the options have the same meaning than the corresponding compiler, +assembler or linker option. See the documentation for these tools for an +explanation. If an option is available for more than one of the tools, it +is set for all tools, where it is available. One example for this is <tt/-v/: +The compiler, the assembler and the linker are all called with the <tt/-v/ +switch. + +There are a few remaining options that control the behaviour of cl65: + +<descrip> + + <tag><tt>-S</tt></tag> + + This option forces cl65 to stop after the assembly step. This means that + C files are translated into assembler files, but nothing more is done. + Assembler files, object files and libraries given on the command line + are ignored. + + + <tag><tt>-c</tt></tag> + + This options forces cl65 to stop after the assembly step. This means + that C and assembler files given on the command line are translated into + object files, but there is no link step, and object files and libraries + given on the command line are ignored. + + + <tag><tt>-o name</tt></tag> + + The -o option is used for the target name in the final step. This causes + problems, if the linker will not be called, and there are several input + files on the command line. In this case, the name given with -o will be + used for all of them, which makes the option pretty useless. You + shouldn't use -o when more than one output file is created. + + + <tag><tt>-t sys, --target sys</tt></tag> + + The default for this option is different from the compiler and linker in the + case that the option is missing: While the other tools (compiler, assembler + and linker) will use the "none" system settings by default, cl65 will use + the C64 as a target system by default. This was chosen since most people + seem to use cc65 to develop for the C64. + + <tag><tt>-Wa options, --asm-args options</tt></tag> + + Pass options directly to the assembler. This may be used to pass options + that aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the + assembler. Beware: Passing arguments directly to the assembler may interfere + with some of the defaults, because cl65 doesn't parse the options passed. So + if cl65 supports an option by itself, do not pass this option to the + assembler by means of the <tt/-Wa/ switch. + + <tag><tt>-Wc options, --cc-args options</tt></tag> + + Pass options directly to the compiler. This may be used to pass options + that aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the + compiler. Beware: Passing arguments directly to the compiler may interfere + with some of the defaults, because cl65 doesn't parse the options passed. So + if cl65 supports an option by itself, do not pass this option to the + compiler by means of the <tt/-Wc/ switch. + + <tag><tt>-Wl options, --ld-args options</tt></tag> + + Pass options directly to the linker. This may be used to pass options that + aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the linker. + Beware: Passing arguments directly to the linker may interfere with some of + the defaults, because cl65 doesn't parse the options passed. So if cl65 + supports an option by itself, do not pass this option to the linker by means + of the <tt/-Wl/ switch. + +</descrip> + + + +<sect>More usage<p> + +Since cl65 was created to simplify the use of the cc65 development +package, it tries to be smart about several things. + +<itemize> + +<item> If you don't give a target system on the command line, cl65 + defaults to the C64. + +<item> When linking, cl65 will supply the names of the startup file and + library for the target system to the linker, so you don't have to do + that. + +<item> If the final step is the linker, and the name of the output file was + not explicitly given, cl65 will use the name of the first input file + without the extension, provided that the name of this file has an + extension. So you don't need to name the executable name in most + cases, just give the name of your "main" file as first input file. +</itemize> + +The command line is parsed from left to right, and the actual processing tool +(compiler, assembler, ...) is invoked whenever a file name is encountered. +This means that only the options to the left of a file name are in effect when +this file is processed. It does also mean that you're able to specify +different options for different files on the command line. As an example. + +<tscreen><verb> + cl65 -Oirs main.c -O -g module.c +</verb></tscreen> + +translates main.c with full optimization and module.c with less optimization +and debug info enabled. + +The type of an input file is derived from its extension: + +<itemize> +<item>C files: <tt/.c/ +<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/ +<item>Object files: <tt/.o/ <tt/.obj/ +<item>Libraries: <tt/.a/, <tt/.lib/ +<item>GEOS resource files: <tt/.grc/ +<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/ +</itemize> + +Please note that the program cannot handle input files with unknown file +extensions. + + +<sect>Examples<p> + +The morse trainer software, which consists of one C file (morse.c) and one +assembler file (irq.s) will need the following separate steps to compile +into an executable named morse: + +<tscreen><verb> + cc65 -g -Oi -t c64 morse.c + ca65 -g morse.s + ca65 -g irq.s + ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib +</verb></tscreen> + +When using cl65, this is simplified to + +<tscreen><verb> + cl65 -g -Oi morse.c irq.s +</verb></tscreen> + +As a general rule, you may use cl65 instead of cc65 at most times, +especially in makefiles to build object files directly from C files. Use + +<tscreen><verb> + .c.o: + cl65 -g -Oi $< +</verb></tscreen> + +to do this. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the utility, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + diff --git a/doc/co65.sgml b/doc/co65.sgml new file mode 100644 index 000000000..126ed56fd --- /dev/null +++ b/doc/co65.sgml @@ -0,0 +1,353 @@ +<!doctype linuxdoc system> + +<article> +<title>co65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>12.02.2003 + +<abstract> +co65 is an object file conversion utility. It converts o65 object files into +the native object file format used by the cc65 tool chain. Since o65 is the +file format used by cc65 for loadable drivers, the co65 utility allows (among +other things) to link drivers statically to the generated executables instead +of loading them from disk. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +co65 is an object file conversion utility. It converts o65 object files into +assembler files, which may be translated by ca65 to generate object files in +the native object file format used by the cc65 tool chain. + +Since loadable drivers used by the library that comes with cc65 use the o65 +relocatable object code format, using the co65 utility allows to link these +drivers statically. This enables the use of these drivers without loading +additional files from a disk or other secondary storage. + +Another use would be to link object files generated by other development tools +to projects using the cc65 tool chain, but this has not been tested until now, +since such tools are currently rare. + + + +<sect>Usage<p> + +The co65 utility converts one o65 file per run into one assembler files in +ca65 format. The utility tries to autodetect the type of the o65 input file +using the operating system identifier contained in the o65 option list. + + +<sect1>Command line option overview<p> + +The converter may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: co65 [options] file +Short options: + -V Print the version number + -g Add debug info to object file + -h Help (this text) + -m model Override the o65 model + -n Don't generate an output file + -o name Name the output file + -v Increase verbosity + +Long options: + --bss-label name Define and export a BSS segment label + --bss-name seg Set the name of the BSS segment + --code-label name Define and export a CODE segment label + --code-name seg Set the name of the CODE segment + --data-label name Define and export a DATA segment label + --data-name seg Set the name of the DATA segment + --debug-info Add debug info to object file + --help Help (this text) + --no-output Don't generate an output file + --o65-model model Override the o65 model + --verbose Increase verbosity + --version Print the version number + --zeropage-label name Define and export a ZEROPAGE segment label + --zeropage-name seg Set the name of the ZEROPAGE segment +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--bss-label name</tt></tag> + + Set the label used to mark the start of the bss segment. When this option is + given, the label is also exported and may be accessed from other code. When + accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the bss segment, there's no need to + use this option. + + + <tag><tt>--bss-name seg</tt></tag> + + Set the name of the bss segment. The default name is "BSS" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--code-label name</tt></tag> + + Set the label used to mark the start of the code segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the code segment, there's no need to + use this option. + + + <tag><tt>--code-name seg</tt></tag> + + Set the name of the code segment. The default name is "CODE" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--data-label name</tt></tag> + + Set the label used to mark the start of the data segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the data segment, there's no need to + use this option. + + + <tag><tt>--data-name seg</tt></tag> + + Set the name of the data segment. The default name is "DATA" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere mortals. + Currently the converter does only accept cc65 loadable modules generated by + ld65 when not in debug mode. Please note that correct conversion has never + been tested for o65 files from other sources, so be careful when using + <tt/-d/. + + + <tag><tt>-g, --debug-info</tt></tag> + + This will cause the converter to insert a <tt/.DEBUGINFO/ command into the + generated assembler code. This will cause the assembler to include all + symbols in a special section in the object file. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-m model, --o65-model model</tt></tag> + + Set an o65 model. This option changes the way, output is generated for the + given o65 file. For example, cc65 loadable drivers have a zero page segment, + but this segment must not be defined in the file itself, because the + standard module loader will overlay it with the zeropage space used by the + application that loads this module. So instead of allocating space in the + zero page segment, the converter will reference the start of the zero page + area used by the application. + + Currently, the following models are defined: + + <itemize> + <item>lunix + <item>os/a65 + <item>cc65-module + </itemize> + + The default is to autodetect the model to use from the input file, so + there's rarely a need to use this option. + + + <tag><tt>-n, --no-output</tt></tag> + + Don't do the actual conversion, just read in the o65 file checking for + problems. This option may be used in conjunction with <tt/--verbose/ to + view some information about the input file. + + + <tag><tt>-o name</tt></tag> + + Specify the name of the output file. If you don't specify a name, the + name of the o65 input file is used, with the extension replaced by ".s". + + + <tag><tt>-v, --verbose</tt></tag> + + Using this option, the converter will be somewhat more verbose and print + some information about the o65 input file (among other things). You may use + this option together with <tt/--no-output/ to just get the o65 info. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. + + + <tag><tt>--zeropage-label name</tt></tag> + + Set the label used to mark the start of the zeropage segment. When this + option is given, the label is also exported and may be accessed from other + code. When accessing such a label from C code, be sure to include the + leading underscore. If you don't need to access the zeropage segment, + there's no need to use this option. + + + <tag><tt>--zeropage-name seg</tt></tag> + + Set the name of the zeropage segment. The default name is "ZEROPAGE" which is + compatible with the standard ld65 linker configurations. + +</descrip> + + +<sect>Input and output<p> + +The converter will accept one o65 file per invocation and create a file with +the same base name, but with the extension replaced by ".s". The output +file contains assembler code suitable for the use with the ca65 macro +assembler. + + +<sect>Converting loadable drivers<p> + +<sect1>Differences between static linking and runtime loading<p> + +One main use of the utility is conversion of loadable drivers, so they may be +linked statically to an application. Statically linking will cause a few +things to be different from runtime loading: + +<itemize> + +<item> Without changing the segment names, all segments take the default + names used by the standard linker configurations. This means that the + driver code is no longer contingous in memory, instead the code + segment is placed somewhere in between all other code segments, the + data segment is placed with all other data segments and so on. If the + driver doesn't do strange things this shouldn't be a problem. + +<item> With statically linked code, data and bss segments will get intialized + once (when the application is loaded), while a loadable driver will + get its initialization each time the driver is loaded into memory + (which may be more than once in the lifetime of a program). It depends + on the driver if this is a problem. Currently, most drivers supplied + with cc65 behave correctly when linked statically. + +</itemize> + + +<sect1>Additional requirements<p> + +All loadable drivers used by cc65 have a header and a jump table at the start +of the code segment. The header is needed to detect the driver (it may also +contain some data that is necessary to access the driver). The jump table is +used to access the functions in the driver code. + +When loading a driver at runtime, the load address of the driver is also the +address of the code segment, so the locations of the header and jump table are +known. However, when linking the driver statically, it is up to the programmer +to provide this information to the driver API. + +For this purpose, it is necessary to define a code segment label that can be +accessed from the outside later. Please note that the converter does currently +<em/not/ create such a label without being ordered to do so, even if the input +file is a cc65 module. + +To create such a label, use the <tt/--code-label/ option when calling the +converter. Be sure to begin the label with a leading underscore when accessing +it from C code. In your code, define an arbitrary variable with this name. Use +the address of this variable as the address of the code segment of the driver. +Be sure to never modify the variable which is in reality the start of your +driver! + + +<sect1>Example - Convert and link a graphics driver<p> + +As an example, here are some instructions to convert and use the c64-hi.tgi +graphics driver: + +First, convert the driver, generating a label named "_c64_hi" for the code +segment. Use the assembler to generate an object file from the assembler +output. + + <tscreen><verb> + co65 --code-label _c64_hi c64-hi.tgi + ca65 c64-hi.s + </verb></tscreen> + +Next, change your C code to declare a variable that is actually the address +of the driver: + + <tscreen><verb> + extern void c64_hi[]; + </verb></tscreen> + +Instead of loading and unloading the driver, change the code to install and +uninstall the driver, which will be already in memory after linking: + + <tscreen><verb> + /* Install the driver */ + tgi_install (c64_hi); + + ... + + /* Uninstall the driver */ + tgi_uninstall (); + </verb></tscreen> + +Don't forget to link the driver object file to your application, otherwise you +will get an "undefined external" error for the _c64_hi symbol. + + + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the code, I would be glad to hear from you. +Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries +and/or sources the following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/coding.sgml b/doc/coding.sgml new file mode 100644 index 000000000..1aa454f12 --- /dev/null +++ b/doc/coding.sgml @@ -0,0 +1,308 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 coding hints +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-12-03, 2009-09-01 + +<abstract> +How to generate the most effective code with cc65. +</abstract> + + + +<sect>Use prototypes<p> + +This will not only help to find errors between separate modules, it will also +generate better code, since the compiler must not assume that a variable sized +parameter list is in place and must not pass the argument count to the called +function. This will lead to shorter and faster code. + + + +<sect>Don't declare auto variables in nested function blocks<p> + +Variable declarations in nested blocks are usually a good thing. But with +cc65, there is a drawback: Since the compiler generates code in one pass, it +must create the variables on the stack each time the block is entered and +destroy them when the block is left. This causes a speed penalty and larger +code. + + + +<sect>Remember that the compiler does no high level optimizations<p> + +The compiler needs hints from you about the code to generate. It will try to +optimize the generated code, but follow the outline you gave in your C +program. So for example, when accessing indexed data structures, get a pointer +to the element and use this pointer instead of calculating the index again and +again. If you want to have your loops unrolled, or loop invariant code moved +outside the loop, you have to do that yourself. + + + +<sect>Longs are slow!<p> + +While long support is necessary for some things, it's really, really slow on +the 6502. Remember that any long variable will use 4 bytes of memory, and any +operation works on double the data compared to an int. + + + +<sect>Use unsigned types wherever possible<p> + +The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So +sign extension, test of signedness etc. has to be done with extra code. As a +consequence, the code to handle signed operations is usually a bit larger and +slower than the same code for unsigned types. + + + +<sect>Use chars instead of ints if possible<p> + +While in arithmetic operations, chars are immidiately promoted to ints, they +are passed as chars in parameter lists and are accessed as chars in variables. +The code generated is usually not much smaller, but it is faster, since +accessing chars is faster. For several operations, the generated code may be +better if intermediate results that are known not to be larger than 8 bit are +casted to chars. + +You should especially use unsigned chars for loop control variables if the +loop is known not to execute more than 255 times. + + + +<sect>Make the size of your array elements one of 1, 2, 4, 8<p> + +When indexing into an array, the compiler has to calculate the byte offset +into the array, which is the index multiplied by the size of one element. When +doing the multiplication, the compiler will do a strength reduction, that is, +replace the multiplication by a shift if possible. For the values 2, 4 and 8, +there are even more specialized subroutines available. So, array access is +fastest when using one of these sizes. + + + +<sect>Expressions are evaluated from left to right<p> + +Since cc65 is not building an explicit expression tree when parsing an +expression, constant subexpressions may not be detected and optimized properly +if you don't help. Look at this example: + +<tscreen><verb> + #define OFFS 4 + int i; + i = i + OFFS + 3; +</verb></tscreen> + +The expression is parsed from left to right, that means, the compiler sees 'i', +and puts it contents into the secondary register. Next is OFFS, which is +constant. The compiler emits code to add a constant to the secondary register. +Same thing again for the constant 3. So the code produced contains a fetch +of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the +compiler does not see, that "OFFS + 3" is a constant for itself, since it does +its evaluation from left to right. There are some ways to help the compiler +to recognize expression like this: + +<enum> + +<item>Write "i = OFFS + 3 + i;". Since the first and second operand are +constant, the compiler will evaluate them at compile time reducing the code to +a fetch, one addition (secondary + constant) and one store. + +<item>Write "i = i + (OFFS + 3)". When seeing the opening parenthesis, the +compiler will start a new expression evaluation for the stuff in the braces, +and since all operands in the subexpression are constant, it will detect this +and reduce the code to one fetch, one addition and one store. + +</enum> + + +<sect>Use the preincrement and predecrement operators<p> + +The compiler is not always smart enough to figure out, if the rvalue of an +increment is used or not. So it has to save and restore that value when +producing code for the postincrement and postdecrement operators, even if this +value is never used. To avoid the additional overhead, use the preincrement +and predecrement operators if you don't need the resulting value. That means, +use + +<tscreen><verb> + ... + ++i; + ... +</verb></tscreen> + + instead of + +<tscreen><verb> + ... + i++; + ... +</verb></tscreen> + + + +<sect>Use constants to access absolute memory locations<p> + +The compiler produces optimized code, if the value of a pointer is a constant. +So, to access direct memory locations, use + +<tscreen><verb> + #define VDC_STATUS 0xD601 + *(char*)VDC_STATUS = 0x01; +</verb></tscreen> + +That will be translated to + +<tscreen><verb> + lda #$01 + sta $D601 +</verb></tscreen> + +The constant value detection works also for struct pointers and arrays, if the +subscript is a constant. So + +<tscreen><verb> + #define VDC ((unsigned char*)0xD600) + #define STATUS 0x01 + VDC[STATUS] = 0x01; +</verb></tscreen> + +will also work. + +If you first load the constant into a variable and use that variable to access +an absolute memory location, the generated code will be much slower, since the +compiler does not know anything about the contents of the variable. + + + +<sect>Use initialized local variables<p> + +Initialization of local variables when declaring them gives shorter and faster +code. So, use + +<tscreen><verb> + int i = 1; +</verb></tscreen> + +instead of + +<tscreen><verb> + int i; + i = 1; +</verb></tscreen> + +But beware: To maximize your savings, don't mix uninitialized and initialized +variables. Create one block of initialized variables and one of uniniitalized +ones. The reason for this is, that the compiler will sum up the space needed +for uninitialized variables as long as possible, and then allocate the space +once for all these variables. If you mix uninitialized and initialized +variables, you force the compiler to allocate space for the uninitialized +variables each time, it parses an initialized one. So do this: + +<tscreen><verb> + int i, j; + int a = 3; + int b = 0; +</verb></tscreen> + +instead of + +<tscreen><verb> + int i; + int a = 3; + int j; + int b = 0; +</verb></tscreen> + +The latter will work, but will create larger and slower code. + + + +<sect>Use the array operator [] even for pointers<p> + +When addressing an array via a pointer, don't use the plus and dereference +operators, but the array operator. This will generate better code in some +common cases. + +Don't use + +<tscreen><verb> + char* a; + char b, c; + char b = *(a + c); +</verb></tscreen> + +Use + +<tscreen><verb> + char* a; + char b, c; + char b = a[c]; +</verb></tscreen> + +instead. + + + +<sect>Use register variables with care<p> + +Register variables may give faster and shorter code, but they do also have an +overhead. Register variables are actually zero page locations, so using them +saves roughly one cycle per access. The calling routine may also use register +variables, so the old values have to be saved on function entry and restored +on exit. Saving an d restoring has an overhead of about 70 cycles per 2 byte +variable. It is easy to see, that - apart from the additional code that is +needed to save and restore the values - you need to make heavy use of a +variable to justify the overhead. + +As a general rule: Use register variables only for pointers that are +dereferenced several times in your function, or for heavily used induction +variables in a loop (with several 100 accesses). + +When declaring register variables, try to keep them together, because this +will allow the compiler to save and restore the old values in one chunk, and +not in several. + +And remember: Register variables must be enabled with <tt/-r/ or <tt/-Or/. + + + +<sect>Decimal constants greater than 0x7FFF are actually long ints<p> + +The language rules for constant numeric values specify that decimal constants +without a type suffix that are not in integer range must be of type long int +or unsigned long int. So a simple constant like 40000 is of type long int! +This is often unexpected and may cause an expression to be evaluated with 32 +bits. While in many cases the compiler takes care about it, in some places it +can't. So be careful when you get a warning like + +<tscreen><verb> + test.c(7): Warning: Constant is long +</verb></tscreen> + +Use the <tt/U/, <tt/L/ or <tt/UL/ suffixes to tell the compiler the desired +type of a numeric constant. + + + +<sect>Access to parameters in variadic functions is expensive<p> + +Since cc65 has the "wrong" calling order, the location of the fixed parameters +in a variadic function (a function with a variable parameter list) depends on +the number and size of variable arguments passed. Since this number and size +is unknown at compile time, the compiler will generate code to calculate the +location on the stack when needed. + +Because of this additional code, accessing the fixed parameters in a variadic +function is much more expensive than access to parameters in a "normal" +function. Unfortunately, this additional code is also invisible to the +programmer, so it is easy to forget. + +As a rule of thumb, if you access such a parameter more than once, you should +think about copying it into a normal variable and using this variable instead. + + +</article> + diff --git a/doc/customizing.sgml b/doc/customizing.sgml new file mode 100644 index 000000000..23cf8c5e8 --- /dev/null +++ b/doc/customizing.sgml @@ -0,0 +1,730 @@ +<!doctype linuxdoc system> + +<article> +<title>Defining a Custom cc65 Target +<author>Bruce Reidenbach +<date>2010-02-22 + +<abstract> +This section provides step-by-step instructions on how to use the cc65 +toolset for a custom hardware platform (a target system not currently +supported by the cc65 library set). +</abstract> + +<!-- Table of contents --> + +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +The cc65 toolset provides a set of pre-defined libraries that allow the +user to target the executable image to a variety of hardware platforms. +In addition, the user can create a customized environment so that the +executable can be targeted to a custom platform. The following +instructions provide step-by-step instructions on how to customize the +toolset for a target that is not supported by the standard cc65 +installation. + +The platform used in this example is a Xilinx Field Programmable Gate +Array (FPGA) with an embedded 65C02 core. The processor core supports +the additional opcodes/addressing modes of the 65SC02, along with the +STP and WAI instructions. These instructions will create a set of files +to create a custom target, named SBC, for <bf>S</bf>ingle <bf>B</bf>oard +<bf>C</bf>omputer. + +<sect>System Memory Map Definition<p> + +The targeted system uses block RAM contained on the XILINX FPGA for the +system memory (both RAM and ROM). The block RAMs are available in +various aspect ratios, and they will be used in this system as 2K*8 +devices. There will be two RAMs used for data storage, starting at +location $0000 and growing upwards. There will be one ROM (realized as +initialized RAM) used code storage, starting at location $FFFF and +growing downwards. + +The cc65 toolset requires a memory configuration file to define the +memory that is available to the cc65 run-time environment, which is +defined as follows: + +<tscreen><code> +MEMORY { + ZP: start = $0, size = $100, type = rw, define = yes; + RAM: start = $200, size = $0E00, define = yes; + ROM: start = $F800, size = $0800, file = %O; +} +</code></tscreen> + +ZP defines the available zero page locations, which in this case starts +at $0 and has a length of $100. Keep in mind that certain systems may +require access to some zero page locations, so the starting address may +need to be adjusted accordingly to prevent cc65 from attempting to reuse +those locations. Also, at a minimum, the cc65 run-time environment uses +26 zero page locations, so the smallest zero page size that can be +specified is $1A. The usable RAM memory area begins after the 6502 +stack storage in page 1, so it is defined as starting at location $200 +and filling the remaining 4K of space (4096 - 2 * +256 = 3584 = $0E00). The 2K of ROM space begins at +address $F800 and goes to $FFFF (size = $0800). + +Next, the memory segments within the memory devices need to be defined. +A standard segment definition is used, with one notable exception. The +interrupt and reset vector locations need to be defined at locations +$FFFA through $FFFF. A special segment named VECTORS is defined that +resides at these locations. Later, the interrupt vector map will be +created and placed in the VECTORS segment, and the linker will put these +vectors at the proper memory locations. The segment definition is: + +<tscreen><code> +SEGMENTS { + ZEROPAGE: load = ZP, type = zp, define = yes; + DATA: load = ROM, type = rw, define = yes, run = RAM; + BSS: load = RAM, type = bss, define = yes; + HEAP: load = RAM, type = bss, optional = yes; + STARTUP: load = ROM, type = ro; + INIT: load = ROM, type = ro, optional = yes; + CODE: load = ROM, type = ro; + RODATA: load = ROM, type = ro; + VECTORS: load = ROM, type = ro, start = $FFFA; +} +</code></tscreen> + +The meaning of each of these segments is as follows. + +<p><tt> ZEROPAGE: </tt>Data in page 0, defined by ZP as starting at $0 with length $100 +<p><tt> DATA: </tt>Initialized data that can be modified by the program, stored in RAM +<p><tt> BSS: </tt>Uninitialized data stored in RAM (used for variable storage) +<p><tt> HEAP: </tt>Uninitialized C-level heap storage in RAM, optional +<p><tt> STARTUP: </tt>The program initialization code, stored in ROM +<p><tt> INIT: </tt>The code needed to initialize the system, stored in ROM +<p><tt> CODE: </tt>The program code, stored in ROM +<p><tt> RODATA: </tt>Initialized data that cannot be modified by the program, stored in ROM +<p><tt> VECTORS: </tt>The interrupt vector table, stored in ROM at location $FFFA + +A note about initialized data: any variables that require an initial +value, such as external (global) variables, require that the initial +values be stored in the ROM code image. However, variables stored in +ROM cannot change; therefore the data must be moved into variables that +are located in RAM. Specifying <tt>run = RAM</tt> as part of +the DATA segment definition will indicate that those variables will +require their initialization value to be copied via a call to the +<tt>copydata</tt> routine in the startup assembly code. In addition, +there are system level variables that will need to be initialized as +well, especially if the heap segment is used via a C-level call to +<tt>malloc ()</tt>. + +The final section of the definition file contains the data constructors +and destructors used for system startup. In addition, if the heap is +used, the maximum C-level stack size needs to be defined in order for +the system to be able to reliably allocate blocks of memory. The stack +size selection must be greater than the maximum amount of storage +required to run the program, keeping in mind that the C-level subroutine +call stack and all local variables are stored in this stack. The +<tt>FEATURES</tt> section defines the required constructor/destructor +attributes and the <tt>SYMBOLS</tt> section defines the stack size. The +constructors will be run via a call to <tt>initlib</tt> in the startup +assembly code and the destructors will be run via an assembly language +call to <tt>donelib</tt> during program termination. + +<tscreen><code> +FEATURES { + CONDES: segment = STARTUP, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = STARTUP, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} + +SYMBOLS { + # Define the stack size for the application + __STACKSIZE__: value = $0200, weak = yes; +} +</code></tscreen> + +These definitions are placed in a file named "sbc.cfg" +and are referred to during the ld65 linker stage. + +<sect>Startup Code Definition<p> + +In the cc65 toolset, a startup routine must be defined that is executed +when the CPU is reset. This startup code is marked with the STARTUP +segment name, which was defined in the system configuration file as +being in read only memory. The standard convention used in the +predefined libraries is that this code is resident in the crt0 module. +For this custom system, all that needs to be done is to perform a little +bit of 6502 housekeeping, set up the C-level stack pointer, initialize +the memory storage, and call the C-level routine <tt>main ()</tt>. +The following code was used for the crt0 module, defined in the file +"crt0.s": + +<tscreen><code> +; --------------------------------------------------------------------------- +; crt0.s +; --------------------------------------------------------------------------- +; +; Startup code for cc65 (Single Board Computer version) + +.export _init, _exit +.import _main + +.export __STARTUP__ : absolute = 1 ; Mark as startup +.import __RAM_START__, __RAM_SIZE__ ; Linker generated + +.import copydata, zerobss, initlib, donelib + +.include "zeropage.inc" + +; --------------------------------------------------------------------------- +; Place the startup code in a special segment + +.segment "STARTUP" + +; --------------------------------------------------------------------------- +; A little light 6502 housekeeping + +_init: LDX #$FF ; Initialize stack pointer to $01FF + TXS + CLD ; Clear decimal mode + +; --------------------------------------------------------------------------- +; Set cc65 argument stack pointer + + LDA #<(__RAM_START__ + __RAM_SIZE__) + STA sp + LDA #>(__RAM_START__ + __RAM_SIZE__) + STA sp+1 + +; --------------------------------------------------------------------------- +; Initialize memory storage + + JSR zerobss ; Clear BSS segment + JSR copydata ; Initialize DATA segment + JSR initlib ; Run constructors + +; --------------------------------------------------------------------------- +; Call main() + + JSR _main + +; --------------------------------------------------------------------------- +; Back from main (this is also the _exit entry): force a software break + +_exit: JSR donelib ; Run destructors + BRK +</code></tscreen> + +The following discussion explains the purpose of several important +assembler level directives in this file. + +<tscreen><verb> +.export _init, _exit +</verb></tscreen> + +This line instructs the assembler that the symbols <tt>_init</tt> and +<tt>_exit</tt> are to be accessible from other modules. In this +example, <tt>_init</tt> is the location that the CPU should jump to when +reset, and <tt>_exit</tt> is the location that will be called when the +program is finished. + +<tscreen><verb> +.import _main +</verb></tscreen> + +This line instructs the assembler to import the symbol <tt>_main</tt> +from another module. cc65 names all C-level routines as +{underscore}{name} in assembler, thus the <tt>main ()</tt> routine +in C is named <tt>_main</tt> in the assembler. This is how the startup +code will link to the C-level code. + +<tscreen><verb> +.export __STARTUP__ : absolute = 1 ; Mark as startup +</verb></tscreen> + +This line marks this code as startup code (code that is executed when +the processor is reset), which will then be automatically linked into +the executable code. + +<tscreen><verb> +.import __RAM_START__, __RAM_SIZE__ ; Linker generated +</verb></tscreen> + +This line imports the RAM starting address and RAM size constants, which +are used to initialize the cc65 C-level argument stack pointer. + +<tscreen><verb> +.segment "STARTUP" +</verb></tscreen> + +This line instructs the assembler that the code is to be placed in the +STARTUP segment of memory. + +<tscreen><verb> + JSR zerobss ; Clear BSS segment + JSR copydata ; Initialize DATA segment + JSR initlib ; Run constructors +</verb></tscreen> + +These three lines initialize the external (global) and system +variables. The first line sets the BSS segment -- the memory locations +used for external variables -- to 0. The second line copies the +initialization value stored in ROM to the RAM locations used for +initialized external variables. The last line runs the constructors +that are used to initialize the system run-time variables. + +<tscreen><verb> + JSR _main +</verb></tscreen> + +This is the actual call to the C-level <tt>main ()</tt> routine, +which is called after the startup code completes. + +<tscreen><verb> +_exit: JSR donelib ; Run destructors + BRK +</verb></tscreen> + +This is the code that will be executed when <tt>main ()</tt> +terminates. The first thing that must be done is run the destructors +via a call to <tt>donelib</tt>. Then the program can terminate. In +this example, the program is expected to run forever. Therefore, there +needs to be a way of indicating when something has gone wrong and the +system needs to be shut down, requiring a restart only by a hard reset. +The BRK instruction will be used to indicate a software fault. This is +advantageous because cc65 uses the BRK instruction as the fill byte in +the final binary code. In addition, the hardware has been designed to +force the data lines to $00 for all illegal memory accesses, thereby +also forcing a BRK instruction into the CPU. + +<sect>Custom Run-Time Library Creation<p> + +The next step in customizing the cc65 toolset is creating a run-time +library for the targeted hardware. The easiest way to do this is to +modify a standard library from the cc65 distribution. In this example, +there is no console I/O, mouse, joystick, etc. in the system, so it is +most appropriate to use the simplest library as the base, which is for +the Watara Supervision and is named "supervision.lib" in the +lib directory of the distribution. + +The only modification required is to replace the <tt>crt0</tt> module in +the supervision.lib library with custom startup code. This is simply +done by first copying the library and giving it a new name, compiling +the startup code with ca65, and finally using the ar65 archiver to +replace the module in the new library. The steps are shown below: + +<tscreen><verb> +$ copy "C:\Program Files\cc65\lib\supervision.lib" sbc.lib +$ ca65 crt0.s +$ ar65 a sbc.lib crt0.o +</verb></tscreen> + +<sect>Interrupt Service Routine Definition<p> + +For this system, the CPU is put into a wait condition prior to allowing +interrupt processing. Therefore, the interrupt service routine is very +simple: return from all valid interrupts. However, as mentioned +before, the BRK instruction is used to indicate a software fault, which +will call the same interrupt service routine as the maskable interrupt +signal IRQ. The interrupt service routine must be able to tell the +difference between the two, and act appropriately. + +The interrupt service routine shown below includes code to detect when a +BRK instruction has occurred and stops the CPU from further processing. +The interrupt service routine is in a file named +"interrupt.s". + +<tscreen><code> +; --------------------------------------------------------------------------- +; interrupt.s +; --------------------------------------------------------------------------- +; +; Interrupt handler. +; +; Checks for a BRK instruction and returns from all valid interrupts. + +.import _stop +.export _irq_int, _nmi_int + +.segment "CODE" + +.PC02 ; Force 65C02 assembly mode + +; --------------------------------------------------------------------------- +; Non-maskable interrupt (NMI) service routine + +_nmi_int: RTI ; Return from all NMI interrupts + +; --------------------------------------------------------------------------- +; Maskable interrupt (IRQ) service routine + +_irq_int: PHX ; Save X register contents to stack + TSX ; Transfer stack pointer to X + PHA ; Save accumulator contents to stack + INX ; Increment X so it points to the status + INX ; register value saved on the stack + LDA $100,X ; Load status register contents + AND #$10 ; Isolate B status bit + BNE break ; If B = 1, BRK detected + +; --------------------------------------------------------------------------- +; IRQ detected, return + +irq: PLA ; Restore accumulator contents + PLX ; Restore X register contents + RTI ; Return from all IRQ interrupts + +; --------------------------------------------------------------------------- +; BRK detected, stop + +break: JMP _stop ; If BRK is detected, something very bad + ; has happened, so stop running +</code></tscreen> + +The following discussion explains the purpose of several important +assembler level directives in this file. + +<tscreen><verb> +.import _stop +</verb></tscreen> + +This line instructs the assembler to import the symbol <tt>_stop</tt> +from another module. This routine will be called if a BRK instruction +is encountered, signaling a software fault. + +<tscreen><verb> +.export _irq_int, _nmi_int +</verb></tscreen> + +This line instructs the assembler that the symbols <tt>_irq_int</tt> and +<tt>_nmi_int</tt> are to be accessible from other modules. In this +example, the address of these symbols will be placed in the interrupt +vector table. + +<tscreen><verb> +.segment "CODE" +</verb></tscreen> + +This line instructs the assembler that the code is to be placed in the +CODE segment of memory. Note that because there are 65C02 mnemonics in +the assembly code, the assembler is forced to use the 65C02 instruction +set with the <tt>.PC02</tt> directive. + +The final step is to define the interrupt vector memory locations. +Recall that a segment named VECTORS was defined in the memory +configuration file, which started at location $FFFA. The addresses of +the interrupt service routines from "interrupt.s" along with +the address for the initialization code in crt0 are defined in a file +named "vectors.s". Note that these vectors will be placed in +memory in their proper little-endian format as: + +<p><tt> $FFFA - $FFFB:</tt> NMI interrupt vector (low byte, high byte) +<p><tt> $FFFC - $FFFD:</tt> Reset vector (low byte, high byte) +<p><tt> $FFFE - $FFFF:</tt> IRQ/BRK interrupt vector (low byte, high byte) + +using the <tt>.addr</tt> assembler directive. The contents of the file are: + +<tscreen><code> +; --------------------------------------------------------------------------- +; vectors.s +; --------------------------------------------------------------------------- +; +; Defines the interrupt vector table. + +.import _init +.import _nmi_int, _irq_int + +.segment "VECTORS" + +.addr _nmi_int ; NMI vector +.addr _init ; Reset vector +.addr _irq_int ; IRQ/BRK vector +</code></tscreen> + +The cc65 toolset will replace the address symbols defined here with the +actual addresses of the routines during the link process. + +<sect>Adding Custom Instructions<p> + +The cc65 instruction set only supports the WAI (Wait for Interrupt) and +STP (Stop) instructions when used with the 65816 CPU (accessed via the +--cpu command line option of the ca65 macro assembler). The 65C02 core +used in this example supports these two instructions, and in fact the +system benefits from the use of both the WAI and STP instructions. + +In order to use the WAI instruction in this case, a C routine named +"wait" was created that consists of the WAI opcode followed by +a subroutine return. It was convenient in this example to put the IRQ +interrupt enable in this subroutine as well, since interrupts should +only be enabled when the code is in this wait condition. + +For both the WAI and STP instructions, the assembler is +"fooled" into placing those opcodes into memory by inserting a +single byte of data that just happens to be the opcode for those +instructions. The assembly code routines are placed in a file, named +"wait.s", which is shown below: + +<tscreen><code> +; --------------------------------------------------------------------------- +; wait.s +; --------------------------------------------------------------------------- +; +; Wait for interrupt and return + +.export _wait, _stop + +; --------------------------------------------------------------------------- +; Wait for interrupt: Forces the assembler to emit a WAI opcode ($CB) +; --------------------------------------------------------------------------- + +.segment "CODE" + +.proc _wait: near + + CLI ; Enable interrupts +.byte $CB ; Inserts a WAI opcode + RTS ; Return to caller + +.endproc + +; --------------------------------------------------------------------------- +; Stop: Forces the assembler to emit a STP opcode ($DB) +; --------------------------------------------------------------------------- + +.proc _stop: near + +.byte $DB ; Inserts a STP opcode + +.endproc +</code></tscreen> + +The label <tt>_wait</tt>, when exported, can be called by using the +<tt>wait ()</tt> subroutine call in C. The section is marked as +code so that it will be stored in read-only memory, and the procedure is +tagged for 16-bit absolute addressing via the "near" +modifier. Similarly, the <tt>_stop</tt> routine can be called from +within the C-level code via a call to <tt>stop ()</tt>. In +addition, the routine can be called from assembly code by calling +<tt>_stop</tt> (as was done in the interrupt service routine). + +<sect>Hardware Drivers<p> + +Oftentimes, it can be advantageous to create small application helpers +in assembly language to decrease codespace and increase execution speed +of the overall program. An example of this would be the transfer of +characters to a FIFO (<bf>F</bf>irst-<bf>I</bf>n, +<bf>F</bf>irst-<bf>O</bf>ut) storage buffer for transmission over a +serial port. This simple action could be performed by an assembly +language driver which would execute much quicker than coding it in C. +The following discussion outlines a method of interfacing a C program +with an assembly language subroutine. + +The first step in creating the assembly language code for the driver is +to determine how to pass the C arguments to the assembly language +routine. The cc65 toolset allows the user to specify whether the data +is passed to a subroutine via the stack or by the processor registers by +using the <tt>__fastcall__</tt> function declaration (note that there +are two underscore characters in front of and two behind the +<tt>fastcall</tt> declaration). When <tt>__fastcall__</tt> is +specified, the rightmost argument in the function call is passed to the +subroutine using the 6502 registers instead of the stack. Note that if +there is only one argument in the function call, the execution overhead +required by the stack interface routines is completely avoided. + +Without <tt>__fastcall__</tt>, the argument is loaded in the A and X +registers and then pushed onto the stack via a call to <tt>pushax</tt>. +The first thing the subroutine does is retrieve the argument from the +stack via a call to <tt>ldax0sp</tt>, which copies the values into the A +and X. When the subroutine is finished, the values on the stack must be +popped off and discarded via a jump to <tt>incsp2</tt>, which includes +the RTS subroutine return command. This is shown in the following code +sample. + +Calling sequence: + +<tscreen><verb> + lda #<(L0001) ; Load A with the high order byte + ldx #>(L0001) ; Load X with the low order byte + jsr pushax ; Push A and X onto the stack + jsr _foo ; Call foo, i.e., foo (arg) +</verb></tscreen> + +Subroutine code: + +<tscreen><verb> +_foo: jsr ldax0sp ; Retrieve A and X from the stack + sta ptr ; Store A in ptr + stx ptr+1 ; Store X in ptr+1 + ... ; (more subroutine code goes here) + jmp incsp2 ; Pop A and X from the stack (includes return) +</verb></tscreen> + +If <tt>__fastcall__</tt> is specified, the argument is loaded into the A +and X registers as before, but the subroutine is then called +immediately. The subroutine does not need to retrieve the argument +since the value is already available in the A and X registers. +Furthermore, the subroutine can be terminated with an RTS statement +since there is no stack cleanup which needs to be performed. This is +shown in the following code sample. + +Calling sequence: + +<tscreen><verb> + lda #<(L0001) ; Load A with the high order byte + ldx #>(L0001) ; Load X with the low order byte + jsr _foo ; Call foo, i.e., foo (arg) +</verb></tscreen> + +Subroutine code: + +<tscreen><verb> +_foo: sta ptr ; Store A in ptr + stx ptr+1 ; Store X in ptr+1 + ... ; (more subroutine code goes here) + rts ; Return from subroutine +</verb></tscreen> + +The hardware driver in this example writes a string of character data to +a hardware FIFO located at memory location $1000. Each character is +read and is compared to the C string termination value ($00), which will +terminate the loop. All other character data is written to the FIFO. +For convenience, a carriage return/line feed sequence is automatically +appended to the serial stream. The driver defines a local pointer +variable which is stored in the zero page memory space in order to allow +for retrieval of each character in the string via the indirect indexed +addressing mode. + +The assembly language routine is stored in a file names +"rs232_tx.s" and is shown below: + +<tscreen><code> +; --------------------------------------------------------------------------- +; rs232_tx.s +; --------------------------------------------------------------------------- +; +; Write a string to the transmit UART FIFO + +.export _rs232_tx +.exportzp _rs232_data: near + +.define TX_FIFO $1000 ; Transmit FIFO memory location + +.zeropage + +_rs232_data: .res 2, $00 ; Reserve a local zero page pointer + +.segment "CODE" + +.proc _rs232_tx: near + +; --------------------------------------------------------------------------- +; Store pointer to zero page memory and load first character + + sta _rs232_data ; Set zero page pointer to string address + stx _rs232_data+1 ; (pointer passed in via the A/X registers) + ldy #00 ; Initialize Y to 0 + lda (_rs232_data) ; Load first character + +; --------------------------------------------------------------------------- +; Main loop: read data and store to FIFO until \0 is encountered + +loop: sta TX_FIFO ; Loop: Store character in FIFO + iny ; Increment Y index + lda (_rs232_data),y ; Get next character + bne loop ; If character == 0, exit loop + +; --------------------------------------------------------------------------- +; Append CR/LF to output stream and return + + lda #$0D ; Store CR + sta TX_FIFO + lda #$0A ; Store LF + sta TX_FIFO + rts ; Return + +.endproc +</code></tscreen> + +<sect>Hello World! Example<p> + +The following short example demonstrates programming in C using the cc65 +toolset with a custom run-time environment. In this example, a Xilinx +FPGA contains a UART which is connected to a 65c02 processor with FIFO +(<bf>F</bf>irst-<bf>I</bf>n, <bf>F</bf>irst-<bf>O</bf>ut) storage to +buffer the data. The C program will wait for an interrupt generated by +the receive UART and then respond by transmitting the string "Hello +World! " every time a question mark character is received via a +call to the hardware driver <tt>rs232_tx ()</tt>. The driver +prototype uses the <tt>__fastcall__</tt> extension to indicate that the +driver does not use the stack. The FIFO data interface is at address +$1000 and is defined as the symbolic constant <tt>FIFO_DATA</tt>. +Writing to <tt>FIFO_DATA</tt> transfers a byte of data into the transmit +FIFO for subsequent transmission over the serial interface. Reading +from <tt>FIFO_DATA</tt> transfers a byte of previously received data out +of the receive FIFO. The FIFO status data is at address $1001 and is +defined as the symbolic constant <tt>FIFO_STATUS</tt>. For convenience, +the symbolic constants <tt>TX_FIFO_FULL</tt> (which isolates bit 0 of +the register) and <tt>RX_FIFO_EMPTY</tt> (which isolates bit 1 of the +register) have been defined to read the FIFO status. + +The following C code is saved in the file "main.c". As this +example demonstrates, the run-time environment has been set up such that +all of the behind-the-scene work is transparent to the user. + +<tscreen><code> +#define FIFO_DATA (*(unsigned char *) 0x1000) +#define FIFO_STATUS (*(unsigned char *) 0x1001) + +#define TX_FIFO_FULL (FIFO_STATUS & 0x01) +#define RX_FIFO_EMPTY (FIFO_STATUS & 0x02) + +extern void wait (); +extern void __fastcall__ rs232_tx (char *str); + +int main () { + while (1) { // Run forever + wait (); // Wait for an RX FIFO interrupt + + while (RX_FIFO_EMPTY == 0) { // While the RX FIFO is not empty + if (FIFO_DATA == '?') { // Does the RX character = '?' + rs232_tx ("Hello World!"); // Transmit "Hello World!" + } // Discard any other RX characters + } + } + + return (0); // We should never get here! +} +</code></tscreen> + +<sect>Putting It All Together<p> + +The following commands will create a ROM image named "a.out" +that can be used as the initialization data for the Xilinx Block RAM +used for code storage: + +<tscreen><verb> +$ cc65 -t none -O --cpu 65sc02 main.c +$ ca65 --cpu 65sc02 main.s +$ ca65 --cpu 65sc02 rs232_tx.s +$ ca65 --cpu 65sc02 interrupt.s +$ ca65 --cpu 65sc02 vectors.s +$ ca65 --cpu 65sc02 wait.s +$ ld65 -C sbc.cfg -m main.map interrupt.o vectors.o wait.o rs232_tx.o + main.o sbc.lib +</verb></tscreen> + +During the C-level code compilation phase (<tt>cc65</tt>), assumptions +about the target system are disabled via the <tt>-t none</tt> command +line option. During the object module linker phase (<tt>ld65</tt>), the +target customization is enabled via inclusion of the <tt>sbc.lib</tt> +file and the selection of the configuration file via the <tt>-C +sbc.cfg</tt> command line option. + +The 65C02 core used most closely matches the cc65 toolset processor +named 65SC02 (the 65C02 extensions without the bit manipulation +instructions), so all the commands specify the use of that processor via +the <tt>--cpu 65sc02</tt> option. + +</article> diff --git a/doc/da65.sgml b/doc/da65.sgml new file mode 100644 index 000000000..58d031eff --- /dev/null +++ b/doc/da65.sgml @@ -0,0 +1,694 @@ +<!doctype linuxdoc system> + +<article> +<title>da65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-08-08 + +<abstract> +da65 is a 6502/65C02 disassembler that is able to read user supplied +information about its input data for better results. The output is ready for +feeding into ca65, the macro assembler supplied with the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with +the cc65 C compiler and generates output that is suitable for the ca65 +macro assembler. + +Besides generating output for ca65, one of the design goals was that the user +is able to feed additional information about the code into the disassembler +for improved results. This information may include the location and size of +tables, and their format. + +One nice advantage of this concept is that disassembly of copyrighted binaries +may be handled without problems: One can just pass the information file for +disassembling the binary, so everyone with a legal copy of the binary can +generate a nicely formatted disassembly with readable labels and other +information. + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The assembler accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: da65 [options] [inputfile] +Short options: + -g Add debug info to object file + -h Help (this text) + -i name Specify an info file + -o name Name the output file + -v Increase verbosity + -F Add formfeeds to the output + -S addr Set the start/load address + -V Print the disassembler version + +Long options: + --argument-column n Specify argument start column + --comment-column n Specify comment start column + --comments n Set the comment level for the output + --cpu type Set cpu type + --debug-info Add debug info to object file + --formfeeds Add formfeeds to the output + --help Help (this text) + --hexoffs Use hexadecimal label offsets + --info name Specify an info file + --label-break n Add newline if label exceeds length n + --mnemonic-column n Specify mnemonic start column + --pagelength n Set the page length for the listing + --start-addr addr Set the start/load address + --text-column n Specify text start column + --verbose Increase verbosity + --version Print the disassembler version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--argument-column"> + <tag><tt>--argument-column n</tt></tag> + + Specifies the column where the argument for a mnemonic or pseudo instruction + starts. + + + <label id="option--comment-column"> + <tag><tt>--comment-column n</tt></tag> + + Specifies the column where the comment for an instruction starts. + + + <label id="option--comments"> + <tag><tt>--comments n</tt></tag> + + Set the comment level for the output. Valid arguments are 0..4. Greater + values will increase the level of additional information written to the + output file in form of comments. + + + <label id="option--cpu"> + <tag><tt>--cpu type</tt></tag> + + Set the CPU type. The option takes a parameter, which may be one of + + 6502, 6502x, 65sc02, 65c02, huc6280 + + 6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC + engine. Support for the 65816 is currently not available. + + + <label id="option--formfeeds"> + <tag><tt>-F, --formfeeds</tt></tag> + + Add formfeeds to the generated output. This feature is useful together + with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option. + If <tt/--formfeeds/ is given, a formfeed is added to the output after each + page. + + + <tag><tt>-g, --debug-info</tt></tag> + + This option adds the <tt/.DEBUGINFO/ command to the output file, so the + assembler will generate debug information when reassembling the generated + output. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option--hexoffs"> + <tag><tt>--hexoffs</tt></tag> + + Output label offsets in hexadecimal instead of decimal notation. + + + <label id="option--info"> + <tag><tt>-i name, --info name</tt></tag> + + Specify an info file. The info file contains global options that may + override or replace command line options plus informations about the code + that has to be disassembled. See the separate section <ref id="infofile" + name="Info File Format">. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + Specify a name for an output file. The default is to use <tt/stdout/, so + without this switch or the corresponding <ref id="global-options" + name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>, + the output will go to the terminal. + + + <label id="option--label-break"> + <tag><tt>--label-break n</tt></tag> + + Adds a newline if the length of a label exceeds the given length. + Note: If the label would run into the code in the mid column, a + linefeed is always inserted regardless of this setting. + + This option overrides the <ref id="global-options" name="global option"> + <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>. + + + <label id="option--mnemonic-column"> + <tag><tt>--mnemonic-column n</tt></tag> + + Specifies the column where a mnemonic or pseudo instrcuction is output. + + + <label id="option--pagelength"> + <tag><tt>--pagelength n</tt></tag> + + Sets the length of a listing page in lines. After this number of lines, a + new page header is generated. If the <tt><ref id="option--formfeeds" + name="--formfeeds"></tt> is also given, a formfeed is inserted before + generating the page header. + + A value of zero for the page length will disable paging of the output. + + + <label id="option--start-addr"> + <tag><tt>-S addr, --start-addr addr</tt></tag> + + Specify the start/load address of the binary code that is going to be + disassembled. The given address is interpreted as an octal value if + preceded with a '0' digit, as a hexadecimal value if preceded + with '0x', '0X', or '$', and as a decimal value in all other cases. If no + start address is specified, $10000 minus the size of the input file is used. + + + <label id="option--text-column"> + <tag><tt>--text-column n</tt></tag> + + Specifies the column where additional text is output. This additional text + consists of the bytes encoded in this line in text representation. + + + <tag><tt>-v, --verbose</tt></tag> + + Increase the disassembler verbosity. Usually only needed for debugging + purposes. You may use this option more than one time for even more + verbose output. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions + or bugfixes, please include the version number. + +</descrip> +<p> + + +<sect>Detailed workings<p> + +<sect1>Supported CPUs<p> + +The default (no CPU given on the command line or in the <tt/GLOBAL/ section of +the info file) is the 6502 CPU. The disassembler knows all "official" opcodes +for this CPU. Invalid opcodes are translated into <tt/.byte/ commands. + +With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the +disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The +latter understands the same opcodes as the former, plus 16 additional bit +manipulation and bit test-and-branch commands. + +While there is some code for the 65816 in the sources, it is currently +unsupported. + + +<sect1>Attribute map<p> + +The disassembler works by creating an attribute map for the whole address +space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an +external info file (if given) is read. Disassembly is done in several passes. +In all passes with the exception of the last one, information about the +disassembled code is gathered and added to the symbol and attribute maps. The +last pass generates output using the information from the maps. + +<sect1>Labels<p> + +Some instructions may generate labels in the first pass, while most other +instructions do not generate labels, but use them if they are available. Among +others, the branch and jump instructions will generate labels for the target +of the branch in the first pass. External labels (taken from the info file) +have precedence over internally generated ones, They must be valid identifiers +as specified for the ca65 assembler. Internal labels (generated by the +disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal +address of the label in upper case letters. You should probably avoid using +such label names for external labels. + + +<sect1>Info File<p> + +The info file is used to pass additional information about the input code to +the disassembler. This includes label names, data areas or tables, and global +options like input and output file names. See the <ref id="infofile" +name="next section"> for more information. + + + +<sect>Info File Format<label id="infofile"><p> + +The info file contains lists of specifications grouped together. Each group +directive has an identifying token and an attribute list enclosed in curly +braces. Attributes have a name followed by a value. The syntax of the value +depends on the type of the attribute. String attributes are places in double +quotes, numeric attributes may be specified as decimal numbers or hexadecimal +with a leading dollar sign. There are also attributes where the attribute +value is a keyword, in this case the keyword is given as is (without quotes or +anything). Each attribute is terminated by a semicolon. + +<tscreen><verb> + group-name { attribute1 attribute-value; attribute2 attribute-value; } +</verb></tscreen> + + +<sect1>Comments<p> + +Comments start with a hash mark (<tt/#/) and extend from the position of +the mark to the end of the current line. Hash marks inside of strings will +of course <em/not/ start a comment. + + +<sect1>Specifying global options<label id="global-options"><p> + +Global options may be specified in a group with the name <tt/GLOBAL/. The +following attributes are recognized: + +<descrip> + + <tag><tt/ARGUMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the argument for + an opcode or pseudo instruction starts. The corresponding command line + option is + <tt><ref id="option--argument-column" name="--argument-column"></tt>. + + + <tag><tt/COMMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the comment starts + in a line. It is only used for in-line comments. The corresponding command + line option is + <tt><ref id="option--comment-column" name="--comment-column"></tt>. + + + <label id="COMMENTS"> + <tag><tt/COMMENTS/</tag> + This attribute may be used instead of the <tt><ref id="option--comments" + name="--comments"></tt> option on the command line. It takes a numerical + parameter between 0 and 4. Higher values increase the amount of information + written to the output file in form of comments. + + + <tag><tt/CPU/</tag> + This attribute may be used instead of the <tt><ref id="option--cpu" + name="--cpu"></tt> option on the command line. For possible values see + there. The value is a string and must be enclosed in quotes. + + + <tag><tt/HEXOFFS/</tag> + The attribute is followed by a boolean value. If true, offsets to labels are + output in hex, otherwise they're output in decimal notation. The default is + false. The attribute may be changed on the command line using the <tt><ref + id="option--hexoffs" name="--hexoffs"></tt> option. + + + <tag><tt/INPUTNAME/</tag> + The attribute is followed by a string value, which gives the name of the + input file to read. If it is present, the disassembler does not accept an + input file name on the command line. + + + <tag><tt/INPUTOFFS/</tag> + The attribute is followed by a numerical value that gives an offset into + the input file which is skipped before reading data. The attribute may be + used to skip headers or unwanted code sections in the input file. + + + <tag><tt/INPUTSIZE/</tag> + <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of + data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/ + is ignored. + + + <label id="LABELBREAK"> + <tag><tt/LABELBREAK/</tag> + <tt/LABELBREAK/ is followed by a numerical value that specifies the label + length that will force a newline. To have all labels on their own lines, + you may set this value to zero. + + See also the <tt><ref id="option--label-break" name="--label-break"></tt> + command line option. A <tt/LABELBREAK/ statement in the info file will + override any value given on the command line. + + + <tag><tt/MNEMONICCOLUMN/</tag> + This attribute specifies the column in the output, where the mnemonic or + pseudo instruction is placed. The corresponding command line option is + <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>. + + + <tag><tt/NEWLINEAFTERJMP/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/JMP/ instruction. The default is false. + + + <tag><tt/NEWLINEAFTERRTS/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/RTS/ instruction. The default is false. + + + <label id="OUTPUTNAME"> + <tag><tt/OUTPUTNAME/</tag> + The attribute is followed by string value, which gives the name of the + output file to write. If it is present, specification of an output file on + the command line using the <tt><ref id="option-o" name="-o"></tt> option is + not allowed. + + The default is to use <tt/stdout/ for output, so without this attribute or + the corresponding command line option <tt/<ref id="option-o" name="-o">/ + the output will go to the terminal. + + + <tag><tt/PAGELENGTH/</tag> + This attribute may be used instead of the <tt><ref id="option--pagelength" + name="--pagelength"></tt> option on the command line. It takes a numerical + parameter. Using zero as page length (which is the default) means that no + pages are generated. + + + <tag><tt/STARTADDR/</tag> + This attribute may be used instead of the <tt><ref id="option--start-addr" + name="--start-addr"></tt> option on the command line. It takes a numerical + parameter. The default for the start address is $10000 minus the size of + the input file (this assumes that the input file is a ROM that contains the + reset and irq vectors). + + + <tag><tt/TEXTCOLUMN/</tag> + This attribute specifies the column, where the data bytes are output + translated into ASCII text. It is only used if + <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The + corresponding command line option is + <tt><ref id="option--text-column" name="--text-column"></tt>. + +</descrip> + + +<sect1>Specifying Ranges<p> + +The <tt/RANGE/ directive is used to give information about address ranges. The +following attributes are recognized: + +<descrip> + + <tag><tt>COMMENT</tt></tag> + This attribute is only allowed if a label is also given. It takes a string + as argument. See the description of the <tt><ref id="infofile-label" + name="LABEL"></tt> directive for an explanation. + + <tag><tt>END</tt></tag> + This gives the end address of the range. The end address is inclusive, that + means, it is part of the range. Of course, it may not be smaller than the + start address. + + <tag><tt>NAME</tt></tag> + This is a convenience attribute. It takes a string argument and will cause + the disassembler to define a label for the start of the range with the + given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt> + directive is not needed. + + <tag><tt>START</tt></tag> + This gives the start address of the range. + + <tag><tt>TYPE</tt></tag> + This attribute specifies the type of data within the range. The attribute + value is one of the following keywords: + + <descrip> + <tag><tt>ADDRTABLE</tt></tag> + The range consists of data and is disassembled as a table of words + (16 bit values). The difference to the <tt/WORDTABLE/ type is that + a label is defined for each entry in the table. + + <tag><tt>BYTETABLE</tt></tag> + The range consists of data and is disassembled as a byte table. + + <tag><tt>CODE</tt></tag> + The range consists of code. + + <tag><tt>DBYTETABLE</tt></tag> + The range consists of data and is disassembled as a table of dbytes + (double byte values, 16 bit values with the low byte containing the + most significant byte of the 16 bit value). + + <tag><tt>DWORDTABLE</tt></tag> + The range consists of data and is disassembled as a table of double + words (32 bit values). + + <tag><tt>RTSTABLE</tt></tag> + The range consists of data and is disassembled as a table of words (16 bit + values). The values are interpreted as words that are pushed onto the + stack and jump to it via <tt/RTS/. This means that they contain + <tt/address-1/ of a function, for which a label will get defined by the + disassembler. + + <tag><tt>SKIP</tt></tag> + The range is simply ignored when generating the output file. Please note + that this means that reassembling the output file will <em/not/ generate + the original file, not only because the missing piece in between, but also + because the following code will be located on wrong addresses. Output + generated with <tt/SKIP/ ranges will need manual rework. + + <tag><tt>TEXTTABLE</tt></tag> + The range consists of readable text. + + <tag><tt>WORDTABLE</tt></tag> + The range consists of data and is disassembled as a table of words + (16 bit values). + + </descrip> + +</descrip> + + +<sect1>Specifying Labels<label id="infofile-label"><p> + +The <tt/LABEL/ directive is used to give names for labels in the disassembled +code. The following attributes are recognized: + +<descrip> + + <tag><tt>ADDR</tt></tag> + Followed by a numerical value. Specifies the value of the label. + + <tag><tt>COMMENT</tt></tag> + Attribute argument is a string. The comment will show up in a separate line + before the label, if the label is within code or data range, or after the + label if it is outside. + + Example output: + +<tscreen><verb> + foo := $0001 ; Comment for label named "foo" + + ; Comment for label named "bar" + bar: +</verb></tscreen> + + <tag><tt>NAME</tt></tag> + The attribute is followed by a string value which gives the name of the + label. Empty names are allowed, in this case the disassembler will create + an unnamed label (see the assembler docs for more information about unnamed + labels). + + <tag><tt>SIZE</tt></tag> + This attribute is optional and may be used to specify the size of the data + that follows. If a size greater than 1 is specified, the disassembler will + create labels in the form <tt/label+offs/ for all bytes within the given + range, where <tt/label/ is the label name given with the <tt/NAME/ + attribute, and <tt/offs/ is the offset within the data. + +</descrip> + + +<sect1>Specifying Segments<label id="infofile-segment"><p> + +The <tt/SEGMENT/ directive is used to specify a segment within the +disassembled code. The following attributes are recognized: + +<descrip> + + <tag><tt>START</tt></tag> + Followed by a numerical value. Specifies the start address of the segment. + + <tag><tt>END</tt></tag> + Followed by a numerical value. Specifies the end address of the segment. The + end address is last the address that is part of the segment. + + <tag><tt>NAME</tt></tag> + The attribute is followed by a string value which gives the name of the + segment. +</descrip> + +All attributes are mandatory. Segments may not overlap. Since there is no +explicit "end this segment" pseudo op, the disassembler cannot notify the +assembler that one segment has ended. This may lead to errors if you don't +define your segments carefully. As a rule of thumb, if you're using segments, +your should define segments for all disassembled code. + + +<sect1>Specifying Assembler Includes<label id="infofile-asminc"><p> + +The <tt/ASMINC/ directive is used to give the names of input files containing +symbol assignments in assembler syntax: + +<tscreen><verb> + Name = value + Name := value +</verb></tscreen> + +The usual conventions apply for symbol names. Values may be specified as hex +(leading $), binary (leading %) or decimal. The values may optionally +be signed. + +NOTE: The include file parser is very simple. Expressions are not allowed, and +anything but symbol assignments is flagged as an error (but see the +<tt/IGNOREUNKNOWN/ directive below). + +The following attributes are recognized: + +<descrip> + + <tag><tt>FILE</tt></tag> + Followed by a string value. Specifies the name of the file to read. + + <tag><tt>COMMENTSTART</tt></tag> + The optional attribute is followed by a character constant. It specifies the + character that starts a comment. The default value is a semicolon. This + value is ignored if <tt/IGNOREUNKNOWN/ is true. + + <tag><tt>IGNOREUNKNOWN</tt></tag> + This attribute is optional and is followed by a boolean value. It allows to + ignore input lines that don't have a valid syntax. This allows to read in + assembler include files that contain more than just symbol assignments. + Note: When this attribute is used, the disassembler will ignore any errors + in the given include file. This may have undesired side effects. + +</descrip> + + +<sect1>An Info File Example<p> + +The following is a short example for an info file that contains most of the +directives explained above: + +<tscreen><verb> + # This is a comment. It extends to the end of the line + GLOBAL { + OUTPUTNAME "kernal.s"; + INPUTNAME "kernal.bin"; + STARTADDR $E000; + PAGELENGTH 0; # No paging + CPU "6502"; + }; + + # One segment for the whole stuff + SEGMENT { START $E000; END $FFFF; NAME kernal; }; + + RANGE { START $E612; END $E631; TYPE Code; }; + RANGE { START $E632; END $E640; TYPE ByteTable; }; + RANGE { START $EA51; END $EA84; TYPE RtsTable; }; + RANGE { START $EC6C; END $ECAB; TYPE RtsTable; }; + RANGE { START $ED08; END $ED11; TYPE AddrTable; }; + + # Zero page variables + LABEL { NAME "fnadr"; ADDR $90; SIZE 3; }; + LABEL { NAME "sal"; ADDR $93; }; + LABEL { NAME "sah"; ADDR $94; }; + LABEL { NAME "sas"; ADDR $95; }; + + # Stack + LABEL { NAME "stack"; ADDR $100; SIZE 255; }; + + # Indirect vectors + LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ + LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK + LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI + + # Jump table at end of kernal ROM + LABEL { NAME "kscrorg"; ADDR $FFED; }; + LABEL { NAME "kplot"; ADDR $FFF0; }; + LABEL { NAME "kiobase"; ADDR $FFF3; }; + LABEL { NAME "kgbye"; ADDR $FFF6; }; + + # Hardware vectors + LABEL { NAME "hanmi"; ADDR $FFFA; }; + LABEL { NAME "hares"; ADDR $FFFC; }; + LABEL { NAME "hairq"; ADDR $FFFE; }; +</verb></tscreen> + + + + + +<sect>Bugs/Feedback<p> + +If you have problems using the disassembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to hear +from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + + diff --git a/doc/debugging.sgml b/doc/debugging.sgml new file mode 100644 index 000000000..7566370b9 --- /dev/null +++ b/doc/debugging.sgml @@ -0,0 +1,154 @@ +<!doctype linuxdoc system> + +<article> + +<title>Using emulators 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 and Oricutron emulators. +</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, 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: + +<htmlurl url="http://www.viceteam.org/"> + +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> + + + +<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/-Ln/ 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 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib +</verb></tscreen> +or +<tscreen><verb> + ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.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 with VICE<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>How to use the label file with Oricutron<p> + +Load your program, then enter the monitor and use the "<tt/sl/" command to +load your label file like this: + +<tscreen><verb> + sl hello.sym +</verb></tscreen> + +After loading the labels, they are used by Oricutron 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). + + + +</article> diff --git a/doc/dio.sgml b/doc/dio.sgml new file mode 100644 index 000000000..f340fa254 --- /dev/null +++ b/doc/dio.sgml @@ -0,0 +1,134 @@ +<!doctype linuxdoc system> + +<article> +<title>Diskette Sector I/O Routines +<author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> +<date>20-Feb-2005 + +<abstract> +The cc65 library provides functions to read and write raw disk sectors. +Include the dio.h header file to get the necessary definitions. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Opening the disk for low level I/O<p> + +Prior to using these functions a handle to the device has to be obtained. This +is done with the <tt>dio_open</tt> function. After use, the handle should be +released with the <tt>dio_close</tt> function. + +<tscreen><verb> + dhandle_t __fastcall__ dio_open (unsigned char device); +</verb></tscreen> + +The <tt>device</tt> specifies the device to access, with 0 being the first +device, 1 the second, and so on. + +<tscreen><verb> + unsigned char __fastcall__ dio_close (dhandle_t handle); +</verb></tscreen> + +Closes a handle obtained by <tt>dio_open</tt>. Returns status code. +<p> + +<sect>Reading and writing sectors<p> + +The read and write functions are: + +<tscreen><verb> + unsigned char __fastcall__ dio_read (dhandle_t handle, + unsigned sect_num, + void *buffer); +</verb></tscreen> + +This function will read the sector specified by <tt>sect_num</tt> into the memory +location at buffer. + +<tscreen><verb> + unsigned char __fastcall__ dio_write (dhandle_t handle, + unsigned sect_num, + const void *buffer); +</verb></tscreen> + +This function will write the memory contents at buffer to the sector specified +by <tt>sect_num</tt>. No verify is performed. + +<tscreen><verb> + unsigned char __fastcall__ dio_write_verify (dhandle_t handle, + unsigned sect_num, + const void *buffer); +</verb></tscreen> + +This function will write the memory contents at buffer to the sector specified +by <tt>sect_num</tt>. A verification is performed. +<p> + +Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query +the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt> +function to query the number of available sectors. +<p> + +All these functions will return 0 for success and an OS specific error code in +case of failure. +<p> + +<sect>Querying sector size and count<label id="sectsizecount"><p> + +Some systems support multiple diskette formats which have different sector sizes +and/or different sector counts. +<p> + +The following function returns the sector size of the currently inserted disk: + +<tscreen><verb> + unsigned __fastcall__ dio_query_sectsize (dhandle_t handle); +</verb></tscreen> + +On the Atari platform, the sector size is handled specially. Please refer +to the DIO section in the <htmlurl url="atari.html" name="Atari"> +specific platform documentation. +<p> + +The following function returns the sector count of the currently inserted disk: + +<tscreen><verb> + unsigned __fastcall__ dio_query_sectcount (dhandle_t handle); +</verb></tscreen> + +<sect>Converting sector numbers<p> + +Since the read and write functions expect a sector number, for systems where +the sectors aren't addressed by a logical sector number (e.g. CBM devices), +there are 2 conversion functions. One of them converts a logical sector number +to a head/track/sector triple. The other conversion function works the other +way round. + +<tscreen><verb> + unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle, + const dio_phys_pos *physpos, + unsigned *sectnum); +</verb></tscreen> + +This function converts track/head/sector to logical sector number. + +<tscreen><verb> + unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle, + const unsigned *sectnum, + dio_phys_pos *physpos); +</verb></tscreen> + +This function converts a logical sector number to track/head/sector notation. +<p> + +Note, that on systems which natively use logical sector numbers (e.g. Atari), +the conversion functions are dummies. They ignore head/track +(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>). +The logical sector number is returned as physical sector and vice versa. +<p> + + +</article> diff --git a/doc/funcref.sgml b/doc/funcref.sgml new file mode 100644 index 000000000..ba8fb8abc --- /dev/null +++ b/doc/funcref.sgml @@ -0,0 +1,7439 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>cc65 function reference +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>07.11.2002 + +<abstract> +cc65 is a C compiler for 6502 based systems. This function reference describes +the C functions available in the standard library. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction<p> + +cc65 is a C compiler for 6502 based systems. It implements a subset of the ISO +C standard plus additional functions specially crafted for 6502 systems or +just some of the supported machines. This function refrence describes the +available functions together with any limitations. + +For an overview about the available libraries, their purpose, and any +differences to the ISO standard, please have a look at the <htmlurl +url="library.html" name="cc65 Library Overview">. + +<bf/Note:/ Standard C functions are listed here, but not described in detail. +Since these functions behave identical on all standard compliant systems, they +are described in any book covering standard C. + +Each entry for a function contains a detailed description + +<quote> +<descrip> +<tag/Function/Summary of what <bf/function/ does. +<tag/Header/The header file that contains the declaration. +<tag/Declaration/Describes the needed header files and declaration of the +function. +<tag/Description/Description of the function. +<tag/Limits/Limits. +<tag/Availability/The availability of the function. +<tag/See also/Other related functions. +<tag/Example/A piece of actual code using the function. +</descrip> +</quote> + + +<sect>Functions by header file<p> + +<sect1><tt/6502.h/<label id="6502.h"><p> + +<itemize> +<item><ref id="BRK" name="BRK"> +<item><ref id="CLI" name="CLI"> +<item><ref id="SEI" name="SEI"> +<item><ref id="_sys" name="_sys"> +<item><ref id="getcpu" name="getcpu"> +<item><ref id="reset_brk" name="reset_brk"> +<item><ref id="reset_irq" name="reset_irq"> +<item><ref id="set_brk" name="set_brk"> +<item><ref id="set_irq" name="set_irq"> +</itemize> + + +<sect1><tt/apple2.h/<label id="apple2.h"><p> + +<itemize> +<item>_dos_type +<item><ref id="get_ostype" name="get_ostype"> +<item>rebootafterexit +</itemize> + + +<sect1><tt/apple2enh.h/<label id="apple2enh.h"><p> + +<itemize> +<item>_dos_type +<item><ref id="get_ostype" name="get_ostype"> +<item>rebootafterexit +<item>textframe +<item>textframexy +<item><ref id="videomode" name="videomode"> +</itemize> + + +<sect1><tt/assert.h/<label id="assert.h"><p> + +<itemize> +<item><ref id="assert" name="assert"> +</itemize> + + +<sect1><tt/atari.h/<label id="atari.h"><p> + +<itemize> +<!-- <item><ref id="_getcolor" name="_getcolor"> --> +<!-- <item><ref id="_getdefdev" name="_getdefdev"> --> +<!-- <item><ref id="_graphics" name="_graphics"> --> +<!-- <item><ref id="_rest_vecs" name="_rest_vecs"> --> +<!-- <item><ref id="_save_vecs" name="_save_vecs"> --> +<!-- <item><ref id="_scroll" name="_scroll"> --> +<!-- <item><ref id="_setcolor" name="_setcolor"> --> +<!-- <item><ref id="_setcolor_low" name="_setcolor_low"> --> +<item><ref id="get_ostype" name="get_ostype"> +<!-- <item><ref id="get_tv" name="get_tv"> --> +</itemize> + +(incomplete) + + +<sect1><tt/atmos.h/<label id="atmos.h"><p> + +<itemize> +<item><ref id="atmos_load" name="atmos_load"> +<item><ref id="atmos_save" name="atmos_save"> +</itemize> + + +<sect1><tt/c128.h/<label id="c128.h"><p> + +<itemize> +<item><ref id="c64mode" name="c64mode"> +<item><ref id="fast" name="fast"> +<item><ref id="slow" name="slow"> +<item><ref id="toggle_videomode" name="toggle_videomode"> +<item><ref id="videomode" name="videomode"> +</itemize> + + +<sect1><tt/c16.h/<label id="c16.h"><p> + +(incomplete) + + +<sect1><tt/c64.h/<label id="c64.h"><p> + +<itemize> +<item><ref id="get_ostype" name="get_ostype"> +</itemize> + + +<sect1><tt/cbm.h/<label id="cbm.h"><p> + +<itemize> +<item><ref id="cbm_k_acptr" name="cbm_k_acptr"> +<item><ref id="cbm_k_basin" name="cbm_k_basin"> +<item><ref id="cbm_k_bsout" name="cbm_k_bsout"> +<item><ref id="cbm_k_chkin" name="cbm_k_chkin"> +<item><ref id="cbm_k_ciout" name="cbm_k_ciout"> +<item><ref id="cbm_k_ckout" name="cbm_k_ckout"> +<item><ref id="cbm_k_clall" name="cbm_k_clall"> +<item><ref id="cbm_k_close" name="cbm_k_close"> +<item><ref id="cbm_k_clrch" name="cbm_k_clrch"> +<item><ref id="cbm_k_getin" name="cbm_k_getin"> +<item><ref id="cbm_k_iobase" name="cbm_k_iobase"> +<item><ref id="cbm_k_listen" name="cbm_k_listen"> +<item><ref id="cbm_k_load" name="cbm_k_load"> +<item><ref id="cbm_k_open" name="cbm_k_open"> +<item><ref id="cbm_k_readst" name="cbm_k_readst"> +<item><ref id="cbm_k_save" name="cbm_k_save"> +<item><ref id="cbm_k_setlfs" name="cbm_k_setlfs"> +<item><ref id="cbm_k_setnam" name="cbm_k_setnam"> +<item><ref id="cbm_k_unlsn" name="cbm_k_unlsn"> +<!-- <item><ref id="cbm_load" name="cbm_load"> --> +<!-- <item><ref id="cbm_open" name="cbm_open"> --> +<!-- <item><ref id="cbm_opendir" name="cbm_opendir"> --> +<!-- <item><ref id="cbm_read" name="cbm_read"> --> +<!-- <item><ref id="cbm_readdir" name="cbm_readdir"> --> +<!-- <item><ref id="cbm_save" name="cbm_save"> --> +<!-- <item><ref id="cbm_write" name="cbm_write"> --> +</itemize> + +(incomplete) + + +<sect1><tt/cbm510.h/<label id="cbm510.h"><p> + +<itemize> +<item><ref id="peekbsys" name="peekbsys"> +<item><ref id="peekwsys" name="peekwsys"> +<item><ref id="pokebsys" name="pokebsys"> +<item><ref id="pokewsys" name="pokewsys"> +</itemize> + + +<sect1><tt/cbm610.h/<label id="cbm610.h"><p> + +<itemize> +<item><ref id="peekbsys" name="peekbsys"> +<item><ref id="peekwsys" name="peekwsys"> +<item><ref id="pokebsys" name="pokebsys"> +<item><ref id="pokewsys" name="pokewsys"> +</itemize> + + +<sect1><tt/cc65.h/<label id="cc65.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="cc65_cos" name="cc65_cos"> --> +<!-- <item><ref id="cc65_idiv32by16r16" name="cc65_idiv32by16r16"> --> +<!-- <item><ref id="cc65_imul16x16r32" name="cc65_imul16x16r32"> --> +<!-- <item><ref id="cc65_imul8x8r16" name="cc65_imul8x8r16"> --> +<!-- <item><ref id="cc65_sin" name="cc65_sin"> --> +<!-- <item><ref id="cc65_udiv32by16r16" name="cc65_udiv32by16r16"> --> +<!-- <item><ref id="cc65_umul16x16r32" name="cc65_umul16x16r32"> --> +<!-- <item><ref id="cc65_umul16x8r32" name="cc65_umul16x8r32"> --> +<!-- <item><ref id="cc65_umul8x8r16" name="cc65_umul8x8r16"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/conio.h/<label id="conio.h"><p> + +<itemize> +<item><ref id="bgcolor" name="bgcolor"> +<item><ref id="bordercolor" name="bordercolor"> +<item><ref id="cclear" name="cclear"> +<item><ref id="cclearxy" name="cclearxy"> +<item><ref id="cgetc" name="cgetc"> +<item><ref id="chline" name="chline"> +<item><ref id="chlinexy" name="chlinexy"> +<item><ref id="clrscr" name="clrscr"> +<item><ref id="cprintf" name="cprintf"> +<item><ref id="cputc" name="cputc"> +<item><ref id="cputcxy" name="cputcxy"> +<item><ref id="cputs" name="cputs"> +<item><ref id="cputsxy" name="cputsxy"> +<item><ref id="cursor" name="cursor"> +<item><ref id="cvline" name="cvline"> +<item><ref id="cvlinexy" name="cvlinexy"> +<item><ref id="gotox" name="gotox"> +<item><ref id="gotoxy" name="gotoxy"> +<item><ref id="gotoy" name="gotoy"> +<item><ref id="kbhit" name="kbhit"> +<item><ref id="revers" name="revers"> +<item><ref id="screensize" name="screensize"> +<item><ref id="textcolor" name="textcolor"> +<item><ref id="vcprintf" name="vcprintf"> +<item><ref id="wherex" name="wherex"> +<item><ref id="wherey" name="wherey"> +</itemize> + + +<sect1><tt/ctype.h/<label id="ctype.h"><p> + +<itemize> +<item><ref id="isalnum" name="isalnum"> +<item><ref id="isalpha" name="isalpha"> +<item><ref id="isascii" name="isascii"> +<item><ref id="isblank" name="isblank"> +<item><ref id="iscntrl" name="iscntrl"> +<item><ref id="isdigit" name="isdigit"> +<item><ref id="isgraph" name="isgraph"> +<item><ref id="islower" name="islower"> +<item><ref id="isprint" name="isprint"> +<item><ref id="ispunct" name="ispunct"> +<item><ref id="isspace" name="isspace"> +<item><ref id="isupper" name="isupper"> +<item><ref id="isxdigit" name="isxdigit"> +<item><ref id="tolower" name="tolower"> +<item><ref id="toupper" name="toupper"> +</itemize> + + +<sect1><tt/dbg.h/<label id="dbg.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="DbgInit" name="DbgInit"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/dio.h/<label id="dio.h"><p> + +<htmlurl url="dio.html" name="dio.html"> +Low-level disk I/O API. + + +<sect1><tt/dirent.h/<label id="dirent.h"><p> + +<itemize> +<item><ref id="_DE_ISDIR" name="_DE_ISDIR"> +<item><ref id="_DE_ISLBL" name="_DE_ISLBL"> +<item><ref id="_DE_ISLNK" name="_DE_ISLNK"> +<item><ref id="_DE_ISREG" name="_DE_ISREG"> +<item><ref id="closedir" name="closedir"> +<item><ref id="opendir" name="opendir"> +<item><ref id="readdir" name="readdir"> +<item><ref id="rewinddir" name="rewinddir"> +<item><ref id="seekdir" name="seekdir"> +<item><ref id="telldir" name="telldir"> +</itemize> + +(incomplete) + + +<sect1><tt/em.h/<label id="em.h"><p> + +<itemize> +<item><ref id="em_commit" name="em_commit"> +<item><ref id="em_copyfrom" name="em_copyfrom"> +<item><ref id="em_copyto" name="em_copyto"> +<item><ref id="em_install" name="em_install"> +<item><ref id="em_load_driver" name="em_load_driver"> +<item><ref id="em_map" name="em_map"> +<item><ref id="em_pagecount" name="em_pagecount"> +<item><ref id="em_uninstall" name="em_uninstall"> +<item><ref id="em_unload" name="em_unload"> +<item><ref id="em_use" name="em_use"> +</itemize> + + +<sect1><tt/errno.h/<label id="errno.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="_directerrno" name="_directerrno"> --> +<!-- <item><ref id="_mappederrno" name="_mappederrno"> --> +<!-- <item><ref id="_osmaperrno" name="_osmaperrno"> --> +<!-- <item><ref id="_seterrno" name="_seterrno"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/fcntl.h/<label id="fcntl.h"><p> + +<itemize> +<item><ref id="close" name="close"> +<item><ref id="creat" name="creat"> +<item><ref id="open" name="open"> +</itemize> + + +<sect1><tt/geos.h/<label id="geos.h"><p> + +(incomplete) + + +<sect1><tt/joystick.h/<label id="joystick.h"><p> + +<itemize> +<item><ref id="joy_count" name="joy_count"> +<item><ref id="joy_install" name="joy_install"> +<item><ref id="joy_load_driver" name="joy_load_driver"> +<item><ref id="joy_read" name="joy_read"> +<item><ref id="joy_uninstall" name="joy_uninstall"> +<item><ref id="joy_unload" name="joy_unload"> +</itemize> + + +<sect1><tt/locale.h/<label id="locale.h"><p> + +<itemize> +<item><ref id="localeconv" name="localeconv"> +<item><ref id="setlocale" name="setlocale"> +</itemize> + + +<sect1><tt/lynx.h/<label id="lynx.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="lynx_eeprom_erase" name="lynx_eeprom_erase"> --> +<!-- <item><ref id="lynx_eeprom_read" name="lynx_eeprom_read"> --> +<!-- <item><ref id="lynx_eeprom_write" name="lynx_eeprom_write"> --> +<!-- <item><ref id="lynx_eeread" name="lynx_eeread"> --> +<!-- <item><ref id="lynx_eewrite" name="lynx_eewrite"> --> +<!-- <item><ref id="lynx_exec" name="lynx_exec"> --> +<!-- <item><ref id="lynx_load" name="lynx_load"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/modload.h/<label id="modload.h"><p> + +<itemize> +<item><ref id="mod_load" name="mod_load"> +<item><ref id="mod_free" name="mod_free"> +</itemize> + + +<sect1><tt/mouse.h/<label id="mouse.h"><p> + +<itemize> +<item><ref id="mouse_buttons" name="mouse_buttons"> +<item><ref id="mouse_getbox" name="mouse_getbox"> +<item><ref id="mouse_geterrormsg" name="mouse_geterrormsg"> +<item><ref id="mouse_hide" name="mouse_hide"> +<item><ref id="mouse_info" name="mouse_info"> +<item><ref id="mouse_install" name="mouse_install"> +<item><ref id="mouse_ioctl" name="mouse_ioctl"> +<item><ref id="mouse_load_driver" name="mouse_load_driver"> +<item><ref id="mouse_move" name="mouse_move"> +<item><ref id="mouse_pos" name="mouse_pos"> +<item><ref id="mouse_setbox" name="mouse_setbox"> +<item><ref id="mouse_show" name="mouse_show"> +<item><ref id="mouse_uninstall" name="mouse_uninstall"> +<item><ref id="mouse_unload" name="mouse_unload"> +</itemize> + + +<sect1><tt/nes.h/<label id="nes.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="get_tv" name="get_tv"> --> +<!-- <item><ref id="waitvblank" name="waitvblank"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/o65.h/<label id="o65.h"><p> + +The <tt/o65.h/ header file contains structure and constant definitions that +may be used when dealing with files in <htmlurl +url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65 format">. +It does not declare any functions. + + +<sect1><tt/peekpoke.h/<label id="peekpoke.h"><p> + +<itemize> +<item><ref id="PEEK" name="PEEK"> +<item><ref id="PEEKW" name="PEEKW"> +<item><ref id="POKE" name="POKE"> +<item><ref id="POKEW" name="POKEW"> +</itemize> + + +<sect1><tt/pet.h/<label id="pet.h"><p> + +(incomplete) + + +<sect1><tt/plus4.h/<label id="plus4.h"><p> + +(incomplete) + + +<sect1><tt/serial.h/<label id="serial.h"><p> + +The <tt/serial.h/ header file contains definitions for initializing serial +communication. + +<itemize> +<item><ref id="ser_close" name="ser_close"> +<item><ref id="ser_get" name="ser_get"> +<item><ref id="ser_install" name="ser_install"> +<item><ref id="ser_ioctl" name="ser_ioctl"> +<item><ref id="ser_load_driver" name="ser_load_driver"> +<item><ref id="ser_open" name="ser_open"> +<item><ref id="ser_put" name="ser_put"> +<item><ref id="ser_status" name="ser_status"> +<item><ref id="ser_uninstall" name="ser_uninstall"> +<item><ref id="ser_unload" name="ser_unload"> +</itemize> + + +<sect1><tt/setjmp.h/<label id="setjmp.h"><p> + +<itemize> +<item><ref id="setjmp" name="setjmp"> +<item><ref id="longjmp" name="longjmp"> +</itemize> + + +<sect1><tt/signal.h/<label id="signal.h"><p> + +<itemize> +<item><ref id="raise" name="raise"> +<item><ref id="signal" name="signal"> +</itemize> + + +<sect1><tt/stdarg.h/<label id="stdarg.h"><p> + +(incomplete) + + +<sect1><tt/stdbool.h/<label id="stdbool.h"><p> + +(incomplete) + + +<sect1><tt/stddef.h/<label id="stddef.h"><p> + +<itemize> +<item><ref id="offsetof" name="offsetof"> +</itemize> + + +<sect1><tt/stdio.h/<label id="stdio.h"><p> + +<itemize> +<item><ref id="_poserror" name="_poserror"> +<item><ref id="clearerr" name="clearerr"> +<!-- <item><ref id="fclose" name="fclose"> --> +<!-- <item><ref id="fdopen" name="fdopen"> --> +<item><ref id="feof" name="feof"> +<item><ref id="ferror" name="ferror"> +<!-- <item><ref id="fflush" name="fflush"> --> +<!-- <item><ref id="fgetc" name="fgetc"> --> +<!-- <item><ref id="fgetpos" name="fgetpos"> --> +<!-- <item><ref id="fgets" name="fgets"> --> +<item><ref id="fileno" name="fileno"> +<!-- <item><ref id="fopen" name="fopen"> --> +<!-- <item><ref id="fprintf" name="fprintf"> --> +<!-- <item><ref id="fputc" name="fputc"> --> +<!-- <item><ref id="fputs" name="fputs"> --> +<!-- <item><ref id="fread" name="fread"> --> +<!-- <item><ref id="freopen" name="freopen"> --> +<!-- <item><ref id="fscanf" name="fscanf"> --> +<!-- <item><ref id="fseek" name="fseek"> --> +<!-- <item><ref id="fsetpos" name="fsetpos"> --> +<!-- <item><ref id="ftell" name="ftell"> --> +<!-- <item><ref id="fwrite" name="fwrite"> --> +<!-- <item><ref id="getc" name="getc"> --> +<!-- <item><ref id="getchar" name="getchar"> --> +<!-- <item><ref id="gets" name="gets"> --> +<!-- <item><ref id="printf" name="printf"> --> +<!-- <item><ref id="putc" name="putc"> --> +<!-- <item><ref id="putchar" name="putchar"> --> +<!-- <item><ref id="puts" name="puts"> --> +<item><ref id="rename" name="rename"> +<item><ref id="remove" name="remove"> +<!-- <item><ref id="rewind" name="rewind"> --> +<!-- <item><ref id="scanf" name="scanf"> --> +<!-- <item><ref id="snprintf" name="snprintf"> --> +<!-- <item><ref id="sprintf" name="sprintf"> --> +<!-- <item><ref id="sscanf" name="sscanf"> --> +<!-- <item><ref id="vfprintf" name="vfprintf"> --> +<!-- <item><ref id="vfscanf" name="vfscanf"> --> +<!-- <item><ref id="vprintf" name="vprintf"> --> +<!-- <item><ref id="vscanf" name="vscanf"> --> +<!-- <item><ref id="vsnprintf" name="vsnprintf"> --> +<!-- <item><ref id="vsprintf" name="vsprintf"> --> +<!-- <item><ref id="vsscanf" name="vsscanf"> --> +</itemize> + +(incomplete) + + +<sect1><tt/stdlib.h/<label id="stdlib.h"><p> + +<itemize> +<item><ref id="_heapadd" name="_heapadd"> +<item><ref id="_heapblocksize" name="_heapblocksize"> +<item><ref id="_heapmaxavail" name="_heapmaxavail"> +<item><ref id="_heapmemavail" name="_heapmemavail"> +<item><ref id="_randomize" name="_randomize"> +<item><ref id="_swap" name="_swap"> +<item><ref id="abort" name="abort"> +<item><ref id="abs" name="abs"> +<item><ref id="atexit" name="atexit"> +<item><ref id="atoi" name="atoi"> +<item><ref id="atol" name="atol"> +<item><ref id="bsearch" name="bsearch"> +<item><ref id="calloc" name="calloc"> +<item><ref id="div" name="div"> +<item><ref id="exit" name="exit"> +<item><ref id="free" name="free"> +<item><ref id="getenv" name="getenv"> +<item><ref id="itoa" name="itoa"> +<item><ref id="labs" name="labs"> +<item><ref id="ltoa" name="ltoa"> +<item><ref id="malloc" name="malloc"> +<item><ref id="perror" name="perror"> +<!-- <item><ref id="posix_memalign" name="posix_memalign"> --> +<!-- <item><ref id="putenv" name="putenv"> --> +<item><ref id="qsort" name="qsort"> +<item><ref id="rand" name="rand"> +<item><ref id="realloc" name="realloc"> +<item><ref id="srand" name="srand"> +<!-- <item><ref id="system" name="system"> --> +<item><ref id="ultoa" name="ultoa"> +<item><ref id="utoa" name="utoa"> +</itemize> + +(incomplete) + + +<sect1><tt/string.h/<label id="string.h"><p> + +<itemize> +<item><ref id="_stroserror" name="_stroserror"> +<item><ref id="bzero" name="bzero"> +<item><ref id="memchr" name="memchr"> +<item><ref id="memcmp" name="memcmp"> +<item><ref id="memcpy" name="memcpy"> +<item><ref id="memmove" name="memmove"> +<item><ref id="memset" name="memset"> +<item><ref id="strcasecmp" name="strcasecmp"> +<item><ref id="strcat" name="strcat"> +<item><ref id="strchr" name="strchr"> +<item><ref id="strcmp" name="strcmp"> +<item><ref id="strcoll" name="strcoll"> +<item><ref id="strcpy" name="strcpy"> +<item><ref id="strcspn" name="strcspn"> +<item><ref id="strdup" name="strdup"> +<item><ref id="strerror" name="strerror"> +<item><ref id="stricmp" name="stricmp"> +<item><ref id="strlen" name="strlen"> +<item><ref id="strlower" name="strlower"> +<item><ref id="strlwr" name="strlwr"> +<item><ref id="strncat" name="strncat"> +<item><ref id="strncmp" name="strncmp"> +<item><ref id="strncpy" name="strncpy"> +<item><ref id="strrchr" name="strrchr"> +<item><ref id="strspn" name="strspn"> +<item><ref id="strstr" name="strstr"> +<item><ref id="strtok" name="strtok"> +<item><ref id="strxfrm" name="strxfrm"> +<item><ref id="strupper" name="strupper"> +<item><ref id="strupr" name="strupr"> +</itemize> + +(incomplete) + + +<sect1><tt/tgi.h/<label id="tgi.h"><p> + +<itemize> +<item><ref id="tgi_arc" name="tgi_arc"> +<item><ref id="tgi_bar" name="tgi_bar"> +<item><ref id="tgi_circle" name="tgi_circle"> +<item><ref id="tgi_clear" name="tgi_clear"> +<item><ref id="tgi_done" name="tgi_done"> +<item><ref id="tgi_ellipse" name="tgi_ellipse"> +<item><ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<item><ref id="tgi_getaspectratio" name="tgi_getaspectratio"> +<item><ref id="tgi_getcolor" name="tgi_getcolor"> +<item><ref id="tgi_getcolorcount" name="tgi_getcolorcount"> +<item><ref id="tgi_getdefpalette" name="tgi_getdefpalette"> +<item><ref id="tgi_geterror" name="tgi_geterror"> +<item><ref id="tgi_geterrormsg" name="tgi_geterrormsg"> +<item><ref id="tgi_getmaxcolor" name="tgi_getmaxcolor"> +<item><ref id="tgi_getmaxx" name="tgi_getmaxx"> +<item><ref id="tgi_getmaxy" name="tgi_getmaxy"> +<item><ref id="tgi_getpagecount" name="tgi_getpagecount"> +<item><ref id="tgi_getpalette" name="tgi_getpalette"> +<item><ref id="tgi_getpixel" name="tgi_getpixel"> +<item><ref id="tgi_gettextheight" name="tgi_gettextheight"> +<item><ref id="tgi_gettextwidth" name="tgi_gettextwidth"> +<item><ref id="tgi_getxres" name="tgi_getxres"> +<item><ref id="tgi_getyres" name="tgi_getyres"> +<item><ref id="tgi_gotoxy" name="tgi_gotoxy"> +<item><ref id="tgi_init" name="tgi_init"> +<item><ref id="tgi_install" name="tgi_install"> +<item><ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> +<item><ref id="tgi_ioctl" name="tgi_ioctl"> +<item><ref id="tgi_line" name="tgi_line"> +<item><ref id="tgi_lineto" name="tgi_lineto"> +<item><ref id="tgi_load_driver" name="tgi_load_driver"> +<item><ref id="tgi_load_vectorfont" name="tgi_load_vectorfont"> +<item><ref id="tgi_outtext" name="tgi_outtext"> +<item><ref id="tgi_outtextxy" name="tgi_outtextxy"> +<item><ref id="tgi_setaspectratio" name="tgi_setaspectratio"> +<item><ref id="tgi_setcolor" name="tgi_setcolor"> +<item><ref id="tgi_setdrawpage" name="tgi_setdrawpage"> +<item><ref id="tgi_setpalette" name="tgi_setpalette"> +<item><ref id="tgi_setpixel" name="tgi_setpixel"> +<item><ref id="tgi_setviewpage" name="tgi_setviewpage"> +<item><ref id="tgi_settextscale" name="tgi_settextscale"> +<item><ref id="tgi_settextstyle" name="tgi_settextstyle"> +<item><ref id="tgi_uninstall" name="tgi_uninstall"> +<item><ref id="tgi_unload" name="tgi_unload"> +</itemize> + +<sect1><tt/time.h/<label id="time.h"><p> + +<itemize> +<!-- <item><ref id="_systime" name="_systime"> --> +<!-- <item><ref id="asctime" name="asctime"> --> +<item><ref id="clock" name="clock"> +<!-- <item><ref id="ctime" name="ctime"> --> +<!-- <item><ref id="gmtime" name="gmtime"> --> +<!-- <item><ref id="localtime" name="localtime"> --> +<!-- <item><ref id="mktime" name="mktime"> --> +<!-- <item><ref id="strftime" name="strftime"> --> +<item><ref id="time" name="time"> +</itemize> + +(incomplete) + + +<sect1><tt/unistd.h/<label id="unistd.h"><p> + +<itemize> +<!-- <item><ref id="chdir" name="chdir"> --> +<item><ref id="exec" name="exec"> +<!-- <item><ref id="getcwd" name="getcwd"> --> +<item><ref id="getopt" name="getopt"> +<!-- <item><ref id="lseek" name="lseek"> --> +<!-- <item><ref id="mkdir" name="mkdir"> --> +<!-- <item><ref id="read" name="read"> --> +<!-- <item><ref id="rmdir" name="rmdir"> --> +<item><ref id="sleep" name="sleep"> +<item><ref id="unlink" name="unlink"> +<!-- <item><ref id="write" name="write"> --> +</itemize> + +(incomplete) + + +<sect1><tt/vic20.h/<label id="vic20.h"><p> + +(incomplete) + + +<sect1><tt/zlib.h/<label id="zlib.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="adler32" name="adler32"> --> +<!-- <item><ref id="crc32" name="crc32"> --> +<!-- <item><ref id="inflatemem" name="inflatemem"> --> +<!-- <item><ref id="uncompress" name="uncompress"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect>Alphabetical function reference<p> + +<sect1>_DE_ISDIR<label id="_DE_ISDIR"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISDIR(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a directory. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISLNK" name="_DE_ISLNK">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISLBL<label id="_DE_ISLBL"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a disk label. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISLBL(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a disk label. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLNK" name="_DE_ISLNK">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISLNK<label id="_DE_ISLNK"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a link. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISLNK(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a link. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISREG<label id="_DE_ISREG"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a regular file. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISREG(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a regular file. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +<item>A "regular file" means anything with data in it. This might still mean +that special processing is needed, when accessing the file. Relative files of +the CBM systems are classified as being "regular" files, for example. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISLNK" name="_DE_ISLNK"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapadd<label id="_heapadd"><p> + +<quote> +<descrip> +<tag/Function/Add a block to the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ _heapadd (void* mem, size_t size);/ +<tag/Description/The function adds a block of raw memory to the heap. +<tag/Limits/ +<itemize> +<item>The minimum blocksize that can be added is 6 bytes; the function will +ignore smaller blocks. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapblocksize<label id="_heapblocksize"><p> + +<quote> +<descrip> +<tag/Function/Return the size of an allocated block. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t __fastcall__ _heapblocksize (const void* block);/ +<tag/Description/The function returns the size of a block that must have +previously been allocated by <tt/<ref id="malloc" name="malloc">/, <tt/<ref +id="calloc" name="calloc">/ or <tt/<ref id="realloc" name="realloc">/. +<tag/Limits/ +<itemize> +<item>Passing a pointer to a block that was is not the result of one of the +allocation functions, or that has been free'd will give unpredicable results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapmaxavail<label id="_heapmaxavail"><p> + +<quote> +<descrip> +<tag/Function/Return the largest block that is available on the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t _heapmaxavail (void);/ +<tag/Description/The function returns the size of the largest block that may +be allocated from the heap using <tt/<ref id="malloc" name="malloc">/. +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapmemavail<label id="_heapmemavail"><p> + +<quote> +<descrip> +<tag/Function/Return the total available space on the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t __fastcall__ _heapmemavail (void);/ +<tag/Description/The function returns the total number of bytes available on +the heap. +<tag/Limits/ +<itemize> +<item>This function is of less use than usually assumed, since the returned +heap space may be available but not in one block. So even if this function +says that several times more heap space is available than needed, <ref +id="malloc" name="malloc"> may still return <tt/NULL/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_poserror<label id="_poserror"><p> + +<quote> +<descrip> +<tag/Function/Print an error message for the error in <tt/_oserror/. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ _poserror (const char* msg);/ +<tag/Description/<tt/_poserror/ prints an error message to <tt/stderr/. If +<tt/msg/ is not <tt/NULL/ and not an empty string, it is printed followed by +a colon and a blank. Then the error message for the current contents of +<tt/_oserror/ are printed followed by a newline. The message output is the +same as returned by <tt/<ref id="_stroserror" name="_stroserror">/ with an +argument of <tt/_oserror/. +<tag/Limits/ +<itemize> +<item>Since operating system specific error code are - you guessed it - +operating system specific, the value in <tt/_oserror/ and the message that is +printed depends on the cc65 target. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_stroserror" name="_stroserror">, +<ref id="perror" name="perror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_randomize<label id="_randomize"><p> + +<quote> +<descrip> +<tag/Function/Initialize the pseudo random number generator. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void _randomize (void);/ +<tag/Description/The function initializes the random number generator with +a seed derived from fast changing hardware events, so the seed itself can be +considered random to a certain degree. +<tag/Limits/<itemize> +<item>The randomness of the seed depends on the machine hardware. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="rand" name="rand">, +<ref id="srand" name="srand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_stroserror<label id="_stroserror"><p> + +<quote> +<descrip> +<tag/Function/Return a string describing an OS specific error code. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/const char* __fastcall__ _stroserror (unsigned char errcode);/ +<tag/Description/<tt/_stroserror/ will return a string describing the given +operating system specific error code. +<tag/Limits/<itemize> +<item>Since operating system specific error code are - you guessed it - +operating system specific, the parameter and the string returned depend on the +cc65 target. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strerror" name="strerror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_swap<label id="_swap"><p> + +<quote> +<descrip> +<tag/Function/Swap the contents of memory areas. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ _swap (void* p, void* q, size_t size);/ +<tag/Description/<tt/_swap/ will swap (exchange) the contents of the two memory +areas pointed to by <tt/p/ and <tt/q/. Both memory areas are assumed to be +<tt/size/ bytes in size. +<tag/Limits/<itemize> +<item>The memory areas may not overlap, otherwise the results are undefined. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_sys<label id="_sys"><p> + +<quote> +<descrip> +<tag/Function/Call a subroutine passing register values. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ _sys (struct regs* r);/ +<tag/Description/The function will call the subroutine at the address +specified in the <tt/pc/ member of the passed <tt/regs/ structure. All +registers and the CPU flags are set to the values given in the <tt/regs/ +structure. On return from the subroutine, the new values of the registers and +flags are stored back overwriting the old values. +<tag/Limits/<itemize> +<item>Bits 4 and 5 of the flags value in the <tt/regs/ structure are ignored +when calling the subroutine (they are unchanged from their current values). +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>BRK<label id="BRK"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 BRK instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void BRK (void);/ +<tag/Description/The function will insert a 6502 BRK instruction into the code +which may be used to trigger a debugger. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>The inserted instruction may lead to unexpected results if no debugger +is present. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="CLI" name="CLI">, +<ref id="SEI" name="SEI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>CLI<label id="CLI"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 CLI instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void CLI (void);/ +<tag/Description/The function will insert a 6502 CLI instruction into the code, +so interrupts are enabled. Enabling interrupts has no effects if they are +already enabled (the default). +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>Disabling interrupts may lead to unexpected results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="BRK" name="BRK">, +<ref id="SEI" name="SEI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>PEEK<label id="PEEK"><p> + +<quote> +<descrip> +<tag/Function/Read a byte from memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/unsigned char PEEK (unsigned addr);/ +<tag/Description/The function will read the absolute memory given by <tt/addr/ +and return the value read. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEKW" name="PEEKW">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>PEEKW<label id="PEEKW"><p> + +<quote> +<descrip> +<tag/Function/Read a word (two bytes) from memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/unsigned PEEKW (unsigned addr);/ +<tag/Description/The function will read the absolute memory given by <tt/addr/ +and return the value read. The byte read from the higher address is the high +byte of the return value. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>The order in which the two bytes are read is unspecified and may +depend of the address expression used. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>POKE<label id="POKE"><p> + +<quote> +<descrip> +<tag/Function/Write a byte to memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/void POKE (unsigned addr, unsigned char val);/ +<tag/Description/The function writes the value <tt/val/ to the absolute +memory address given by <tt/addr/. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>Careless use will cause the program to act strange or may crash the +machine. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKEW" name="POKEW"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>POKEW<label id="POKEW"><p> + +<quote> +<descrip> +<tag/Function/Write a word (two bytes) to memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/void POKEW (unsigned addr, unsigned val);/ +<tag/Description/The function writes the value <tt/val/ to the absolute +memory address given by <tt/addr/. The low byte of <tt/val/ is written to +the <tt/addr/, the high byte is written to <tt/addr+1/. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>Careless use will cause the program to act strange or may crash the +machine. +<item>The order in which the two bytes are written is unspecified and may +depend of the address expression used. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>SEI<label id="SEI"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 SEI instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void SEI (void);/ +<tag/Description/The function will insert a 6502 SEI instruction into the code, +so interrupts are disabled. Note that non maskable interrupts cannot be +disabled. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>Disabling interrupts may lead to unexpected results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="BRK" name="BRK">, +<ref id="CLI" name="CLI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>abort<label id="abort"><p> + +<quote> +<descrip> +<tag/Function/Terminates a program abnormally. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void abort (void);/ +<tag/Description/<tt/abort/ raises <tt/SIGABRT/, writes a termination message +on stderr, then terminates the program with an exit code of 3. +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="assert" name="assert">, +<ref id="exit" name="exit">, +<ref id="raise" name="raise"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>abs<label id="abs"><p> + +<quote> +<descrip> +<tag/Function/Returns the absolute value of an integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ abs (int v);/ +<tag/Description/<tt/abs/ returns the absolute value of the argument passed to +the function. +<tag/Limits/<itemize> +<item>The return value is undefined if <tt/INT_MIN/ is passed to the function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="labs" name="labs"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>assert<label id="assert"><p> + +<quote> +<descrip> +<tag/Function/Test a condition and possibly abort. +<tag/Header/<tt/<ref id="assert.h" name="assert.h">/ +<tag/Declaration/<tt/void assert (int cond);/ +<tag/Description/<tt/assert/ is a macro that expands to a <tt/id/ +statement. If the condition evaluates t zero (false), assert prints a message +on stderr and aborts the program. +<tag/Limits/<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atexit<label id="atexit"><p> + +<quote> +<descrip> +<tag/Function/Register an exit function. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ atexit (void (*exitfunc) (void));/ +<tag/Description/<tt/atexit/ registers the function pointed to by +<tt/exitfunc/ as an exit function. Exit functions are called when the program +terminates, they are called in LIFO order (the last function registered is +called first). <tt/atexit/ returns zero on success and a nonzero value on +failure. +<tag/Limits/<itemize> +<item>A maximum of 5 exit functions can be registered. +<item>There is no way to unregister an exit function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atmos_load<label id="atmos_load"><p> + +<quote> +<descrip> +<tag/Function/Load Atmos tape. +<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ +<tag/Declaration/<tt/void __fastcall__ atmos_load(const char* name);/ +<tag/Description/<tt/atmos_load/ reads a memory block from tape. +<tag/Availability/cc65 +<tag/See also/ +<ref id="atmos_save" name="atmos_save"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atmos_save<label id="atmos_save"><p> + +<quote> +<descrip> +<tag/Function/Save Atmos tape. +<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ +<tag/Declaration/<tt/void __fastcall__ atmos_save(const char* name, const void* start, const void* end);/ +<tag/Description/<tt/atmos_save/ writes a memory block to tape. +<tag/Availability/cc65 +<tag/See also/ +<ref id="atmos_load" name="atmos_load"> +<tag/Example/<verb> +atmos_save("hires", 0xa000, 0xc000); +</verb> +</descrip> +</quote> + + +<sect1>atoi<label id="atoi"><p> + +<quote> +<descrip> +<tag/Function/Convert a string to an integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ atoi (const char* s);/ +<tag/Description/<tt/atoi/ converts the given string into an integer. +Conversion stops as soon as any invalid character is encountered. +<tag/Limits/<itemize> +<item>There is no way to detect any conversion errors. +<item>The function does not check for an numerical overflow when converting. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atol<label id="atol"><p> + +<quote> +<descrip> +<tag/Function/Convert a string to a long integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/long __fastcall__ atol (const char* s);/ +<tag/Description/<tt/atol/ converts the given string into a long integer. +Conversion stops as soon as any invalid character is encountered. +<tag/Limits/<itemize> +<item>There is no way to detect any conversion errors. +<item>The function does not check for an numerical overflow when converting. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bgcolor<label id="bgcolor"><p> + +<quote> +<descrip> +<tag/Function/Set the background text color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ bgcolor (unsigned char color);/ +<tag/Description/The function will set a new background color and return the +old (current) one. The background color is valid for the whole text output +area of the screen, not just for new text. +<tag/Limits/<itemize> +<item>Background colors are system dependent. The function may have no effect +on systems where the background color cannot be changed. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bordercolor" name="bordercolor">, +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bordercolor<label id="bordercolor"><p> + +<quote> +<descrip> +<tag/Function/Set the border (frame) color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ bordercolor (unsigned char color);/ +<tag/Description/The function will set a new border color. It returns the old +(current) border color. +<tag/Limits/<itemize> +<item>Border colors are system dependent. The function may have no effect +on systems where the border color cannot be changed. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bgcolor" name="bgcolor">, +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bsearch<label id="bsearch"><p> + +<quote> +<descrip> +<tag/Function/Do a binary search in a sorted array. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ bsearch (const void* key, +const void* base, size_t n, size_t size, +int (*cmp) (const void*, const void*));/ +<tag/Description/<tt/bsearch/ searches a sorted array for a member that +matches the one pointed to by <tt/key/. <tt/base/ is the address of the array, +<tt/n/ is the number of elements, <tt/size/ the size of an element and <tt/cmp/ +the function used to compare the members against the key. The function returns +a pointer to the member found, or <tt/NULL/ if there was no match. +<tag/Limits/ +<itemize> +<item>The contents of the array must be sorted in ascending order according to +the compare function given. +<item>If there are multiple members that match the key, the function will +return one of the members. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="qsort" name="qsort"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bzero<label id="bzero"><p> + +<quote> +<descrip> +<tag/Function/Fill a memory area with zeroes. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void __fastcall__ bzero (void* p, size_t count);/ +<tag/Description/<tt/bzero/ fills the memory area pointed to by <tt/p/ with +zero. +<tag/Limits/ +<itemize> +<item>The function is non standard and therefore only available in non ANSI +mode. You should use <tt/<ref id="memset" name="memset">/ instead. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>c64mode<label id="c64mode"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into C64 compatible mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void c64mode (void);/ +<tag/Description/The function will cause the machine to reboot into C64 mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>The function will not return to the caller. +</itemize> +<tag/Availability/C128 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>calloc<label id="calloc"><p> + +<quote> +<descrip> +<tag/Function/Allocate and clear memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ calloc (size_t n, size_t size);/ +<tag/Description/<tt/calloc/ allocates memory for an array of <tt/n/ elements +of size <tt/size/, clears the whole block with binary zeroes and returns a +pointer to it. On error (not enough memory available), <tt/calloc/ returns +<tt/NULL/. +<tag/Limits/ +<itemize> +<item>Clearing the memory may not have the expected effect on all platforms: +pointers in the block may not be <tt/NULL/ and floating point variables may +not be zero (0.0). In other words: The "clearing" effect of this function +should be used with care for portable programs. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_acptr<label id="cbm_k_acptr"><p> + +<quote> +<descrip> +<tag/Function/Input byte from serial bus +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_acptr (void);/ +<tag/Description/The function returns a byte of data, which it +gets from the current TALKer on the serial bus. +In order to receive the data, the device must have previously been +sent a command to TALK and a secondary address if it needs one. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_talk" name="cbm_k_talk">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_basin<label id="cbm_k_basin"><p> + +<quote> +<descrip> +<tag/Function/Input a Character from the Current Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_basin (void);/ +<tag/Description/The function returns a character from the current input device. +Device must first have been OPENed and then designated as the input channel by the CHKIN routine. +When this function is called, the next byte of data available from the device is returned. +Exception is the routine for the keyboard device (which is the default input device). +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_chkin" name="cbm_k_chkin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_bsout<label id="cbm_k_bsout"><p> + +<quote> +<descrip> +<tag/Function/Output a byte +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_bsout (unsigned char C);/ +<tag/Description/Function sends the character to the current output device. +Unless a device has been OPENed and designated as the +current output channel using the CHKOUT routine, the character is +printed to the screen, which is the default output device. If the +cassette is the current device, outputting a byte will only add it to +the buffer. No actual transmission of data will occur until the +192-byte buffer is full. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_chkin" name="cbm_k_chkout"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_chkin<label id="cbm_k_chkin"><p> + +<quote> +<descrip> +<tag/Function/Designate a Logical File As the Current Input Channel +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_chkin (unsigned char FN);/ +<tag/Description/If you wish to +get data from any device other than the keyboard, this function must be +called after OPENing the device, before you can get a data byte with +the cbm_k_basin or cbm_k_getin routine. When called, the routine will designate +the logical file whose file number was supplied as the +current file, its device as the current device, and its secondary +address as the current secondary address. If the device on the +channel is a serial device, which requires a TALK command and +sometimes a secondary address, function will send them over the +serial bus. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_basin" name="cbm_k_basin">, +<ref id="cbm_k_getin" name="cbm_k_getin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_ciout<label id="cbm_k_ciout"><p> + +<quote> +<descrip> +<tag/Function/Transmit a byte over the serial bus +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_ciout (unsigned char C);/ +<tag/Description/Purpose of this function is to send a byte of data over +the serial bus. In order for the data to be received, the serial +device must have first been commanded to LISTEN and been given a +secondary address if necessary. This routine always buffers the +current character, and defers sending it until the next byte is +buffered. When the UNLISTEN command is sent, the last byte will be +sent with an End or Identify (EOI). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_listen" name="cbm_k_listen">, +<ref id="cbm_k_unlsn" name="cbm_k_unlsn"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_ckout<label id="cbm_k_ckout"><p> + +<quote> +<descrip> +<tag/Function/Designate a Logical File As the Current Output Channel +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_ckout (unsigned char FN);/ +<tag/Description/If you wish to +output data to any device other than the screen, this routine must be +called after OPENing the device, and before you output a data byte +with the cbm_k_bsout() function. When called, the function will designate the +logical file whose file number was supplied as the current +file, its device as the current device, and its secondary address as +the current secondary address. If the device on the channel uses the +serial bus, and therefore requires a LISTEN command and possibly a +secondary address, this information will be sent on the bus. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_bsout" name="cbm_k_bsout">, +<ref id="cbm_k_listen" name="cbm_k_listen"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_clall<label id="cbm_k_clall"><p> + +<quote> +<descrip> +<tag/Function/Close All Logical I/O Files +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_clall (void);/ +<tag/Description/It closes all +open files, by resetting the index into open files to +zero and restores the default I/O devices. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_close" name="cbm_k_close"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_close<label id="cbm_k_close"><p> + +<quote> +<descrip> +<tag/Function/Close a Logical I/O File +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_close (unsigned char FN);/ +<tag/Description/It is used to +close a logical file after all I/O operations involving that file have +been completed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_clall" name="cbm_k_clall"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_clrch<label id="cbm_k_clrch"><p> + +<quote> +<descrip> +<tag/Function/Restore Current Input and Output Devices to the Default Devices +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_clrch (void);/ +<tag/Description/It sets the +current input device to the keyboard, and the current output device to +the screen. Also, if the current input device was formerly a serial +device, the routine sends it an UNTALK command on the serial bus, and +if a serial device was formerly the current output device, the routine +sends it an UNLISTEN command. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_chkin" name="cbm_k_chkin">, +<ref id="cbm_k_ckout" name="cbm_k_ckout"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_getin<label id="cbm_k_getin"><p> + +<quote> +<descrip> +<tag/Function/Get One Byte from the Input Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_getin (void);/ +<tag/Description/Function gets a character from the current input device. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_basin" name="cbm_k_basin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_iobase<label id="cbm_k_iobase"><p> + +<quote> +<descrip> +<tag/Function/Return Base Address of Memory-Mapped I/O Devices +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned cbm_k_iobase (void);/ +<tag/Description/This function returns the address of +the memory section where the memory mapped I/O devices are located. This +address can then be used with an offset to access the memory mapped I/O +devices in the Commodore 64. The offset is the number of locations from +the beginning of the page on which the I/O register you want is located. +This function exists to provide compatibility between the Commodore 64, +VIC-20, and future models of the Commodore 64. If the I/O locations for +a program are set by a call to this function, they should +still remain compatible with future versions of the Commodore 64, the +KERNAL and BASIC. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ + +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_listen<label id="cbm_k_listen"><p> + +<quote> +<descrip> +<tag/Function/Command a device on the serial bus to LISTEN +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_listen (unsigned char dev);/ +<tag/Description/This function will command a device on the serial bus to +receive data. The KERNAL routine will OR the supplied device number bit by bit +to convert it to a listen address, then transmits this data as a command on +the serial bus. The specified device will then go into listen mode, and +be ready to accept information. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_unlsn" name="cbm_k_unlsn">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_load<label id="cbm_k_load"><p> + +<quote> +<descrip> +<tag/Function/Load RAM from a Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);/ +<tag/Description/This function LOADs data bytes from any input device directly into the memory. +It can also be used for a verify operation, comparing data from a device with the data already in +memory, while leaving the data stored in RAM unchanged. +The flag must be set to 0 for a LOAD operation, or 1 for a +verify, If the input device is OPENed with a secondary address (SA) of 0 +the header information from the device is ignored. In this case, the starting address for the load must be supplied. +If the device is addressed with a secondary address of 1, then the data is +loaded into memory starting at the location specified by the header. +Function returns the address of the highest RAM location loaded. +Before this function can be called, the KERNAL SETLFS, and SETNAM +routines must be called. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_save" name="cbm_k_save">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_open<label id="cbm_k_open"><p> + +<quote> +<descrip> +<tag/Function/Open a Logical I/O File +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_open (void);/ +<tag/Description/This function assigns a logical file to a device, so that it can be used for +Input/Output operations. In order to specify the logical file number, +the device number, and the secondary address if any, the cbm_k_setlfs() function must first be called. +Likewise, in order to designate the filename, the cbm_k_setnam() function must be used first. After these two +functions are called, cbm_k_open() is then called. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_close" name="cbm_k_close">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_readst<label id="cbm_k_readst"><p> + +<quote> +<descrip> +<tag/Function/Read status word +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_readst (void);/ +<tag/Description/This function returns the current status of the I/O devices. It is usually called after new communication to an I/O device and gives information about device status, or errors that have occurred during the I/O operation. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ + +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_save<label id="cbm_k_save"><p> + +<quote> +<descrip> +<tag/Function/Save RAM to a Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end)/ +<tag/Description/This function saves a section of memory. The cbm_k_setlfs() and cbm_k_setnam() functions must be +used before calling this function. However, a file name is not required to +SAVE to device 1 (the Datassette(TM) recorder). Any attempt to save to +other devices without using a file name results in an error. NOTE: Device 0 (the keyboard), device 2 (RS-232), and device 3 (the screen) cannot be SAVEd to. If the attempt is made, an error occurs, and the SAVE is stopped. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_load" name="cbm_k_load">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p> + +<quote> +<descrip> +<tag/Function/Set up a logical file +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV, unsigned char SA);/ +<tag/Description/This functions sets up the logical file by setting its number, device address, +and secondary address. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_setnam<label id="cbm_k_setnam"><p> + +<quote> +<descrip> +<tag/Function/Set Filename Parameters +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_setnam (const char* Name);/ +<tag/Description/This function is used to set up the file name for the OPEN, +SAVE, or LOAD operations. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_load" name="cbm_k_load">, +<ref id="cbm_k_save" name="cbm_k_save"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_talk<label id="cbm_k_talk"><p> + +<quote> +<descrip> +<tag/Function/Commands device to TALK +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_talk (unsigned char dev);/ +<tag/Description/When called, it ORs the device number with the TALK code (64, $40) and sends it on the serial +bus. This commands the device to TALK. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_acptr" name="cbm_k_acptr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p> + +<quote> +<descrip> +<tag/Function/Send an UNLISTEN command +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_unlsn (void);/ +<tag/Description/This function commands all devices on the serial bus to +stop receiving data from the host computer (i.e., UNLISTEN). Calling this +function results in an UNLISTEN command being transmitted on the serial +bus. Only devices previously commanded to LISTEN are affected. This +function is normally used after the host computer is finished sending data +to external devices. Sending the UNLISTEN commands the listening devices +to get off the serial bus so it can be used for other purposes. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_listen" name="cbm_k_listen"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cclear<label id="cclear"><p> + +<quote> +<descrip> +<tag/Function/Clear part of a line (write a given number of spaces). +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cclear (unsigned char length);/ +<tag/Description/The function clears part of a line by writing <tt/length/ +spaces in the current text color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclearxy" name="cclearxy">, +<ref id="clrscr" name="clrscr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cclearxy<label id="cclearxy"><p> + +<quote> +<descrip> +<tag/Function/Clear part of a line (write a given number of spaces) starting +at a specific screen position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cclearxy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function moves the cursor to a specific position, and +will then clear part of the line by writing <tt/length/ spaces in the current +text color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclear" name="cclear">, +<ref id="clrscr" name="clrscr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cgetc<label id="cgetc"><p> + +<quote> +<descrip> +<tag/Function/Read a character from the keyboard. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/char cgetc (void);/ +<tag/Description/The function reads a character from the keyboard. If there is +no character available, <tt/cgetc/ waits until the user presses a key. If the +cursor is enabled by use of the <tt/cursor/ function, a blinking cursor is +displayed while waiting. +<tag/Limits/<itemize> +<item>If the system supports a keyboard buffer, <tt/cgetc/ will fetch a key +from this buffer and wait only if the buffer is empty. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cursor" name="cursor">, +<ref id="kbhit" name="kbhit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>chline<label id="chline"><p> + +<quote> +<descrip> +<tag/Function/Output a horizontal line in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ chline (unsigned char length);/ +<tag/Description/The function outputs a horizontal line with the given length +starting at the current cursor position. +<tag/Limits/<itemize> +<item>The character used to draw the horizontal line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chlinexy" name="chlinexy">, +<ref id="cvline" name="cvline">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>chlinexy<label id="chlinexy"><p> + +<quote> +<descrip> +<tag/Function/Output a horizontal line at a given position in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ chlinexy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function outputs a horizontal line with the given length +starting at a given position. +<tag/Limits/<itemize> +<item>The character used to draw the horizontal line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="cvline" name="cvline">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clearerr<label id="clearerr"><p> + +<quote> +<descrip> +<tag/Function/Clear error and end-of-file status of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ clearerr (FILE* f);/ +<tag/Description/<tt/clearerr/ clears the error and end-of-file status +indicators for the stream <tt/f/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="feof">, +<ref id="ferror" name="ferror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clock<label id="clock"><p> + +<quote> +<descrip> +<tag/Function/Determine the processor time used. +<tag/Header/<tt/<ref id="time.h" name="time.h">/ +<tag/Declaration/<tt/clock_t clock (void);/ +<tag/Description/The <tt/clock/ function returns an approximaton of processor +time used by the program. The time is returned in implementation defined +units. It can be converted to seconds by dividing by the value of the macro +<tt/CLOCKS_PER_SEC/. +<tag/Limits/<itemize> +<item>Since the machines, cc65 generated programs run on, cannot run multiple +processes, the function will actually return the time since some +implementation defined point in the past. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="time" name="time"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clrscr<label id="clrscr"><p> + +<quote> +<descrip> +<tag/Function/Clear the text screen. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void clrscr (void);/ +<tag/Description/The function clears the text screen and moves the cursor to +the upper left corner. +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclear" name="cclear">, +<ref id="cclearxy" name="cclearxy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>close<label id="close"><p> + +<quote> +<descrip> +<tag/Function/Close a file descriptor. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int __fastcall__ close (int fd);/ +<tag/Description/The function closes the given file descriptor. It returns zero +on success and -1 on error. If an error occurs, the cause can be determined by +reading the <tt/errno/ variable. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="creat" name="creat">, +<ref id="open" name="open"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>closedir<label id="closedir"><p> + +<quote> +<descrip> +<tag/Function/Close a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int __fastcall__ closedir (DIR* dir);/ +<tag/Description/The function closes the given directory descriptor. It returns +zero on success and -1 on error. If an error occurs, the cause can be determined +by reading the <tt/errno/ variable. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="opendir" name="opendir">, +<ref id="readdir" name="readdir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>creat<label id="creat"><p> + +<quote> +<descrip> +<tag/Function/Create a file. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int __fastcall__ creat (const char* name, unsigned mode);/ +<tag/Description/<tt/creat/ creates a new file and returns the file descriptor +associated with it. On error, -1 is returned and an error code is stored in +<tt/errno/. +<tag/Limits/<itemize> +<item><tt/creat/ is identical to calling <tt/<ref id="open" name="open">/ with +<tt/flags/ equal to <tt/O_WRONLY | O_CREAT | O_TRUNC/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="close" name="close">, +<ref id="open" name="open"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cprintf<label id="cprintf"><p> + +<quote> +<descrip> +<tag/Function/Formatted output to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/int cprintf (const char* format, ...);/ +<tag/Description/The arguments are converted to text where necessary and +formatted according to the format string given. The resulting string is output +to the console. <tt/cprintf/ supports the same format specifiers as +<tt/printf/. <!-- <tt/<ref id="printf" name="printf">/. --> +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cprintf/ distinguishes +between <tt/\r/ and <tt/\n/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputc<label id="cputc"><p> + +<quote> +<descrip> +<tag/Function/Output a character directly to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputc (char c);/ +<tag/Description/Output one character to the console at the current cursor +position. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputc/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputcxy<label id="cputcxy"><p> + +<quote> +<descrip> +<tag/Function/Output a character at a specific screen position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputcxy (unsigned char x, unsigned char y, char c);/ +<tag/Description/<tt/cputcxy/ moves the cursor to the given x/y position on +the screen and outputs one character. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputcxy/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputs<label id="cputs"><p> + +<quote> +<descrip> +<tag/Function/Output a string directly to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputs (const char* s);/ +<tag/Description/The function outputs the given string on the console at the +current cursor position. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputs/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputsxy<label id="cputsxy"><p> + +<quote> +<descrip> +<tag/Function/Output a string to the console at a given position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputsxy (unsigned char x, unsigned char y, const char* s);/ +<tag/Description/<tt/cputsxy/ moves the cursor to the given x/y position, +and outputs the string <tt/s/. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputsxy/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cursor<label id="cursor"><p> + +<quote> +<descrip> +<tag/Function/Enable/disable a blinking cursor when waiting for keyboard input. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cursor (unsigned char onoff);/ +<tag/Description/If the argument to the function is non zero, a blinking cursor +will be enabled when the <tt/cgetc/ function waits for input from the keyboard. +If the argument is zero, <tt/cgetc/ will wait without a blinking cursor. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cgetc" name="cgetc">, +<ref id="kbhit" name="kbhit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cvline<label id="cvline"><p> + +<quote> +<descrip> +<tag/Function/Output a vertical line in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cvline (unsigned char length);/ +<tag/Description/The function outputs a vertical line with the given length +starting at the current cursor position. +<tag/Limits/<itemize> +<item>The character used to draw the vertical line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="chlinexy" name="chlinexy">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cvlinexy<label id="cvlinexy"><p> + +<quote> +<descrip> +<tag/Function/Output a vertical line at a given position in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cvlinexy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function outputs a vertical line with the given length +starting at a given position. +<tag/Limits/<itemize> +<item>The character used to draw the vertical line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="chlinexy" name="chlinexy">, +<ref id="cvline" name="cvline"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>div<label id="div"><p> + +<quote> +<descrip> +<tag/Function/Divide two ints and return quotient and remainder. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/div_t __fastcall__ div (int numer, int denom);/ +<tag/Description/<tt/div/ divides <tt/numer/ by <tt/denom/ and returns the +quotient and remainder in a <tt/div_t/ structure. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +ldiv +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_commit<label id="em_commit"><p> + +<quote> +<descrip> +<tag/Function/Commit changes into extended memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void em_commit (void);/ +<tag/Description/Commit changes in the memory window to extended storage. If +the contents of the memory window have been changed, these changes may be lost +if <tt/<ref id="em_map" name="em_map">/, <tt/<ref id="em_use" name="em_use">/, +<tt/<ref id="em_copyfrom" name="em_copyfrom">/ or <tt/<ref id="em_copyto" +name="em_copyto">/ are called without calling <tt/em_commit/ first. +<tag/Limits/<itemize> +<item>Calling <tt/em_commit/ does not necessarily mean that changes to the +memory window are discarded, it does just mean that the drivers is allowed +to discard it. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_map" name="em_map">, +<ref id="em_use" name="em_use"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_copyfrom<label id="em_copyfrom"><p> + +<quote> +<descrip> +<tag/Function/Copy from extended into normal memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_copyfrom (const struct em_copy* copy_data);/ +<tag/Description/Copy data from extended memory into linear memory. Source and +target addresses as well as the number of bytes to transfer are specified in +the <tt/em_copy/ structure that is passed as a parameter. +<tag/Limits/<itemize> +<item>Calling <tt/em_copyfrom/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_copyto" name="em_copyto">, +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_copyto<label id="em_copyto"><p> + +<quote> +<descrip> +<tag/Function/Copy from normal into extended memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_copyto (const struct em_copy* copy_data);/ +<tag/Description/Copy data from linear into extended memory. Source and +target addresses as well as the number of bytes to transfer are specified in +the <tt/em_copy/ structure that is passed as a parameter. +<tag/Limits/<itemize> +<item>Calling <tt/em_copyto/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_copyfrom" name="em_copyfrom">, +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_install<label id="em_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char _fastcall__ em_install (void* driver);/ +<tag/Description/The function installs an already loaded extended memory driver +and returns an error code. The function may be used to install a driver linked +statically to the program. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_uninstall" name="em_uninstall">, +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_load_driver<label id="em_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and initialize an extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_load_driver (const char* name);/ +<tag/Description/Load an extended memory driver into memory and initialize +it. The function returns an error code that tells if all this has been +successful. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The driver is loaded by name, so currently you must know the type of +extended memory that should be supported. There is no autodetect capability. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_map<label id="em_map"><p> + +<quote> +<descrip> +<tag/Function/Make a page of extended memory accessible. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void* __fastcall__ em_map (unsigned page);/ +<tag/Description/The function maps one page of extended memory into linear +memory and returns a pointer to the page frame. Depending on the hardware +and driver, the data is either mapped into the address space or transfered +into a buffer. If you don't need the actual contents of the page (for example +because you're going to overwrite it completely), it is better to call +<tt/<ref id="em_use" name="em_use">/ instead. <tt/em_use/ will not transfer the +data if it is possible to avoid that. +<tag/Limits/<itemize> +<item>Calling <tt/em_map/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_use" name="em_use"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_pagecount<label id="em_pagecount"><p> + +<quote> +<descrip> +<tag/Function/Return the number of available extended memory pages. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned em_pagecount (void);/ +<tag/Description/The function returns the size of the extended memory supported +by the driver in 256 byte pages. +<tag/Limits/<itemize> +<item>The function returns zero if no extended memory driver is loaded. +<item>The function may return zero if the supported hardware was not detected. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_uninstall<label id="em_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall an already loaded extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char em_uninstall (void);/ +<tag/Description/The function uninstalls an already loaded extended memory +driver but doesn't remove it from memory. +<tag/Limits/<itemize> +<item>If the driver has been loaded using <tt/<ref id="em_load_driver" +name="em_load_driver">/, <tt/<ref id="em_unload" name="em_unload">/ +should be used instead of <tt/em_uninstall/ so the driver is also removed +from memory. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_install" name="em_install">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_unload<label id="em_unload"><p> + +<quote> +<descrip> +<tag/Function/Unload an extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char em_unload (void);/ +<tag/Description/The function unloads a loaded extended memory driver and +frees all memory allocated for the driver. +<tag/Limits/<itemize> +<item>The function does nothing if no driver is loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_use<label id="em_use"><p> + +<quote> +<descrip> +<tag/Function/Prepare an extended memory page for use. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void* __fastcall__ em_use (unsigned page);/ +<tag/Description/The function maps one page of extended memory into linear +memory and returns a pointer to the page frame. This function is similar to +<tt/<ref id="em_map" name="em_map">/, but will not transfer data into the +actual memory window in the assumption that the existing data is wrong or +will get overwritten. +<tag/Limits/<itemize> +<item>Calling <tt/em_use/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_map" name="em_map"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>exit<label id="exit"><p> + +<quote> +<descrip> +<tag/Function/Terminate the program. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ exit (int status);/ +<tag/Description/<tt/exit/ terminates the program. The argument specifies the +return code of the program. Before termination, all files are closed, buffered +output is written and any functions registered with <tt/<ref id="atexit" +name="atexit">/ are called. Common values for status are <tt/EXIT_SUCCESS/ and +<tt/EXIT_FAILURE/ which are also defined in <tt/<ref id="stdlib.h" +name="stdlib.h">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>It depends on the host machine if the program return code can be +evaluated or is ignored. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>exec<label id="exec"><p> + +<quote> +<descrip> +<tag/Function/Execute a program file. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ exec (const char* progname, const char* cmdline);/ +<tag/Description/<tt/exec/ replaces the currently running program by a new one. +Calling <tt/exec()/ is identical to calling <tt/<ref id="exit" name="exit()">/, +then loading and starting the program named in the first argument, passing +the command line specified as second argument. Instead of an empty string, +a <tt/NULL/ pointer may be passed as second parameter. +On success, the function does not return. On failure, -1 is returned and +<tt/errno/ contains an error code. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>On most platforms, the function needs to copy a small stub loader to +some memory area outside the program space. This may collide with other +programs. See the platform specific docs on this. +<item>Because it is necessary to terminate the running program before the +memory can be reused to load the new one, there is a high chance that the +function may not be able to return on errors. +<item>The command line is passed to the new program in the same way as cc65 +programs expect the command line. If the new program is not a cc65 generated +program, it may not be able to read it. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>fast<label id="fast"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into 2MHz mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void fast (void);/ +<tag/Description/The function will switch the clock of the C128 to 2MHz. This +will nearly double the speed compared to slow mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>2MHz clock will not work in 40 column mode. +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="slow" name="slow">, +<ref id="toggle_videomode" name="toggle_videomode">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>feof<label id="feof"><p> + +<quote> +<descrip> +<tag/Function/Return the end-of-file indicator of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ feof (FILE* f);/ +<tag/Description/<tt/feof/ tests the end-of-file indicator ofthe stream +<tt/f/, and returns a non zero value if it is set. +<tag/Limits/<itemize> +<item>The indicator is set only after a read past the end of a file is +attempted. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="clearerr">, +<ref id="ferror" name="ferror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ferror<label id="ferror"><p> + +<quote> +<descrip> +<tag/Function/Return the error indicator of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ ferror (FILE* f);/ +<tag/Description/<tt/ferror/ tests the error indicator of the stream +<tt/f/, and returns a non zero value if it is set. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="clearerr">, +<ref id="ferror" name="feof"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>fileno<label id="fileno"><p> + +<quote> +<descrip> +<tag/Function/Return the file handle used by a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ fileno (FILE* f);/ +<tag/Description/The <tt/fileno/ function returns the file handle used +internally by a C stream. This file handle (an integer) can be used as a +handle for the POSIX input/output functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>Mixing C file I/O functions and POSIX file I/O functions for the same +file may have unpredictable results. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="creat" name="creat">, +<ref id="open" name="open"> <!-- , --> +<!-- <ref id="read" name="read">, --> +<!-- <ref id="write" name="write"> --> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>free<label id="free"><p> + +<quote> +<descrip> +<tag/Function/Free a block of dynamic memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ free (void* block);/ +<tag/Description/Free a block of dynamic memory previously allocated with +<tt/<ref id="malloc" name="malloc">/, <tt/<ref id="calloc" name="calloc">/ +or <tt/<ref id="realloc" name="realloc">/. As an exception, if the passed +pointer is <tt/NULL/, no action is performed. +<tag/Limits/ +<itemize> +<item>Passing an already free'd block to <tt/free/ again will cause undefined +behaviour and may crash your program. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>get_ostype<label id="get_ostype"><p> + +<quote> +<descrip> +<tag/Function/The function returns the operating system, the program runs on. +<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">, +<ref id="atari.h" name="atari.h">, <ref id="c64.h" name="c64.h">/ +<tag/Declaration/<tt/unsigned char get_ostype (void);/ +<tag/Description/<tt/get_ostype/ is machine dependent and does not exist for +all supported targets. If it exists, it returns a number that identifies the +operating system or machine type, the program runs on. The machine dependent +header files define constants that can be used to check the return code. +<tag/Limits/<itemize> +<item>The function does not exist on all platforms. +<item>The return codes are platform dependent. +</itemize> +<tag/Availability/cc65 (not all platforms) +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getcpu<label id="getcpu"><p> + +<quote> +<descrip> +<tag/Function/Determine on which CPU the program is running. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/unsigned char getcpu (void);/ +<tag/Description/The function checks on which CPU the code is running. It +returns one of the constants<itemize> +<item><tt/CPU_6502/ +<item><tt/CPU_65C02/ +<item><tt/CPU_65816/ +</itemize> +<tag/Limits/<itemize> +<item>Other, more exotic CPU types are not disinguished. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getenv<label id="getenv"><p> + +<quote> +<descrip> +<tag/Function/Return a value from the environment. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/ +<tag/Description/The function searches the environment for an entry that +matches <tt/name/ and returns its value. The environment consists of a list +of strings in the form <tt/name=value/. If there is no match, <tt/getenv/ +returns <tt/NULL/. +<tag/Limits/<itemize> +<item>What exactly is stored in the environment depends on the machine the +program is running on. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getopt<label id="getopt"><p> + +<quote> +<descrip> +<tag/Function/Parse command line options. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ getopt (int argc, char* const* argv, +const char* optstring);/ +<tag/Description/The function parses command line arguments, <tt/argc/ and +<tt/argv/ are the argument count and array passed to <tt/main/. <tt/optstring/ +is a string that contains command line option characters. If a character in +<tt/optstring/ is followed by a colon, the option requires an argument. An +option on the command line is recognized if it is one of the option characters +preceeded by a '-'. +<tt/getopt/ must be called repeatedly. It will return each option character +found on the command line and <tt/EOF/ (-1) if there is no other option. An +option argument is placed in <tt/optarg/, the index of the next element on the +command line to be processed is placed in <tt/optind/. +<tag/Limits/<itemize> +<item>The implementation will not reorder options. A non option on the command +line will terminate option processing. All remaining arguments are not +recognized as options, even if the start with a '-' character. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX.2 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotox<label id="gotox"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new X position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotox (unsigned char x);/ +<tag/Description/The function moves the text mode cursor to the specified X +position while leaving the Y position untouched. The leftmost position on the +screen has the coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Invalid values for the X position (out of screen coordinates) may +lead to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotoxy<label id="gotoxy"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotoxy (unsigned char x, unsigned char y);/ +<tag/Description/The function moves the text mode cursor to the specified +position. The leftmost position on the screen has the X coordinate 0, the +topmost line has the Y coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>Invalid values for any of both coordinates (out of screen positions) may +lead to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotoy<label id="gotoy"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new Y position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotoy (unsigned char x);/ +<tag/Description/The function moves the text mode cursor to the specified Y +position while leaving the X position untouched. The uppermost position on the +screen has the coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Invalid values for the Y position (out of screen coordinates) may lead +to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isalnum<label id="isalnum"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a letter or digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isalnum (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a letter or digit. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing +the macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isalpha<label id="isalpha"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isalpha (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a letter. The return value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isascii<label id="isascii"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is in the ASCII (0..127) range. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isascii (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is in the range 0..127 (the range of valid ASCII characters) and zero if not. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isblank<label id="isblank"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a space or tab. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isblank (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a space or tab character. The return value is zero if the character is +anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>iscntrl<label id="iscntrl"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a control character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ iscntrl (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a control character. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isdigit<label id="isdigit"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isdigit (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a digit. The return value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isgraph<label id="isgraph"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character (except +space). +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isgraph (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character with the exception of space. The return value is zero +if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>islower<label id="islower"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a lower case letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ islower (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a lower case letter. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isprint<label id="isprint"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isprint (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character (this includes the space character). The return value +is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ispunct<label id="ispunct"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character but not a +space or an alphanumeric character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ ispunct (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character, but not a space or anything alphanumeric. The return +value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isspace<label id="isspace"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a a white-space character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isspace (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a white space character. The return value is zero if the character is +anything else. The standard white space characters are: space, formfeed ('\f'), +newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab +('\v'). +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isupper<label id="isupper"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is an upper case letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isupper (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is an upper case letter. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isxdigit<label id="isxdigit"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a hexadecimal digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isxdigit (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a hexadecimal digit (0..9, a..f and A..F). The return value is zero if the +character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>itoa<label id="itoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ itoa (int val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the integer <tt/val/ into a string using +<tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>If <tt/val/ contains <tt/INT_MIN/, the behaviour is undefined. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_count<label id="joy_count"><p> + +<quote> +<descrip> +<tag/Function/Return the number of joysticks supported by the current driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_count (void);/ +<tag/Description/The function returns a the number of joysticks supported +by the current joystick driver. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +<item>The function returns the number of joysticks supported by the driver. +There's no way to check for the number of actually connected joysticks. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_read" name="joy_read"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_install<label id="joy_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/JOY_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_uninstall" name="joy_uninstall">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_load_driver<label id="joy_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load a driver from disk and install it. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_load_driver (const char* driver);/ +<tag/Description/The function loads a driver with the given name from disk +and installs it. An error code is returned, which is <tt/JOY_ERR_OK/ if the +driver was successfully loaded and installed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_install" name="joy_install">, +<ref id="joy_uninstall" name="joy_uninstall">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_read<label id="joy_read"><p> + +<quote> +<descrip> +<tag/Function/Read the status of a joystick. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_read (unsigned char joystick);/ +<tag/Description/The function reads the status bits for a joystick. The number +of the joystick is passed as parameter. The result may be examined by using one +of the <tt/JOY_xxx/ macros from <ref id="joystick.h" name="joystick.h">. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_count" name="joy_count">, +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_uninstall<label id="joy_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the current joystick driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_uninstall (void);/ +<tag/Description/The function uninstalls the currently installed joystick +driver. It does not remove the driver from memory. The function returns an +error code, which is <tt/JOY_ERR_OK/ if the driver was successfully uninstalled. +<tag/Limits/<itemize> +<item>A joystick driver must be installed using <ref id="joy_install" +name="joy_install"> before calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_install" name="joy_install">, +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_unload<label id="joy_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the current joystick driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_unload (void);/ +<tag/Description/The function uninstalls the currently installed joystick +driver and removes it from memory. An error code is returned, which is +<tt/JOY_ERR_OK/ if the driver was successfully uninstalled. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>kbhit<label id="kbhit"><p> + +<quote> +<descrip> +<tag/Function/Check if there's a key waiting in the keyboard buffer. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char kbhit (void);/ +<tag/Description/The function returns a value of zero if there is no character +waiting to be read from the keyboard. It returns non zero otherwise. +<tag/Limits/<itemize> +<item>If the system does not support a keyboard buffer (most systems +do), the function is rather useless. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cgetc" name="cgetc">, +<ref id="cursor" name="cursor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>labs<label id="labs"><p> + +<quote> +<descrip> +<tag/Function/Returns the absolute value of a long integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/long __fastcall__ labs (long v);/ +<tag/Description/<tt/labs/ returns the absolute value of the argument passed to +the function. +<tag/Limits/<itemize> +<item>The return value is undefined if <tt/LONG_MIN/ is passed to the function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abs" name="abs"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ltoa<label id="ltoa"><p> + +<quote> +<descrip> +<tag/Function/Convert a long integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ ltoa (long val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the long integer <tt/val/ into a string +using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>If <tt/val/ contains <tt/LONG_MIN/, the behaviour is undefined. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>localeconv<label id="localeconv"><p> + +<quote> +<descrip> +<tag/Function/Returns a pointer to the current locale structure. +<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ +<tag/Declaration/<tt/struct lconv* localeconv (void);/ +<tag/Description/<tt/localeconv/ returns a pointer to the current locale +structure. +<tag/Limits/<itemize> +<item>cc65 supports only the "C" locale, so even after setting a new locale +using <tt/<ref id="setlocale" name="setlocale">/, the structure returned will +always be the same. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setlocale" name="setlocale"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>longjmp<label id="longjmp"><p> + +<quote> +<descrip> +<tag/Function/Non local goto. +<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ +<tag/Declaration/<tt/void __fastcall__ longjmp (jmp_buf buf, int retval);/ +<tag/Description/The <tt/longjmp/ function restores a program context from the +data in <tt/buf/, which must have been set by a preceeding call to +<tt/<ref id="setjmp" name="setjmp">/. Program execution continues as if the +call to <tt/<ref id="setjmp" name="setjmp">/ has just returned the value +<tt/retval/. +<tag/Limits/ +<itemize> +<item>If the parameter <tt/retval/ is zero, the function will behave as if it +was called with a value of one. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setjmp" name="setjmp"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>malloc<label id="malloc"><p> + +<quote> +<descrip> +<tag/Function/Allocate dynamic memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ malloc (size_t size);/ +<tag/Description/<tt/malloc/ allocates size bytes on the heap and returns a +pointer to the allocated memory block. On error (not enough memory available), +<tt/malloc/ returns <tt/NULL/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="realloc" name="realloc">, +<ref id="strdup" name="strdup"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memchr<label id="memchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a block of raw memory. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ strchr (const void* mem, int c, size_t count);/ +<tag/Description/The <tt/memchr/ function locates the first occurrence of <tt/c/ +(converted to a char) in the block of raw memory string pointed to by <tt/mem/ +that is of size <tt/count/. Upon completion, the function returns a pointer to +the character found, or a null pointer if the character was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strchr" name="strchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memcmp<label id="memcmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two memory areas. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ memcmp (const void* p1, const void* p2, size_t count);/ +<tag/Description/<tt/memcmp/ compares <tt/count/ bytes from the memory area +pointed to by <tt/p1/ into the memory area pointed to by <tt/p2/. It returns a value that is less than +zero if <tt/p1/ is less than <tt/p2/, zero if <tt/p1/ is the same as <tt/p2/, +and a value greater than zero if <tt/p1/ is greater than <tt/p2/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memcpy<label id="memcpy"><p> + +<quote> +<descrip> +<tag/Function/Copy a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memcpy (void* dest, const void* src, size_t count);/ +<tag/Description/<tt/memcpy/ copies <tt/count/ bytes from the memory area +pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns +<tt/dest/. +<tag/Limits/ +<itemize> +<item>The result is undefined if the memory areas do overlap. Use +<tt/<ref id="memmove" name="memmove">/ to copy overlapping memory areas. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memmove<label id="memmove"><p> + +<quote> +<descrip> +<tag/Function/Copy a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memmove (void* dest, const void* src, size_t count);/ +<tag/Description/<tt/memmove/ copies <tt/count/ bytes from the memory area +pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns +<tt/dest/. +<tag/Limits/ +<itemize> +<item>While <tt/memmove/ allows the memory areas to overlap, it has some +additional overhead compared to <tt/<ref id="memcpy" name="memcpy">/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memcpy" name="memcpy">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memset<label id="memset"><p> + +<quote> +<descrip> +<tag/Function/Fill a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memset (void* p, int val, size_t count);/ +<tag/Description/<tt/memset/ fills the memory area pointed to by <tt/p/ with +the value <tt/val/. The function returns <tt/p/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="bzero" name="bzero">, +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mod_free<label id="mod_free"><p> + +<quote> +<descrip> +<tag/Function/Free a relocatable module. +<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ +<tag/Declaration/<tt/void __fastcall__ mod_free (void* module);/ +<tag/Description/The function will free a module loaded into memory by use of +the <tt/<ref id="mod_load" name="mod_load">/ function. +<tag/Limits/<itemize> +<item>The pointer passed as parameter is the pointer to the module memory, +not the pointer to the control structure. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mod_load" name="mod_load"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mod_load<label id="mod_load"><p> + +<quote> +<descrip> +<tag/Function/Load a relocatable module. +<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ +<tag/Declaration/<tt/unsigned char mod_load (struct mod_ctrl* ctrl);/ +<tag/Description/The function will load a code module into memory and relocate +it. The function will return an error code. If <tt/MLOAD_OK/ is returned, the +outgoing fields in the passed <tt/mod_ctrl/ struct contain information about +the module just loaded. Possible error codes are: +<itemize> +<item><tt/MLOAD_OK/ - Module load successful +<item><tt/MLOAD_ERR_READ/ - Read error +<item><tt/MLOAD_ERR_HDR/ - Header error +<item><tt/MLOAD_ERR_OS/ - Wrong operating system +<item><tt/MLOAD_ERR_FMT/ - Data format error +<item><tt/MLOAD_ERR_MEM/ - Not enough memory +</itemize> +<tag/Limits/<itemize> +<item>The <htmlurl url="ld65.html" name="ld65"> linker is needed to create +relocatable o65 modules for use with this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mod_free" name="mod_free"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_setbox<label id="mouse_setbox"><p> + +<quote> +<descrip> +<tag/Function/Specify a bounding box for the mouse cursor. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_setbox (const struct mouse_box* box);/ +<tag/Description/The function allows to set a bounding box for mouse movement. +<tag/Limits/<itemize> +<item>The function does not check if the mouse cursor is currently within the +given rectangle. Placing the mouse cursor within the bounding box is the +responsibility of the programmer. +<item>While the bounding box may be larger than the actual screen size, the +standard mouse cursor draw routines may fail to set the cursor to coordinates +outside of the screen area. Depending on the platform, you may have to supply +your own mouse cursor routines. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_getbox" name="mouse_getbox">, +<ref id="mouse_move" name="mouse_move"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_getbox<label id="mouse_getbox"><p> + +<quote> +<descrip> +<tag/Function/Return the current bounding box for the mouse cursor. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_getbox (struct mouse_box* box);/ +<tag/Description/The function queries the current bounding box for mouse +movement. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_move" name="mouse_move">, +<ref id="mouse_setbox" name="mouse_setbox"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_buttons<label id="mouse_buttons"><p> + +<quote> +<descrip> +<tag/Function/Return a bit mask encoding the state of the mouse buttons. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char mouse_buttons (void);/ +<tag/Description/The function returns a bit mask that encodes the state of the +mouse buttons. You may use the <tt/MOUSE_BTN_XXX/ flags to decode the function +return value. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_info" name="mouse_info">, +<ref id="mouse_pos" name="mouse_pos"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_geterrormsg<label id="mouse_geterrormsg"><p> + +<quote> +<descrip> +<tag/Function/Return a readable error message for an error code. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/const char* __fastcall__ mouse_geterrormsg (unsigned char +code);/ +<tag/Description/The function returns an error message (in english) for the +error code passed parameter. +<tag/Limits/<itemize> +<item>The function will return "Unknown error" for invalid error codes. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_hide<label id="mouse_hide"><p> + +<quote> +<descrip> +<tag/Function/Hide the mouse pointer. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void mouse_hide (void);/ +<tag/Description/The function hides the mouse pointer. It manages a counter +that is shared between <tt/<ref id="mouse_show" name="mouse_show">/ and +<tt/mouse_hide/ so that every call call to <tt/mouse_hide/ must be followed by +a call to <tt/<ref id="mouse_show" name="mouse_show">/ to make the mouse cursor +visible. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_show" name="mouse_show"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_info<label id="mouse_info"><p> + +<quote> +<descrip> +<tag/Function/Return the state of the mouse buttons and the position of the +mouse. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_info (struct mouse_info* info);/ +<tag/Description/The function returns the state of the mouse buttons and the +position of the mouse in the <tt/mouse_info/ structure passed as parameter. +<tag/Limits/<itemize> +<item>The <tt/mouse_info/ struct is a superset of the <tt/mouse_pos/ struct, +so if you just need the mouse position, call <tt/<ref id="mouse_pos" +name="mouse_pos">/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_buttons" name="mouse_buttons">, +<ref id="mouse_pos" name="mouse_pos"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_install<label id="mouse_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_install (const struct +mouse_callbacks* c, void* driver);/ +<tag/Description/The function installs an already loaded mouse driver and +returns an error code. The <tt/mouse_callbacks/ structure passed as first +parameter contains pointers to routines needed to move or hide/show the mouse +pointer. Defaults for these routines are supplied by the library, so if you +can live with these defaults (which are platform specific), just pass a +pointer to <tt/mouse_def_callbacks/. The function may be used to install a +driver linked statically to the program. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>After installing a driver, the mouse cursor is hidden. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_ioctl<label id="mouse_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Call the driver specific ioctl function. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_ioctl (unsigned char code, void* data);/ +<tag/Description/The function calls the IOCTL entry in the mouse driver, +which is driver specific. The <tt/code/ parameter will choose between +different IOCTL functions, and the <tt/data/ depends on code. The +function returns an error code. The purpose of this function is to allow +for driver specific extensions. See the documentation for a specific mouse +driver for supported ioctl calls. +<tag/Limits/<itemize> +<item>Calling this function is non portable, because each driver may +implement different ioctl calls (or none at all). +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_load_driver<label id="mouse_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and initialize a mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_load_driver (const struct +mouse_callbacks* c, const char* driver);/ +<tag/Description/Load a mouse driver into memory and initialize it. The +function returns an error code that tells if the call has been successful. The +<tt/mouse_callbacks/ structure passed as first parameter contains pointers to +routines needed to move or hide/show the mouse pointer. Defaults for these +routines are supplied by the library, so if you can live with these defaults +(which are platform specific), just pass a pointer to <tt/mouse_def_callbacks/. +<tag/Limits/<itemize> +<item>The driver is loaded by name, so currently you must know the type of +mouse that should be supported. There is no autodetect capability. +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>After installing a driver, the mouse cursor is hidden. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_move<label id="mouse_move"><p> + +<quote> +<descrip> +<tag/Function/Move the mouse cursor to a specific position. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_move (int x, int y);/ +<tag/Description/The function updates the mouse position. If the mouse cursor +is visible, it is shown at the new position. +<tag/Limits/<itemize> +<item>The function does not check if the new position is within the bounding +box specified with <tt/<ref id="mouse_setbox" name="mouse_setbox">/. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_getbox" name="mouse_getbox">, +<ref id="mouse_setbox" name="mouse_setbox"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_pos<label id="mouse_pos"><p> + +<quote> +<descrip> +<tag/Function/Return the position of the mouse. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_pos (struct mouse_pos* pos);/ +<tag/Description/The function returns the position of the mouse in the +<tt/mouse_pos/ structure passed as parameter. +<tag/Limits/<itemize> +<item>The <tt/mouse_pos/ struct is a subset of the <tt/mouse_info/ struct, +so if you do also need the mouse buttons, call <tt/<ref id="mouse_info" +name="mouse_info">/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_buttons" name="mouse_buttons">, +<ref id="mouse_info" name="mouse_info"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_show<label id="mouse_show"><p> + +<quote> +<descrip> +<tag/Function/Show the mouse pointer. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void mouse_show (void);/ +<tag/Description/The function shows the mouse pointer. It manages a counter +that is shared between <tt/<ref id="mouse_hide" name="mouse_hide">/ and +<tt/mouse_show/. The mouse cursor is visible if there was one more call to +<tt/mouse_show/ than to <tt/<ref id="mouse_hide" name="mouse_hide">/. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_hide" name="mouse_hide"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_uninstall<label id="mouse_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall an already loaded mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char mouse_uninstall (void);/ +<tag/Description/The function uninstalls an already loaded mouse driver but +don't removes it from memory. +<tag/Limits/<itemize> +<item>If the driver has been loaded using <tt/<ref id="mouse_load_driver" +name="mouse_load_driver">/, <tt/<ref id="mouse_unload" name="mouse_unload">/ +should be used instead of <tt/mouse_uninstall/ so the driver is also removed +from memory. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_unload<label id="mouse_unload"><p> + +<quote> +<descrip> +<tag/Function/Unload a mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_unload (void);/ +<tag/Description/The function unloads a loaded mouse driver and frees all +memory allocated for the driver. +<tag/Limits/<itemize> +<item>The function does nothing if no driver is loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>offsetof<label id="offsetof"><p> + +<quote> +<descrip> +<tag/Function/Calculate the offset of a struct or union member. +<tag/Header/<tt/<ref id="stddef.h" name="stddef.h">/ +<tag/Declaration/<tt/size_t offsetof (type, member);/ +<tag/Description/<tt/offsetof/ calculates the address offset of a <tt/struct/ +or <tt/union/ member. +<tag/Limits/<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/ISO 9899 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>open<label id="open"><p> + +<quote> +<descrip> +<tag/Function/Open and possibly create a file. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int open (const char* name, int flags, ...);/ +<tag/Description/<tt/open/ opens a file and returns the file descriptor +associated with it. On error, -1 is returned and an error code is stored in +<tt/errno/. Several flags may be passed to <tt/open/ that change the behaviour. +<tag/Limits/<itemize> +<item>POSIX specifies an additional <tt/mode/ argument that may be passed to +open, which is used as the permission mask when a new file is created. While +cc65 allows to pass this argument, it is ignored. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="close" name="close">, +<ref id="creat" name="creat"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>opendir<label id="opendir"><p> + +<quote> +<descrip> +<tag/Function/Open a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/DIR* __fastcall__ opendir (const char* name);/ +<tag/Description/<tt/opendir/ opens a directory and returns the direcory +descriptor associated with it. On error, NULL is returned and an error code is +stored in <tt/errno/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="closedir" name="closedir">, +<ref id="readdir" name="readdir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>peekbsys<label id="peekbsys"><p> + +<quote> +<descrip> +<tag/Function/Read one byte from a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ peekbsys (unsigned addr);/ +<tag/Description/<tt/peekbsys/ reads one byte from the given address in the +system bank (bank 15) of the CBM PET-II machines and returns it. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>This function may be a macro depending on the compiler options. The +actual function is accessible by #undef'ing the macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="PEEKW" name="PEEKW">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokebsys" name="pokebsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>peekwsys<label id="peekwsys"><p> + +<quote> +<descrip> +<tag/Function/Read one word from a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ peekwsys (unsigned addr);/ +<tag/Description/<tt/peekwsys/ reads one word from the given address in the +system bank (bank 15) of the CBM PET-II machines and returns it. Following +the usual 6502 conventions, the low byte is read from <tt/addr/, and the +high byte is read from <tt/addr+1/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The order in which the two bytes are read is undefined. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="PEEKW" name="PEEKW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="pokebsys" name="pokebsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>perror<label id="perror"><p> + +<quote> +<descrip> +<tag/Function/Print an error message for the error in <tt/errno/. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ perror (const char* s);/ +<tag/Description/<tt/perror/ prints an error message to <tt/stderr/. If <tt/s/ +is not <tt/NULL/ and not an empty string, it is printed followed by a colon and +a blank. Then the error message for the current contents of <tt/errno/ is +printed followed by a newline. The message output is the same as returned by +<tt/<ref id="strerror" name="strerror">/ with an argument of <tt/errno/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_poserror" name="_poserror">, +<ref id="strerror" name="strerror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>pokebsys<label id="pokebsys"><p> + +<quote> +<descrip> +<tag/Function/Write one byte to a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/void __fastcall__ pokebsys (unsigned addr, unsigned char val);/ +<tag/Description/<tt/pokebsys/ writes one byte to the given address in the +system bank (bank 15) of the CBM PET-II machines. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="POKE" name="POKE">, +<ref id="POKEW" name="POKEW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>pokewsys<label id="pokewsys"><p> + +<quote> +<descrip> +<tag/Function/Write one word to a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/void __fastcall__ pokewsys (unsigned addr, unsigned val);/ +<tag/Description/<tt/pokewsys/ writes one word to the given address in the +system bank (bank 15) of the CBM PET-II machines. Following the usual 6502 +conventions, the low byte of <tt/val/ is written to <tt/addr/, and the +high byte is written to <tt/addr+1/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The order in which the two bytes are written is undefined. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="POKE" name="POKE">, +<ref id="POKEW" name="POKEW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokebsys" name="pokebsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>qsort<label id="qsort"><p> + +<quote> +<descrip> +<tag/Function/Sort an array. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ qsort (void* base, size_t count, +size_t size, int (*compare) (const void*, const void*));/ +<tag/Description/<tt/qsort/ sorts an array according to a given compare +function <tt/compare/. <tt/base/ is the address of the array, <tt/count/ +is the number of elements, <tt/size/ the size of an element and <tt/compare/ +the function used to compare the members. +<tag/Limits/ +<itemize> +<item>If there are multiple members with the same key, the order after calling +the function is undefined. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="bsearch" name="bsearch"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>raise<label id="raise"><p> + +<quote> +<descrip> +<tag/Function/Send a signal to the executing program. +<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ +<tag/Declaration/<tt/int __fastcall__ raise (int sig);/ +<tag/Description/<tt/raise/ sends the given signal to the program. If the +program has installed a signal handler for the signal, this signal handler +will be executed. If no handler has been installed, the default action for +the raised signal will be taken. The function returns zero on success, +nonzero otherwise. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="signal" name="signal"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>rand<label id="rand"><p> + +<quote> +<descrip> +<tag/Function/Return a pseudo random number. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int rand (void);/ +<tag/Description/The function returns a pseudo random number +between 0 and <tt/RAND_MAX/ (exclusive). +<tag/Limits/<itemize> +<item>Without using <tt><ref id="srand" name="srand"></tt>, always the same +flow of numbers is generated. +<item>On startup, the function behaves as if <ref id="srand" name="srand"> +had been used with an argument of 1. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_randomize" name="_randomize">, +<ref id="srand" name="srand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>readdir<label id="readdir"><p> + +<quote> +<descrip> +<tag/Function/Read a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/struct dirent* __fastcall__ readdir (DIR* dir);/ +<tag/Description/<tt/readdir/ reads the next directory entry from the directory +stream pointed to by <tt/dir/. It stores the data in a <tt/dirent/ structure +and returns a pointer to it. If the end of directory is reached, or an error +occurs, NULL is returned. In case of errors, an error code is stored into +<tt/errno/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The returned pointer may point to a statically allocated instance of +<tt/struct dirent/, so it may get overwritten by subsequent calls to +<tt/readdir/. +<item>On several platforms, namely the CBMs and the Atari, the disk drives get +confused when opening/closing files between directory reads. So for example a +program that reads the list of files on a disk, and after each call to +<tt/readdir/, opens the file to process it, will fail.<newline> +Possible solutions are reading the directory into memory before processing the +file list, or to reset the directory by seeking to the correct position after +opening/closing a file: +<verb> + seekdir (DIR, telldir (DIR)); +</verb> +Platforms known to work without problems are: Apple. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="closedir" name="closedir">, +<ref id="opendir" name="opendir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>realloc<label id="realloc"><p> + +<quote> +<descrip> +<tag/Function/Change the size of an allocated memory block. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ realloc (void* block, size_t size);/ +<tag/Description/<tt/realloc/ changes the size of the memory block pointed to +by <tt/block/ to <tt/size/ bytes. If <tt/block/ is <tt/NULL/, <tt/realloc/ +behaves as if <tt/malloc/ had been called. If <tt/size/ is zero, <tt/realloc/ +behaves as if <tt/free/ had been called. On error (not enough memory +available), <tt/realloc/ returns <tt/NULL/. +<tag/Limits/ +<itemize> +<item>The part of the memory block that is returned will have its contents +unchanged. +<item>This function is somewhat dangerous to use. Be careful to save the +pointer you're passing somewhere else, otherwise +<tscreen><verb> + ptr = realloc (ptr, size); +</verb></tscreen> +will loose your only copy of <tt/ptr/ if <tt/realloc/ returns <tt/NULL/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>remove<label id="remove"><p> + +<quote> +<descrip> +<tag/Function/Delete a file. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ remove (const char* name);/ +<tag/Description/<tt/remove/ deletes the file with the given name. On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>This function is not available on all cc65 targets (depends on the +availability of file I/O). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="rename" name="rename">, +<ref id="unlink" name="unlink"> +<tag/Example/ +<verb> +#include <stdio.h> + +#define FILENAME "helloworld" + +if (remove (FILENAME) == 0) { + printf ("We deleted %s successfully\n", FILENAME); +} else { + printf ("There was a problem deleting %s\n", FILENAME); +} +</verb> +</descrip> +</quote> + + +<sect1>rename<label id="rename"><p> + +<quote> +<descrip> +<tag/Function/Rename a file. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ rename (const char* oldname, const char* newname);/ +<tag/Description/<tt/rename/ renames a file (gives it a new name). On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>This function is not available on all cc65 targets (depends on the +capabilities of the storage devices). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="remove" name="remove"> +<tag/Example/ +<verb> +#include <stdio.h> + +#define OLDNAME "textfile.txt" +#define NEWNAME "textfile.bak" + +if (rename (OLDNAME, NEWNAME) == 0) { + printf ("Renamed %s to %s\n", OLDNAME, NEWNAME); +} else { + printf ("Error renaming %s to %s\n", OLDNAME, NEWNAME); +} +</verb> +</descrip> +</quote> + + +<sect1>reset_brk<label id="reset_brk"><p> + +<quote> +<descrip> +<tag/Function/Resets the break vector to its original value. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void reset_brk (void);/ +<tag/Description/<tt/reset_brk/ resets the break vector to the value it had +before a call to <tt/set_brk/. +<tag/Limits/ +<itemize> +<item>Since <tt/<ref id="set_brk" name="set_brk">/ installs an exit handler, +it is not strictly necessary to call this function as part of the cleanup when +the program ends. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_irq" name="reset_irq">, +<ref id="set_brk" name="set_brk">, +<ref id="set_irq" name="set_irq"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>reset_irq<label id="reset_irq"><p> + +<quote> +<descrip> +<tag/Function/Resets the C level interrupt request vector. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void reset_irq (void);/ +<tag/Description/<tt/reset_irq/ resets the C level interrupt request vector. +<tag/Limits/ +<itemize> +<item>The original IRQ vector is restored on program termination even without +calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk">, +<ref id="set_brk" name="set_brk">, +<ref id="set_irq" name="set_irq"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>revers<label id="revers"><p> + +<quote> +<descrip> +<tag/Function/Control revers character display. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ revers (unsigned char onoff);/ +<tag/Description/If the argument is non zero, the function enables reverse +character display. If the argument is zero, reverse character display is +switched off. The old value of the setting is returned. +<tag/Limits/<itemize> +<item>The function may not be supported by the hardware, in which case +the call is ignored. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>rewinddir<label id="rewinddir"><p> + +<quote> +<descrip> +<tag/Function/Reset a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/void __fastcall__ rewinddir (DIR* dir);/ +<tag/Description/<tt/rewinddir/ sets the position of the directory stream +pointed to by <tt/dir/ to the start of the directory. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="seekdir" name="seekdir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>screensize<label id="screensize"><p> + +<quote> +<descrip> +<tag/Function/Return the dimensions of the text mode screen. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ screensize (unsigned char* x, unsigned char* y);/ +<tag/Description/The function returns the dimensions of the text mode screen. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoxy" name="gotoxy">, +<ref id="gotoy" name="gotoy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>seekdir<label id="seekdir"><p> + +<quote> +<descrip> +<tag/Function/Set the position of a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/void __fastcall__ seekdir (DIR* dir, long offset);/ +<tag/Description/<tt/seekdir/ sets the position of the directory stream +pointed to by <tt/dir/ to the value given in <tt/offset/, which should be a +value returned by <tt/<ref id="telldir" name="telldir">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="rewinddir" name="rewinddir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ser_close<label id="ser_close"><p> + +<quote> +<descrip> +<tag/Function/Close the port and disable interrupts +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_close (void);/ +<tag/Description/Close the port by clearing buffers and disable interrupts. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +#include <serial.h> + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(lynx_comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} +</verb> +</descrip> +</quote> + + +<sect1>ser_get<label id="ser_get"><p> + +<quote> +<descrip> +<tag/Function/Read a character from serial port. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_get (char* b);/ +<tag/Description/Get a character from the serial port. If no characters are +available, the function will return SER_ERR_NO_DATA, so this is not a fatal +error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +Wait for a character to be available from a serial port. +<verb> +char ch; +while (ser_get(&ch) == SER_ERR_NO_DATA) + ; +</verb> +</descrip> +</quote> + + +<sect1>ser_install<label id="ser_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/SER_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="ser_load_driver" name="ser_load_driver">, +<ref id="ser_uninstall" name="ser_uninstall">, +<ref id="ser_unload" name="ser_unload"> +<tag/Example/<verb> +ser_install(lynx_comlynx); //Include the driver statically instead of loading it. +</verb> +</descrip> +</quote> + + +<sect1>ser_ioctl<label id="ser_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Platform dependent code extensions. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);/ +<tag/Description/Some platforms have extra serial functions that are not +supported by standard serial driver functions. You can extend the driver to support +this extra functionality bt using ser_ioctl functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>These functions are not easily portable to other cc65 platforms. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None +</descrip> +</quote> + +<sect1>ser_load_driver<label id="ser_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and install a serial driver. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_load_driver (const char *name);/ +<tag/Description/Load and install the driver by name. +Will just load the driver and check if loading was successful. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ser_open<label id="ser_open"><p> + +<quote> +<descrip> +<tag/Function/Open the port by setting the port parameters and enable interrupts +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_open (const struct ser_params* params);/ +<tag/Description/Open the port by setting the port parameters and enable interrupts. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +#include <serial.h> + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(lynx_comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} +</verb> +</descrip> +</quote> + + +<sect1>ser_put<label id="ser_put"><p> + +<quote> +<descrip> +<tag/Function/Write a character to a serial port. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (char b);/ +<tag/Description/Send a character via the serial port. There is a transmit +buffer, but transmitting is not done via interrupt. The function returns +SER_ERR_OVERFLOW if there is no space left in the transmit buffer. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +ser_put('A'); +</verb> +</descrip> +</quote> + + +<sect1>ser_status<label id="ser_status"><p> + +<quote> +<descrip> +<tag/Function/Return the serial port status. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_status (unsigned char* status);/ +<tag/Description/Return the serial port status. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None +</descrip> +</quote> + + +<sect1>ser_uninstall<label id="ser_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the currently loaded driver but do not unload it. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_uninstall (void);/ +<tag/Description/Uninstall the currently loaded driver but do not unload it. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>ser_unload<label id="ser_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the currently loaded driver. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_unload (void);/ +<tag/Description/Uninstall, then unload the currently loaded driver. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>set_brk<label id="set_brk"><p> + +<quote> +<descrip> +<tag/Function/Set the break vector to a user function. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ set_brk (brk_handler func);/ +<tag/Description/<tt/set_brk/ allows a user program to handle breaks within the +program code by letting the vector point to a user written C function. The +runtime library installs a small stub that saves the registers into global +variables that may be accessed (and changed) by the break handler. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The stub saves the zero page registers used by the C runtime and switches +to a small break handler stack. This means that it is safe to execute C code, +even if C code was interrupted. Be careful however not to use too many local +variables, and do not enable stack checks for the handler function or any other +function called from it. +<item>The <tt/brk_pc/ variable points to the <tt/BRK/ instruction. If you want +the continue with the interrupted code, you have to adjust <tt/brk_pc/, +otherwise the <tt/BRK/ instruction will get executed over and over again. +<item>Since <tt/set_brk/ installs an exit handler, it is not strictly necessary +to call <tt/<ref id="reset_brk" name="reset_brk">/ as part of the cleanup when +the program terminates. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>set_irq<label id="set_irq"><p> + +<quote> +<descrip> +<tag/Function/Set the C level interrupt request vector to the given address. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ set_irq (irq_handler f, void *stack_addr, size_t stack_size);/ +<tag/Description/<tt/set_irq/ allows a user program to handle interrupt requests +(IRQs) within the program code by letting the vector point to a user written C +function. The runtime library installs a small stub that saves the zero page +registers used by the C runtime before calling the handler function and restores +them after the handler function returns. Additionally the stub temporarily switches +the C runtime stack to the stack area provided as parameter. If the handler function +was set up to handle a "private", "exclusive" interrupt request source it must +return the value <tt/IRQ_HANDLED/ if and only if it has verified that the current +interrupt request actually stems from that source. In all other cases it must return +the value <tt/IRQ_NOT_HANDLED/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The stub saves the registers and zero page locations used by the C runtime +and switches to the provided stack area. As a consequence, there is some +runtime overhead, but it it is safe to execute C code, even if other C code +was interrupted. Be careful however not to call C library functions, and do not +enable stack checks for the handler function or any other function called from +it. +<item>The interrupt vector is reset on function termination, so it's not +strictly necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as part +of the cleanup when the program terminates. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk">, +<ref id="reset_irq" name="reset_irq">, +<ref id="set_brk" name="set_brk"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>setjmp<label id="setjmp"><p> + +<quote> +<descrip> +<tag/Function/Save the context for use with <tt/longjmp/. +<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ +<tag/Declaration/<tt/int __fastcall__ setjmp (jmp_buf buf);/ +<tag/Description/The <tt/setjmp/ function saves the current context in <tt/buf/ +for subsequent use by the <tt/<ref id="longjmp" name="longjmp">/ function and +returns zero. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item><tt/setjmp/ is actually a macro as required by the ISO standard. +<item><tt/setjmp/ will not save the signal context. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="longjmp" name="longjmp"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>setlocale<label id="setlocale"><p> + +<quote> +<descrip> +<tag/Function/Selects a locale. +<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ +<tag/Declaration/<tt/char* __fastcall__ setlocale (int category, const char* locale);/ +<tag/Description/<tt/setlocale/ sets or queries the program's locale. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>cc65 supports only the "C" locale, so calling this function to set a +different locale has no effect. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="localeconv" name="localeconv">, +<ref id="strcoll" name="strcoll"> +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>signal<label id="signal"><p> + +<quote> +<descrip> +<tag/Function/Install a signal handler. +<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ +<tag/Declaration/<tt/__sigfunc __fastcall__ signal (int sig, __sigfunc func);/ +<tag/Description/<tt/signal/ installs a handler for the given signal. The +handler may either be a user supplied function, or one of the predefined +signal handlers <tt/SIG_IGN/ or <tt/SIG_DFL/. The function returns the +previous value if the signal , or the special function vector SIG_ERR in +case of an error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="raise" name="raise"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>sleep<label id="sleep"><p> + +<quote> +<descrip> +<tag/Function/Sleep for a specified amount of time. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/void __fastcall__ sleep (unsigned seconds);/ +<tag/Description/The function will return after the specified number of +seconds have elapsed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>slow<label id="slow"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into 1MHz mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void slow (void);/ +<tag/Description/The function will switch the clock of the C128 to 1MHz. This +will halve the speed compared to fast mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="toggle_videomode" name="toggle_videomode">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>srand<label id="srand"><p> + +<quote> +<descrip> +<tag/Function/Initialize the pseudo random number generator. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ srand (unsigned seed);/ +<tag/Description/The function initializes the random number generator using +the given seed. On program startup, the generator behaves as if <tt/srand/ has +been called with an argument of 1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_randomize" name="_randomize">, +<ref id="rand" name="rand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcasecmp<label id="strcasecmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcasecmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcasecmp/ function compares the two strings passed +as parameters without case sensitivity. It returns a value that is less than +zero if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, +and a value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcat<label id="strcat"><p> + +<quote> +<descrip> +<tag/Function/Concatentate two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcat (char* s1, const char* s2);/ +<tag/Description/The <tt/strcat/ function appends a copy of the string +pointed to by s2 (including the terminating null byte) to the end of the +string pointed to by s1. The initial byte of s2 overwrites the null byte at +the end of s1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strchr<label id="strchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strchr (const char* s, int c);/ +<tag/Description/The <tt/strchr/ function locates the first occurrence of <tt/c/ +(converted to a char) in the string pointed to by <tt/s/. The terminating null +byte is considered to be part of the string. Upon completion, the function +returns a pointer to the byte, or a null pointer if the byte was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="memchr" name="memchr">, +<ref id="strrchr" name="strrchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcmp<label id="strcmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcmp/ function compares the two strings passed as +parameters. It returns a value that is less than zero if <tt/s1/ is less than +<tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater than zero +if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp"> +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcoll<label id="strcoll"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcoll (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcoll/ function compares the two strings passed as +parameters, according to the collating sequence set by <tt/<ref id="setlocale" +name="setlocale">/. It returns a value that is less than zero if <tt/s1/ is +less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater +than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setlocale" name="setlocale">, +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcpy<label id="strcpy"><p> + +<quote> +<descrip> +<tag/Function/Copy a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2);/ +<tag/Description/The <tt/strcpy/ function copies the string pointed to by +<tt/s2/ (including the terminating null byte) into the array pointed to by +<tt/s1/. The function will always return <tt/s1/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcat" name="strcat">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/ +<verb> +#include <string.h> + +static char hello[14]; + +strcpy (hello, "Hello world!\n"); +</verb> +</descrip> +</quote> + + +<sect1>strcspn<label id="strcspn"><p> + +<quote> +<descrip> +<tag/Function/Compute the length of a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strcspn (const char* s, const char* set);/ +<tag/Description/The <tt/strcspn/ function computes and returns the length of +the substring pointed to by <tt/s/ which does <em>not</em> consist of +characters contained in the string <tt/set/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strspn" name="strspn">, +<ref id="strstr" name="strstr">, +<ref id="strtok" name="strtok"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strdup<label id="strdup"><p> + +<quote> +<descrip> +<tag/Function/Allocate a copy of a string on the heap. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strdup (const char* s);/ +<tag/Description/<tt/strdup/ allocates a memory block on the heap, big enough +to hold a copy of <tt/s/ including the terminating zero. If the allocation +fails, <tt/NULL/ is returned, otherwise <tt/s/ is copied into the allocated +memory block, and a pointer to the block is returned. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>It is up to the caller to free the allocated memory block. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="free" name="free">, +<ref id="malloc" name="malloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strerror<label id="strerror"><p> + +<quote> +<descrip> +<tag/Function/Return a string describing an error code. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strerror (int errcode);/ +<tag/Description/The <tt/strerror/ function returns a string describing the +given error code. If an invalid error code is passed, the string "Unknown +error" is returned, and <tt/errno/ is set to <tt/EINVAL/. In all other cases, +<tt/errno/ is left untouched. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>While the return type of the function is a <tt/char*/, the returned +string must not be modified by the caller! +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_stroserror" name="_stroserror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>stricmp<label id="stricmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ stricmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/stricmp/ function compares the two strings passed as +parameters without case sensitivity. It returns a value that is less than zero +if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a +value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlen<label id="strlen"><p> + +<quote> +<descrip> +<tag/Function/Return the length of a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strlen (const char* s);/ +<tag/Description/The <tt/strlen/ function computes the number of bytes in the +string to which s points, not including the terminating null byte. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>When compiling with <tt/-Os/ (inline known standard functions), the +function does not work correctly for strings with more than 255 characters. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlower<label id="strlower"><p> + +<quote> +<descrip> +<tag/Function/Make a string lower case. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strlower (char* s);/ +<tag/Description/The <tt/strlower/ function will apply the <tt/tolower/ +function to each character of a string. The function will always return <tt/s/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function prototype is unavailable when compiling in strict ANSI mode. +<item>An alias name for this function is <tt/strlwr/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strupper" name="strupper">, +<ref id="tolower" name="tolower"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlwr<label id="strlwr"><p> + +<quote> +See <tt/strlower/. +</quote> + + +<sect1>strncat<label id="strncat"><p> + +<quote> +<descrip> +<tag/Function/Concatentate two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strncat (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strncat/ function appends not more than n characters +of the string pointed to by s2 to the end of the string pointed to by s1. The +terminating null character at the end of s1 is overwritten. A terminating null +character is appended to the result, even if not all of s2 is appended to s1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strncmp<label id="strncmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strncmp (const char* s1, const char* s2, size_t count);/ +<tag/Description/The <tt/strncmp/ function compares not more than <tt/count/ +characters of the two strings passed as parameters. It returns a value that is +less than zero if the first <tt/count/ characters of <tt/s1/ are less than +<tt/s2/, zero if they are identical, and a value greater than zero they are +greater. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strncpy<label id="strncpy"><p> + +<quote> +<descrip> +<tag/Function/Copy part of a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strncpy/ function copies not more than n bytes from +the array pointed to by <tt/s2/ to the array pointed to by <tt/s1/. If the array +pointed to by <tt/s2/ is a string that is shorter than n bytes, null bytes are +appended to the copy in the array pointed to by <tt/s1/, until <tt/n/ bytes are +written. The function will always return <tt/s1/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. If there is no null byte in the first <tt/n/ +bytes of the array pointed to by <tt/s2/, the result is not null-terminated. +<item>If copying takes place between objects that overlap, the behaviour is +undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcat" name="strcat">, +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat"> +<tag/Example/ +<verb> +#include <string.h> + +static char hello[6]; + +strcpy (hello, "Hello world!\n", sizeof (hello) - 1); +hello[5] = '\0'; +</verb> +</descrip> +</quote> + + +<sect1>strrchr<label id="strrchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strrchr (const char* s, int c);/ +<tag/Description/The <tt/strrchr/ function locates the last occurrence of <tt/c/ +(converted to a char) in the string pointed to by <tt/s/. The terminating null +byte is considered to be part of the string. Upon completion, the function +returns a pointer to the byte, or a null pointer if the byte was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strchr" name="strchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strspn<label id="strspn"><p> + +<quote> +<descrip> +<tag/Function/Compute the length of a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strspn (const char* s, const char* set);/ +<tag/Description/The <tt/strspn/ function computes and returns the length of +the substring pointed to by <tt/s/ which does consist only of characters +contained in the string <tt/set/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<ref id="strstr" name="strstr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strstr<label id="strstr"><p> + +<quote> +<descrip> +<tag/Function/Find a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strstr (const char* str, const char* substr);/ +<tag/Description/<tt/strstr/ searches for the first occurance of the string +<tt/substr/ within <tt/str/. If found, it returns a pointer to the copy, +otherwise it returns <tt/NULL/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<ref id="strspn" name="strspn"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strtok<label id="strtok"><p> + +<quote> +<descrip> +<tag/Function/Break a string into tokens. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strtok (char* s1, const char* s2);/ +<tag/Description/<tt/strtok/ will break the string s1 into a sequence of +tokens, which are delimited by characters from the string s2. The first call +to <tt/strtok/ will return a pointer to the first token in the string s1. +Following calls must pass a <tt/NULL/ pointer as s1 in order to get the next +token in the string. Different sets of delimiters may be used for the +subsequent calls to <tt/strtok/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item><tt/strtok/ will modify the string s1. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<!-- <ref id="strpbrk" name="strpbrk"> --> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strxfrm<label id="strxfrm"><p> + +<quote> +<descrip> +<tag/Function/Transform a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strxfrm (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strxfrm/ function transforms the string pointed to by +s2 and places the resulting string into the string pointed to by s1. The +transformation is such that if the <tt/strcmp/ function is applied to two +transformed strings, it returns a value greater than, equal to, or less than +zero, corresponding to the result of the <tt/strcoll/ function applied to the +same two original strings. No more than n characters are placed into the +resulting array pointed to by s1, including the terminating null character. +<tag/Limits/<itemize> +<item><tt/s1/ and <tt/s2/ must not point to the same memory area, otherwise +the behaviour is undefined. +<item>If <tt/n/ is zero, <tt/s1/ may be a NULL pointer. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>Since cc65 doesn't support different charcter sets, <tt/strxfrm/ will +just copy s2 to s1 using <tt><ref id="strncpy" name="strncpy"></tt>. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strupper<label id="strupper"><p> + +<quote> +<descrip> +<tag/Function/Make a string upper case. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strupper (char* s);/ +<tag/Description/The <tt/strupper/ function will apply the <tt/toupper/ +function to each character of a string. The function will always return <tt/s/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function prototype is unavailable when compiling in strict ANSI mode. +<item>An alias name for this function is <tt/strupr/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strlower" name="strlower"> +<ref id="toupper" name="toupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strupr<label id="strupr"><p> + +<quote> +See <tt/strupper/. +</quote> + + +<sect1>telldir<label id="telldir"><p> + +<quote> +<descrip> +<tag/Function/Return the current position of a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/long __fastcall__ telldir (DIR* dir);/ +<tag/Description/<tt/telldir/ returns the current position of a directory +stream. The return value may be used in subsequent calls to +<tt/<ref id="seekdir" name="seekdir">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="seekdir" name="seekdir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>textcolor<label id="textcolor"><p> + +<quote> +<descrip> +<tag/Function/Set the text color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ textcolor (unsigned char color);/ +<tag/Description/The function will set a new text color. It returns the old +(current) text color. Text output using any <tt/conio.h/ function will use +the color set by this function. +<tag/Limits/<itemize> +<item>Text colors are system dependent. The function may have no effect +on systems where the text color cannot be changed. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bgcolor" name="bgcolor">, +<ref id="bordercolor" name="bordercolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_arc<label id="tgi_arc"><p> + +<quote> +<descrip> +<tag/Function/Draw an elliptic arc in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_arc (int x, int y, +unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ +<tag/Description/The function draws an elliptic arc with center at x/y and +radii rx/ry using the current drawing color. The arc covers the angle +between sa and ea (startangle and endangle), which must be in the range +0..360. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function behaves unexpectedly or may crash if the angles are out +of range. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +/* Draw the upper half of an ellipse */ +tgi_setcolor(TGI_COLOR_BLUE); +tgi_arc (50, 50, 40, 20, 0, 180); +</verb> +</descrip> +</quote> + + +<sect1>tgi_bar<label id="tgi_bar"><p> + +<quote> +<descrip> +<tag/Function/The function fills a rectangle on the drawpage with the current +color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_bar (int x1, int y1, int x2, int y2);/ +<tag/Description/The function fills a rectangle on the drawpage with the current +color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi function +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_GREEN); +tgi_bar(10, 10, 100, 60); +</verb> +</descrip> +</quote> + + +<sect1>tgi_circle<label id="tgi_circle"><p> + +<quote> +<descrip> +<tag/Function/The function draws a circle in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_circle (int x, int y, unsigned char radius);/ +<tag/Description/The function draws a circle in the current color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_arc" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_BLACK); +tgi_circle(50, 40, 40); +</verb> +</descrip> +</quote> + + +<sect1>tgi_clear<label id="tgi_clear"><p> + +<quote> +<descrip> +<tag/Function/Clear the drawpage +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_clear (void);/ +<tag/Description/Clear the drawpage +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_done<label id="tgi_done"><p> + +<quote> +<descrip> +<tag/Function/End graphics mode, switch back to text mode. +Will NOT uninstall or unload the driver! +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_done (void);/ +<tag/Description/End graphics mode, switch back to text mode. +Will NOT uninstall or unload the driver! +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_ellipse<label id="tgi_ellipse"><p> + +<quote> +<descrip> +<tag/Function/The function draws an ellipse in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_ellipse (int x, int y, unsigned char rx, unsigned char ry);/ +<tag/Description/The function draws an ellipse at position x/y with radii +rx and ry, using the current drawing color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_arc" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_RED); +tgi_ellipse (50, 40, 40, 20); +</verb> +</descrip> +</quote> + + +<sect1>tgi_free_vectorfont<label id="tgi_free_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Free a vector font that was previously loaded into memory. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_free_vectorfont (const tgi_vectorfont* font);/ +<tag/Description/Free a vector font that was previously loaded into memory. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, +<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getaspectratio<label id="tgi_getaspectratio"><p> + +<quote> <descrip> <tag/Function/Return the pixel aspect ratio. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getaspectratio (void);/ +<tag/Description/The function returns the pixel aspect ratio for the current +driver and display as an 8.8 fixed point value. It may be used to correct +geometric shapes so they look correct on the display. As an example, a circle +with a radius of 100 pixels may look elliptic on some driver/display +combinations if the aspect ratio is not 1.00. +<tag/Limits/<itemize> +<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" +monitor for the given platform. The aspect ratio may be wrong if another +monitor is used. +<item>No TGI function will use the aspect ratio. It is up to the programmer to +make use of it. +<item>The <ref id="tgi_setaspectratio" name="tgi_setaspectratio"> function can +be used to change the aspect ratio for a loaded driver. The value is not reset +by <ref id="tgi_init" name="tgi_init">, so if a driver is linked statically to +an application, switching into and out of graphics mode will not restore the +original aspect ratio. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_setaspectratio" name="tgi_setaspectratio"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getcolor<label id="tgi_getcolor"><p> + +<quote> +<descrip> +<tag/Function/Return the current drawing color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getcolor (void);/ +<tag/Description/The actual color is an index to a palette. During tgi_init +you will get a default palette. The number of colors depend on the platform. +All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some +platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN +and then you change the green of the palette to blue using tgi_setpalette then +after this painting in TGI_COLOR_GREEN will actually be blue. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/<verb> +color = tgi_getcolor(); +</verb> +</descrip> +</quote> + + +<sect1>tgi_getcolorcount<label id="tgi_getcolorcount"><p> + +<quote> +<descrip> +<tag/Function/Get the number of available colors. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getcolorcount (void);/ +<tag/Description/Tgi platforms use indexed color palettes. This function +returns the number of entries we can use in the palette. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/<verb> +if (tgi_getcolorcount() == 2) { + printf("Only monochrome graphics is supported\n"); +} +</verb> +</descrip> +</quote> + + +<sect1>tgi_getdefpalette<label id="tgi_getdefpalette"><p> + +<quote> +<descrip> +<tag/Function/Get the palette installed by default. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/ +<tag/Description/The tgi driver has a default palette that is active at startup. +The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this +palette to work correctly. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_geterror<label id="tgi_geterror"><p> + +<quote> +<descrip> +<tag/Function/Return the error code for the last operation. +This will also clear the error. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_geterror (void);/ +<tag/Description/Return the error code for the last operation. +This will also clear the error. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_geterrormsg<label id="tgi_geterrormsg"><p> + +<quote> +<descrip> +<tag/Function/Get an error message describing the error. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const char* __fastcall__ tgi_geterrormsg (unsigned char code);/ +<tag/Description/Get an error message describing the error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxcolor<label id="tgi_getmaxcolor"><p> + +<quote> +<descrip> +<tag/Function/Get the highest index of the palette. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getmaxcolor (void);/ +<tag/Description/Get the highest index of the palette. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxx<label id="tgi_getmaxx"><p> + +<quote> +<descrip> +<tag/Function/Get the maximum x coordinate that can be used on this screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getmaxx (void);/ +<tag/Description/Get the maximum x coordinate that can be used on this screen. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxy<label id="tgi_getmaxy"><p> + +<quote> +<descrip> +<tag/Function/Get the maximum y coordinate that can be used on this screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getmaxy (void);/ +<tag/Description/Get the maximum y coordinate that can be used on this screen. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpagecount<label id="tgi_getpagecount"><p> + +<quote> +<descrip> +<tag/Function/Return the number of screen pages available. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getpagecount (void);/ +<tag/Description/Return the number of screen pages available. +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_setdrawpage" name="tgi_setdrawpage">, +<ref id="tgi_setviewpage" name="tgi_setviewpage"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpalette<label id="tgi_getpalette"><p> + +<quote> +<descrip> +<tag/Function/Get the palette installed. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const unsigned char* tgi_getpalette (void);/ +<tag/Description/Get the palette installed. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpixel<label id="tgi_getpixel"><p> + +<quote> +<descrip> +<tag/Function/Get the color of a pixel from the viewpage. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getpixel (int x, int y);/ +<tag/Description/Get the color of a pixel from the viewpage. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getxres<label id="tgi_getxres"><p> + +<quote> +<descrip> +<tag/Function/Get number of horisontal pixels on the screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getxres (void);/ +<tag/Description/Get number of horisontal pixels on the screen. +This is same as tgi_maxx()+1. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getyres<label id="tgi_getyres"><p> + +<quote> +<descrip> +<tag/Function/Get number of vertical pixels on the screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getyres (void);/ +<tag/Description/Get number of vertical pixels on the screen. +This is same as tgi_maxy()+1. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_gotoxy<label id="tgi_gotoxy"><p> + +<quote> +<descrip> +<tag/Function/Set graphics cursor at x, y. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_gotoxy (int x, int y);/ +<tag/Description/Set graphics cursor at x, y. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_init<label id="tgi_init"><p> + +<quote> +<descrip> +<tag/Function/Initialize the already loaded graphics driver. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_init (void);/ +<tag/Description/The tgi_init function will set the default palette to the +hardware. +<tag/Limits/<itemize> +<item><tt/tgi_init/ will not clear the screen. This allows switching between +text and graphics mode on platforms that have separate memory areas for the +screens. If you want the screen cleared, call <tt/<ref id="tgi_clear" +name="tgi_clear">/ after <tt/tgi_init/. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. +tgi_init(); //Set up the default palette and clear the screen. +</verb> +</descrip> +</quote> + + +<sect1>tgi_install<label id="tgi_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ tgi_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/TGI_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_driver" name="tgi_load_driver">, +<ref id="tgi_uninstall" name="tgi_uninstall">, +<ref id="tgi_unload" name="tgi_unload"> +<tag/Example/<verb> +tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. +tgi_init(); //Set up the default palette and clear the screen. +</verb> +</descrip> +</quote> + + +<sect1>tgi_install_vectorfont<label id="tgi_install_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_install_vectorfont (const tgi_vectorfont* font);/ +<tag/Description/ +Install a vector font for use. More than one vector font can be loaded, +but only one can be active. This function is used to tell which one. Call +with a NULL pointer to uninstall the currently installed font. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, +<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_ioctl<label id="tgi_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Platform dependent code extensions. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_ioctl (unsigned char code, void* data);/ +<tag/Description/Some platforms have extra display hardware that is not +supported by standard tgi functions. You can extend the driver to support +this extra hardware using tgi_ioctl functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>These functions are not easily portable to other cc65 platforms. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +#define tgi_sprite(spr) tgi_ioctl(0, (void*)(spr)) +#define tgi_flip() tgi_ioctl(1, (void*)0) +#define tgi_setbgcolor(bgcol) tgi_ioctl(2, (void*)(bgcol)) +#define tgi_setframerate(rate) tgi_ioctl(3, (void*)(rate)) +#define tgi_busy() tgi_ioctl(4, (void*)0) +#define tgi_updatedisplay() tgi_ioctl(4, (void*)1) +if (!tgi_busy()) { + tgi_sprite(&background); + tgi_setcolor(TGI_COLOR_BLUE); + tgi_outttextxy(20,40,"Hello World"); + tgi_updatedisplay(); +} +</verb> +</descrip> +</quote> + + +<sect1>tgi_line<label id="tgi_line"><p> + +<quote> +<descrip> +<tag/Function/Draw a line in the current drawing color. +The graphics cursor will be set to x2/y2 by this call. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_line (int x1, int y1, int x2, int y2);/ +<tag/Description/Draw a line in the current drawing color. +The graphics cursor will be set to x2/y2 by this call. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_lineto<label id="tgi_lineto"><p> + +<quote> +<descrip> +<tag/Function/Draw a line in the current drawing color from the graphics +cursor to the new end point. The graphics cursor will be updated to x2/y2. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_lineto (int x2, int y2);/ +<tag/Description/Draw a line in the current drawing color from the graphics +cursor to the new end point. The graphics cursor will be updated to x2/y2. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_load_driver<label id="tgi_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and install the given driver. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_load_driver (const char *name);/ +<tag/Description/Load and install the driver by name. +Will just load the driver and check if loading was successful. +Will not switch to graphics mode. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_load_vectorfont<label id="tgi_load_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Load the given vector font. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const tgi_vectorfont* __fastcall__ tgi_load_vectorfont (const char* name);/ +<tag/Description/ +Load a vector font into memory and return it. In case of errors, NULL is +returned and an error is set, which can be retrieved using tgi_geterror. +To use the font, it has to be installed using tgi_install_vectorfont. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont">, +<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_outtext<label id="tgi_outtext"><p> + +<quote> +<descrip> +<tag/Function/Output text at the current graphics cursor position. +The graphics cursor is moved to the end of the text. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_outtext (const char* s);/ +<tag/Description/Output text at the current graphics cursor position. +The graphics cursor is moved to the end of the text. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_outtextxy<label id="tgi_outtextxy"><p> + +<quote> +<descrip> +<tag/Function/Output text at the given cursor position. +The graphics cursor is moved to the end of the text. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_outtextxy (int x, int y, const char* s);/ +<tag/Description/Output text at the given cursor position. +The graphics cursor is moved to the end of the text. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_pieslice<label id="tgi_pieslice"><p> + +<quote> +<descrip> +<tag/Function/Draw an elliptic pie slice in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_pie slice (int x, int y, +unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ +<tag/Description/The function draws an elliptic pie slice with center at x/y +and radii rx/ry using the current drawing color. The pie slice covers the angle +between sa and ea (startangle and endangle), which must be in the range +0..360. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function behaves unexpectedly or may crash if the angles are out +of range. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_bar" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +/* Draw the closed upper half of an ellipse */ +tgi_setcolor(TGI_COLOR_BLUE); +tgi_pieslice (50, 50, 40, 20, 0, 180); +</verb> +</descrip> +</quote> + + +<sect1>tgi_setaspectratio<label id="tgi_setaspectratio"><p> + +<quote> <descrip> <tag/Function/Set the pixel aspect ratio. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setaspectratio (unsigned ratio);/ +<tag/Description/The function sets the pixel aspect ratio for the current +driver and display. The argument is an 8.8 fixed point value. The aspect ratio +may be used to correct geometric shapes so they look correct on a given +display. As an example, a circle with a radius of 100 pixels may look elliptic +on some driver/display combinations if the aspect ratio is not 1.00. +<tag/Limits/<itemize> +<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" +monitor for the given platform. The aspect ratio may be wrong if another +monitor is used. +<item>No TGI function will use the aspect ratio. It is up to the programmer to +make use of it. +<item>The <tt/tgi_setaspectratio/ function can be used to change the aspect +ratio for a loaded driver. The value is not reset by <ref id="tgi_init" +name="tgi_init">, so if a driver is linked statically to an application, +switching into and out of graphics mode will not restore the original aspect +ratio. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_getaspectratio" name="tgi_getaspectratio"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_setcolor<label id="tgi_setcolor"><p> + +<quote> +<descrip> +<tag/Function/Set color to be used in future draw operations. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color);/ +<tag/Description/Set color to be used in future draw operations. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_BLACK); +tgi_bar(0,0,30,30); +tgi_setcolor(TGI_COLOR_WHITE); +tgi_bar(10,10,20,20); +</verb> +</descrip> +</quote> + +<sect1>tgi_setdrawpage<label id="tgi_setdrawpage"><p> + +<quote> +<descrip> +<tag/Function/Set the page for drawing. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setdrawpage (unsigned char page);/ +<tag/Description/If the drawpage and the viewpage are the same then all drawing +is seen immediately as it is drawn. For double buffered games you can set the +drawpage to a different page than the viewpage. This lets you draw the next +screen in the background and when the screen is ready you display it. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setdrawpage(1); +tgi_outtextxy(10, 10, "Hello World"); +tgi_setviewpage(1); // Show page 1 +tgi_setdrawpage(0); +tgi_outtextxy(10, 10, "Creating next frame"); +... +tgi_setviewpage(0); // Show page 0 +</verb> +</descrip> +</quote> + +<sect1>tgi_setpalette<label id="tgi_setpalette"><p> + +<quote> +<descrip> +<tag/Function/Set the palette (not available with all drivers/hardware). +Palette is a pointer to as many entries as there are colors. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setpalette (const unsigned char* palette);/ +<tag/Description/Set the palette (not available with all drivers/hardware). +Palette is a pointer to as many entries as there are colors. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_setpixel<label id="tgi_setpixel"><p> + +<quote> +<descrip> +<tag/Function/Plot a pixel on the drawpage with the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setpixel (int x, int y);/ +<tag/Description/Plot a pixel on the drawpage with the current color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_setviewpage<label id="tgi_setviewpage"><p> + +<quote> +<descrip> +<tag/Function/Set page to be visible on screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setviewpage (unsigned char page);/ +<tag/Description/If the drawpage and the viewpage are the same then all drawing +is seen immediately as it is drawn. For double buffered games you can set the +drawpage to a different page than the viewpage. This lets you draw the next +screen in the background and when the screen is ready you display it. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setdrawpage(1); +tgi_outtextxy(10, 10, "Hello World"); +tgi_setviewpage(1); // Show page 1 +tgi_setdrawpage(0); +tgi_outtextxy(10, 10, "Creating next frame"); +... +tgi_setviewpage(0); // Show page 0 +</verb> +</descrip> +</quote> + +<sect1>tgi_gettextheight<label id="tgi_gettextheight"><p> + +<quote> +<descrip> +<tag/Function/Calculate the height of the text in pixels according to +the current text style. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextheight (const char* s);/ +<tag/Description/Calculate the height of the text in pixels according to +the current text style. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_settextscale<label id="tgi_settextscale"><p> + +<quote> +<descrip> +<tag/Function/Set the scaling for text output. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_settextscale (unsigned width, unsigned height);/ +<tag/Description/ +Set the scaling for text output. The scaling factors for width and height +are 8.8 fixed point values. This means that $100 = 1 $200 = 2 etc. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_settextstyle" name="tgi_settextstyle"> +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_settextstyle<label id="tgi_settextstyle"><p> + +<quote> +<descrip> +<tag/Function/Set the style for text output. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir, unsigned char font);/ +<tag/Description/Set the style for text output. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_settextscale" name="tgi_settextscale"> +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_gettextwidth<label id="tgi_gettextwidth"><p> + +<quote> +<descrip> +<tag/Function/Calculate the width of the text in pixels according to the current text style. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextwidth (const char* s);/ +<tag/Description/Calculate the width of the text in pixels according to the current text style. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_uninstall<label id="tgi_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the currently loaded driver but do not unload it. +Will call tgi_done if necessary. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_uninstall (void);/ +<tag/Description/Uninstall the currently loaded driver but do not unload it. +Will call tgi_done if necessary. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_unload<label id="tgi_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the currently loaded driver. +Will call tgi_done if necessary. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_unload (void);/ +<tag/Description/Uninstall, then unload the currently loaded driver. +Will call tgi_done if necessary. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>time<label id="time"><p> + +<quote> +<descrip> +<tag/Function/Get the time. +<tag/Header/<tt/<ref id="time.h" name="time.h">/ +<tag/Declaration/<tt/time_t __fastcall__ time (time_t* t);/ +<tag/Description/The function returns the time since the 1970-01-01 00:00:00 +measured in seconds. If the pointer <tt/t/ is not <tt/NULL/, the function +result will also be stored there. If no time is available, <tt/(time_t)-1/ is +returned and <tt/errno/ is set to <tt/ENOSYS/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Many platforms supported by cc65 do not have a realtime clock, so the +returned value may not be valid. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="clock" name="clock"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>toggle_videomode<label id="toggle_videomode"><p> + +<quote> +<descrip> +<tag/Function/Toggle between 40 and 80 column mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void toggle_videomode (void);/ +<tag/Description/Toggle between 40 and 80 column mode. The settings for the +old mode (cursor position, color and so on) are saved and restored together +with the mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>This function is deprecated. Please use <ref id="videomode" +name="videomode"> instead! +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="slow" name="slow">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tolower<label id="tolower"><p> + +<quote> +<descrip> +<tag/Function/Convert a character into its lower case representation. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ tolower (int c);/ +<tag/Description/The function returns the given character converted to lower +case. If the given character is not a letter, it is returned unchanged. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="islower" name="islower">, +<ref id="isupper" name="isupper">, +<ref id="toupper" name="toupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>toupper<label id="toupper"><p> + +<quote> +<descrip> +<tag/Function/Convert a character into its upper case representation. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ toupper (int c);/ +<tag/Description/The function returns the given character converted to upper +case. If the given character is not a letter, it is returned unchanged. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="islower" name="islower">, +<ref id="isupper" name="isupper">, +<ref id="tolower" name="tolower"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ultoa<label id="ultoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an unsigned long integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ ultoa (unsigned long val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the unsigned long integer <tt/val/ into a +string using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>unlink<label id="unlink"><p> + +<quote> +<descrip> +<tag/Function/Delete a file. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ unlink (const char* name);/ +<tag/Description/<tt/unlink/ deletes the file with the given name. On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>The use of this function is discouraged. Please use <tt/<ref id="remove" +name="remove">/ instead, which is a native ANSI C function and does the same. +<item>This function is not available on all cc65 targets (depends on the +availability of file I/O). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>Instead of <tt/unlink/, <tt/<ref id="remove" name="remove">/ should be +used, which has the same semantics, but is more portable, because it conforms +to the ISO C standard. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="remove" name="remove"> +<tag/Example/ +<verb> +#include <stdio.h> +#include <unistd.h> + +#define FILENAME "helloworld" + +if (unlink (FILENAME) == 0) { + printf ("We deleted %s successfully\n", FILENAME); +} else { + printf ("There was a problem deleting %s\n", FILENAME); +} +</verb> +</descrip> +</quote> + + +<sect1>utoa<label id="utoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an unsigned integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ utoa (unsigned val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the unsigned integer <tt/val/ into a string +using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>vcprintf<label id="vcprintf"><p> + +<quote> +<descrip> +<tag/Function/Formatted output to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/int __fastcall__ vcprintf (const char* format, va_list ap);/ +<tag/Description/The arguments specified as a <tt/va_list/ are converted to +text where necessary and formatted according to the format string given. The +resulting string is output to the console. <tt/vcprintf/ supports the same +format specifiers as <tt/vprintf/. <!-- <tt/<ref id="vprintf" name="vprintf">/. --> +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/vcprintf/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>videomode<label id="videomode"><p> + +<quote> +<descrip> +<tag/Function/Switch to either 40 or 80 column mode. +<tag/Header/<tt/<ref id="apple2enh.h" name="apple2enh.h">, +<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ videomode (unsigned Mode);/ +<tag/Description/Switch to 40 or 80 column mode depending on the argument. If +the requested mode is already active, nothing happens. The old mode is returned +from the call. +<tag/Limits/<itemize> +<item>The function is specific to the C128 and enhanced Apple //e. +<item>This function replaces <ref id="toggle_videomode" +name="toggle_videomode">. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/C128 and enhanced Apple //e +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="slow" name="slow">, +<ref id="toggle_videomode" name="toggle_videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>wherex<label id="wherex"><p> + +<quote> +<descrip> +<tag/Function/Return the current X position of the text mode cursor. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char wherex (void);/ +<tag/Description/The function returns the current X position of the text mode +cursor. Zero is returned for the leftmost screen position. +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>wherey<label id="wherey"><p> + +<quote> +<descrip> +<tag/Function/Return the current Y position of the text mode cursor. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char wherey (void);/ +<tag/Description/The function returns the current Y position of the text mode +cursor. Zero is returned for the uppermost screen position. +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex"> +<tag/Example/None. +</descrip> +</quote> + + +</article> diff --git a/doc/geos.sgml b/doc/geos.sgml new file mode 100644 index 000000000..8a5a948a1 --- /dev/null +++ b/doc/geos.sgml @@ -0,0 +1,1662 @@ +<!doctype linuxdoc system> + +<article> + +<!-- Title information --> + +<title>GEOSLib docs +<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl"> +<date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003, 2005 +<abstract> +This is the documentation of cc65's GEOSLib, but information contained here may be also +useful for writing GEOS applications in general. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction +<p> +As we all know that the best computers in the world are the C64 and C128. They have their GUI too - +the excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point +of view. That's not true. The designers of GEOS created a flexible and powerful system, which +is easy to use and program. +<p> +Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65 +package and my GEOSLib you are able to create GEOS applications in no time. +<p> +GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions +are used (e.g. <tt/memset/ is an alias for <tt/FillRam/), however not all are supported. E.g. +string functions like <tt/strcmp/, <tt/strcpy/ are doubled with native <tt/CmpString/, +<tt/CopyString/ because the latter can handle only 256 byte strings. Keep this in mind when +you write your program. If you don't need long strings simply use functions from the Kernal, +the resulting code will be smaller. +<p> +<tt/dio/ - direct disk access is available, but you might have problems with devices other +than 1541, 1571 or 1581. RAM drives emulating these should work. +<p> +<tt/conio/ - simple console input-output is available for command line applications. +This implementation assumes that one character does fit in 8x8 cell, so output with +default BSW font, which is has 9 points, might be a bit messy. There is no color support in +GEOS 2.0 so color functions are disabled. Both 40 and 80 column modes are supported +and automatically detected. +<p> +<tt/tgi/ - TGI driver for GEOS that supports both 40 and 80 column modes but mode can not be +changed between <tt/tgi_init/ and <tt/tgi_done/. +<p> +<tt/joy/ - JOY driver for GEOS that supports only joystick, not current pointing device. +<p> +It is safe to use these standard includes and their contents: +<tt/assert.h, conio.h, dio.h, errno.h, em.h, geos.h, joystick.h, modload.h, mouse.h, stdlib.h, string.h, tgi.h, time.h/ +<p> +For <tt/time.h/ functions <tt/systime()/ and <tt/clock()/ note that the resolution is one second. +<p> +Functions from the headers above are either standard C library functions or cc65-specific, in +either case they are not GEOS specific and so they are not described here. +<p> +I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best +available code (well, the best as for machine :-). Many of the <tt/void foo (void)/ functions are +just raw calls to the Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you +can find many definitions of standard GEOS locations. Access to these addresses is optimized by +cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax. + +<sect1>Requirements +<p> +You don't need a C64 or C128 for development. The only hardware requirement is a PC capable of +running cc65. You do however need C64 or C128 emulator and GEOS disk images (.d64) to test your +programs. + +The software needed: +<itemize> + <item><em/cc65/ Excellent package containing a C crosscompiler, a crossassembler and a linker, you + can get it from: <htmlurl url="http://www.cc65.org/" + name="http://www.cc65.org/"> + <item><em/VICE/ This is a portable C64, C128 and few other Commodore computers emulator, you + can obtain it from: <htmlurl url="http://www.viceteam.org/" + name="http://www.viceteam.org/">. The VICE package contains the + c1541 program that is able to convert/unconvert GEOS files to disk images. + <item><em/The Star Commander/ This tool is only for DOS. You will need it for transferring + object files from a PC to a 1541. There's also one important ability of this + tool - it automatically un-converts .cvt files into GEOS native format on + disk image files. Check out: <htmlurl url="http://sta.c64.org/sc.html" + name="http://sta.c64.org/sc.html"> + <item><em/cbm4linux/ A Linux kernel module that allows for communication with a 1541 and + other Commodore IEC bus drives. It can be a replacement for Star Commander if + you only want to transfer files to a disk and unconvert using GEOS program for + this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/" + name="http://www.lb.shuttle.de/puffin/cbm4linux"> +</itemize> +<p> +VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only +needs cc65. +<p> +<em/Update:/ starting from v2.5.0 GEOSLib is a part of the cc65 package as its GEOS support library. + +<sect1>Legal +<p> +I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's +Reference Guide and BSW for GEOS. +<p> +GEOSLib is covered by the same license as cc65. You can find the whole text +among documentation. I would really appreciate if you would like to send me +your comments, suggestions, questions, changes, bug reports etc. I will also +appreciate if you will just give me a sign that you are using GEOSLib - not +especially something big and important, mail me even if you are just playing +with it. +<p> +You can send postcards with hellos to: +<p> +Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW +<p> +POLAND +<p> +e-mail: <tt/ytm@elysium.pl/ + +<sect>What do you have and what to do with it? +<p> +This chapter describes some rules you ought to obey, and how to use GEOSLib. + +<sect1>Usage +<p> +Apart from this file, which merely describes only standard GEOS library +functions, you should read the <tt/grc65/ (GEOS resource compiler) documentation. +There is information about necessary resource files (each GEOS application +needs at least one) and the build process - what should be done and in what +order. Please also read the cc65 documentation on how to compile C, assembler +and link everything together. +<p> +All in all, you just need to place +<tscreen><verb> +#include <geos.h> +</verb></tscreen> +at the top of your source. +<p> +As a general rule read the sources of the example programs and read the headers. +These are the most reliable sources of knowledge ;-). You will also find there +many C macros representing various arguments passed to the functions. Please use +them. You will find your sources easier to understand, and it will be easier +to find bugs. +<p> +All types used in GEOSLib are <tt/unsigned/. +<p> +Screen coordinates are given in pixels unless stated differently. + +<sect1>Notes on style +<p> +Contrary to a typical GEOS assembly program which has a main function called after loading that +setups the screen, menus, icons etc. exiting from the <tt/main/ function in C is equivalent to +calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT +USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered +with <tt/atexit/ are not called. +<p> +For GEOS GUI applications the recommended program structure is to have everything initialized +in the <tt/main/ function and at the end of it a call to the <tt/MainLoop()/ function. WARNING! This +function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not +be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu +handler or via DialogBox action). +<p> +Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into +series of <tt/lda/ and <tt/sta/, so you can't do it better :-). +<p> +Don't hesitate to use library functions. Everything was written with size and speed in mind. In +fact many calls are just redirections to the GEOS Kernal which results in a simple <tt/jsr/. +<p> +The <tt/main/ function receives the standard <tt/argc/ and <tt/argv/ parameters. There are +always either 1 or 3 parameters. The DOS application name is always set as <tt/argv[0]/. +If present, <tt/argv[1]/ and <tt/argv[2]/ will be set to the data filename and data diskname (it only +works if the user double-clicks on a data file associated with your application). Note that it is up +to your application to determine which of the available (up to four) disk drives has the disk +with given diskname inside. If this fails your program should ask to insert the proper disk into +one of available drives. +<p> +You might wonder why I have chosen a sometimes weird order of arguments in functions. I just +wanted to avoid unnecessary pushing and popping of arguments from the stack because cc65 can pass a single +<tt/unsigned int/ through CPU registers. +<p> +Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in +ANSI. +<p> +It is possible to use dynamically loaded modules, three such modules are provided: +A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver. +Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special +recommendations, read the cc65 documentation about modules and the demo programs source code. + +<sect>Library Functions +<p> +Functions here are sorted more or less in the way they appear in the header files. This way I am able +to keep functions covering similar tasks near each other. All function names are identical to those +from the <tt/geosSym/ file provided with the GeoProgrammer package. Only my extensions to <tt/geosSym/ +are covered by new names, but I tried to keep them in the naming convention. + +<sect1>Graphics +<p> +This section covers the drawing package of GEOS along with text output routines. + +<sect2>SetPattern +<p> +<tt/void SetPattern (char pattern)/ +<p> +This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can +see them together in the filling box in GeoPaint. + +<sect2>GraphicsString +<p> +<tt/void GraphicsString (char *myGString)/ +<p> +One of the more powerfull routines of GEOS. This function calls other graphic functions depending +on the given command string. See the structures chapter for a more detailed description. + +<sect2>Rectangle functions +<p> +Parameters to those functions are grouped in the <tt/struct window drawWindow/. To speed up things and +reduce overhead this structure is bound to zero page locations, where all rectangle functions +expect their parameters. You can modify the data directly (e.g. <tt/drawWindow.top=10/) or via the +<tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change when only +using graphics functions. In other cases you should keep your data in separate <tt/struct window/ +and use <tt/InitDrawWindow/ before the first call to one of the rectangle functions. + +<sect3>InitDrawWindow +<p> +<tt/void InitDrawWindow (struct window *myWindow)/ +<p> +This function only copies the contents of <tt/myWindow/ into the system area of <tt/drawWindow/. Use it +if for some reason you have to keep your window data out of the zero page space. + +<sect3>Rectangle +<p> +<tt/void Rectangle (void)/ +<p> +This draws on screen a rectangle filled with the current pattern. + +<sect3>FrameRectangle +<p> +<tt/void FrameRectangle (char pattern)/ +<p> +This one draws a frame with the given bit pattern (not a pattern from the GEOS palette). + +<sect3>InvertRectangle +<p> +<tt/void InvertRectangle (void)/ +<p> +Just as the name says... + +<sect3>ImprintRectangle and RecoverRectangle +<p> +<tt/void ImprintRectangle (void)/ +<p> +<tt/void RecoverRectangle (void)/ +<p> +These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/) the +backbuffer of the screen. For example when drawing a new menu box GEOS first uses +<tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon +destroying the menu. + +<sect2>Line Functions +<p> +The GEOS drawing package is optimized so there are different functions for drawing vertical and +horizontal lines. + +<sect3>HorizontalLine +<p> +<tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/ +<p> +This function draws a horizontal line using the given pattern. Note that <tt/pattern/ is not a pattern +number as set in <tt/SetPattern/ but a true bit pattern. + +<sect3>InvertLine +<p> +<tt/void InvertLine (char y, unsigned xStart, unsigned xEnd)/ +<p> +There is only a horizontal version. + +<sect3>RecoverLine +<p> +<tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/ +<p> +This function recovers a single line. It is utilized by <tt/RecoverRectangle/. See its description +for more details. + +<sect3>VerticalLine +<p> +<tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/ +<p> +This function draws a vertical line using the given pattern. Note that <tt/pattern/ is not a pattern +number as set in <tt/SetPattern/ but a true bit pattern. + +<sect3>DrawLine +<p> +<tt/void DrawLine (char mode, struct window *myWindow)/ +<p> +The <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while +<tt/bottom/ ones are for the ending point. If <tt/mode/ is <tt/DRAW_DRAW/ then the current pattern from +<tt/SetPattern/ is used for drawing. If <tt/mode/ is <tt/DRAW_ERASE/ then the line is erased from the +screen. If <tt/mode/ is <tt/DRAW_COPY/ then the line is copied from/to back/frontbuffer, according to +the <tt/dispBufferOn/ setting. + +<sect2>Point Functions +<p> +The parameters to these two functions are passed by a pointer to an own <tt/struct pixel/ filled with +proper values. + +<sect3>DrawPoint +<p> +<tt/void DrawPoint (char mode, struct pixel *myPixel)/ +<p> +Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point +on the screen. + +<sect3>TestPoint +<p> +<tt/char TestPoint (struct pixel *myPixel)/ +<p> +This function tests if the given pixel is set and returns <tt/true/ (non-zero) or <tt/false/ (zero). + +<sect2>Character and string output + +<sect3>PutChar +<p> +<tt/void PutChar (char character, char y, unsigned x)/ +<p> +This function outputs a single character using the current style and font to the screen. + +<sect3>PutString +<p> +<tt/void PutString (char *myString, char y, unsigned x)/ +<p> +Same as <tt/PutChar/ except the fact that you can output a whole <tt/NULL/-terminated string. +See <tt/ggraph.h/ for the list of tokens that you can also place in the string - like <tt/CBOLDON/ or +<tt/COUTLINEON/. + +<sect3>PutDecimal +<p> +<tt/void PutDecimal (char parameter, unsigned value, char y, unsigned x)/ +<p> +This function converts <tt/value/ to its decimal representation and outputs it to the screen. +The <tt/parameter/ is the field width in pixels (range 1-31) and the mode bits. Depending on them +the string can be filled with zeroes (the string is always 5 characters long) or not and left or right +justified to the given pixel. See <tt/ggraph.h/ for predefined values for <tt/parameter/. + +<sect2>Font Handling + +<sect3>GetCharWidth +<p> +<tt/char GetCharWidth (char character)/ +<p> +This function returns the real width (in pixels) of the given character with the current font. It can be used +for counting the length of a string on the screen, allowing for indentation or justification. + +<sect3>LoadCharSet +<p> +<tt/void LoadCharSet (struct fontdesc *myFont)/ +<p> +This function forces GEOS to use the given font. <tt/myFont/ should be casted from a +pointer to the start of the area where a record from a font file (VLIR structure) was loaded. + +<sect3>UseSystemFont +<p> +<tt/void UseSystemFont (void)/ +<p> +This function forces GEOS to use the built-in BSW font. + +<sect2>Bitmap handling +<p> +I'm not quite sure how these functions are working (except <tt/BitmapUp/) so you should +probably look into the library sources and compare it with your knowledge. Please let me know +if something is wrong or broken. + +<sect3>BitmapUp +<p> +<tt/void BitmapUp (struct iconpic *myPic)/ +<p> +This function unpacks the bitmap and places it on the screen - just as you set it in the +<tt/struct iconpic/ pointer which you pass. See <tt/gstruct.h/ for a description of this +structure. Note that you can only use packed GEOS bitmaps - a simple Photo Scrap is in this format. + +<sect3>BitmapClip +<p> +<tt/void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)/ +<p> +This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are +to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap, +and the number of rows to skip from the top if it. + +<sect3>BitOtherClip +<p> +<tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop, + struct iconpic *myPic)/ +<p> +Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it +returns in .A the next value), and <tt/proc2/ is called every time the parser reads a byte which is +not a piece of a pattern (byte of code greater than 219). Both procedures should be written +separately in assembler and declared as <tt/__fastcall__/ returning char. + +<sect1>Menus and Icons +<p> +Here you will find information about functions related with menus and icons. + +<sect2>Menus +<p> +Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call +another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up +to 32 items. +<p> +Menus are initialized with <tt/DoMenu/ and then the Kernal takes care of everything. Your code +(called from an event handler) should be a function without parameters, returning void. You should +use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean. + +<sect3>DoMenu +<p> +<tt/void DoMenu (struct menu *myMenu)/ +<p> +This function initializes the GEOS menu processor and exits. See <tt/DoMenu structure/ for more +information about it. Know that many GEOS applications just initialize the screen, menu and +exit to the main Kernal loop, this proves the power of <tt/DoMenu/. + +<sect3>ReDoMenu +<p> +<tt/void ReDoMenu (void)/ +<p> +This simply redraws the menu at the lowest level. It works like calling <tt/DoMenu/ again with +the same parameters. + +<sect3>RecoverMenu +<p> +<tt/void RecoverMenu (void)/ +<p> +This function erases the current menu from the screen. It doesn't change the menu level. + +<sect3>RecoverAllMenus +<p> +<tt/void RecoverAllMenus (void)/ +<p> +This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is +set to 0 (topmost). + +<sect3>DoPreviousMenu +<p> +<tt/void DoPreviousMenu (void)/ +<p> +This functions causes the menu processor to go back one menu level. You should use it in menu +handler code to have the screen clean. + +<sect3>GotoFirstMenu +<p> +<tt/void GotoFirstMenu (void)/ +<p> +This one jumps back to the topmost menu. If there is only a menu and one submenu it works the +same as <tt/DoPreviousMenu/. + +<sect2>Icon Functions +<p> +Icons are working similar to menus except the fact that there is only one level. Icons are +defined as a screen area filled with a bitmap, but if you would setup icons and erase the +screen they would still be active and clicking in the place where formerly an icon was would cause +an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/ +the bitmap would still be on the screen but clicking on it would not cause any action. +There is only one, but powerful icon function. + +<sect3>DoIcons +<p> +<tt/void DoIcons (struct icontab *myIconTab)/ +<p> +This function initializes all icons that are present on the screen at once. For more information +look at the <tt/Icons/ chapter in this manual. + +<sect1>DialogBoxes +<p> +This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/. + +<sect2>GEOS standard + +<sect3>DoDlgBox +<p> +<tt/char DoDlgBox (char *dialogString)/ +<p> +This function returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/) +or whatever the closing routine passes. Register <tt/r0L/ also contains this value. +<p> +Read the structures chapter for the specs of the <tt/dialogString/. + +<sect3>RstrFrmDialogue +<p> +<tt/char RstrFrmDialogue/ +<p> +This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns +the owner ID (or whatever caller has in the .A register). + +<sect2>GEOSLib extensions +<p> +To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox, +with predefined data. In one word - these are standard DialogBoxes you can see in almost every +GEOS application. + +<sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk +<p> +<tt/char DlgBoxYesNo (char *line1, char *line2)/ +<p> +<tt/char DlgBoxOkCancel (char *line1, char *line2)/ +<p> +<tt/void DlgBoxOk (char *line1, char *line2)/ +<p> +These function show two lines of text in a standard-sized DialogBox. You can read the code of the +pressed icon from the return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/. +You can pass an empty string or NULL to get a blank line. + +<sect3>DlgBoxGetString +<p> +<tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/ +<p> +This function prompts the user to enter a string of at most <tt/strlen/ characters. It is returned +in <tt/string/. The two given lines of text are shown above the input line. Please remember +that there is also a <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his +input or gave up. The <tt/string/ is also shown so you can place a default input there or remember +to place <tt/NULL/ at start. + +<sect3>DlgBoxFileSelect +<p> +<tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/ +<p> +This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error +on reading the directory or opening the disk. +There is also a <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters +<tt/filetype/ and a pointer to a string containing the first part of a file's class. If this string is +empty (<tt/NULL/ at the start), then all files with given filetype will be shown. +<p> +At present this file selector handles only first 16 files of given type and supports only one +(current) drive. + +<sect3>MessageBox +<p> +<tt/char MessageBox (char mode, const char *format, ...)/ +<p> +This function is a more general one. It works very much like <tt/printf/ in a +box. The only difference is the <tt/mode/ parameter which allows for placing +default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values). +Any too wide text will be clipped to the size of the default window. If <tt/mode/ +is invalid or equal to <tt/MB_EMPTY/ then the window will be closed +after a click. Otherwise the user must choose an icon. +<p> +Note: Use it if you really need (or if you use it in many places) as +it adds quite amount of code to your program. +<p> +Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check +for that. + +<sect1>Mouse, Sprites and Cursors +<p> +You will find here functions related to sprite and mouse drawing and handling. + +<sect2>Mouse related functions +<p> +These cover the mouse - as a general pointing device, but expect users to utilize as different devices +as a digital or analog joystick, a mouse, a lightpen or a koalapad (whatever it is). + +<sect3>StartMouseMode +<p> +<tt/void StartMouseMode (void)/ +<p> +This function initializes the mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then +calls <tt/MouseUp/. + +<sect3>ClearMouseMode +<p> +<tt/void ClearMouseMode (void)/ +<p> +This function disables all mouse activities - icons and menus stop to respond to mouse events, +but they are not cleared from the screen. + +<sect3>MouseUp and MouseOff +<p> +<tt/void MouseUp (void)/ +<p> +<tt/void MouseOff (void)/ +<p> +The first function turns the mouse pointer on. It appears on the next IRQ. The second one does +the opposite - it turns off the pointer, but its position is still updated by the input driver. + +<sect3>IsMseInRegion +<p> +<tt/char IsMseInRegion (struct window *myWindow)/ +<p> +This function tests if the mouse pointer is actually in the given range of the screen. See <tt/gsprite.h/ for +a description of the bits in the return values - they describe the position in detail. + +<sect2>Sprites +<p> +You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse +pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about +40/80 column issues because GEOS128 has a pretty good sprite emulator for the VDC. + +<sect3>DrawSprite +<p> +<tt/void DrawSprite (char sprite, char *mySprite)/ +<p> +This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which +is copied to the system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are +not initialized and the sprite is not yet visible. + +<sect3>PosSprite +<p> +<tt/void PosSprite (char sprite, struct pixel *myPixel)/ +<p> +This function positions the sprite on the screen. The given coordinates are screen ones - they are +converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your +sprite off the left or top to the screen. + +<sect3>EnablSprite and DisablSprite +<p> +<tt/void EnablSprite (char sprite)/ +<p> +<tt/void DisablSprite (char sprite)/ +<p> +These two functions are responsible for making the sprite visible or not. + +<sect2>Cursors and Console + +<sect3>InitTextPrompt +<p> +<tt/void InitTextPrompt (char height)/ +<p> +This function initializes sprite 1 for a text prompt with given <tt/height/. This parameter can be in +range 1-48. + +<sect3>PromptOn and PromptOff +<p> +<tt/void PromptOn (struct pixel *myPixel)/ +<p> +<tt/void PromptOff (void)/ +<p> +The first function places a text prompt in given place and enables blinking. +The second one is pretty self-explanatory. + +<sect3>GetNextChar +<p> +<tt/char GetNextChar (void)/ +<p> +This function gets the next character from the keyboard queue. If the queue is empty it returns +<tt/NULL/, otherwise you receive the true ASCII code of a character or the value of a special (function) +key. See <tt/gsprite.h/ for the list of them. + +<sect1>Disk +<p> +This chapter covers rather low-level disk routines. You should use them with care, because +you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various +devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be +dangerous. +<p> +For some purposes you might consider using the <tt/dio.h/ interface to disk access. It is native. +<p> +All GEOS disk functions return an error code in the X register. In some cases this is returned by the +GEOSLib function (if its type is <tt/char/), but in all cases the last error is saved in the <tt/__oserror/ +location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes. +You need to include <tt/errno.h/ to get <tt/__oserror/, together with the standard <tt/errno/. The +latter gives less verbose, but still usable information and can be used with <tt/strerror/. +Probably you will get more information using <tt/_stroserror/ in a similar way. +<p> +For passing parameters use almost always a pointer to your data e.g. <tt/ReadBuff (&myTrSe)/. + +<sect2>Buffer functions +<p> +These functions take a single data sector (256 bytes) to read or write on the disk. + +<sect3>ReadBuff and Writebuff +<p> +<tt/char ReadBuff (struct tr_se *myTrSe)/ +<p> +<tt/char WriteBuff (struct tr_se *myTrSe)/ +<p> +These functions read and write a sector placed at <tt/diskBlkBuf/. + +<sect3>GetBlock and ReadBlock +<p> +<tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +These two functions read a single block directly to the 256 byte array placed at <tt/buffer/. +The difference between them is that <tt/GetBlock/ initializes TurboDos in the drive if it was not +enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster. + +<sect3>PutBlock, WriteBlock, VerWriteBlock +<p> +<tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after +writing. In case of an error five tries are attempted before an error code is returned. + +<sect2>Directory header +<p> +The functions described here operate on <tt/curDirHeader/ where the current disk header is stored. +On larger (than 1541) capacity drives the second part of the directory header is in <tt/dir2Head/. + +<sect3>GetPtrCurDkNm +<p> +<tt/void GetPtrCurDkNm (char *diskName)/ +<p> +This function fills the given character string with the name of current disk. It is converted to C +standard - the string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS. +Note that the passed pointer must point to an array of at least 17 bytes. + +<sect3>GetDirHead and PutDirHead +<p> +<tt/char GetDirHead (void)/ +<p> +<tt/char PutDirHead (void)/ +<p> +These functions read and write the directory header. You should use <tt/GetDirHead/ before +using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the +disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/. + +<sect3>CalcBlksFree +<p> +<tt/unsigned CalcBlksFree (void)/ +<p> +This function returns the number of free blocks on the current disk. It is counted using data in +<tt/curDirHead/ so you must initialize the disk before calling it. + +<sect3>ChkDskGEOS +<p> +<tt/char ChkDskGEOS (void)/ +<p> +This functions checks <tt/curDirHead/ for the GEOS Format identifier. It returns either true or false, +and also sets <tt/isGEOS/ properly. You must initialize the disk before using this. + +<sect3>SetGEOSDisk +<p> +<tt/char SetGEOSDisk (void)/ +<p> +This function initializes disk for use with GEOS. It sets the indicator in directory header and +allocates a sector for the directory of border files. You don't need to initialize the disk before +using. + +<sect3>FindBAMBit +<p> +<tt/char FindBAMBit (struct tr_se *myTrSe)/ +<p> +This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is +set if the sector is free to use. The returned value is always zero if the sector is already allocated. +In fact, this function could be used in a following way: +<tscreen><verb> +#define BlockInUse FindBAMBit +... +if (!BlockInUse(&myTrSe)) { +... block not allocated ... +} +</verb></tscreen> +<p> +Anyway, I feel that this function is too low-level. + +<sect3>BlkAlloc and NxtBlkAlloc +<p> +<tt/char BlkAlloc (struct tr_se output[&rsqb, unsigned length)/ +<p> +<tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, unsigned length)/ +<p> +Both functions allocate enough disk sectors to fit <tt/length/ bytes in them. You +find the output in <tt/output/ which is a table of <tt/struct tr_se/. The last entry will have the +track equal to 0 and sector equal to 255. The simplest way of using them is to use +predefined space in the GEOS data space and pass <tt/fileTrScTab/, which is a predefined table. +<p> +The difference between those two is that <tt/NextBlkAlloc/ starts allocating from the given sector, +and <tt/BlkAlloc/ starts from the first nonused sector. +<p> +You need to use <tt/PutDirHead/ later to save any changes in BAM. + +<sect3>FreeBlock +<p> +<tt/char FreeBlock (struct tr_se *myTrSe)/ +<p> +Simply deallocates a block in the BAM. You need to update the BAM with <tt/PutDirHead/. + +<sect3>SetNextFree +<p> +<tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/ +<p> +This function finds the first free sector starting from given track and sector and allocates it. +It might return the same argument if the given block is not allocated. I wanted it to be type +clean, but this made the usage a bit tricky. To assign a value to your own <tt/struct tr_se/ you have to +cast both variables to <tt/unsigned/. E.g. +<tscreen><verb> +struct tr_se myTrSe; +... +(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe); +</verb></tscreen> +<p> +In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/. +<p> +Note: you <em/must/ use casting to have the correct values. + +<sect2>Low-level disk IO +<p> +Functions described here are more usable in Kernal or drivers code, less common in applications, +but who knows, maybe someone will need them. + +<sect3>EnterTurbo, ExitTurbo, PurgeTurbo +<p> +<tt/void EnterTurbo (void)/ +<p> +<tt/void ExitTurbo (void)/ +<p> +<tt/void PurgeTurbo (void)/ +<p> +These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit +more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will +have to wait a bit to transfer the TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos. +This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any +interaction with the Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed. +<tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with +<tt/ExitTurbo/. <tt/PurgeTurbo/ acts differently from <tt/ExitTurbo/ - it not only disables TurboDos, +but also removes it from drive RAM (not quite true, but it works like that). After using +<tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM. + +<sect3>ChangeDiskDevice +<p> +<tt/char ChangeDiskDevice (char newDevice)/ +<p> +This function changes the device number of the current device (in fact drives only) to the given one. It is +usable for swapping drives. There's no check if the given <tt/newDevice/ already exist, so if you want +to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably +hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30. + +<sect2>Disk Initialization +<p> +GEOS has two functions for initialization ('logging in' as they say on CP/M) of a disk. +<sect3>OpenDisk +<p> +<tt/char OpenDisk (void)/ +<p> +This function initializes everything for a new disk. It loads and enables TurboDos if needed. +Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/. +Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is +checked with <tt/ChkDkGEOS/ and the disk name is updated in the internal tables. + +<sect3>NewDisk +<p> +<tt/char NewDisk (void)/ +<p> +This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed. + +<sect1>Files +<p> +This section covers the GEOS file interface. + +<sect2>Directory handling +<p> +The functions described here are common for SEQ and VLIR structures. + +<sect3>Get1stDirEntry and GetNxtDirEntry +<p> +<tt/struct filehandle *Get1stDirEntry (void)/ +<p> +<tt/struct filehandle *GetNxtDirEntry (void)/ +<p> +These two functions are best suited for scanning the whole directory for particular files. Note that +the returned filehandles describe all file slots in the directory - even those with deleted files. +The return value can be obtained by casting both sides to <tt/unsigned/ - as in the <tt/SetNextFree/ +function or read directly after a call to those two functions from <tt/r5/. The current sector number +is in <tt/r1/ and the sector data itself is in <tt/diskBlkBuf/. + +<sect3>FindFile +<p> +<tt/char FindFile (char *fName)/ +<p> +This function scans the whole directory for the given filename. It returns either 0 (success) or 5 +(FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After a successful +<tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with the file's data and +other registers set as described in <tt/GetNxtDirEntry/. + +<sect3>FindFTypes +<p> +<tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/ +<p> +This function scans the directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries. +<tt/fType/ is the GEOS type of the searched files and <tt/classTxt/ is a string for the Class field in the file +header. Class matches if the given string is equal or shorter than that found in the file's header block. +If you want just to find all files with the given GEOS type you should pass an empty string or <tt/NULL/ as +<tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files you must pass <tt/NULL/ as <tt/classTxt/. +<tt/fMaxNum/ is the maximal number of files to find, thus the <tt/buffer/ must provide an area of size +equal to <tt/17 * fMaxNum/. This function returns the number of found files, ranging from 0 to number +passed as <tt/fMaxNum/. The return value can be also restored from <tt/r7H/. + +<sect3>DeleteFile +<p> +<tt/char DeleteFile (char *fName)/ +<p> +This function deletes a file by its name. It works for SEQ and VLIR files. + +<sect3>RenameFile +<p> +<tt/char RenameFile (char *oldName, char *newName)/ +<p> +I think it is obvious... + +<sect3>GetFHdrInfo +<p> +<tt/char GetFHdrInfo (struct filehandle *myFile)/ +<p> +This function loads the file header into the <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/ +you can pass the address of <tt/dirEntryBuf/. + +<sect2>Common and SEQ structure +<p> +Functions described here are common for SEQ and VLIR structures because the arguments passed are the +starting track and sector which may point either to the start of a chain for VLIR or the data for SEQ. + +<sect3>GetFile +<p> +<tt/char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)/ +<p> +This routine loads and runs a given file <tt/fname/. The file must be one of following types: +<tt/SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,/ or <tt/INPUT_DEVICE/. The execution +address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain +from VLIR files is loaded. If <tt/flag/ has bit 0 set then the load address is taken from <tt/loadaddr/ +and not from the file header. In this case <tt/APPLICATION/ files will be only loaded, not executed. +This does not apply to <tt/DESK_ACC/. If either bit 6 or 7 of <tt/flag/ are set, then 16 bytes from +<tt/datadname/ are copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ go to <tt/dataFileName/ +thus becoming parameters for the new application. Pass <tt/NULL/ for any unused parameter. + +<sect3>ReadFile +<p> +<tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/ +<p> +This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at +<tt/myTrSe/. + +<sect3>ReadByte +<p> +<tt/char ReadByte (void)/ +<p> +This function returns the next byte from a file. Before the first call to it you must load <tt/r5/ +with <tt/NULL/, <tt/r4/ with the sector buffer address and <tt/r1/ with the track and sector of the +first block of a file. +Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between +calls to <tt/ReadByte/. +<p> +The returned value is valid only if there was no error. The end of file is marked as <tt/BFR_OVERFLOW/ +in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case the +returned value is invalid. + +<sect3>SaveFile +<p> +<tt/char SaveFile (char skip, struct fileheader *myHeader)/ +<p> +<tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter if VLIR of SEQ +structure. All you need to do is to place the data in the proper place and prepare a header which will +contain all information about a file. The <tt/skip/ parameter says how many directory pages you +want to skip before searching for a free slot for the directory entry. In most cases you will put +<tt/0/ there. +<p> +You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one +difference - the first two bytes which are a link to a nonexistent next sector are replaced by a +pointer to the DOS filename of the file. +<p> +When saving sequential files the two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/ +and <tt/fileheader.end_address/. + +<sect3>FreeFile +<p> +<tt/char FreeFile (struct tr_se myTable[])/ +<p> +This function deallocates all sectors contained in the passed table. + +<sect3>FollowChain +<p> +<tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/ +<p> +This function fills a <tt/struct tr_se/ table at <tt/buffer/ with the sector numbers for a chain of +sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/. + +<sect2>VLIR structure +<p> +Here is information about VLIR files (later called RecordFiles) and functions. +<p> +A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one +SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and +an own number. Each record pointed to by its number is described by the starting track and sector numbers. +VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/), +or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent the starting track and sector of +a particular file. +<p> +In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information +about it is copied into memory. You can retrieve the records table at <tt/fileTrScTab/ (table of +128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/. +E.g. the size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/. + +<sect3>OpenRecordFile +<p> +<tt/char OpenRecordFile (char *fName)/ +<p> +This function finds and opens a given file. An error is returned if the file is not found or if it is not +in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is +loaded at <tt/fileTrScTab/ and will be valid until a call to <tt/CloseRecordFile/ so don't modify it. +You should call <tt/PointRecord/ before trying to do something with the file. + +<sect3>CloseRecordFile +<p> +<tt/char CloseRecordFile (void)/ +<p> +This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables. + +<sect3>UpdateRecordFile +<p> +<tt/char UpdateRecordFile (void)/ +<p> +This function will check the <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is +updated along with size and date stamps in the directory entry. + +<sect3>PointRecord +<p> +<tt/char PointRecord (char recordNumber)/ +<p> +This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and +sector of the given record in <tt/r1/. Note that the data may not be valid (if the record is non-existing +you will get 0,0 and if it is empty - 255,0). + +<sect3>NextRecord and PreviousRecord +<p> +<tt/char NextRecord (void)/ +<p> +<tt/char PreviousRecord (void)/ +<p> +These two work like <tt/PointRecord/. Names are self-explanatory. + +<sect3>AppendRecord +<p> +<tt/char AppendRecord (void)/ +<p> +This function will append an empty record (pair of 255,0) to the current VLIR track and sector +table. It will also set <tt/VLIRInfo.curRecord/ to its number. + +<sect3>DeleteRecord +<p> +<tt/char DeleteRecord (void)/ +<p> +This function will remove the current record from the table, and move all current+1 records one place +back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to +commit changes. + +<sect3>InsertRecord +<p> +<tt/char InsertRecord (void)/ +<p> +This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following +records in the table one place forward (contents of <tt/VLIRInfo.curRecord/ after a call to <tt/InsertRecord/ +can be found in <tt/VLIRInfo.curRecord + 1/). + +<sect3>ReadRecord and WriteRecord +<p> +<tt/char ReadRecord (char *buffer, unsigned fLength)/ +<p> +<tt/char WriteRecord (char *buffer, unsigned fLength)/ +<p> +This function will load or save at most <tt/fLength/ bytes from the currently pointed record into or from +<tt/buffer/. + +<sect1>Memory and Strings +<p> +The functions covered in this section are common for the whole C world - copying memory parts and +strings is one of the main computer tasks. GEOS also has an interface to do this. These functions +are replacements for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries. +If you are dealing with short strings (up to 255 characters) you should use these functions +instead of standard ones, e.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster. +<p> +However some of them have slightly different calling conventions (order of arguments to be specific), +so please check their syntax here before a direct replacement. +<p> +Please note that the memory areas described here as <em/strings/ are up to 255 characters (without +counting the terminating <tt/NULL/), and <em/regions/ can cover the whole 64K of memory. + +<sect2>CopyString +<p> +<tt/void CopyString (char *dest, char *src)/ +<p> +This function copies the string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. The <tt/NULL/ +is also copied. + +<sect2>CmpString +<p> +<tt/char CmpString (char *s1, char *s2)/ +<p> +This function compares the strings <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both +strings have to have the same length. It returns either <tt/true/ (non-zero) or <tt/false/ (zero). + +<sect2>CopyFString and CmpFString +<p> +<tt/void CopyFString (char length, char *dest, char *src)/ +<p> +<tt/char CmpFString (char length, char *s1, char *s2)/ +<p> +These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide +the length of the copied or compared strings. The strings can also contain several <tt/NULL/ +characters - they are not treated as delimiters. + +<sect2>CRC +<p> +<tt/unsigned CRC (char *src, unsigned length)/ +<p> +This function calculates the CRC checksum for the given memory range. I don't know if it is +compatible with standard CRC routines. + +<sect2>FillRam and ClearRam +<p> +<tt/void *FillRam (char *dest, char value, unsigned length)/ +<p> +<tt/void *ClearRam (char *dest, unsigned length)/ +<p> +Both functions are filling the given memory range. <tt/ClearRam/ fills with <tt/0s/, while +<tt/FillRam/ uses the given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and +r2L/ registers. The functions are aliases for <tt/memset/ and <tt/bzero/, respectively. + +<sect2>MoveData +<p> +<tt/void *MoveData (char *dest, char *src, unsigned length)/ +<p> +This functions copies one memory region to another. There are checks for an overlap and the +non-destructive method is chosen. Be warned that this function destroys contents of the +<tt/r0, r1 and r2/ registers. This function is an alias for <tt/memcpy/. + +<sect2>InitRam +<p> +<tt/void InitRam (char *table)/ +<p> +This function allows to initialize multiple memory locations with single bytes or strings. +This is done with a <tt/table/ where everything is defined. See the structures chapter for a description of +<tt/InitRam's/ command string. + +<sect2>StashRAM, FetchRAM, SwapRAM, and VerifyRAM +<p> +<tt/void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +These functions are the interface to a REU - Ram Expansion Unit. I think that they are self-explanatory. +You can check for REU presence by taking the value of <tt/ramExpSize/. You have to do it before +using any of these functions. + +<sect1>Processes and Multitasking +<p> +Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions +called in specified intervals and you can put the main program to sleep without disturbing other +tasks and making the user interface unresponsive. + +<sect2>InitProcesses +<p> +<tt/void InitProcesses (char number, struct process *processTab)/ +<p> +This is the main initialization routine. After calling it processes are set up, but not +enabled. The parameters for <tt/InitProcesses/ are: +<itemize> + <item><tt/number/ - number of processes + <item><tt/processTab/ - a table of <tt/struct process/, with size equal to <tt/number/ +</itemize> +<p> +A single task is described by an entry in <tt/processTab/, it contains two values - a <tt/pointer/ to +the task function and a number of <tt/jiffies/ which describe the delay between calls to task. On PAL +systems there are 50 jiffies per second, while on NTSC there are 60. +<p> +The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and +if <tt/processTab/ would be too large it would overwrite existing data in GEOS space. +<p> +There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the +maximum size of <tt/processTab/ is equal to 21. +<p> +See the description of <tt/process/ structure for a more detailed discussion on this. + +<sect2>RestartProcess and EnableProcess +<p> +<tt/void RestartProcess (char processNumber)/ +<p> +<tt/void EnableProcess (char processNumber)/ +<p> +These two functions start the task counter. <tt/RestartProcess/ should be called for each process +after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters. +<p> +<tt/RestartProcess/ enables the counters and sets their initial value to that given in <tt/processTab/. +<p> +<tt/EnableProcess/ forces the given process to execute by simulating the timer expiring. + +<sect2>BlockProcess and UnblockProcess +<p> +<tt/void BlockProcess (char processNumber)/ +<p> +<tt/void UnblockProcess (char processNumber)/ +<p> +<tt/BlockProcess/ disables the execution of the given process, but this does not disable the timers. +It means that if you call <tt/UnblockProcess/ before the timer runs out, the process will be executed. +<p> +<tt/UnblockProcess/ does the opposite. + +<sect2>FreezeProcess and UnfreezeProcess +<p> +<tt/void FreezeProcess (char processNumber)/ +<p> +<tt/void UnfreezeProcess (char processNumber)/ +<p> +<tt/FreezeProcess/ disables timer for given process. <tt/UnfreezeProcess/ does the opposite. +This is not equal to <tt/RestartProcess/ as timers are not reloaded with initial value. + +<sect2>Sleep +<p> +<tt/void Sleep (unsigned jiffies)/ +<p> +This function is a multitasking sleep - the program is halted, but it doesn't block other functions +e.g. callbacks from menus and icons. +The only argument here is the number of jiffies to wait until the app will wake up. It depends on the +video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). +If you don't want to worry about it and need only full second resolution, call the standard +<tt/sleep/ function from <tt/unistd.h/. + +<sect1>System Functions + +<sect2>FirstInit +<p> +<tt/void FirstInit (void)/ +<p> +This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot +up. You shouldn't use this unless you know what you are doing. + +<sect2>InitForIO and DoneWithIO +<p> +<tt/void InitForIO (void)/ +<p> +<tt/void DoneWithIO (void)/ +<p> +These functions are called by some disk routines. You should call them only if you want to +do something with IO registers or call one of the Kernal ROM routines. Note that this is rather an +expensive way of turning off IRQs and enabling IO. + +<sect2>MainLoop +<p> +<tt/void MainLoop (void)/ +<p> +Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current +function will never be executed. When in <tt/MainLoop/ the system waits for your action - using +icons, keyboard or menus to force some specific action from the program. You have to define +proper handlers before that. + +<sect2>EnterDeskTop +<p> +<tt/void EnterDeskTop (void)/ +<p> +This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not +use it. Always use <tt/exit()/ instead. Library destructors and functions registered with +<tt/atexit()/ are called. + +<sect2>ToBASIC +<p> +<tt/void ToBASIC (void)/ +<p> +This one is another way of terminating an application - forcing GEOS to shutdown and exit to BASIC. +I was considering whether to include it or not, but maybe someone will need it - which I doubt. +<p> +<em/WARNING:/ library destructors and functions registered with <tt/atexit()/ will not be called +so it is quite unsafe way to terminate your program. + +<sect2>Panic +<p> +<tt/void Panic (void)/ +<p> +This calls system's <tt/Panic/ handler - it shows a dialog box with the message +<tscreen><verb> +System error at:xxxx +</verb></tscreen> +where <tt/xxxx/ is last known execution address (caller). By default this is bound to the <tt/BRK/ +instruction, but it might be usable in debugging as kind of <tt/assert/. (Note that <tt/assert/ +is available as a separate function and will give you more information than that). +<p> +The system is halted after a call to <tt/Panic/ which means that library destructors will not be +called and some data may be lost (no wonder you're panicking). + +<sect2>CallRoutine +<p> +<tt/void CallRoutine (void *myFunct)/ +<p> +This is a system caller routine. You need to provide a pointer to a function and it will be immediately +called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function - +you don't need to check if the pointer is valid. + +<sect2>GetSerialNumber +<p> +<tt/unsigned GetSerialNumber (void)/ +<p> +This function returns the serial number of the system. It might be used for copy-protection. +However, please remember that Free Software is a true power and you are using it right now. + +<sect2>GetRandom +<p> +<tt/char GetRandom (void)/ +<p> +This function returns a random number. It can be also read from <tt/random/ e.g. +<tscreen><verb> +a=random; +</verb></tscreen> +but by calling this function you are sure that the results will be always different. +<tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/. +<p> +Note that this is not the same as the <tt/rand/ function from the standard library. <tt/GetRandom/ +will give you unpredictable results (if IRQs occur between calls to it) while +<tt/rand/ conforms to the standard and for a given seed (<tt/srand/) always returns with the +same sequence of values. + +<sect2>SetDevice +<p> +<tt/void SetDevice (char device)/ +<p> +This function sets the current device to the given. It might be used together with <tt/InitForIO/, +<tt/DoneWithIO/ and some Kernal routines. Unless the new device is a disk drive this only sets +new value in <tt/curDevice/, in the other case new disk driver is loaded from REU or internal RAM. + +<sect2>get_ostype +<p> +<tt/char get_ostype (void)/ +<p> +This function returns the GEOS Kernal version combined (by logical OR) with the machine type. Read +<tt/gsys.h/ for definitions of the returned values. + +<sect2>get_tv +<p> +<tt/char get_tv (void)/ +<p> +This function returns the PAL/NTSC flag combined (by logical OR) with the 40/80 columns flag. This is +not the best way to check if the screen has 40 or 80 columns since a PAL/NTSC check is always +performed and it can take as long as a full raster frame. If you just want to know if the +screen has 40 or 80 columns use the expression <tt/graphMode & 0x80/ which returns <tt/0/ for +40 columns and <tt/0x80/ for 80 columns. Remember that this value can be changed during +runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test +anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for +definitions of the returned values. + +<sect>Library Structures +<p> +To simplify usage and optimize passing parameters to functions I have declared several structures +which describe the most common objects. Some of these structures are bound to static addresses in +the GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in an optimized way. +Please see <tt/gsym.h/ to find them. All structures are defined in <tt/gstruct.h/ and you may +find also some comments there. + +<sect1>Graphics Structures + +<sect2>pixel +<p> +A simple structure describing a point on the screen. + +<sect2>fontdesc +<p> +This structure describes a font in one pointsize. There is the current font - <tt/struct fontdesc/ +bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling +<tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize - +somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can +pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although +it has 'Load' in the name, that function loads only GEOS internal data structures, not data +from disk). + +<sect2>window +<p> +This widely used structure holds the description of a region of the screen. It describes the top-left and +bottom-right corners of a window. + +<sect2>iconpic +<p> +Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions - +<tt/BitmapUp/ for example. This structure holds the parameters needed to properly decode and show +a bitmap on the screen. The bitmap has to be encoded - if you have some non-GEOS bitmaps simply +convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/ +too. + +<sect1>Icons +<p> +These structures describe click boxes (icons) that can be placed on screen or in a dialog box. + +<sect2>icondef +<p> +This is the definition of a single click box. Please see <tt/gstruct.h/ for a description of its fields. + +<sect2>icontab +<p> +This is the toplevel description of icons to be placed and enabled on the screen. This structure +has the following fields: +<itemize> + <item><tt/char number/ - total number of icons declared here + <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ the mouse pointer will be placed in + this point allowing you to have a hint for the user what the default action is + <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains + descriptions for all icons +</itemize> + +<sect1>File and Disk + +<sect2>tr_se +<p> +This simple structure holds the track and sector number of something. Do not expect the track to be +in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K +expansion is utilized as RAMDisk with a layout of 4 tracks of 128 sectors each. However assuming that +a track number equal to 0 is illegal might be wise. + +<sect2>f_date +<p> +This is a placeholder for a file datestamp. This structure is also present in <tt/struct filehandle/. +GEOS is not Y2K compliant, so if the current file has in <tt/filehandle.date.year/ a value less than 86 +you can safely assume that it is e.g. 2004 and not 1904. + +<sect2>filehandle +<p> +This is the main file descriptor. It is either an entry in the directory (returned from file functions) +or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g. +by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/. + +<sect2>fileheader +<p> +This structure holds the fileheader description. You can load a file's header into the <tt/fileHeader/ +fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while +<tt/fileheader/ is a structure). +You will also need your own fileheader for <tt/SaveFile/. + +<sect1>System Structures + +<sect2>s_date +<p> +This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/ +so I prepared this one. You can e.g. get or set the current time using <tt/system_date.s_hour/ and +<tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/ +pair. + +<sect2>process +<p> +You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number +of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold +only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to the called +function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/. +The second field <tt/jiffies/ holds the amount of time between calls to that function. +On PAL systems there are 50 jiffies per second, while NTSC have 60 of them. + +<sect1>A few things in detail... +<p> +GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a +kind of array of unspecified length and unspecified type. Here is how it works: +<tscreen><verb> +void example = { + (char)3, (unsigned)3, (char)0 }; +</verb></tscreen> +Which will be compiled to following string of bytes: +<tscreen><verb> +_example: + .byte 3 + .word 3 + .byte 0 +</verb></tscreen> +As you see this way it is possible to define data of any type in any order. You must remember to +cast each member to proper type. + +<sect2>DoMenu structure +<p> +<tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs +are just initializing the screen and menu and returning to <tt/MainLoop/. In GEOSLib it is the same as +returning from <tt/main/ function without using <tt/exit(0)/. +<p> +A menu is described by two types of data - menu descriptors and menu items. A descriptor contains +information about the following menu items, and items contain names of entries and either +pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors. +Note that submenu descriptor can be top-level descriptor, there's no difference in structure, +just in the content. +<p> +Here is how a single descriptor looks like: +<tscreen><verb> +void myMenu = { + (char)top, (char)bottom, // this is the size of the menubox + (unsigned)left, (unsigned)right, // counting all items in the current descriptor + (char)number_of_items | type_of_menu, // number of following items ORed with + // type of this menu, it can be either + // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed + // after moving mouse pointer outside the menubox. You can have at most 31 items. +</verb></tscreen> +This is followed by <tt/number_of_items/ of following item description. +<tscreen><verb> + ... + "menuitemname", (char)item_type, (unsigned)pointer, + "nextitemname", (char)item_type, (unsigned)pointer, + ... + "lastitemname", (char)item_type, (unsigned)pointer }; + // Note that there isn't ending <tt/NULL/ or something like that. +</verb></tscreen> +<tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one +can have following values: +<p> +<tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on the menu item +<p> +<tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu +<p> +Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function +which will return in <tt/r0/ the needed pointer (to function to execute or a submenu). +<p> +For creating nested menus (you can have at most 8 levels of submenus) you need to declare such +a structure for each submenu and top level menu. + +<sect2>DoDlgBox command string +<p> +<tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is +responsible for creating dialog boxes, that is windows which task is to interact with the user. +The format of the command string is following: +<tscreen><verb> + (window size and position) + (commands and parameters) + NULL +</verb></tscreen> +There is a custom type defined for the command string: <tt/dlgBoxStr/. + +<sect3>Size and position +<p> +The first element can be specified in two ways - by using the default size and position or specifying +your own. The first case results in +<tscreen><verb> +const dlgBoxStr example = { + DB_DEFPOS (pattern_of_shadow), + ... // commands + DB_END }; +</verb></tscreen> +And the own size and position would be: +<tscreen><verb> +const dlgBoxStr example = { + DB_SETPOS (pattern, top, bottom, left, right) + ... // commands + DB_END }; +</verb></tscreen> + +<sect3>Commands +<p> +The next element of the <tt/DoDlgBox/ command string are the commands themselves. The first six commands are +default icons and the number of the selected icon will be returned from window processor. The icons are +<tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for using them, e.g.: +<tscreen><verb> + ... + DB_ICON(OK, DBI_X_0, DBI_Y_0), + ... +</verb></tscreen> +Note that the position is counted from top left corner of window, not entire screen and that the 'x' +position is counted in cards (8-pixel) and not in pixels. This is also true for all following commands. +<tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), the default positions +which will cause icons to appear on a default window exactly where you would expect them. +<p> +<tt/DB_TXTSTR (x, y, text)/ will cause to show the given text in the window. +<p> +<tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location +where the address of the text is stored. This is useful for information windows where only the text content +is variable. Consider following: +<tscreen><verb> +char text = "foo"; + ... + r15=(unsigned)text; // in code just before call to DoDlgBox + ... + DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15), + ... +</verb></tscreen> +will cause the word ``foo'' to appear in the window, but you may store the pointer to any text in +<tt/r15/ (in this case) before the call to DoDlgBox. +<p> +<tt/DB_GETSTR(x, y, ptr, length)/ - will add a input-from-keyboard feature. <tt/ptr/ works as in the +previous example and points to the location where the text is to be stored. Note that the contents of this +location will be shown upon creating the window. <tt/length/ is the maximum number of characters to input. +<p> +<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to the given pointer. It is called on every keypress. +<p> +<tt/DB_GRPHSTR(ptr)/ - the data for this command is a pointer for <tt/GraphicsString/ commands. +<p> +<tt/DB_GETFILES(x, y)/ - for a standard window you should pass 4 for both x and y. This function +draws a file selection box and searches the current drive for files. Before the call to <tt/DoDlgBox/ you +must load <tt/r7L/ with the GEOS filetype of searched files and <tt/r10/ with the class text. In <tt/r5/ +you have to load a pointer to a <tt/char[17]/ where the selected filename will be copied. It works +like <tt/FindFTypes/ but is limited to first 16 files. +<p> +<tt/DB_OPVEC(ptr)/ - this sets a new pointer for the button press function, if you pass +<tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button. +<p> +<tt/DB_USRICON(x, y, ptr)/ - places a single user icon (click box) on the window, <tt/ptr/ points at a +<tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click +boxes in a window, this is an internal limit of the GEOS Kernal. +<p> +<tt/DB_USRROUT(ptr)/ - this command causes to immediately call the user routine pointed by <tt/ptr/. + +<sect2>GraphicsString command string +<p> +<tt/GraphicsString/ is a very powerful routine to initialize the whole screen at once. There are +predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. The last +command has to be <tt/GSTR_END/. There is a custom type defined for the command string: <tt/graphicStr/. +<p> +Here is an example for clearing the screen: +<tscreen><verb> +const graphicStr example = { + MOVEPENTO(0,0), + NEWPATTERN(0), + RECTANGLETO(319,199) + GSTR_END }; +</verb></tscreen> + +<sect2>InitRam table +<p> +This type of data is used to initialize one or more bytes in different locations at once. The format is +the following: +<tscreen><verb> +void example = { + (unsigned)address_to_store_values_at, + (char)number_of_bytes_that_follow, + (char)data,(char)data (...) + // more such definitions + (unsigned)NULL // address of 0 ends the table + }; +</verb></tscreen> + +<sect2>Intercepting system vectors +<p> +It is possible to intercept events and hook into the GEOS Kernal using vectors. Here is a little example: +<tscreen><verb> +void_func oldVector; + +void NewVectorHandler(void) { + // do something and at the end call the old vector routine + oldVector(); +} + +void hook_into_system(void) { + oldVector = mouseVector; + mouseVector = NewVectorHandler; +} + +void remove_hook(void) { + mouseVector = oldVector; +} +</verb></tscreen> +<p> +In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to the GEOS +Kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/. +Be warned that vectors are most likely to be changed by the GEOS Kernal also via other functions (like +<tt/GotoFirstMenu/, <tt/DoDlgBox/ and its derivatives etc.). It depends on what Kernal functions +you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete +list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of the +information contained there should be still valid for GEOS 2.0. When calling a function that restores +the vector you should add a <tt/hook_into_system()/ call right after it. +<p> +It is critical to restore old vector values before exiting the program. If you have more than one +place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to +be called upon exiting with <tt/atexit(&remove_hook);/ call. This way you will ensure that +such destructor will be always called. +<p> +That little example above intercepts <tt/mouseVector/. The <tt/NewVectorHandler/ function will be +called every time the mouse button changes status. Other important vectors you should know about +are: +<itemize> + <item><tt/appMain/ - this is called from within the <tt/MainLoop/ system loop + <item><tt/keyVector/ - called whenever a keypress occurs + <item><tt/intTopVector/ - called at the start of the IRQ routine + <item><tt/intBotVector/ - called at the end of the IRQ routine +</itemize> + +</article> diff --git a/doc/grc65.sgml b/doc/grc65.sgml new file mode 100644 index 000000000..583c6f80f --- /dev/null +++ b/doc/grc65.sgml @@ -0,0 +1,392 @@ +<!doctype linuxdoc system> +<article> + +<!-- Title information --> + +<title>grc65 -- GEOS Resource Compiler +<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl"> +<and><url name="Greg King" url="mailto:gngking@erols.com"> +<date>VII 2000; VI,VII 2002; 2005-8-3 +<abstract> +This document describes a compiler that can create GEOS headers and menues for +cc65-compiled programs. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview +<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to +generate required and optional resources. A required resource for every GEOS +application is the header, that is: an icon, some strings, and some addresses. +Optional resources might be menu definitions, other headers (e.g., for data +files of an app.), dialog definitions, etc. Without an application's header, +GEOS is unable to load and start it. + +Currently, <bf/grc65/ supports only menues and the required header definition, +along with support for building applications with VLIR-structured overlays. + +<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s). +That is because the application header data must be in assembly format, while +the menu definitions can be translated easily into C. The purpose of the C +file is to include it as a header in only one project file. The assembly source +should be processed by <bf/ca65/ and linked to the application (read about +<ref name="the building process" id="building-seq">). + + + +<sect>Usage +<p>grc65 accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: grc65 [options] file +Short options: + -V Print the version number + -h Help (this text) + -o name Name the C output file + -s name Name the asm output file + -t sys Set the target system + +Long options: + --help Help (this text) + --target sys Set the target system + --version Print the version number +--------------------------------------------------------------------------- +</verb></tscreen> +Default output names are made from input names with extensions replaced by +<tt/.h/ and <tt/.s/. + + + +<sect>Resource file format +<p>A resource file has the name extension <tt/.grc/. That is not required, but +it will make for an easier recognition of the file's purpose. Also, <bf/cl65/ +recognizes those files. <bf/grc65/'s parser is very weak at the moment; so, +read the comments carefully, and write resources exactly as they are written +here. Look out for CAPS and small letters. Everything after a '<tt/;/' +until the end of the line is considered as a comment and ignored. See the +included <ref name="commented example .grc file" id="example-grc"> for a +better view of the situation. + + +<sect1>Menu definition +<p><tscreen><verb> +MENU menuName leftx,topy <ORIENTATION> { + "item name 1" <MENU_TYPE> pointer + ... + "item name x" <MENU_TYPE> pointer +}</verb></tscreen> +The definition starts with the keyword <tt/MENU/, then comes the menu's name, +which will be represented in C as <tt/const void/. Then are the co-ordinates +of the top left corner of the menu box. The position of the bottom right +corner is estimated, based on the length of item names and the menu's +orientation. It means that the menu box always will be as large as it should +be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or +<tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's +content. It consists of item definitions. First is an item name -- it has to +be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or +<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit +(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of +them). You can use C logical operators in expressions, but you have to do it +without spaces. So a dynamically created submenu will be something like: +<tscreen><verb> +"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen> +The last part of the item definition is a pointer which can be any name that is +present in the C source code that includes the generated header. It can point +to a function or to another menu definition. + +If you are doing sub(sub)menu definitions, remember to place the lowest level +definition first, and the top-level menu as the last one. That way the C +compiler won't complain about unknown names. + + +<sect1>Header definition +<p><tscreen><verb> +HEADER <GEOS_TYPE> "dosname" "classname" "version" { + author "Joe Schmoe" + info "This is my killer-app!" + date yy mm dd hh ss + dostype SEQ + mode any + structure SEQ + icon "sprite.raw" +}</verb></tscreen> +The header definition describes the GEOS header sector which is unique to +each file. The definition starts with the keyword <tt/HEADER/, then goes the +GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then, +there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS +Class name (up to 12 characters), and the version info (up to 4 characters). +The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the +major, and <em/y/ is the minor, version number. Those fields, along with both +braces, are required. The lines between braces are optional, and will be replaced +by default and current values. The keyword <tt/author/ and its value in quotes name +the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can +have up to 95 characters. If the <tt/date/ field is omitted, then the time of +that compilation will be placed into the header. Note that, if you do specify +the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/, +<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care. +The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and, +it describes system requirements. <tt/any/ will work on both 64-GEOS and +128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in +40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode, +and <tt/c64only/ will work on only 64-GEOS. The default value for +<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but +then, you also have to put in a third type of resource -- a memory definition. +The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file +are expected to represent a standard monochrome VIC sprite. The file gets accessed +when the generated assembly source is being processed by <bf/ca65/. Examples for +programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the +<url name="sp65 sprite and bitmap utility" url="sp65.html">. The default <tt/icon/ +is an empty frame internally represented in the generated assembly file. + + +<sect1>Memory definition +<p><tscreen><verb> +MEMORY { + stacksize 0x0800 + overlaysize 0x2000 + overlaynums 0 1 2 4 5 +}</verb></tscreen> +The memory definition is unique to each file and describes several attributes related +to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which +contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g. +<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value +of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be +either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied +background screen buffer while the latter means that the program uses the memory of the +background screen buffer for own purposes. The default value of <tt/yes/ comes from the +linker configuration file. If the <tt/structure/ in the header definition is set to the +value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the +VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number +0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. +<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application. +Skipped numbers denote empty records. In the example, record number 3 is missing. Read +<ref name="this description" id="building-vlir"> for details. + + + +<sect>Building a GEOS sequential application<label id="building-seq"> +<p>Before proceeding, please read the <url name="compiler" url="cc65.html">, +<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html"> +documentation, and find the appropriate sections about building programs, in +general. + +GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in +the GEOS world. It means that each file built with the cc65 package has to be +deconverted in GEOS, before it can be run. You can read a step-by-step +description of that in the <url name="GEOS section of the cc65 Compiler Intro" +url="intro-6.html#ss6.5">. + +Each project consists of four parts, two are provided by cc65. Those parts +are:<enum> +<item>application header +<item>start-up object +<item>application objects +<item>system library +</enum> +<bf/2./ and <bf/4./ come with cc65; however you have to write the application +yourself ;-) + +The application header is defined in the <tt/HEADER/ section of the <tt/.grc/ +file and is processed into an assembly <tt/.s/ file. You must assemble it, with +<bf/ca65/, into the object <tt/.o/ format. + +Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C +source), &dquot;<tt/test.h/&dquot; (a header file), and +&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the +fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot; +because you will have to be very careful with names (<bf/grc65/ will make +&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of +&dquot;<tt/test.grc/&dquot; by default; and you don't want that because +&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and +&dquot;<tt/test.h/&dquot; is something completely different)! + +<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like: +<tscreen><verb> +#include <geos.h> +#include "testres.h" +</verb></tscreen> +There are no other includes. + + +<sect1>Building the GEOS application using cl65 +<p>This is a simple one step process: +<tscreen><verb> +cl65 -t geos-cbm -O -o test.cvt testres.grc test.c +</verb></tscreen> +Always place the <tt/.grc/ file as first input file on the command-line in order +to make sure that the generated <tt/.h/ file is available when it is needed for +inclusion by a <tt/.c/ file. + + +<sect1>Building the GEOS application without cl65 +<sect2>First step -- compiling the resources +<p> +<tscreen><verb> +grc65 -t geos-cbm testres.grc +</verb></tscreen> +will produce two output files: &dquot;<tt/testres.h/&dquot; and +&dquot;<tt/testres.s/&dquot;. + +Note that &dquot;<tt/testres.h/&dquot; is included at the top of +&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step. + +<sect2>Second step -- assembling the application header +<p> +<tscreen><verb> +ca65 -t geos-cbm testres.s +</verb></tscreen> +And, voilá -- &dquot;<tt/testres.o/&dquot; is ready. + +<sect2>Third step -- compiling the code +<p> +<tscreen><verb> +cc65 -t geos-cbm -O test.c +ca65 -t geos-cbm test.s +</verb></tscreen> +That way, you have a &dquot;<tt/test.o/&dquot; object file which +contains all of the executable code. + +<sect2>Fourth and last step -- linking the application +<p> +<tscreen><verb> +ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib +</verb></tscreen> +The last file is the GEOS system library. + +The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's +contained in the well-known GEOS <em/Convert/ format. Note that its name +(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name +that was given in the header definition. + +At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is +required for the correct process of GEOS sequential application building. + + + +<sect>Building a GEOS VLIR overlay application<label id="building-vlir"> +<p>Large GEOS applications typically don't fit in one piece in their designated +memory area. They are therefore split into overlays which are loaded into memory +on demand. The individual overlays are stored as records of a VLIR (Variable +Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads +record number 0 which is supposed to contain the main program. The record numbers +starting with 1 are to be used for the actual overlays. + +In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting +of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/". + + +<sect1>Building the GEOS overlay application using cl65 +<p>This is a simple one step process: +<tscreen><verb> +cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c +</verb></tscreen> +Always place the <tt/.grc/ file as first input file on the command-line in order +to make sure that the generated <tt/.h/ file is available when it is needed for +inclusion by a <tt/.c/ file. + +You will almost certainly want to generate a map file that shows (beside a lot of +other infos) how large your individual overlays are. This info is necessary to tune +the distribution of code into the overlays and to optimize the memory area reserved +for the overlays. + + +<sect1>Building the GEOS overlay application without cl65 +<sect2>First step -- compiling the overlay resources +<p> +<tscreen><verb> +grc65 -t geos-cbm overlay-demores.grc +</verb></tscreen> + +<sect2>Second step -- assembling the overlay application header +<p> +<tscreen><verb> +ca65 -t geos-cbm overlay-demores.s +</verb></tscreen> + +<sect2>Third step -- compiling the overlay code +<p> +<tscreen><verb> +cc65 -t geos-cbm -O overlay-demo.c +ca65 -t geos-cbm overlay-demo.s +</verb></tscreen> + +<sect2>Fourth and last step -- linking the overlay application +<p> +<tscreen><verb> +ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib +</verb></tscreen> + + + +<sect>Bugs and feedback +<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I +am aware of them; I know that the parser is weak, and if you don't follow the +grammar rules strictly, then everything will crash. However, if you find an +interesting bug, mail me. :-) Mail me also for help with writing your +<tt/.grc/ file correctly if you have problems with it. I would appreciate +comments also, and help on this file because I am sure that it can be written +better. + + + +<sect>Legal stuff +<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you +should see its documentation for more info. Anyway, if you like it, and want +to encourage me to work more on it, send me a postcard with a sight of your +neighbourhood, city, region, etc. Or, just e-mail me with info that you +actually used it. See <url name="the GEOSLib documentation" url="geos.html"> +for addresses. + + + +<appendix> +<sect>Appendix A -- example.grc<label id="example-grc"> +<p><tscreen><verb> +; Note that MENU can define both menues and submenues. +; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT +; any spaces between the arguments (the parser is simple and weak). + +MENU subMenu1 15,0 VERTICAL +; This is a vertical menu, placed at (15,0). +{ +; There are three items, all of them will call functions. +; The first and third ones are normal functions, see GEOSLib documentation for +; information about what the second function should return (it's a dynamic one). + "subitem1" MENU_ACTION smenu1 + "subitem2" MENU_ACTION|DYN_SUB_MENU smenu2 + "subitem3" MENU_ACTION smenu3 +} + +;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... } + +MENU mainMenu 0,0 HORIZONTAL +; Here, we have our main menu, placed at (0,0), and it is a horizontal menu. +; Because it is a top-level menu, you would register it in your C source by +; using: DoMenu(&ero;mainMenu); +{ +; There are two items -- a submenu and an action. +; This calls a submenu named subMenu1 (see previous definition). + "first sub-menu" SUB_MENU subMenu1 +; This will work the same as an EnterDeskTop() call in C source code. + "quit" MENU_ACTION EnterDeskTop +} + +;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version" + +HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0" +; This is a header for an APPLICATION which will be seen in the directory as a +; file named MyFirstApp with the Class-string "Class Name V1.0" +{ +; Not all fields are required, default and current values will be used. + author "Maciej Witkowiak" ; always in quotes! + info "Information text" ; always in quotes! +; date yy mm dd hh ss ; always 5 fields! +; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case) +; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case) + mode c64only ; can be: any, 40only, 80only, c64only +}</verb></tscreen> +</article> diff --git a/doc/index.sgml b/doc/index.sgml new file mode 100644 index 000000000..e0b110ead --- /dev/null +++ b/doc/index.sgml @@ -0,0 +1,179 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 Documentation Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2005-8-6 + +<abstract> +Main documentation page, contains links to other available stuff. +</abstract> + +<sect>Program documentation<p> + +<descrip> + + <tag><htmlurl url="ar65.html" name="ar65.html"></tag> + Describes the ar65 archiver. + + <tag><htmlurl url="ca65.html" name="ca65.html"></tag> + Describes the ca65 macro assembler. + + <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag> + Describes the ca65html assembler-source-to-HTML converter. + + <tag><htmlurl url="cc65.html" name="cc65.html"></tag> + Describes the cc65 C compiler. + + <tag><htmlurl url="cl65.html" name="cl65.html"></tag> + Describes the cl65 compile & link utility. + + <tag><htmlurl url="co65.html" name="co65.html"></tag> + Describes the co65 object-file converter. + + <tag><htmlurl url="da65.html" name="da65.html"></tag> + Describes the da65 6502/65C02 disassembler. + + <tag><htmlurl url="grc65.html" name="grc65.html"></tag> + Describes the GEOS resource compiler (grc65). + + <tag><htmlurl url="ld65.html" name="ld65.html"></tag> + Describes the ld65 linker. + + <tag><htmlurl url="od65.html" name="od65.html"></tag> + Describes the od65 object-file analyzer. + + <tag><htmlurl url="sp65.html" name="sp65.html"></tag> + Describes the sprite and bitmap utility. + +</descrip> + + +<sect>Usage<p> + +<descrip> + + <tag><htmlurl url="intro.html" name="intro.html"></tag> + Describes the use of the tools, by building a short &dquot;hello world&dquot; + example. + + <tag><htmlurl url="coding.html" name="coding.html"></tag> + Contains hints on creating the most effective code with cc65. + + <tag><htmlurl url="compile.txt" name="compile.txt"></tag> + How to compile cc65 and the support tools. + + <tag><htmlurl url="using-make.html" name="using-make.html"></tag> + Build programs, using the GNU Make utility. + + <tag><htmlurl url="customizing.html" name="customizing.html"></tag> + How to use the cc65 toolset for a custom hardware platform (a target system + not currently supported by the cc65 library set). + + <tag><htmlurl url="debugging.html" name="debugging.html"></tag> + Debug programs, using the VICE emulator. + +</descrip> + + +<sect>Library information and other references<p> + +<descrip> + + <tag><htmlurl url="funcref.html" name="funcref.html"></tag> + A (currently incomplete) function reference. + + <tag><htmlurl url="dio.html" name="dio.html"></tag> + Low-level disk I/O API. + + <tag><htmlurl url="geos.html" name="geos.html"></tag> + The GEOSLib manual. + + <tag><htmlurl url="internal.txt" name="internal.txt"></tag> + A somewhat older text describing several cc65 internals. + + <tag><htmlurl url="library.html" name="library.html"></tag> + An overview over the cc65 runtime and C libraries. + + <tag><htmlurl url="smc.html" name="smc.html"></tag> + Describes Christian Krügers macro package for writing self modifying + assembler code. + + <tag><url name="6502 Binary Relocation Format document" + url="http://www.6502.org/users/andre/o65/fileformat.html"></tag> + Describes the o65 file format that is used for dynamically loadable modules + and LUnix programs. + +</descrip> + + +<sect>Platform-specific information<p> + +<descrip> + + <tag><htmlurl url="apple2.html" name="apple2.html"></tag> + Topics specific to the Apple ][. + + <tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag> + Topics specific to the enhanced Apple //e. + + <tag><htmlurl url="atari.html" name="atari.html"></tag> + Topics specific to the Atari 8-bit machines. + + <tag><htmlurl url="atmos.html" name="atmos.html"></tag> + Topics specific to the Oric Atmos. + + <tag><htmlurl url="c128.html" name="c128.html"></tag> + Topics specific to the Commodore 128. + + <tag><htmlurl url="c16.html" name="c16.html"></tag> + Topics specific to the Commodore 16/116. + + <tag><htmlurl url="c64.html" name="c64.html"></tag> + Topics specific to the Commodore 64. + + <tag><htmlurl url="cbm510.html" name="cbm510.html"></tag> + Topics specific to the Commodore 510. + + <tag><htmlurl url="cbm610.html" name="cbm610.html"></tag> + Topics specific to the Commodore 610. + + <tag><htmlurl url="lynx.html" name="lynx.html"></tag> + Topics specific to the Atari Lynx Game Console. + + <tag><htmlurl url="nes.html" name="nes.html"></tag> + Topics specific to the Nintendo Entertainment System. + + <tag><htmlurl url="pet.html" name="pet.html"></tag> + Topics specific to the Commodore PET machines. + + <tag><htmlurl url="plus4.html" name="plus4.html"></tag> + Topics specific to the Commodore Plus/4. + + <tag><htmlurl url="supervision.html" name="supervision.html"></tag> + Topics specific to the Supervision Console. + + <tag><htmlurl url="vic20.html" name="vic20.html"></tag> + Topics specific to the Commodore VIC20. + +</descrip> + + +<sect>Miscellaneous<p> + +<descrip> + + <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> + Somewhat outdated. Lists the differences between my cc65 releases + and the original Atari version that was created by J. R. Dunning. + + <tag><htmlurl url="BUGS" name="BUGS"></tag> + Known cc65 bugs. + + <tag><htmlurl url="CREDITS" name="CREDITS"></tag> + Here is who helped with the compiler and other tools. + +</descrip> + +</article> + diff --git a/doc/internal.txt b/doc/internal.txt new file mode 100644 index 000000000..0dca618ea --- /dev/null +++ b/doc/internal.txt @@ -0,0 +1,207 @@ + + + Internals doc for CC65 + + + +Stacks: +------- + +The program stack used by programs compiled with CC65 is located in high +memory. The stack starts there and grows down. Arguments to functions, local +data etc are allocated on this stack, and deallocated when functions exit. + +The program code and data is located in low memory. The heap is located +between the program code and the stack. The default size for the parameter +stack is 2K, you may change this for most platforms in the linker +configuration. + +Note: The size of the stack is only needed if you use the heap, or if you +call the stack checking routine (_stkcheck) from somewhere in your program. + +When calling other functions, the return address goes on the normal 6502 +stack, *not* on the parameter stack. + + + +Registers: +---------- + +Since CC65 is a member of the Small-C family of compilers, it uses the notion +of a 'primary register'. In the CC65 implementation, I used the AX register +pair as the primary register. Just about everything interesting that the +library code does is done by somehow getting a value into AX, and then calling +some routine or other. In places where Small-C would use a secondary +register, top-of-stack is used, so for instance two argument function like +integer-multiply work by loading AX, pushing it on the stack, loading the +second value, and calling the internal function. The stack is popped, and the +result comes back in AX. + + + +Calling sequences: +------------------ + +C functions are called by pushing their args on the stack, and JSR'ing to the +entry point. (See ex 1, below) If the function returns a value, it comes back +in AX. NOTE!!! A potentially significant difference between the CC65 +environment and other C environments is that the CALLEE pops arguments, not +the CALLER. (This is done so as to generate more compact code) In normal use, +this doesn't cause any problems, as the normal function entry/exit conventions +take care of popping the right number of things off the stack, but you may +have to worry about it when doing things like writing hand-coded assembly +language routines that take variable numbers of arguments. More about that +later. + +Ex 1: Function call: Assuming 'i' declared int and 'c' declared + char, the following C code + + i = baz(i, c); + + in absence of a prototype generates this assembler code. I've added + the comments. + + lda _i ; get 'i', low byte + ldx _i+1 ; get 'i', hi byte + jsr pushax ; push it + lda _c ; get 'c' + ldx #0 ; fill hi byte with 0 + jsr pushax ; push it + ldy #4 ; arg size + jsr _baz ; call the function + sta _i ; store the result + stx _i+1 + + In presence of a prototype, the picture changes slightly, since the + compiler is able to do some optimizations: + + lda _i ; get 'i', low byte + ldx _i+1 ; get 'i', hi byte + jsr pushax ; push it + lda _c ; get 'c' + jsr pusha ; push it + jsr _baz ; call the function + sta _i ; store the result + stx _i+1 + + +Note that the two words of arguments to baz were popped before it exitted. +The way baz could tell how much to pop was by the argument count in Y at call +time. Thus, even if baz had been called with 3 args instead of the 2 it was +expecting, that would not cause stack corruption. + +There's another tricky part about all this, though. Note that the args to baz +are pushed in FORWARD order, ie the order they appear in the C statement. +That means that if you call a function with a different number of args than it +was expecting, they wont end up in the right places, ie if you call baz, as +above, with 3 args, it'll operate on the LAST two, not the first two. + + + +Symbols: +-------- + +CC65 does the usual trick of prepending an underbar ('_') to symbol names when +compiling them into assembler. Therefore if you have a C function named +'bar', CC65 will define and refer to it as '_bar'. + + + +Systems: +-------- + +Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700, +the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to +Kevin Ruland, who did the port). + +C16: Works with unexpanded or memory expanded C16 and C116 machines. + However, a maximum of 32KB from the total memory is used. The Plus/4 + target supports up to 64K of memory, but has a small code overhead + because of the banking routines involved. Apart from this additional + overhead, the Plus/4 target and the C16 target are the same. 16K + machines (unexpanded C16) have 12K of memory for C programs available, + machines with 32K or more have 28K available. The actual amount of + memory is auto detected. + +C64: The program runs in a memory configuration, where only the kernal ROM + is enabled. The text screen is expected at the usual place ($400), so + 50K of memory are available to the program. + +C128: The startup code will reprogram the MMU, so that only the kernal ROM + is enabled. This means, there are 41K of memory available to the + program. + +Plus/4: Works with bank switching so 59K of memory are available to the + program. + +CBM 500: + The C program runs in bank #0 and has a total of 48K memory available. + This is less than what is available on its bigger brothers (CBM + 600/700) because the character data and video RAM is placed in the + execution bank (#0) to allow the use of sprites. + +CBM 600/700: + The C program runs in a separate segment and has almost full 64K of + memory available. + +PET: The startup code will adjust the upper memory limit to the installed + memory. However, only linear memory is used, this limits the top to + $8000, so on a 8032 or similar machine, 31K of memory are available to + the program. + +Apple ][: + The program starts at $803, end of RAM is $95FF, so 35.5K of memory + (including stack) are available to the program. + +Atari: The startup code will adjust the upper memory limit to the installed + memory detected at runtime. The programmer can adjust the upper memory + limit by setting the __RESERVED_MEMORY__ variable at link time. The + given __RESERVED_MEMORY__ value will be subtracted from the upper + memory limit used by the runtine. This memory could be used as graphics + memory, for example. + In the default case (no setting of __RESERVED_MEMORY__) the upper + memory limit is $9C1F (with Basic cartridge) and $BC1F (without + cartridge). The program starts at $2E00 by default. + These values are for a 48K or 64K machine. + +Note: The above numbers do not mean that the remaining memory is unusable. +However, it is not linear memory and must be accessed by other, nonportable +methods. I'm thinking about a library extension that allows access to the +additional memory as a far heap, but these routines do not exist until now. + + + +Inline Assembly: +---------------- + +CC65 allows inline assembly by a special keyword named "asm". Inline assembly +looks like a function call. The string in parenthesis is output in the +assembler file. + +Example, insert a break instruction into the code: + + asm ("brk") + +Beware: Be careful when inserting inline code since this may collide with +the work of the optimizer. + + + +Pseudo variables: +----------------- + +There are two special variables available named __AX__ and __EAX__. These +variables must never be declared (this gives an error), but may be used as any +other variable. However, accessing these variables will access the primary +register that is used by the compiler to evaluate expressions, return +functions results and pass parameters. + +This feature is useful with inline assembly and macros. For example, a macro +that reads a CRTC register may be written like this: + +#define wr(idx) (__AX__=(idx), \ + asm ("sta $2000"), \ + asm ("lda $2000"), \ + asm ("ldx #$00"), \ + __AX__) + diff --git a/doc/intro.sgml b/doc/intro.sgml new file mode 100644 index 000000000..c5ef7956a --- /dev/null +++ b/doc/intro.sgml @@ -0,0 +1,527 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Compiler Intro +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">, +<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">, +<and><url name="Greg King" url="mailto:gngking@erols.com"> +<date>2005-7-22 + +<abstract> +How to use the cc65 C language system -- an introduction. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This is a short intro of how to use the compiler and the bin-utils. It contains +a step-by-step example of how to build a complete application from one C and +one assembly modules. This file does <em/not/ contain a complete reference for +the tools used in the process. There are separate files describing those tools, +in detail (see <url url="index.html">). + +I do assume that you have downloaded and installed the compiler and +target-specific files. Windows users should use the friendly .exe installer +(named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the +version number if necessary). It does not only install the target files, but +will also set up necessary environment variables for you. + +If you're going for the .ZIP archives, please note that there is one file for +the host platform (Windows, DOS or OS/2), one file for each target platform +(C64 or whatever) and a separate file containing the docs (which include the +file you're currently reading). So for most uses, you will need at least 3 +files and unpack all three into one directory. In case of the .ZIP archives, +you will also need to set the environment variables <tt/CC65_INC/, +<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below. + +<bf/Note/: There is a much simpler way to compile this example, by using the +<bf/cl65/ compile-and-link utility. However, it makes sense to understand how +the separate steps work. How to do the example with the <bf/cl65/ utility is +described <ref id="using-cl65" name="later">. + + +<sect1>Before we start<p> + +You will find a copy of the sample modules, used in the next section, in the +"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with +missing include files and/or libraries, please check the environment variables +<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the +<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you +installed cc65. + + +<sect1>The sample modules<p> + +To explain the development flow, I will use the following example modules: + +hello.c: +<tscreen><code> + #include <stdio.h> + #include <stdlib.h> + + extern const char text[]; /* In text.s */ + + int main (void) + { + printf ("%s\n", text); + return EXIT_SUCCESS; + } +</code></tscreen> + +text.s: +<tscreen><code> + .export _text + _text: .asciiz "Hello world!" +</code></tscreen> + + +<sect1>Translation phases<p> + +We assume that the target file should be named "hello", and the target system +is the C64. + +<tscreen><verb> + +---------+ + | hello.c | + +---------+ + | + cc65 + \/ + +---------+ +---------+ +---------+ + | hello.s | | text.s | | crt0.o | + +---------+ +---------+ +---------+ + | | | + ca65 ca65 ar65 + \/ \/ \/ + +---------+ +---------+ +---------+ + | hello.o | | text.o | | c64.lib | + +---------+ +---------+ +---------+ + | \ / + | \ / + | \ / + +----------------------->ld65< + \/ + hello +</verb></tscreen> + +<tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime +and C library) are provided in binary form in the cc65 package. Actually, the +startup code is contained in the library, so you won't need to care about it. + + + +<sect>The compiler<p> + +The compiler translates one C source into one assembly source, for each +invocation. It does <em/not/ create object files directly, and it is <em/not/ +able to translate more than one file per run. + +In the example above, we would use the following command line, to translate +<tt/hello.c/ into <tt/hello.s/: + +<tscreen><verb> + cc65 -O -t c64 hello.c +</verb></tscreen> + +The <tt/-O/ switch tells the compiler to do an additional optimizer run, which +is usually a good idea, since it makes the code smaller. If you don't care +about the size, but want to have slightly faster code, use <tt/-Oi/ to inline +some runtime functions. + +The <tt/-t/ switch is followed by the target system name. + +If the compiler does not complain about errors in our "hello world" program, we +will have a file named "<tt/hello.s/", in our directory, that contains the +assembly source for the <bf/hello/ module. + +For more information about the compiler, see <url url="cc65.html">. + + + +<sect>The assembler<p> + +The assembler translates one assembly source into an object file, for each +invocation. The assembler is <em/not/ able to translate more than one source +file per run. + +Let's translate the "hello.s" and "text.s" files from our example: + +<tscreen><verb> + ca65 hello.s + ca65 -t c64 text.s +</verb></tscreen> + +The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the +text is converted from the input character-set (usually ISO-8859-1) into the +target character-set (PETSCII, in this example) by the assembler. The +compiler-generated file <tt/hello.s/ does not contain any character constants, +so specification of a target is not necessary (it wouldn't do any harm, +however). + +If the assembler does not complain, we should now have two object files (named +<tt/hello.o/ and <tt/text.o/) in the current directory. + +For more information about the assembler, see <url url="ca65.html">. + + + +<sect>The linker<p> + +The linker combines several object and library files into one output file. +<bf/ld65/ is very configurable, but fortunately has built-in configurations, +so we don't need to mess with configuration files, here. + +The compiler uses small functions to do things that cannot be done inline +without a big impact on code size. Those runtime functions, together with the +C library, are in an object-file archive named after the system, in this case, +"<tt/c64.lib/". We have to specify that file on the command line, so that the +linker can resolve those functions. + +Let's link our files to get the final executable: + +<tscreen><verb> + ld65 -o hello -t c64 hello.o text.o c64.lib +</verb></tscreen> + +The argument after <tt/-o/ specifies the name of the output file, the argument +after <tt/-t/ gives the target system. The following arguments are object +files or libraries. Since the target library resolves imports in <tt/hello.o/ +and <tt/text.o/, it must be specified <em/after/ those files. + +After a successful linker run, we have a file named "<tt/hello/", ready for +our C64! + +For more information about the linker, see <url url="ld65.html">. + + + +<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p> + +The <bf/cl65/ utility is able to do all of the steps described above, in just +one command line, and it has defaults for some options that are very +well-suited for our example. + +To compile both files into one executable, enter: + +<tscreen><verb> + cl65 -O hello.c text.s +</verb></tscreen> + +The <bf/cl65/ utility knows how to translate C files into object files (it will +call the compiler, and then the assembler). It does know also how to create +object files from assembly files (it will call only the assembler, for that). +It knows how to build an executable (it will pass all object files to the +linker). And finally, it has the C64 as a default target, and will supply the +correct startup file and runtime library names to the linker, so you don't +have to care about that. + +The one-liner above should give you a C64 executable named "<tt/hello/" in the +current directory. + +For more information about the compile & link utility, see <url +url="cl65.html">. + + + +<sect>Running The Executable<p> + +<em/Note: this section is incomplete!/ + +Depending on the target, cc65 chooses several methods of making a program +available for execution. Here, we list sample emulators and instructions for +running the program. Unless noted, similar instructions would also apply to a +real machine. One word of advice: we suggest you clear the screen at the +start, and wait for a keypress at the end of your program, as each target +varies in its start and exit conditions. + + +<sect1>Apple + +<sect2>AppleWin<p> +Available at <url +url="http://applewin.berlios.de/">: + +Emulates Apple ][/enhanced Apple //e computers, with +sound, video, joysticks, serial port, and disk images. Includes monitor. Only +for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image; +however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">). + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t apple2 hello.c text.s +</verb></tscreen> +for the Apple ][, or: +<tscreen><verb> +cl65 -O -t apple2enh hello.c text.s +</verb></tscreen> +for the enhanced Apple //e. + +Then, put the file onto an Apple disk image, for use with an emulator. Copy +the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to +<tt/cc65.dsk/, then use <bf/AppleCommander/: + +<tscreen><verb> +java -jar ac.jar -cc65 cc65.dsk test B < hello +</verb></tscreen> + +Note that a convention in the Apple world is that "hello" is the file which is +run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of +the MSDOS/Windows world. We've avoided that in the example, however. Also, +the <tt/B/ parameter must be in caps., and "test" is the name of the program as +it will appear on the Apple disk. + +Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/; +then, click the big Apple logo, to boot the system. Then, type this on the +Apple: + +<tscreen><verb> +BRUN TEST +</verb></tscreen> + +You will see the "Hello, World!" appear on the same line. Thanks to Oliver +Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help +in completing this section. + + +<sect1>Atari + +<sect2>Atari800Win PLus<p> +Available at <url +url="http://www.atari.org.pl/PLus/index_us.htm">: + +Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk +images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM +expansions. Includes monitor. Unfortunately, only for Windows. You will need +the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd" +files (not supplied). + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t atari hello.c text.s +</verb></tscreen> + +Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load +executable/, and point to the "<bf/hello/" executable. It is customary to +rename executables of that type to "<bf/hello.xex/". The file has a 7-byte +header meant to be loaded directly from Atari DOS 2/2.5 or compatibles. + +On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible. +Turn on the computer, type + +<tscreen><verb> +DOS +</verb></tscreen> + +at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/, +then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/. + +The emulation, also, supports that method. Look at <bf/Atari>Settings/, and +check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard +disks/, and set the path of <bf/H1:/ to your executables directory, then use +"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access +your harddrive directly. + +<bf/Note/: There is no delay after the program exits, as you are returned +to the DOS menu. Your C program should wait for a keypress if you want to see +any output. + + +<sect1>Atmos + +<sect2>Oricutron<p> +Available at <url +url="http://code.google.com/p/oriculator/">: + +Emulates Oric-1 and Atmos computers, with sound, disk images, +scanline-exact NTSC/PAL video, and movie export. Includes monitor. +Fortunately for all SDL platforms. You will just need the emulator, all +ROMs are supplied. + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t atmos hello.c text.s -o hello.tap +</verb></tscreen> + +Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to +the "<bf/hello.tap/" executable. The file has an auto start header meant to +be loaded directly from tape. + +On a real Atmos, you would need a tape drive. +Turn on the computer, type + +<tscreen><verb> +CLOAD"" +</verb></tscreen> + +at the BASIC prompt. + +The emulation, also, supports that method. + + +<sect1>Commodore + +<sect2>VICE<p> +Available at <url +url="http://www.viceteam.org/">: + +Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports +printers, serial port and adapters, stereo sound, disk drives and images, RAM +expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, +and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2, +BeOS x86, Acorn RISC OS, and most Unixes. + +Compile the tutorial with +<tscreen><verb> +cl65 -O -t <sys> hello.c text.s +</verb></tscreen> +Substitute the name of a Commodore computer for that <tt/<sys>/: +<itemize> +<item><tt/c128/ +<item><tt/c16/ +<item><tt/c64/ +<item><tt/cbm510/ +<item><tt/cbm610/ +<item><tt/pet/ +<item><tt/plus4/ +<item><tt/vic20/ +</itemize> + +Start the desired version of the emulator (CBM510 and CBM610 programs run on +the CBM II [<tt/xcbm2/] emulator). + +In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape +image...</bf>, choose your executable, and click <bf/OK/. + +In the Unix versions, hold down the mouse's first button. Move the pointer to +<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your +executable, and click <bf/Autostart/. + +The file has a 14-byte header which corresponds to a PRG-format BASIC program, +consisting of a single line, similar to this: + +<tscreen><code> +1000 sys2061 +</code></tscreen> + +On a real Commodore with attached disk drive, you would type: + +<tscreen><verb> +LOAD "0:HELLO",8 +</verb></tscreen> + +for VIC-20/C64, or: + +<tscreen><verb> +DLOAD "HELLO" +</verb></tscreen> + +on PET/CBM II/C128/C16/Plus 4; then, type + +<tscreen><verb> +RUN +</verb></tscreen> + +On a Commodore 128, you can combine those two commands: +<tscreen><verb> +RUN "HELLO" +</verb></tscreen> + +The output will appear on a separate line, and you will be returned to a BASIC +prompt. + + +<sect1>GEOS<p> +Available at <it/Click Here Software's/ <url +url="http://cbmfiles.com/geos/index.html" name="GEOS download section">: + +<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it> +It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User +Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be +controlled by many different types of input devices: +<itemize> +<item>keyboard +<item>joysticks +<item>mice +<item>trackballs +<item>graphics drawing tablets +<item>light-pens +</itemize> + +The tutorial files are different for GEOS. You will find them "next door," in +"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and +"<tt/hello1res.grc/". + +Compile the tutorial with +<tscreen><verb> +cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c +</verb></tscreen> +Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk. + +Boot the GEOS master disk/image. + +<quote> +When you want to run GEOS in an emulator, you must adjust that emulator so that +it does a "true drive" emulation. Each emulator has its own way of turning that +feature on. +</quote> + +<quote> +VICE even has different ways that depend on which operating system is running +the emulator. +<itemize> +<item>In Windows, you must click on <bf/Options/ (in an always visible menu). + Then, you must click on <bf/True drive emulation/. +<item>In Unix, you must <em/hold down/ the second button on your mouse. Move + the pointer down to <bf/Drive settings/. Then, move the pointer over to + <bf/Enable true drive emulation/. (If there is a check-mark in front of + those words, that feature already is turned on -- then, move the pointer + off of that menu.) Release the mouse button. +</itemize> +</quote> + +Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you +should see its icon in the fourth position on the <bf/deskTop/'s directory +notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click +it to run that program. Click on the <bf/Disk/ icon; put the disk with +"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little +icons under the list of file-names to move through that list until you find +"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon. +<bf/CONVERT/ will ask you to confirm that you choose the correct file; click +<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the +program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will +announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list +again. This time, click on <bf/Quit/. + +(You might need to put the boot disk back into the drive, in order to reload +<bf/deskTop/. Then, you must swap back to the disk with the tutorial program +on it, and click on its disk icon [on the right side of the screen].) + +Now, you must find <bf/hello1/. Click on the lower left-hand corner of the +directory notePad. Look at the eight file-positions on each page until you see +<bf/hello1/. Double-click on its icon. + +The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished +reading it. + + +<sect1>Contributions wanted<p> + +We need your help! Recommended emulators and instructions for other targets +are missing. We suggest that you choose emulators with good compatibility. +Also, being able to run all computers in the target series is good for +target compatibility testing. A machine-language monitor is almost essential +for debugging, but a native debugger could be used, as well. + +Finally, emulators which run on Unix or Windows would help to reach a wider +audience. + +</article> diff --git a/doc/ld65.sgml b/doc/ld65.sgml new file mode 100644 index 000000000..5330a21d9 --- /dev/null +++ b/doc/ld65.sgml @@ -0,0 +1,1114 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>ld65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>02.12.2000, 02.10.2001 + +<abstract> +The ld65 linker combines object files into an executable file. ld65 is highly +configurable and uses configuration files for high flexibility. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +The ld65 linker combines several object modules created by the ca65 +assembler, producing an executable file. The object modules may be read +from a library created by the ar65 archiver (this is somewhat faster and +more convenient). The linker was designed to be as flexible as possible. +It complements the features that are built into the ca65 macroassembler: + +<itemize> + +<item> Accept any number of segments to form an executable module. + +<item> Resolve arbitrary expressions stored in the object files. + +<item> In case of errors, use the meta information stored in the object files + to produce helpful error messages. In case of undefined symbols, + expression range errors, or symbol type mismatches, ld65 is able to + tell you the exact location in the original assembler source, where + the symbol was referenced. + +<item> Flexible output. The output of ld65 is highly configurable by a config + file. More common platforms are supported by builtin configurations + that may be activated by naming the target system. The output + generation was designed with different output formats in mind, so + adding other formats shouldn't be a great problem. + +</itemize> + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The linker is called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ld65 [options] module ... +Short options: + -( Start a library group + -) End a library group + -C name Use linker config file + -D sym=val Define a symbol + -L path Specify a library search path + -Ln name Create a VICE label file + -S addr Set the default start address + -V Print the linker version + -h Help (this text) + -m name Create a map file + -o name Name the default output file + -t sys Set the target system + -u sym Force an import of symbol `sym' + -v Verbose mode + -vm Verbose map file + +Long options: + --cfg-path path Specify a config file search path + --config name Use linker config file + --dbgfile name Generate debug information + --define sym=val Define a symbol + --dump-config name Dump a builtin configuration + --end-group End a library group + --force-import sym Force an import of symbol `sym' + --help Help (this text) + --lib file Link this library + --lib-path path Specify a library search path + --mapfile name Create a map file + --module-id id Specify a module id + --obj file Link this object file + --obj-path path Specify an object file search path + --start-addr addr Set the default start address + --start-group Start a library group + --target sys Set the target system + --version Print the linker version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--start-group"> + <tag><tt>-(, --start-group</tt></tag> + + Start a library group. The libraries specified within a group are searched + multiple times to resolve crossreferences within the libraries. Normally, + crossreferences are only resolved within a library, that is the library is + searched multiple times. Libraries specified later on the command line + cannot reference otherwise unreferenced symbols in libraries specified + earlier, because the linker has already handled them. Library groups are + a solution for this problem, because the linker will search repeatedly + through all libraries specified in the group, until all possible open + symbol references have been satisfied. + + + <tag><tt>-), --end-group</tt></tag> + + End a library group. See the explanation of the <tt><ref + id="option--start-group" name="--start-group"></tt> option. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-m"> + <tag><tt>-m name, --mapfile name</tt></tag> + + This option (which needs an argument that will used as a filename for + the generated map file) will cause the linker to generate a map file. + The map file does contain a detailed overview over the modules used, the + sizes for the different segments, and a table containing exported + symbols. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + The -o switch is used to give the name of the default output file. + Depending on your output configuration, this name may NOT be used as + name for the output file. However, for the builtin configurations, this + name is used for the output file name. + + + <label id="option-t"> + <tag><tt>-t sys, --target sys</tt></tag> + + The argument for the -t switch is the name of the target system. Since this + switch will activate a builtin configuration, it may not be used together + with the <tt><ref id="option-C" name="-C"></tt> option. The following target + systems are currently supported: + + <itemize> + <item>none + <item>module + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with memory up to 32K) + <item>c64 + <item>c128 + <item>cbm510 (CBM-II series with 40 column video) + <item>cbm610 (all CBM series-II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>lunix + <item>lynx + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>plus4 + <item>supervision + <item>vic20 + </itemize> + + There are a few more targets defined but neither of them is actually + supported. + + + <tag><tt>-u sym[:addrsize], --force-import sym[:addrsize]</tt></tag> + + Force an import of a symbol. While object files are always linked to the + output file, regardless if there are any references, object modules from + libraries get only linked in if an import can be satisfied by this module. + The <tt/--fore-import/ option may be used to add a reference to a symbol and + as a result force linkage of the module that exports the identifier. + + The name of the symbol may optionally be followed by a colon and an address + size specifier. If no address size is specified, the default address size + for the target machine is used. + + Please note that the symbol name needs to have the internal representation, + meaning you have to prepend an underline for C identifiers. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Using the -v option, you may enable more output that may help you to + locate problems. If an undefined symbol is encountered, -v causes the + linker to print a detailed list of the references (that is, source file + and line) for this symbol. + + + <tag><tt>-vm</tt></tag> + + Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt> + (generate map file). Normally the map file will not include empty segments + and sections, or unreferenced symbols. Using this option, you can force the + linker to include all this information into the map file. + + + <label id="option-C"> + <tag><tt>-C</tt></tag> + + This gives the name of an output config file to use. See section 4 for more + information about config files. -C may not be used together with <tt><ref + id="option-t" name="-t"></tt>. + + + <label id="option-D"> + <tag><tt>-D sym=value, --define sym=value</tt></tag> + + This option allows to define an external symbol on the command line. Value + may start with a '$' sign or with <tt/0x/ for hexadecimal values, + otherwise a leading zero denotes octal values. See also the <ref + id="SYMBOLS" name="SYMBOLS section"> in the configuration file. + + + <label id="option--lib-path"> + <tag><tt>-L path, --lib-path path</tt></tag> + + Specify a library search path. This option may be used more than once. It + adds a directory to the search path for library files. Libraries specified + without a path are searched in current directory, in the directory given in + the <tt/LD65_LIB/ environment variable, and in the list of directories + specified using <tt/--lib-path/. + + + <tag><tt>-Ln</tt></tag> + + This option allows you to create a file that contains all global labels and + may be loaded into VICE emulator using the <tt/ll/ (load label) command. You + may use this to debug your code with VICE. Note: Older versions had some + bugs in the label code. If you have problems, please get the latest VICE + version. + + + <label id="option-S"> + <tag><tt>-S addr, --start-addr addr</tt></tag> + + Using -S you may define the default starting address. If and how this + address is used depends on the config file in use. For the builtin + configurations, only the "none", "apple2" and "apple2enh" systems honor an + explicit start address, all other builtin config provide their own. + + + <tag><tt>-V, --version</tt></tag> + + This option print the version number of the linker. If you send any + suggestions or bugfixes, please include this number. + + + <label id="option--cfg-path"> + <tag><tt>--cfg-path path</tt></tag> + + Specify a config file search path. This option may be used more than once. + It adds a directory to the search path for config files. A config file given + with the <tt><ref id="option-C" name="-C"></tt> option that has no path in + its name is searched in the current directory, in the directory given in the + <tt/LD65_CFG/ environment variable, and in the list of directories specified + using <tt/--cfg-path/. + + + <label id="option--dbgfile"> + <tag><tt>--dbgfile name</tt></tag> + + Specify an output file for debug information. Available information will be + written to this file. Using the <tt/-g/ option for the compiler and assembler + will increase the amount of information available. Please note that debug + information generation is currently being developed, so the format of the + file and its contents are subject to change without further notice. + + + <tag><tt>--lib file</tt></tag> + + Links a library to the output. Use this command line option instead of just + naming the library file, if the linker is not able to determine the file + type because of an unusual extension. + + + <tag><tt>--obj file</tt></tag> + + Links an object file to the output. Use this command line option instead + of just naming the object file, if the linker is not able to determine the + file type because of an unusual extension. + + + <label id="option--obj-path"> + <tag><tt>--obj-path path</tt></tag> + + Specify an object file search path. This option may be used more than once. + It adds a directory to the search path for object files. An object file + passed to the linker that has no path in its name is searched in current + directory, in the directory given in the <tt/LD65_OBJ/ environment variable, + and in the list of directories specified using <tt/--obj-path/. + +</descrip> + + + +<sect>Search paths<p> + +Starting with version 2.10 there are now several search paths for files needed +by the linker: One for libraries, one for object files and one for config +files. + + +<sect1>Library search path<p> + +The library search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_LIB/ if it is defined. +<item>A subdirectory named <tt/lib/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--lib-path" + name="--lib-path"></tt> option on the command line. +</enum> + + +<sect1>Object file search path<p> + +The object file search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined. +<item>A subdirectory named <tt/obj/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--obj-path" + name="--obj-path"></tt> option on the command line. +</enum> + + +<sect1>Config file search path<p> + +The config file search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_CFG/ if it is defined. +<item>A subdirectory named <tt/cfg/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--cfg-path" + name="--cfg-path"></tt> option on the command line. +</enum> + + + +<sect>Detailed workings<p> + +The linker does several things when combining object modules: + +First, the command line is parsed from left to right. For each object file +encountered (object files are recognized by a magic word in the header, so +the linker does not care about the name), imported and exported +identifiers are read from the file and inserted in a table. If a library +name is given (libraries are also recognized by a magic word, there are no +special naming conventions), all modules in the library are checked if an +export from this module would satisfy an import from other modules. All +modules where this is the case are marked. If duplicate identifiers are +found, the linker issues a warning. + +This procedure (parsing and reading from left to right) does mean, that a +library may only satisfy references for object modules (given directly or from +a library) named <em/before/ that library. With the command line + +<tscreen><verb> + ld65 crt0.o clib.lib test.o +</verb></tscreen> + +the module test.o may not contain references to modules in the library +clib.lib. If this is the case, you have to change the order of the modules +on the command line: + +<tscreen><verb> + ld65 crt0.o test.o clib.lib +</verb></tscreen> + +Step two is, to read the configuration file, and assign start addresses +for the segments and define any linker symbols (see <ref id="config-files" +name="Configuration files">). + +After that, the linker is ready to produce an output file. Before doing that, +it checks its data for consistency. That is, it checks for unresolved +externals (if the output format is not relocatable) and for symbol type +mismatches (for example a zero page symbol is imported by a module as absolute +symbol). + +Step four is, to write the actual target files. In this step, the linker will +resolve any expressions contained in the segment data. Circular references are +also detected in this step (a symbol may have a circular reference that goes +unnoticed if the symbol is not used). + +Step five is to output a map file with a detailed list of all modules, +segments and symbols encountered. + +And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch +twice, you get a dump of the segment data. However, this may be quite +unreadable if you're not a developer:-) + + + +<sect>Configuration files<label id="config-files"><p> + +Configuration files are used to describe the layout of the output file(s). Two +major topics are covered in a config file: The memory layout of the target +architecture, and the assignment of segments to memory areas. In addition, +several other attributes may be specified. + +Case is ignored for keywords, that is, section or attribute names, but it is +<em/not/ ignored for names and strings. + + + +<sect1>Memory areas<p> + +Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an +example (this one describes the usable memory layout of the C64): + +<tscreen><verb> + MEMORY { + RAM1: start = $0800, size = $9800; + ROM1: start = $A000, size = $2000; + RAM2: start = $C000, size = $1000; + ROM2: start = $E000, size = $2000; + } +</verb></tscreen> + +As you can see, there are two ram areas and two rom areas. The names +(before the colon) are arbitrary names that must start with a letter, with +the remaining characters being letters or digits. The names of the memory +areas are used when assigning segments. As mentioned above, case is +significant for these names. + +The syntax above is used in all sections of the config file. The name +(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the +semicolon specify attributes for this identifier. You may use the equal sign +to assign values to attributes, and you may use a comma to separate +attributes, you may also leave both out. But you <em/must/ use a semicolon to +mark the end of the attributes for one identifier. The section above may also +have looked like this: + +<tscreen><verb> + # Start of memory section + MEMORY + { + RAM1: + start $0800 + size $9800; + ROM1: + start $A000 + size $2000; + RAM2: + start $C000 + size $1000; + ROM2: + start $E000 + size $2000; + } +</verb></tscreen> + +There are of course more attributes for a memory section than just start and +size. Start and size are mandatory attributes, that means, each memory area +defined <em/must/ have these attributes given (the linker will check that). I +will cover other attributes later. As you may have noticed, I've used a +comment in the example above. Comments start with a hash mark (`#'), the +remainder of the line is ignored if this character is found. + + +<sect1>Segments<p> + +Let's assume you have written a program for your trusty old C64, and you would +like to run it. For testing purposes, it should run in the <tt/RAM/ area. So +we will start to assign segments to memory sections in the <tt/SEGMENTS/ +section: + +<tscreen><verb> + SEGMENTS { + CODE: load = RAM1, type = ro; + RODATA: load = RAM1, type = ro; + DATA: load = RAM1, type = rw; + BSS: load = RAM1, type = bss, define = yes; + } +</verb></tscreen> + +What we are doing here is telling the linker, that all segments go into the +<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So +the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/ +segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/ +segment. Why? Enter the segment type: For each segment specified, you may also +specify a segment attribute. There are four possible segment attributes: + +<tscreen><verb> + ro means readonly + rw means read/write + bss means that this is an uninitialized segment + zp a zeropage segment +</verb></tscreen> + +So, because we specified that the segment with the name BSS is of type bss, +the linker knows that this is uninitialized data, and will not write it to an +output file. This is an important point: For the assembler, the <tt/BSS/ +segment has no special meaning. You specify, which segments have the bss +attribute when linking. This approach is much more flexible than having one +fixed bss segment, and is a result of the design decision to supporting an +arbitrary segment count. + +If you specify "<tt/type = bss/" for a segment, the linker will make sure that +this segment does only contain uninitialized data (that is, zeroes), and issue +a warning if this is not the case. + +For a <tt/bss/ type segment to be useful, it must be cleared somehow by your +program (this happens usually in the startup code - for example the startup +code for cc65 generated programs takes care about that). But how does your +code know, where the segment starts, and how big it is? The linker is able to +give that information, but you must request it. This is, what we're doing with +the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each +segment, where this attribute is true, the linker will export three symbols. + +<tscreen><verb> + __NAME_LOAD__ This is set to the address where the + segment is loaded. + __NAME_RUN__ This is set to the run address of the + segment. We will cover run addresses + later. + __NAME_SIZE__ This is set to the segment size. +</verb></tscreen> + +Replace <tt/NAME/ by the name of the segment, in the example above, this would +be <tt/BSS/. These symbols may be accessed by your code. + +Now, as we've configured the linker to write the first three segments and +create symbols for the last one, there's only one question left: Where does +the linker put the data? It would be very convenient to have the data in a +file, wouldn't it? + +<sect1>Output files<p> + +We don't have any files specified above, and indeed, this is not needed in a +simple configuration like the one above. There is an additional attribute +"file" that may be specified for a memory area, that gives a file name to +write the area data into. If there is no file name given, the linker will +assign the default file name. This is "a.out" or the one given with the +<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the +default behaviour is ok for our purposes, I did not use the attribute in the +example above. Let's have a look at it now. + +The "file" attribute (the keyword may also be written as "FILE" if you like +that better) takes a string enclosed in double quotes (`"') that specifies the +file, where the data is written. You may specify the same file several times, +in that case the data for all memory areas having this file name is written +into this file, in the order of the memory areas defined in the <tt/MEMORY/ +section. Let's specify some file names in the <tt/MEMORY/ section used above: + +<tscreen><verb> + MEMORY { + RAM1: start = $0800, size = $9800, file = %O; + ROM1: start = $A000, size = $2000, file = "rom1.bin"; + RAM2: start = $C000, size = $1000, file = %O; + ROM2: start = $E000, size = $2000, file = "rom2.bin"; + } +</verb></tscreen> + +The <tt/%O/ used here is a way to specify the default behaviour explicitly: +<tt/%O/ is replaced by a string (including the quotes) that contains the +default output name, that is, "a.out" or the name specified with the <tt><ref +id="option-o" name="-o"></tt> option on the command line. Into this file, the +linker will first write any segments that go into <tt/RAM1/, and will append +then the segments for <tt/RAM2/, because the memory areas are given in this +order. So, for the RAM areas, nothing has really changed. + +We've not used the ROM areas, but we will do that below, so we give the file +names here. Segments that go into <tt/ROM1/ will be written to a file named +"rom1.bin", and segments that go into <tt/ROM2/ will be written to a file +named "rom2.bin". The name given on the command line is ignored in both cases. + +Assigning an empty file name for a memory area will discard the data written +to it. This is useful, if the memory area has segments assigned that are empty +(for example because they are of type bss). In that case, the linker will +create an empty output file. This may be suppressed by assigning an empty file +name to that memory area. + +The <tt/%O/ sequence is also allowed inside a string. So using + +<tscreen><verb> + MEMORY { + ROM1: start = $A000, size = $2000, file = "%O-1.bin"; + ROM2: start = $E000, size = $2000, file = "%O-2.bin"; + } +</verb></tscreen> + +would write two files that start with the name of the output file specified on +the command line, with "-1.bin" and "-2.bin" appended respectively. Because +'%' is used as an escape char, the sequence "%%" has to be used if a single +percent sign is required. + +<sect1>LOAD and RUN addresses (ROMable code)<p> + +Let us look now at a more complex example. Say, you've successfully tested +your new "Super Operating System" (SOS for short) for the C64, and you +will now go and replace the ROMs by your own code. When doing that, you +face a new problem: If the code runs in RAM, we need not to care about +read/write data. But now, if the code is in ROM, we must care about it. +Remember the default segments (you may of course specify your own): + +<tscreen><verb> + CODE read only code + RODATA read only data + DATA read/write data + BSS uninitialized data, read/write +</verb></tscreen> + +Since <tt/BSS/ is not initialized, we must not care about it now, but what +about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was +explicitly assigned a value. And your program will rely on these values on +startup. Since there's no other way to remember the contents of the data +segment, than storing it into one of the ROMs, we have to put it there. But +unfortunately, ROM is not writable, so we have to copy it into RAM before +running the actual code. + +The linker won't copy the data from ROM into RAM for you (this must be done by +the startup code of your program), but it has some features that will help you +in this process. + +First, you may not only specify a "<tt/load/" attribute for a segment, but +also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if +you don't specify a "<tt/run/" attribute, the linker assumes that load area +and run area are the same. We will use this feature for our data area: + +<tscreen><verb> + SEGMENTS { + CODE: load = ROM1, type = ro; + RODATA: load = ROM2, type = ro; + DATA: load = ROM2, run = RAM2, type = rw, define = yes; + BSS: load = RAM2, type = bss, define = yes; + } +</verb></tscreen> + +Let's have a closer look at this <tt/SEGMENTS/ section. We specify that the +<tt/CODE/ segment goes into <tt/ROM1/ (the one at $A000). The readonly data +goes into <tt/ROM2/. Read/write data will be loaded into <tt/ROM2/ but is run +in <tt/RAM2/. That means that all references to labels in the <tt/DATA/ +segment are relocated to be in <tt/RAM2/, but the segment is written to +<tt/ROM2/. All your startup code has to do is, to copy the data from its +location in <tt/ROM2/ to the final location in <tt/RAM2/. + +So, how do you know, where the data is located? This is the second point, +where you get help from the linker. Remember the "<tt/define/" attribute? +Since we have set this attribute to true, the linker will define three +external symbols for the data segment that may be accessed from your code: + +<tscreen><verb> + __DATA_LOAD__ This is set to the address where the segment + is loaded, in this case, it is an address in + ROM2. + __DATA_RUN__ This is set to the run address of the segment, + in this case, it is an address in RAM2. + __DATA_SIZE__ This is set to the segment size. +</verb></tscreen> + +So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from +<tt/__DATA_LOAD__/ to <tt/__DATA_RUN__/ before any other routines are called. +All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/ +by the linker, so things will work properly. + +There's a library subroutine called <tt/copydata/ (in a module named +<tt/copydata.s/) that might be used to do actual copying. Be sure to have a +look at it's inner workings before using it! + + +<sect1>Other MEMORY area attributes<p> + +There are some other attributes not covered above. Before starting the +reference section, I will discuss the remaining things here. + +You may request symbols definitions also for memory areas. This may be +useful for things like a software stack, or an i/o area. + +<tscreen><verb> + MEMORY { + STACK: start = $C000, size = $1000, define = yes; + } +</verb></tscreen> + +This will define some external symbols that may be used in your code: + +<tscreen><verb> + __STACK_START__ This is set to the start of the memory + area, $C000 in this example. + __STACK_SIZE__ The size of the area, here $1000. + __STACK_LAST__ This is NOT the same as START+SIZE. + Instead, it it defined as the first + address that is not used by data. If we + don't define any segments for this area, + the value will be the same as START. + __STACK_FILEOFFS__ The binary offset in the output file. This + is not defined for relocatable output file + formats (o65). +</verb></tscreen> + +A memory section may also have a type. Valid types are + +<tscreen><verb> + ro for readonly memory + rw for read/write memory. +</verb></tscreen> + +The linker will assure, that no segment marked as read/write or bss is put +into a memory area that is marked as readonly. + +Unused memory in a memory area may be filled. Use the "<tt/fill = yes/" +attribute to request this. The default value to fill unused space is zero. If +you don't like this, you may specify a byte value that is used to fill these +areas with the "<tt/fillval/" attribute. If there is no "<tt/fillval/" +attribute for the segment, the "<tt/fillval/" attribute of the memory area (or +its default) is used instead. This means that the value may also be used to +fill unfilled areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ +directives. + +The symbol <tt/%S/ may be used to access the default start address (that is, +the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the +value given on the command line with the <tt><ref id="option-S" name="-S"></tt> +option). + +To support systems with banked memory, a special attribute named <tt/bank/ is +available. The attribute value is an arbitrary 32 bit integer. The assembler +has a builtin function named <tt/.BANK/ which may be used with an argument +that has a segment reference (for example a symbol). The result of this +function is the value of the bank attribute for the run memory area of the +segment. + + +<sect1>Other SEGMENT attributes<p> + +Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to +request this feature. Num must be a power of two. To align all segments on a +page boundary, use + +<tscreen><verb> + SEGMENTS { + CODE: load = ROM1, type = ro, align = $100; + RODATA: load = ROM2, type = ro, align = $100; + DATA: load = ROM2, run = RAM2, type = rw, define = yes, + align = $100; + BSS: load = RAM2, type = bss, define = yes, align = $100; + } +</verb></tscreen> + +If an alignment is requested, the linker will add enough space to the output +file, so that the new segment starts at an address that is dividable by the +given number without a remainder. All addresses are adjusted accordingly. To +fill the unused space, bytes of zero are used, or, if the memory area has a +"<tt/fillval/" attribute, that value. Alignment is always needed, if you have +used the <tt/.ALIGN/ command in the assembler. The alignment of a segment +must be equal or greater than the alignment used in the <tt/.ALIGN/ command. +The linker will check that, and issue a warning, if the alignment of a segment +is lower than the alignment requested in an <tt/.ALIGN/ command of one of the +modules making up this segment. + +For a given segment you may also specify a fixed offset into a memory area or +a fixed start address. Use this if you want the code to run at a specific +address (a prominent case is the interrupt vector table which must go at +address $FFFA). Only one of <tt/ALIGN/ or <tt/OFFSET/ or <tt/START/ may be +specified. If the directive creates empty space, it will be filled with zero, +of with the value specified with the "<tt/fillval/" attribute if one is given. +The linker will warn you if it is not possible to put the code at the +specified offset (this may happen if other segments in this area are too +large). Here's an example: + +<tscreen><verb> + SEGMENTS { + VECTORS: load = ROM2, type = ro, start = $FFFA; + } +</verb></tscreen> + +or (for the segment definitions from above) + +<tscreen><verb> + SEGMENTS { + VECTORS: load = ROM2, type = ro, offset = $1FFA; + } +</verb></tscreen> + +The "<tt/align/", "<tt/start/" and "<tt/offset/" attributes change placement +of the segment in the run memory area, because this is what is usually +desired. If load and run memory areas are equal (which is the case if only the +load memory area has been specified), the attributes will also work. There is +also an "<tt/align_load/" attribute that may be used to align the start of the +segment in the load memory area, in case different load and run areas have +been specified. There are no special attributes to set start or offset for +just the load memory area. + +A "<tt/fillval/" attribute may not only be specified for a memory area, but +also for a segment. The value must be an integer between 0 and 255. It is used +as fill value for space reserved by the assemblers <tt/.ALIGN/ and <tt/.RES/ +commands. It is also used as fill value for space between sections (part of a +segment that comes from one object file) caused by alignment, but not for +space that preceeds the first section. + +To suppress the warning, the linker issues if it encounters a segment that is +not found in any of the input files, use "<tt/optional=yes/" as additional +segment attribute. Be careful when using this attribute, because a missing +segment may be a sign of a problem, and if you're suppressing the warning, +there is no one left to tell you about it. + +<sect1>The FILES section<p> + +The <tt/FILES/ section is used to support other formats than straight binary +(which is the default, so binary output files do not need an explicit entry +in the <tt/FILES/ section). + +The <tt/FILES/ section lists output files and as only attribute the format of +each output file. Assigning binary format to the default output file would +look like this: + +<tscreen><verb> + FILES { + %O: format = bin; + } +</verb></tscreen> + +The only other available output format is the o65 format specified by Andre +Fachat (see the <htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" +name="6502 binary relocation format specification">). It is defined like this: + +<tscreen><verb> + FILES { + %O: format = o65; + } +</verb></tscreen> + +The necessary o65 attributes are defined in a special section labeled +<tt/FORMAT/. + + + +<sect1>The FORMAT section<p> + +The <tt/FORMAT/ section is used to describe file formats. The default (binary) +format has currently no attributes, so, while it may be listed in this +section, the attribute list is empty. The second supported format, +<htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65">, +has several attributes that may be defined here. + +<tscreen><verb> + FORMATS { + o65: os = lunix, version = 0, type = small, + import = LUNIXKERNEL, + export = _main; + } +</verb></tscreen> + + + +<sect1>The FEATURES section<label id="FEATURES"><p> + +In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the +linker has features that may be enabled by an additional section labeled +<tt/FEATURES/. + + +<sect2>The CONDES feature<p> + +<tt/CONDES/ is used to tell the linker to emit module constructor/destructor +tables. + +<tscreen><verb> + FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + } +</verb></tscreen> + +The <tt/CONDES/ feature has several attributes: + +<descrip> + + <tag><tt>segment</tt></tag> + + This attribute tells the linker into which segment the table should be + placed. If the segment does not exist, it is created. + + + <tag><tt>type</tt></tag> + + Describes the type of the routines to place in the table. Type may be one of + the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or + a numeric value between 0 and 6. + + + <tag><tt>label</tt></tag> + + This specifies the label to use for the table. The label points to the start + of the table in memory and may be used from within user written code. + + + <tag><tt>count</tt></tag> + + This is an optional attribute. If specified, an additional symbol is defined + by the linker using the given name. The value of this symbol is the number + of entries (<em/not/ bytes) in the table. While this attribute is optional, + it is often useful to define it. + + + <tag><tt>order</tt></tag> + + Optional attribute that takes one of the keywords <tt/increasing/ or + <tt/decreasing/ as an argument. Specifies the sorting order of the entries + within the table. The default is <tt/increasing/, which means that the + entries are sorted with increasing priority (the first entry has the lowest + priority). "Priority" is the priority specified when declaring a symbol as + <tt/.CONDES/ with the assembler, higher values mean higher priority. You may + change this behaviour by specifying <tt/decreasing/ as the argument, the + order of entries is reversed in this case. + + Please note that the order of entries with equal priority is undefined. + + <tag><tt>import</tt></tag> + + This attribute defines a valid symbol name, that is added as an import + to the modules defining a constructor/desctructor of the given type. + This can be used to force linkage of a module if this module exports the + requested symbol. + +</descrip> + +Without specifying the <tt/CONDES/ feature, the linker will not create any +tables, even if there are <tt/condes/ entries in the object files. + +For more information see the <tt/.CONDES/ command in the <htmlurl +url="ca65.html" name="ca65 manual">. + + +<sect2>The STARTADDRESS feature<p> + +<tt/STARTADDRESS/ is used to set the default value for the start address, +which can be referenced by the <tt/%S/ symbol. The builtin default for the +linker is $200. + +<tscreen><verb> + FEATURES { + # Default start address is $1000 + STARTADDRESS: default = $1000; + } +</verb></tscreen> + +Please note that order is important: The default start address must be defined +<em/before/ the <tt/%S/ symbol is used in the config file. This does usually +mean, that the <tt/FEATURES/ section has to go to the top of the config file. + + + +<sect1>The SYMBOLS section<label id="SYMBOLS"><p> + +The configuration file may also be used to define symbols used in the link +stage or to force symbols imports. This is done in the SYMBOLS section. The +symbol name is followed by a colon and symbol attributes. + +The following symbol attributes are supported: + +<descrip> + + <tag><tt>addrsize</tt></tag> + + The <tt/addrsize/ attribute specifies the address size of the symbol and + may be one of +<itemize> + <item><tt/zp/, <tt/zeropage/ or <tt/direct/ + <item><tt/abs/, <tt/absolute/ or <tt/near/ + <item><tt/far/ + <item><tt/long/ or <tt/dword/. +</itemize> + +Without this attribute, the default address size is <tt/abs/. + + <tag><tt>type</tt></tag> + + This attribute is mandatory. Its value is one of <tt/export/, <tt/import/ or + <tt/weak/. <tt/export/ means that the symbol is defined and exported from + the linker config. <tt/import/ means that an import is generated for this + symbol, eventually forcing a module that exports this symbol to be included + in the output. <tt/weak/ is similar as <tt/export/. However, the symbol is + only defined if it is not defined elsewhere. + + <tag><tt>value</tt></tag> + + This must only be given for symbols of type <tt/export/ or <tt/weak/. It + defines the value of the symbol and may be an expression. + +</descrip> + +The following example defines the stack size for an application, but allows +the programmer to override the value by specifying <tt/--define +__STACKSIZE__=xxx/ on the command line. + +<tscreen><verb> + SYMBOLS { + # Define the stack size for the application + __STACKSIZE__: type = weak, value = $800; + } +</verb></tscreen> + + + +<sect1>Builtin configurations<p> + +The builtin configurations are part of the linker source. They can be retrieved +with <tt/--dump-config/ and don't have a special format. So if you need a +special configuration, it's a good idea to start with the builtin configuration +for your system. In a first step, just replace <tt/-t target/ by <tt/-C +configfile/. Then go on and modify the config file to suit your needs. + + + +<sect1>Secondary configurations<p> + +Several machine specific binary packages are distributed together with secondary +configurations (in the cfg directory). These configurations can be used with +<tt/-C configfile/ too. + + + +<sect>Special segments<p> + +The builtin config files do contain segments that have a special meaning for +the compiler and the libraries that come with it. If you replace the builtin +config files, you will need the following information. + +<sect1>INIT<p> + +The INIT segment is used for initialization code that may be reused once +execution reaches main() - provided that the program runs in RAM. You +may for example add the INIT segment to the heap in really memory +constrained systems. + +<sect1>LOWCODE<p> + +For the LOWCODE segment, it is guaranteed that it won't be banked out, so it +is reachable at any time by interrupt handlers or similar. + +<sect1>STARTUP<p> + +This segment contains the startup code which initializes the C software stack +and the libraries. It is placed in its own segment because it needs to be +loaded at the lowest possible program address on several platforms. + +<sect1>ZPSAVE<p> + +The ZPSAVE segment contains the original values of the zeropage locations used +by the ZEROPAGE segment. It is placed in its own segment because it must not be +initialized. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the linker, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> diff --git a/doc/library.sgml b/doc/library.sgml new file mode 100644 index 000000000..29a8ca063 --- /dev/null +++ b/doc/library.sgml @@ -0,0 +1,251 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Library Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-12-02, 2002-11-26 + +<abstract> +An overview over the runtime and C libraries that come with the cc65 compiler, +including a discussion of the differences to the ISO standard. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains a short overview of the libraries available for the cc65 C +compiler. Please have a look at the <htmlurl url="funcref.html" name="function +reference"> for a list function by function. Since the function reference is +not complete (I'm working on that) it may happen that you don't find a +specific function. In this case, have a look into the header files. All +functions, that are not defined by the ISO C standard have a short comment in +the headers, explaining their use. + + + +<sect>ISO C compatible library<p> + +The C library contains a large subset of the ISO C library. Functions are +usually missing in areas, where there is no support on typical 6502 systems. +Wide character sets are an example for this. + +I will not go into detail about the ISO functions. If a function is not +mentioned here explicitly, expect it to be available and to behave as defined +in the C standard. + +Functions that are <em/not/ available: + +<itemize> + <item><tt>tmpfile/tmpnam</tt> + <p> + <item><tt>system</tt> + <p> + <item>All functions that handle floating point numbers in some manner. + <p> + <item>The <tt/ldiv/ function (cc65 is currently not able to return structs + with a size not equal to 1, 2 or 4 bytes by value). + <p> + <item>All functions handling wide character strings. + <p> + <item>Signals and all related functions (having <tt/SIGSEGV/ would be + cool:-) + <p> + <item><tt>setbuf/setvbuf</tt> +</itemize> + +Functions not available on all supported systems: + +<itemize> + <item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions + are built on open/read/write/close. These latter functions are not available + on all systems. + <p> + <item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the + capabilities of the target machine. + <p> + <item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of + the target machine. + <p> + <item><tt>time</tt>: Since many of the supported systems do not have a real + time clock, which means that the <tt/time/ function is not available. Please + note that the other functions from <tt/time.h/ <em/are/ available. +</itemize> + + +Functions that are limited in any way: + +<itemize> + <item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length + limitation of 256 for the second string argument. Since this string gives a + character set, and there are only 256 distinct characters, this shouldn't be + a problem. + <p> + <item><tt>getenv</tt>: Since there is no such thing as an environment on all + supported systems, the <tt/getenv/ function will always return a <tt/NULL/ + pointer. + <p> + <item><tt>locale</tt>: There is no other locale than the "C" locale. The + native locale is identical to the "C" locale. +</itemize> + + +In addition to these limitations, some more functions are limited if inlined +versions are requested by using -Os: + +<itemize> + <item>The <tt/strlen/ function only works for strings with a maximum length + of 255 characters. + <p> + <item>The <tt/isxxx/ character classification functions from + <tt/<ctype.h>/ will give unpredictable results if the argument is not + in character range (0..255). This limitation may be removed by #undef'ing + the function name (when using <tt/-Os/, the functions are actually macros + that expand to inline assembler code, but the real functions are still + available if the macro definition is removed). +</itemize> + + + +<sect>CPU specific stuff - 6502.h<p> + +The header file 6502.h contains some functions that make only sense with the +6502 CPU. Examples are macros to insert more or less useful instructions into +your C code, or a function to call arbitrary machine language subroutines, +passing registers in and out. + + + +<sect>Target specific stuff<p> + +For each supported system there's a header file that contains calls or defines +specific for this system. So, when programming for the C64, include c64.h, for +the C128, include c128.h and so on. To make the task for the Commodore systems +easier, there is also a header file named cbm.h that will define stuff common +for all CBM systems, and include the header file for the specific target +system. + +The header files contain + +<itemize> + + <item>Defines for special keys (like function keys) + + <item>Defines for special characters (like the graphics characters) + + <item>Variables with a fixed address in memory that may be used to access + special hardware. For the C64 and C128 there is a variable struct named + <tt/SID/. Writing to the fields of this struct will write to the SID device + instead. Using these variables will make your program more readable and more + portable. Don't fear ineffective code when using these variables, the + compiler will translate reads and writes to these structs into direct memory + accesses. + + <item>Other routines that make only sense for a specific system. One example + are routines to write memory locations in the system bank for the CBM PET-II + family. + +</itemize> + + +<sect>Direct console I/O - <tt/conio.h/<p> + +The <tt/conio.h/ header file contains a large set of functions that do screen +and keyboard I/O. The functions will write directly to the screen or poll the +keyboard directly with no more help from the operating system than needed. +This has some disadvantages, but on the other side it's fast and reasonably +portable. conio implementations exist for the following targets: + + <itemize> + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with up to 32K memory) + <item>c64 + <item>c128 + <item>plus4 (or expanded c16/c116) + <item>cbm510 (40 column video) + <item>cbm610 (all CBM series-II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>vic20 + </itemize> + +The conio.h header file does also include the system specific header files +which define constants for special characters and keys. + + + +<sect>Using the joystick - <tt/joystick.h/<p> + +For systems that have a joystick, <tt/joystick.h/ will define a subroutine to +read the current value, including constants to evaluate the result of this +function. To help in writing portable code, the header file will define the +symbol <tt/__JOYSTICK__/ on systems that have a joystick. + + + +<sect>Using a mouse - <tt/mouse.h/<p> + +Some target machines support a mouse. Mouse support is currently available for +the following targets: + + <itemize> + <item>apple2 + <item>apple2enh + <item>atari + <item>c64 + <item>c128 + <item>cbm510 + </itemize> + +The available functions are declared in <tt/mouse.h/ To help writing portable +code, the header file will define the symbol <tt/__MOUSE__/ in systems that +support a mouse. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +This C runtime library implementation for the cc65 compiler is (C) +Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries +and/or sources the following conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/lynx.sgml b/doc/lynx.sgml new file mode 100644 index 000000000..48c3d7d4a --- /dev/null +++ b/doc/lynx.sgml @@ -0,0 +1,360 @@ +<!doctype linuxdoc system> + +<article> + +<title>Atari Lynx specific information for cc65 +<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi"> +Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2011-04-01 + +<abstract> +An overview over the Atari Lynx runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atari Lynx runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Lynx specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that Lynx specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Building your first Hello World application<p> + +Here is a small traditional Hello World program for the Atari Lynx. + +<tscreen><verb> +#include <lynx.h> +#include <tgi.h> +#include <6502.h> + +void main(void) { + tgi_install(tgi_static_stddrv); + tgi_init(); + CLI(); + while (tgi_busy()) + ; + tgi_clear(); + tgi_setcolor(COLOR_GREEN); + tgi_outtextxy(0, 0, "Hello World"); + tgi_updatedisplay(); + while (1) + ; +} +</verb></tscreen> + +The lynx.h contains all kind of system dependent things. + +The tgi.h contains the graphics driver functions. + +The 6502.h is needed for executing the CLI() command. + +As the Atari Lynx does not have ASCII characters available you need to use +the Tiny Graphics Interface library for producing letters on the screen. + +The cc65 compiler suite has a graphics library called "Tiny Graphics +Interface". This interface has some relocatable code. In order to use this +in your own program you need to load it at run time. + +Unfortunately the Lynx does not have a disk drive from where to load it. +Therefore you must already load it at compile time. The easiest way is to +automatically link it in statically from the Lynx C library. + +<tscreen><verb> +cl65 -t lynx -o game.lnx main.c +</verb></tscreen> + +This will create a bootable cart image called game.lnx + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Lynx target +is a cart image. By specifying the config file lynx-bll.cfg the linker will +generate BLL download compatible binary files. + +It is of course possible to change this behaviour by using a modified startup +file and linker config. + +The bootloader used in the cc65 lynx library uses a very minimal bootloader +that does not check the cart or show a title screen. + +The advantage of this bootloader is that it allows creation of cart images to +many common formats. + +Cart sizes +<tscreen><verb> +Block size Rom size Description +512 bytes 128k Standard old games like Warbirds +1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings +2048 bytes 512k Largest games like EOTB +</verb></tscreen> + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal enabled, which gives a usable memory range of $200 - $C037. + +Special locations: +<tscreen><verb> + 0000 - 00FF Zero page + 0100 - 01FF Machine stack + + A058 - C037 Collision buffer + C038 - E017 Screen buffer 1 + E018 - FFF7 Screen buffer 0 + FFF8 - FFFF Hardware vectors +</verb></tscreen> + +<descrip> + <tag/Text screen/ + No conio support is currently available for the Lynx. + + <tag/Keyboard/ + The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the + conio interface. The only characters the keyboard is able to produce are + 'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause), + 'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and + '?' for all keys down at the same time. + + <tag/Stack/ + The C runtime stack is located at $C037 (or $A057 if collision + detection is enabled) and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + + <tag/Screen/ + The collision detection screen is at $A058 if it is enabled. The + double buffered screens are at $C038 and $E018. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Lynx specific code may use the <tt/lynx.h/ header file. + + +<sect1>Lynx specific functions<p> + +<itemize> +<item>lynx_eeprom_erase +<item>lynx_eeprom_read +<item>lynx_eeprom_write +<item>lynx_eeread +<item>lynx_eewrite +<item>lynx_exec +<item>lynx_load +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/lynx.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/MIKEY/</tag> + The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/ + header file located in the include directory for the declaration of the + structure. + + <tag><tt/SUZY/</tag> + The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/ + header file located in the include directory for the declaration of the + structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16)/</tag> + A TGI driver for the standard graphics mode (160×102 in 16 colors). + + The TGI driver is implemented as an interrupt driven dual buffering device. + To use it as a single-buffer device set draw page and view page to the same + value 0 or 1; + + The TGI driver has a few Lynx-specific extensions. + + Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx + sprite on screen. + + Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen. + + Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text + background color to the index defined by bgindex. If bgindex is 0 then the + background color is transparent. + + To set the framerate of the display hardware call tgi_setframerate(rate) or + tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per + second. Actually there is no real reason to use anything else than 75 frames + per second. + + To check if the drawing engine is busy with the previous swap you can + call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy + + To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it + will wait for the next VBL interrupt and set the draw buffer to the + view buffer. The draw buffer is also changed to (drawbuffer xor 1). + + You can also enable or disable collision detection by a call to + tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision + result is located before the sprite structure by default in this driver. + + In order to reserve memory for the collision detection buffer you need to + specify lynx-coll.cfg as the configuration file to the linker. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Lynx. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag> + A joystick driver for the standard buttons. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Lynx. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag> + A serial driver for the ComLynx port. + + The ComLynx port has Tx and Rx wired together. Every byte is sent + to all connected Lynxes. Only one Lynx can send at a time. There is no + protocol created for communication. You are on your own. + + If the Lynx returns framing error then it is likely that another Lynx is + sending data at the same time. + + The Lynx can also send a break and receive a break. The Lynx break is + recognized if the bit is down for 24 bit cycles or more. + + To send a break you just set the break bit. The length of the break depends + on how long this bit is down. + + The driver supports the baudrates: + <itemize> + <item>62500 + <item>31250 + <item>9600 + <item>7200 + <item>4800 + <item>3600 + <item>2400 + <item>1800 + <item>1200 + <item>600 + <item>300 + <item>150 + <item>134.5 + <item>110 + <item>75 + </itemize> + The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity + but the parity bit is included in the calculation. Most of us don't want it + this way. But there is nothing we can do about it. + + The Lynx hardware will always check parity on incoming traffic. Currently + the driver cannot receive data from standard PC's due to this parity bug. + For working with Lynx to Lynx communication use EVEN parity. + + To send data to standard PC's use MARK or SPACE as parity setting. + + There is always only one stop bit. And the data length is always 8 bits. + + We have no handshaking available. Even software handshake is impossible + as ComLynx has only one wire for the data. + + Both transmit and receive are interrupt driven. + +</descrip><p> + + +<sect>Limitations<p> + + + +<sect>Cart access<p> + +At this point in time there is no support for the cart filesystem yet. I have +a <tt/lynx-cart-demo/ example project that uses an interrupt driven display, +has support for the cart filesystem and an abcmusic sound module. + +At some point in time we may find a way to rewrite these to fit the way the +cc65 drivers require. But for the time being you can create less portable +applications using these Lynx specific modules in <tt/lynx-cart-demo/. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/nes.sgml b/doc/nes.sgml new file mode 100644 index 000000000..c66b1f2ba --- /dev/null +++ b/doc/nes.sgml @@ -0,0 +1,197 @@ +<!doctype linuxdoc system> + +<article> + +<title>Nintendo Entertainment System specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-07-17 + +<abstract> +An overview over the NES runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the NES runtime system as it comes +with the cc65 C compiler. It describes the memory layout, NES specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that NES specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the NES target +is a machine language program with an INES cartridge header. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and a +CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. +All boot ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at VRAM $2000. + + <tag/Stack/ + The C runtime stack is located at $7FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing NES specific code may use the <tt/nes.h/ header file. + + +<sect1>NES specific functions<p> + +<itemize> +<item>waitvblank +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/nes.inc/ include file do +allow access to hardware located in the address space. + +<descrip> + + <tag><tt/PPU/</tag> + The <tt/PPU/ defines allow access to the PPU chip. + + <tag><tt/APU/</tag> + The <tt/APU/ defines allow access to the APU chip. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +All drivers must be statically linked because no file I/O is available. +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/nes-64-56-2.tgi (nes_64_56_2)/</tag> + This driver features a resolution of 64×56 with 2 colors using the + CHR bank. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the NES. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/nes-stdjoy.joy (nes_stdjoy)/</tag> + A joystick driver for the standard four buttons joypad is available. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the NES. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the NES. + + + +<sect>Limitations<p> + +<sect1>Disk I/O<p> + +The existing library for the NES doesn't implement C file +I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/od65.sgml b/doc/od65.sgml new file mode 100644 index 000000000..2668b0b86 --- /dev/null +++ b/doc/od65.sgml @@ -0,0 +1,224 @@ +<!doctype linuxdoc system> + +<article> +<title>od65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2010-07-30 + +<abstract> +od65 is the object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +od65 is an object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +Since the contents and format of the object files are not documented +elsewhere and may change at any time, this tool is a portable way to look at +the contents. + +Apart from curiosity, most people don't need to use this tool. + + + +<sect>Usage<p> + +The od65 utility dumps contents of one or more ca65 generated object file to +standard output. It has no cross-version compatibility, so you have to use +a version that matches the version of ca65 used to create the object files. + + +<sect1>Command line option overview<p> + +The program may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: od65 [options] file [options] [file] +Short options: + -h Help (this text) + -H Dump the object file header + -S Dump segments sizes + -V Print the version number and exit + +Long options: + --dump-all Dump all object file information + --dump-dbgsyms Dump debug symbols + --dump-exports Dump exported symbols + --dump-files Dump the source files + --dump-header Dump the object file header + --dump-imports Dump imported symbols + --dump-lineinfo Dump line information + --dump-options Dump object file options + --dump-segments Dump the segments in the file + --dump-segsize Dump segments sizes + --help Help (this text) + --version Print the version number and exit +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<label id="cmdline-opt-detail"><p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--dump-all</tt></tag> + + This will output all information, od65 is able to process. The option is a + shortcut for specifying all the other <tt/--dump/ options. + + + <tag><tt>--dump-dbgsyms</tt></tag> + + Dump all debug symbols contained in the object file. + + + <tag><tt>--dump-exports</tt></tag> + + Dump all exported symbols contained in the object file. + + + <tag><tt>--dump-files</tt></tag> + + Dump the file table contained in the object file. + + + <tag><tt>-H, --dump-header</tt></tag> + + Dump the object file header. + + + <tag><tt>--dump-imports</tt></tag> + + Dump the list of imported symbols contained in the object file. + + + <tag><tt>--dump-lineinfo</tt></tag> + + Dump the line info contained in the object file. + + + <tag><tt>--dump-segments</tt></tag> + + Dump the list of segments contained in the object file. + + + <tag><tt>--dump-scopes</tt></tag> + + Dump the scope (lexical level) information contained in the object file. + + + <tag><tt>-S, --dump-segsize</tt></tag> + + Dump the sizes of all segments contained in the object file. This option is + quite useful to determine the effect of measures that increase or decrease + code size. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. +</descrip> + + +<sect>Input and output<p> + +The converter will read one or more object files per invocation and write the +contents in readable format to standard output. Please note that you need to +specify any of the <tt/--dump/ options listed <ref id="cmdline-opt-detail" +name="above">, otherwise no useful output will be generated. + +Example output for the command +<tscreen><verb> +od65 --dump-header --dump-files t.o +</verb></tscreen> +<tscreen><verb> +t.o: + Header: + Magic: 0x616E7A55 + Version: 12 + Flags: 0x0001 (OBJ_FLAGS_DBGINFO) + Options: + Offset: 88 + Size: 9 + Files: + Offset: 97 + Size: 10 + Segments: + Offset: 107 + Size: 101 + Imports: + Offset: 208 + Size: 1 + Exports: + Offset: 209 + Size: 1 + Debug symbols: + Offset: 210 + Size: 55 + Line infos: + Offset: 265 + Size: 1 + String pool: + Offset: 266 + Size: 80 + Files: + Count: 1 + Index: 0 + Name: "t.s" + Size: 402 + Modification time: 1280498435 (Fri Jul 30 16:00:35 2010) +</verb></tscreen> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the code, I would be glad to hear from you. +Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the +binaries and/or sources the following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/pet.sgml b/doc/pet.sgml new file mode 100644 index 000000000..35e794db5 --- /dev/null +++ b/doc/pet.sgml @@ -0,0 +1,261 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore PET specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-05-24 + +<abstract> +An overview over the PET runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the PET runtime system as it comes with the +cc65 C compiler. It describes the memory layout, PET specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that PET specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the PET target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal and BASIC ROM enabled, which gives a usable memory range of +$0400 - $7FFF (32KB machine). +All ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $8000. + + <tag/Stack/ + The C runtime stack is located at $7FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing PET specific code may use the <tt/pet.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/pet.h/ and declares several functions +common to all CBM platforms. + + +<sect1>PET specific functions<p> + +There are currently no special PET functions. + + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/pet.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/PIA1, PIA2/</tag> + Access to the two PIA (peripheral interface adapter) chips is available via + the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables + is explained in <tt/_pia.h/. + + <tag><tt/VIA/</tag> + The <tt/VIA/ structure allows access to the VIA (versatile interface + adapter). See the <tt/_6522.h/ header file located in the include + directory for the declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the PET. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the PET. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/pet-ptvjoy.joy (pet_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to two joysticks are supported. + + <tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag> + Driver for the standard PET userport joystick. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the PET. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the PET. + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the PET uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + +<sect1>Using extended memory<p> + +The extended memory at $9000 of the CBM 8x96 may be added to the heap by using +the following code: + +<tscreen><verb> + /* Check for the existence of RAM */ + if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) { + /* Add it to the heap */ + _heapadd ((void *) 0x9000, 0x2000); + } +</verb></tscreen> + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/plus4.sgml b/doc/plus4.sgml new file mode 100644 index 000000000..eefb85e21 --- /dev/null +++ b/doc/plus4.sgml @@ -0,0 +1,270 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore Plus/4 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-14 + +<abstract> +An overview over the Plus/4 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Plus/4 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Plus/4 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that Plus/4 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are +missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl +url="c16.html" name="C16 documentation"> is also worth a look. The difference +between both cc65 targets is that the Plus/4 runtime uses banking to support +full 64K RAM, while the C16 does not use banking and supports up to 32K RAM. +Because banking is not needed, most C16 programs will be somewhat smaller than +the same program compiled for the Plus/4. However, programs compiled for the +C16 will always run on the Plus/4, while the reverse is not necessarily true. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Plus/4 +target is a machine language program with a one line BASIC stub, which calls +the machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the kernal and basic +banked out. This gives a usable memory range of $1000 - $FD00. +Having the kernal and basic ROMs banked out means, that no ROM entry points +may be called directly from user code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $C00 (as in the standard setup). + + <tag/Color RAM/ + The color RAM is located at $800 (standard location). + + <tag/Stack/ + The C runtime stack is located at $FCFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Plus/4 specific code may use the <tt/plus4.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/plus4.h/ and declares several functions +common to all CBM platforms. + +Please note that most of the header file declarations from the <tt/plus4.h/ +header file are shared between the C16 and Plus/4 configurations. For this +reason, most of it is located in a common header file named <tt/cbm264.h/. + + + +<sect1>Plus/4 specific functions<p> + +There are currently no special Plus/4 functions. + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/plus4.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/TED/</tag> + The <tt/TED/ structure allows access to the TED chip. See the + <tt/_ted.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the Plus/4 at $0800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Plus/4. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Plus/4. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/plus4-stdjoy.joy (plus4_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the Plus/4. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/plus4-stdser.ser (plus4_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200 + baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + + You need an adapter to use the builtin port, since the output levels + available at the user port don't follow the RS232 standard. + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the Plus/4 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/smc.sgml b/doc/smc.sgml new file mode 100644 index 000000000..b58fc51ab --- /dev/null +++ b/doc/smc.sgml @@ -0,0 +1,596 @@ +<!doctype linuxdoc system> + +<article> +<title>ca65 Macros for Self Modifying Code +<author>Christian Krüger +<date>2012-02-19 + +<abstract> +The 'smc.inc' macro package for ca65 eases the use, increases the safeness and +self-explanation of 'self-modifying-code' (SMC). +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> +When reading assembler sources, self modifying code is often hard to identify +and applying it needs a lot of discipline. + +Since the cacheless 6502 is a thankful target of such kind of code, the macro +package will not only reduce this complexness, but also document the use. The +resulting source is more self-explanatory and so easier to maintain. + +While for general purposes SMC is not a desired form for implementations, it +can be quite useful for a small range of scenarios. Normally SMC will be +introduced when optimizing code in respect to: + +<itemize> +<item>speed and/or +<item>size. +</itemize> + +Please mind that SMC can only be applied for code in RAM, which means that a +general purpose library with SMC excludes ROM targets! + +The ca65 SMC macro package consists of two files: + +<itemize> +<item><tt>smc.inc</tt> +<item><tt>opcodes.inc</tt> +</itemize> + +The latter is only needed if you also plan to modify opcodes and not only data +within your code. + +<sect>Usage<p> +The use of the macros is quite simple: + +Original: + +<tscreen><verb> + PHA + JSR SUBROUTINE + PLA +</verb></tscreen> + +By applying SMC, the speed will now be increased by once cycle: + +SMC: + +<tscreen><verb> + SMC_StoreValue RestoreAccu + JSR SUBROUTINE +SMC RestoreAccu, { LDA #SMC_Value } +</verb></tscreen> + +The first line stores the value of the accu into the '<tt>RestoreAccu</tt>' +labeled SMC target. + +Please note: +<enum> +<item> for all SMC store or transfer operations, a second argument can be + given. This determines the register for the operation: + '<tt>SMC_StoreValue Label, y</tt>' will store the value of the + Y-register. + + If the second argument is missing, the accu will be used automatically. + +<item> The label targets a 'special SMC namespace'. It fits only to + destinations which are introduced with the macro '<tt>SMC</tt>'. A + normal label '<tt>RestoreAccu</tt>' wouldn't match and could even + coexist (even if you should abstain from doing so). + +<item> The macro '<tt>SMC_StoreValue</tt>' takes care, that the store + operation will occur on the value-position of a SMC-instruction. As + you will see, other macros influence other instruction part positions. + There is no consistency check, if the targeted SMC instruction acually + contains a value. Storing a 'value' on an immplied SMC instruction + would corrupt the following memory cell! +</enum> + +The second line needs no further explanation, this is just a placeholder for +some code in the example. + +The third line is the code line which is about to be modified. It has to start +with the '<tt>SMC</tt>' macro and must be labeled, so that the modification +can be designated. Then the unmodified code is given in curly braces. + +Please note the usage of the value placeholder 'SMC_Value'. Using such a +placeholder has two advantages: + +<enum> +<item> The code is better documented. It is clearly visible that the given + value is about to be changed. +<item> When examining an (initial) disassembly (e.g. in a debugger), these + placegolders can be better identified: They are fixed and, you may + notice that below, quite eye catching defined. +</enum> + +<sect1>Argument placeholders<p> + +There are four kinds of placeholders: + +<descrip> + + <label id="Address placeholder"> + <tag><tt>SMC_AbsAdr</tt></tag> + + Used to indicate an address. The value is '<tt>$FADE</tt>'. + + Example: <tt>STA SMC_AbsAdr</tt> + + + <label id="Zero-Page-Address placeholder"> + <tag><tt>SMC_ZpAdr</tt></tag> + + Used to indicate a zero-page-address. The value is '<tt>$00</tt>'. + + Example: <tt>LDA SMC_ZpAdr</tt> + + + <label id="Opcode placeholder"> + <tag><tt>SMC_Opcode</tt></tag> + + Used to indicate an instruction. The value is '<tt>NOP</tt>'. + + Example: <tt>SMC_Opcode</tt> + + + <label id="Immediate value placeholder"> + <tag><tt>SMC_Value</tt></tag> + + Used to indicate a value. The value is '<tt>$42</tt>'. + + Example: <tt>LDX #SMC_Value</tt> +</descrip> + +Attention: Often code is modified after the initial use - where using the +placeholders does not makes sense. Please mind also, that in very variable +expressions (e.g. opcode and argument is about to be changed), placeholders +can lead to unidentifyable code for a debugger/disassembler: + +<tt>SMC Example, { SMC_Opcode SMC_AbsAdr } </tt> + +Since the opcode is '<tt/NOP/', the value '<tt/$DE/' from '<tt/$FADE/' will +interpreted as opcode in a disassembler too. This breaks the correct +disassembly, because '<tt/$DE/' is interpreted as '<tt/DEC abx/'. Establishing +a valid placeholder instruction may be better: + +<tt>SMC Example, { sta SMC_AbsAdr } ; Note: Opcode will be modified too!</tt> + +<sect1>Accessing opcodes<p> + +Some macros are designed to access the instruction of a code line. To increase +readability, please use the opcodes as defined in the '<tt>opcodes.inc</tt>' +file. + +<descrip> + + <label id="Transfer opcode"> + <tag><tt>SMC_TransferOpcode label, opcode (, register)</tt></tag> + Loads and store an opcode to given SMC instruction. + + Example: + +<tscreen><verb> +SMC SumRegister, { LDA #10 } + JSR OUTPUT + SMC_TransferOpcode SumRegister, OPC_ADC_imm, x +</verb></tscreen> + +The macro above will load the opcode '<tt>ADC #</tt>' into the x - register +and stores it at the place of the '<tt>LDA #</tt>'. + + <label id="Load opcode"> + <tag><tt>SMC_LoadOpcode label (, register)</tt></tag> + Loads the opcode of a SMC line to the given register. + + Example: +<tscreen><verb> +SMC ShiftOrNothing, { LSL } + SMC_LoadOpcode ShiftOrNothing, y + CPY #OPC_NOP + BEQ Exit +</verb></tscreen> + + <label id="Store opcode"> + <tag><tt>SMC_StoreOpcode label (, register)</tt></tag> + Stores the value of the given register at the opcode place of a SMC line. + + Example: +<tscreen><verb> +SetBoldMode: + LDA #OPC_INX + SMC_StoreOpcode AdaptCharWidth + SMC_StoreOpcode AdaptUnderlineWidth + RTS + ... +SMC AdaptCharWidth, { NOP } + ... +SMC AdaptUnderlineWidth, { NOP } +</verb></tscreen> + +</descrip> + +<sect1>Accessing arguments<p> + +These marcos are determined to get, set and change arguments of instructions: + +<descrip> + + <label id="Change branch"> + <tag><tt>SMC_ChangeBranch label, destination (, register)</tt></tag> + + Used to modify the destination of a branch instruction. If the adress offset + exceeds the supported range of 8-bit of the 6502, a error will be thrown. + + Example: +<tscreen><verb> +Disable Handler: + SMC_ChangeBranch BranchToHandler, Exit + RTS + ... + LDA warning +SMC BranchToHandler, { BNE Handler } +Exit: + RTS +</verb></tscreen> + + + <label id="Transfer value"> + <tag><tt>SMC_TransferValue label, value (, register)</tt></tag> + + Changes the value of a SMC line. + + Example: +<tscreen><verb> +ClearDefault: + SMC_TransferValue LoadDefault, 0 + RTS + ... +SMC LoadDefault, { LDX #25 } +</verb></tscreen> + + + <label id="Load value"> + <tag><tt>SMC_LoadValue label (, register)</tt></tag> + + Retreives the value of a SMC line. + + Example: +<tscreen><verb> +ShowDefault: + SMC_LoadValue LoadDefault + JSR PrintValue + RTS + ... +SMC LoadDefault, { LDX #25 } +</verb></tscreen> + + + <label id="Store value"> + <tag><tt>SMC_StoreValue label (, register)</tt></tag> + + Stores the value in the register to given SMC line. + + Example: +<tscreen><verb> +InitCounters: + LDY #0 + SMC_StoreValue GetI, y + SMC_StoreValue GetJ, y + SMC_StoreValue GetK, y + ... +SMC GetI, { LDX #SMC_Value } + ... +SMC GetJ, { LDX #SMC_Value } + ... +SMC GetK, { LDX #SMC_Value } +</verb></tscreen> + + + <label id="Transfer low-byte"> + <tag><tt>SMC_TransferLowByte label, value (, register)</tt></tag> + + Does the same as '<tt>SMC_TransferValue</tt>' but should be used for + low-bytes of adresses for better readability. + + Example: +<tscreen><verb> +ActivateSecondDataSet: + SMC_TransferLowByte LoadData, $40 + RTS + ... +SMC LoadData, { LDA $2000 } +</verb></tscreen> + + + <label id="Load low-byte"> + <tag><tt>SMC_LoadLowByte label (, register)</tt></tag> + + Does the same as '<tt>SMC_LoadValue</tt>' but should be used for low-bytes + of adresses for better readability. + + Example: +<tscreen><verb> +IsSecondDataSetActive: + SMC_LoadLowByte LoadData, y + CPY #$40 + BNE NotActive + ... +SMC LoadData, { LDA $2000 } +</verb></tscreen> + + + <label id="Store low-byte"> + <tag><tt>SMC_StoreLowByte label (, register)</tt></tag> + + Does the same as '<tt>SMC_StoreValue</tt>' but should be used for low-bytes + of adresses for better readability. + + Example: +<tscreen><verb> +InitStructureBaseAddresses: + LDX #0 + SMC_StoreLowByte GetPlayerGraphic, x + SMC_StoreLowByte GetObjectGraphic, x + SMC_StoreLowByte StoreCollisionData, x + RTS + ... +SMC GetPlayerGraphic, { LDX $2000 } + ... +SMC GetObjectGraphic, { LDA $2100,x } + ... +SMC StoreCollisionData, { STY $2200 } +</verb></tscreen> + + + <label id="Transfer high-byte"> + <tag><tt>SMC_TransferHighByte label, value (, register)</tt></tag> + + Loads and stores the given value via the named register to the high-byte + adress portion of an SMC-instruction. + + Example: +<tscreen><verb> +PlaySFX: +SMC GetVolume { LDA $3200,x } + STA SoundOut + INX + BNE PlaySFX + ... +PlayOtherSound: + SMC_TransferHighByte GetVolume, $34 +</verb></tscreen> + + + <label id="Load high-byte"> + <tag><tt>SMC_LoadHighByte label (, register)</tt></tag> + + Loads the high-byte part of an SMC-instruction adress to the given register. + + Example: +<tscreen><verb> +PlaySFX: +SMC GetVolume { LDA $3200,x } + ... + SMC_LoadHighByte GetVolume + cmp #$34 + beq OtherSoundPlaying + ... +</verb></tscreen> + + + <label id="Store high-byte"> + <tag><tt>SMC_StoreHighByte label (, register)</tt></tag> + + Stores the high-byte adress part of an SMC-instruction from the given + register. + + Example: +<tscreen><verb> +SetupLevel2: + LDX #(>Level2Base) + SMC_StoreHighByte GetLevelData, x + SMC_StoreHighByte GetScreenData, x + SMC_StoreHighByte GetSoundData, x + RTS + ... +SMC GetLevelData, { LDA Level1Base+Data } + ... +SMC GetScreenData, { LDA Level1Base+Screen, x } + ... +SMC GetSoundData, { LDA Level1Base+Sound, y } +</verb></tscreen> + + + <label id="Transfer single adress"> + <tag><tt>SMC_TransferAddressSingle label, address (, register)</tt></tag> + + Transfers the contents of the given address via the given register to the + designated SMC instruction. + + Example: +<tscreen><verb> +PrintHello: + SMC_TransferAddressSingle GetChar, #HelloMsg + ... + LDX #0 +NextChar: +SMC GetChar, { LDA SMC_AbsAdr, x } + BEQ leave + JSR CharOut + INX + BNE NextChar +</verb></tscreen> + + + <label id="Transfer adress"> + <tag><tt>SMC_TransferAddress label, address</tt></tag> + + Loads contents of given address to A/X and stores the result to SMC + instruction. Allows reuse of register contents by using + '<tt>SMC_StoreAddress</tt>' for multiple SMC instruction modifications. + + Example: +<tscreen><verb> + SMC_TransferAddress JumpTo, #CloseChannel + ... +SMC JumpTo, { JMP OpenChannel } +</verb></tscreen> + + + <label id="Store address"> + <tag><tt>SMC_StoreAddress label</tt></tag> + + Stores the address value in a/x to a SMC instruction address position. + + Example: +<tscreen><verb> + SMC_StoreAddress GetData + ... +SMC GetData, { LDA SMC_AbsAdr } +</verb></tscreen> + +</descrip> + +<sect1>Operational macros<p> + +These marcos are determined to let read/modify/write opcodes work on parts of +SMC instructions. + +<descrip> + + <label id="Operate on value"> + <tag><tt>SMC_OperateOnValue opcode, label</tt></tag> + + Let given opcode work on the value part of a SMC instruction. + + Example: +<tscreen><verb> + SMC_OperateOnValue ASL, LoadMask ; shift mask to left + ... +SMC LoadMask, { LDA #$20 } +</verb></tscreen> + + <label id="Operate on low-byte"> + <tag><tt>SMC_OperateOnLowByte opcode, label</tt></tag> + + Same as '<tt/SMC_OperateOnValue/' but renamed for better readability when + accessing low-bytes of address. + + Example: +<tscreen><verb> + SMC_OperateOnLowByte DEC, AccessData + ... +SMC AccessData, { LDX Data } +</verb></tscreen> + + <label id="Operate on high-byte"> + <tag><tt>SMC_OperateOnHighByte opcode, label</tt></tag> + + Let the given opcode work on the high-byte part on a SMC-instruction. + + Example: +<tscreen><verb> +NextPage: + SMC_OperateOnHighByte INC, GetPageData + ... +SMC GetPageData, { LDA SourceData, X } +</verb></tscreen> +</descrip> + +<sect1>Scope macros<p> + +These marcos are determined to export and import SMC labels out of the current +file scope. Please handle with care! If you cannot abstain from leaving the +file scope, you should at least document the exported SMC lines very well. On +import side no checking is available if the SMC line is correct accessed (e.g. +invalid access to the value of an implied instruction)! + +<descrip> + <label id="Export SMC line under given name"> + <tag><tt>SMC_Export alias, label</tt></tag> + + SMC label will be exported under given alias. + + Example: +<tscreen><verb> +.proc GetValue +SMC LoadValue, { LDA #12 } + rts +.endproc + +SMC_Export GetValueLoader, GetValue::LoadValue +</verb></tscreen> + + <label id="Import SMC alias"> + <tag><tt>SMC_Import alias</tt></tag> + + SMC line is made accessible under given alias. + + Example: +<tscreen><verb> +SMC_Import GetValueLoader + ... + SMC_TransferValue GetValueLoader, #47 + ... +</verb></tscreen> +</descrip> + +<sect>A complex example<p> +Let's have a look on a quite sophisticated example for the usage of SMC. It +not only modifies code, but also the modification of the code is modified - +allowing reuse of some instructions. + +The code is from my 'memset()'implementation: + +<descrip> +<tscreen><verb> + 1: ... + 2: SMC_StoreAddress StoreAccuFirstSection + 3: + 4: StoreToFirstSection: + 5: SMC StoreAccuFirstSection, { sta SMC_AbsAdr, Y } + 6: ... + 7: RestoreCodeBranchBaseAdr: + 8: SMC FirstIncHighByte, { SMC_OperateOnHighByte inc, StoreAccuFirstSection } ; code will be overwritten to 'beq RestoreCode' (*) + 9: ... +10: SMC_TransferOpcode FirstIncHighByte, OPC_BEQ , x ; change code marked above with (*) +11: SMC_TransferValue FirstIncHighByte, #(restoreCode - RestoreCodeBranchBaseAdr-2), x ; set relative adress to 'RestoreCode' +12: ... +13: restoreCode: +14: SMC_TransferOpcode FirstIncHighByte, OPC_INC_abs , x ; restore original code... +15: SMC_TransferValue FirstIncHighByte, #(<(StoreToFirstSection+2)), x ; (second byte of inc contained low-byte of adress) +16: ... +</verb></tscreen> + +Some explanation: + +Line 2: The register pair A/X contains an address, which is stored on the +address location of a SMC line called 'StoreAccuFirstSection'. According to +cc65's calling convention, the low-byte is in accu while the high-byte is in +the X-register. + +Line 5: The (modified) address is accessed. + +Line 8: We have a line here, which is about to be modified (it begins with +SMC), but itself modifies code. Please note: Contrary to the rest of SMC-line +modifying macros, the 'OperateOn'-macros just expand their given arguments +into a single instruction line. These can be changed of course too. + +Line 10,11: These lines construct a branch operation for line 8: The +X-register will be used to change it from 'inc StoreAccuFirstSection+2' +(high-byte operation) to 'beq restoreCode'. Please note: To calculate the +relaive branch offset, we introduced a second label +('RestoreCodeBranchBaseAdr') for to calculate it. Some could also use the +internal name of the SMC label, but you should abstain to do so - it may be +changed in the future... + +Line 14,15: The original code from line 8 is reestablished. +</descrip> +</article> + diff --git a/doc/sp65.sgml b/doc/sp65.sgml new file mode 100644 index 000000000..32dead645 --- /dev/null +++ b/doc/sp65.sgml @@ -0,0 +1,424 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>sp65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2012-03-11 + +<abstract> +sp65 is a sprite and bitmap utility that is part of the cc65 development suite. +It is used to convert graphics and bitmaps into the target formats of the +supported machines. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +sp65 is a tool that converts images from common formats into formats used +on the 6502 platforms that are the targets of the cc65 compiler suite. In +addition, it allows some very simple operation with loaded graphics data, like +using part of an image for further processing. + +The utility has been designed in a way that adding additional source or target +formats is easy. The final output is either binary, or C/assembler source. + + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The sp65 utility accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: sp65 [options] file [options] [file] +Short options: + -V Print the version number and exit + -c fmt[,attrlist] Convert into target format + -h Help (this text) + -lc List all possible conversions + -r file[,attrlist] Read an input file + -v Increase verbosity + -w file[,attrlist] Write the output to a file + +Long options: + --convert-to fmt[,attrlist] Convert into target format + --help Help (this text) + --list-conversions List all possible conversions + --pop Restore the original loaded image + --read file[,attrlist] Read an input file + --slice x,y,w,h Generate a slice from the loaded bitmap + --verbose Increase verbosity + --version Print the version number and exit + --write file[,attrlist] Write the output to a file +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Below is a description of all the command line options. For the concept of +attribute lists see <ref id="attr-lists" name="below">. + +<descrip> + + <label id="option--convert-to"> + <tag><tt>-c, --convert-to format[,attrlist]</tt></tag> + + Convert a bitmap into one of the supported target formats. The option + argument must at least contain the "format" attribute. For more attributes, + see section <ref id="conversions" name="Conversions">. + + + <label id="option--help"> + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option--list-conversions"> + <tag><tt>-lc, --list-conversions</tt></tag> + + Print a list of possible conversions. + + + <label id="option--pop"> + <tag><tt>--pop</tt></tag> + + Restore the working copy of the bitmap from the one originally loaded from + the file. This may for example be used when creating several output files + from one input file. + + + <label id="option--read"> + <tag><tt>-r, --read filename[,attrlist]</tt></tag> + + Read an input file. The option argument must at least contain the "name" + attribute. See <ref id="input-formats" name="input formats"> for more + information. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Increase verbosity. Usually only needed for debugging purposes. You may use + this option more than one time for even more verbose output. + + + <label id="option-V"> + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions or + bugfixes, please include the version number. + + + <label id="option--write"> + <tag><tt>-w, --write filename[,attrlist]</tt></tag> + + Write an output file. The option argument must at least contain the "name" + attribute. See <ref id="output-formats" name="output formats"> for more + information. + +</descrip> +<p> + + + +<sect>Processing pipeline<label id="processing-pipeline"><p> + +sp65 consists of + +<itemize> +<item>Front ends that read graphics data, +<item>processors for graphics data, +<item>converters +<item>and output modules for several formats. +</itemize> + +These modules can be combined to a pipeline that reads data, does some +optional bitmap processing, converts the bitmap into a target format, and +writes this binary data to disk in one of several forms. + + + +<sect>Attribute lists<label id="attr-lists"><p> + +As described in <ref id="processing-pipeline" name="Processing pipeline">, +sp65 consists of lots of different modules that may be combined in different +ways, to convert an input bitmap to some output. + +Many of the processors and converters have options to change the way, they're +working. To avoid having lots of command line options that must be parsed on +high level and passed down to the relevant parts of the program, sp65 features +something called "attribute lists". Attribute lists are lists of +attribute/value pairs. These lists are parsed by the main program module +without any knowledge about their meaning. Lower level parts just grab the +attributes they need. + +In general, attribute lists look like this: + +<tscreen><verb> + attr1=val1[,attr2=val2[,...]] +</verb></tscreen> + +Instead of the comma, colons may also be used (even mixed). + +To simplify things and to make the most common options look "normal", some +mandatory attributes may be given without an attribute name. If the attribute +name is missing, the default name is determined by the position. For example, +the option <tt/<ref id="option--read" name="--read">/ does always need a file +name. The attribute name for the file name is "name". To avoid having to type + +<tscreen><verb> + sp65 --read name=ball.pcx ... +</verb></tscreen> + +the first attribute gets the default name "name" assigned. So if the first +attribute doesn't have a name, it is assumed that it is the file name. This +means that instead of the line above, one can also use + +<tscreen><verb> + sp65 --read ball.pcx ... +</verb></tscreen> + +The second attribute for <tt/--read/ is the format of the input file. So when +using + +<tscreen><verb> + sp65 --read ball.pic:pcx ... +</verb></tscreen> + +a PCX file named "ball.pic" is read. The long form would be + +<tscreen><verb> + sp65 --read name=ball.pic:format=pcx ... +</verb></tscreen> + +Changing the order of the attributes is possible only when explicitly +specifying the names of the attributes. Using + +<tscreen><verb> + sp65 --read pcx:ball.pic ... +</verb></tscreen> + +will make sp65 complain, because it tries to read a file named "pcx" with an +(unknown) format of "ball.pic". The following however will work: + +<tscreen><verb> + sp65 --read format=pcx:name=ball.pic ... +</verb></tscreen> + +The attributes that are valid for each processor or converter are listed +below. + + + +<sect>Input formats<label id="input-formats"><p> + +Input formats are either specified explicitly when using <tt/<ref +id="option--read" name="--read">/, or are determined by looking at the +extension of the file name given. + +<sect1>PCX<p> + +While sp65 is prepared for more, this is currently the only possible input +format. There are no additional attributes for this format. + + + +<sect>Conversions<label id="conversions"><p> + +<sect1>GEOS bitmap<p> + +The current bitmap working copy is converted to a GEOS compacted bitmap. This +format is used by several GEOS functions (i.e. 'BitmapUp') and is described +in 'The Official GEOS Programmers Reference Guide', chapter 4, section +'Bit-Mapped Graphics'. + + +<sect1>GEOS icon<p> + +The current bitmap working copy is converted to GEOS icon format. A GEOS icon +has the same format as a C64 high resolution sprite (24x21, monochrome, 63 +bytes). There are no additional attributes for this conversion. + + +<sect1>Koala image<p> + + +<sect1>Lynx sprite<p> + +Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size +of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by +102 pixels which makes very large sprites useless. + +The number per pixels is taken from the number of colors of the input bitmap. + +There are a few attributes that you can give to the conversion software. + +<descrip> + + <tag/mode/ + The first is what kind of encoding to use for the sprite. The attribute for + this is called "mode" and the possible values are "literal", "packed" or + "transparent". The default is "packed" if no mode is specified. + + The "literal" is a totally literal mode with no packing. In this mode the + number of pixels per scanline will be a multiple of 8 both right and left from + the action point. + + If the source bitmap edge ends with a color where the least significant bit is + one then there will be an extra 8 zero bits on that scan line. + + So if you are using totally literal sprites and intend to change them at + runtime then please add a single pixel border far left and far right with + zeros in order to prevent graphical glitches in the game. + + The standard encoding is called "packed". In this mode the sprite is packed + using run-length encoding and literal coding mixed for optimisation to + produce a small sprite. + + The last encoding mode "transparent" is like packed. But here we know that + the index 0 will be transparent so we can clip off all 0 pixels from the left + and right edge of the sprite. This will produce the smallest sprite possible + on the Lynx. The sprite is not rectangular anymore. + + <tag/ax/ + The sprite is painted around the Anchor point. The anchor point x can be + between 0 and the width of the sprite - 1. If anchor point x is zero then + painting the sprite in location 10,20 will set the left edge of the sprite + 10 pixels from the left of the Lynx screen. When the sprite is scaled by + hardware the anchor point stays in place and the sprite grows or shrinks + around the anchor point. The default value is 0 (left). + + <tag/ay/ + The sprite is painted around the Anchor point. The anchor point y can be + between 0 and the height of the sprite - 1. If anchor point y is zero then + painting the sprite in location 10,20 will set the top of the sprite 20 + pixels from the top of the Lynx screen. When the sprite is scaled by + hardware the anchor point stays in place and the sprite grows or shrinks + around the anchor point. The default value is 0 (top). + +</descrip> + +<sect1>VIC2 sprite<p> + + + + +<sect>Output formats<label id="output-formats"><p> + +Using <tt/<ref id="option--write" name="--write">/ it is possible to write +processed data to an output file. An attribute "name" is mandatory, it is used +as the file name for the output. The output format can be specified using an +attribute named "format". If this attribute doesn't exist, the output format +is determined by looking at the file name extension. + + +<sect1>Binary<p> + +For this format, the processed data is written to the output file in raw +binary format. There are no additional attributes (besides "name" and +"format") for this output format. + + +<sect1>Assembler code<p> + +For this format, the processed data is written to the output file in ca65 +assembler format. There are several attributes for this output format: + +<descrip> + + <tag/base/ + The value for this attribute specifies the numeric base for the data + values. It may be either 2, 10 or 16. The default is 16. If the base is + 2, the numbers are prefixed by '%', if the base is 16, the numbers are + prefixed by '$'. For base 10, there is no prefix. + + <tag/bytesperline/ + The value for this attribute specifies the number of bytes output in one + line of the assembler file. The default is 16. + + <tag/ident/ + This is an optional attribute. When given, the output processor will wrap + the data into a <tt/.PROC/ with the given name. In addition, three constants + are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/ + and <tt/HEIGHT/. + +</descrip> + + + +<sect1>C code<p> + +When using C output format, a small piece of C source code is generated that +defines the data containing the output in an array of <tt/unsigned char/. + +Possible attributes for this format are: + +<descrip> + <tag/base/ + The value for this attribute specifies the numeric base for the data values. + It may be either 10 or 16. The default is 16. If the base is 16, the numbers + are prefixed by 0x. For base 10, there is no prefix. + + <tag/bytesperline/ + The value for this attribute specifies the number of bytes output in one + line of the C source code. The default is 16. + + <tag/ident/ + This is an optional attribute. When given, the output processor will wrap + the data into an array of unsigned char with the given name. In addition, + three <tt/#define/s are added for <tt/<ident>_COLORS/, + <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/. + +</descrip> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the assembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to +hear from you. Feel free to contact me by email +(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz +and others. For usage of the binaries and/or sources the following conditions +do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/supervision.sgml b/doc/supervision.sgml new file mode 100644 index 000000000..504ba5194 --- /dev/null +++ b/doc/supervision.sgml @@ -0,0 +1,179 @@ +<!doctype linuxdoc system> + +<article> + +<title>Watara Supervision specific information for cc65 +<author>Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-07-17 + +<abstract> +An overview over the Supervision runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Supervision runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Supervision specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that Supervision specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Supervision target +is a 2×16 kbyte machine language program. It is of course +possible to change this behaviour by using one of the different linker configs. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area enabled, +which gives a usable memory range of $8000 - $FFF9. +More ROM may need additional bankswitching code. + +Special locations: + +<descrip> + <tag/Text screen/ +<!-- The text screen is located at VRAM $4000.--> + No conio support is currently available for the Supervision. + + <tag/Stack/ + The C runtime stack is located at $1FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Supervision specific code may use the <tt/supervision.h/ header file. + + +<sect1>Supervision specific functions<p> + +<itemize> +<item>waitvblank +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/supervision.inc/ include file do +allow access to hardware located in the address space. + +<descrip> + + <tag><tt/IO/</tag> + The <tt/IO/ defines allow access to the IO chip. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Supervision. +<!--A TGI driver for the standard graphics mode (160×160 in 4 colors) is +available, but must be statically linked, because no file I/O is available. +See the documentation for the <htmlurl url="co65.html" name="co65 utility"> +for information on how to do that.--> + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Supervision. + + +<sect1>Joystick drivers<p> + +No joystick drivers are currently available for the Supervision. +<!--A joystick driver for the standard buttons is available, but must be +statically linked, because no file I/O is available. See the documentation for +the <htmlurl url="co65.html" name="co65 utility"> for information on how to do +that.--> + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Supervision. + + +<sect1>RS232 device drivers<p> + +No communication port drivers are currently available for the Supervision. + + + +<sect>Limitations<p> + +<sect1>Disk I/O<p> + +The existing library for the Supervision doesn't implement C file +I/O. There are even no hacks for the <tt/read()/ and <tt/write()/ routines. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/using-make.sgml b/doc/using-make.sgml new file mode 100644 index 000000000..5affe3b9f --- /dev/null +++ b/doc/using-make.sgml @@ -0,0 +1,156 @@ +<!doctype linuxdoc system> + +<article> + +<title>Using GNU Make with cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-06-26 + +<abstract> +How to build your program using the GNU Make utility. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This document describes how to build your programs using the cc65 development +tools and the GNU Make utility. + +The cc65 development package doesn't come with a make utility. However this is +no issue because GNU Make works very nicely with cc65. + + + +<sect>What is GNU Make?<p> + +GNU Make is a both very powerful and very popular make utility. It might even +be called the de facto standard for make utilities. For more information see +the GNU Make home page: + +<url url="http://www.gnu.org/software/make/"> + +The cc65 development package is available as binaries for several host systems +and can easily built for quite some additional systems. The very same is true +for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily +be built by any cc65 developer no matter what host system is used. + +Because of the strong alignment of the cc65 compiler with the ISO C standard it +is very well feasible to compile a single C code base both with the cc65 +compiler and other C compilers like for example GCC. GNU Make turns out to be +very well suited to build projects for several target systems using multiple +compilers as it isn't tied to any C compiler. + + + +<sect>A sample Makefile<p> + +This Makefile is a fully functional sample for compiling several C sources +(here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an +executable program (here <tt/foobar/): + +<tscreen><verb> +SOURCES = foo.c bar.c + +PROGRAM = foobar + +ifdef CC65_TARGET +CC = $(CC65_HOME)/bin/cl65 +CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O +LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map +else +CC = gcc +CFLAGS = -MMD -MP -O +LDFLAGS = -Wl,-Map,$(PROGRAM).map +endif + +######################################## + +.SUFFIXES: +.PHONY: all clean +all: $(PROGRAM) + +ifneq ($(MAKECMDGOALS),clean) +-include $(SOURCES:.c=.d) +endif + +%.o: %.c + $(CC) -c $(CFLAGS) -o $@ $< + +$(PROGRAM): $(SOURCES:.c=.o) + $(CC) $(LDFLAGS) -o $@ $^ + +clean: + $(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map +</verb></tscreen> + +<bf/Important:/ When using the sample Makefile above via copy & paste it is +necessary to replace the eight spaces at the beginning of command lines (lines +26, 29 and 32) with a tab character (ASCII code 9). + + +<sect1>Invoking the sample Makefile<p> + +Without any specific configuration the sample Makefile will compile and link +using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be +defined. This may by done as an environment variable or simply as part of the +Makefile. However to quickly switch between compilers and/or cc65 targets it is +best done on the GNU Make command line like this: + +<tscreen><verb> +make CC65_TARGET=c64 +</verb></tscreen> + +The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the +directory cc65 is located in. Again there are several ways to define this +variable but as its value typically won't change often it is best done as an +environment variable. On Windows the cc65 .exe installer package takes care +of creating a <tt/CC65_HOME/ environment variable. + + +<sect1>Understanding the sample Makefile<p> + +Most parts of the sample Makefile follow the guidelines in the +<htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual"> +that can be searched online for background information. The automatic generation of +dependency however rather works as described by the GNU Make maintainer Paul D. Smith in +<htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">. +Fortunately both GCC and cc65 directly support this method in the meantime. + + +<sect1>Invoking the sample Makefile on Windows<p> + +The recommended way to use GNU Make on Windows is to install it as part of a +Cygwin environment. For more information see the Cygwin home page: + +<url url="http://www.cygwin.com/"> + +If however installing Cygwin shouldn't be an option for one or the other reason +then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe) +by downloading the following programs: + +<itemize> +<item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm"> +<item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm"> +</itemize> + + + +<sect>Target-specific Variable Values<p> + +The very limited resources of the cc65 target machines now and then require +manual optimization of the build process by compiling individual source files +with different compiler options. GNU Make offers +<htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values"> +perfectly suited for doing so. For example placing the code of the two modules +<tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this +target-specific variable definition: + +<tscreen><verb> +foo.o bar.o: CFLAGS += --code-name FOOBAR +</verb></tscreen> + +</article> diff --git a/doc/vic20.sgml b/doc/vic20.sgml new file mode 100644 index 000000000..1227ee667 --- /dev/null +++ b/doc/vic20.sgml @@ -0,0 +1,269 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore VIC20 (aka VC20) specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2004-09-13 + +<abstract> +An overview over the VIC20 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the VIC20 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, VIC20 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that VIC20 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the VIC20 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with unexpanded memory +(RAM at $A000 - $BFFF may be used for the heap), +which gives a usable memory range of $1000 - $1DFF. +All ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $1E00 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $1DFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing VIC20 specific code may use the <tt/vic20.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/vic20.h/ and declares several functions +common to all CBM platforms. + + +<sect1>VIC20 specific functions<p> + +There are currently no special VIC20 functions. + + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/vic20.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC (the graphics + controller). See the <tt/_vic.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/VIA1, VIA2/</tag> + Access to the two VIA (versatile interface adapter) chips is available via + the <tt/VIA1/ and <tt/VIA2/ variables. The structure behind these variables + is explained in <tt/_6522.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the VIC20 at $9600. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the VIC20. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the VIC20. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/vic20-stdjoy.joy (vic20_stdjoy)/</tag> + Supports one standard joystick connected to the joysticks port of the VIC20. + + <tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to three joysticks are supported. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the VIC20. + + +<sect1>RS232 device drivers<p> + +No VIC1011 drivers are currently available for the VIC20. + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Escape code<p> + +For an Esc press CTRL and [ key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Using extended memory<p> + +The extended memory at $A000 may be added to the heap by using the following +code: + +<tscreen><verb> + /* Check for the existence of RAM */ + if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {<br> + /* Add it to the heap */ + _heapadd ((void *) 0xA000, 0x2000); + } +</verb></tscreen> + + +<sect1>Interrupts<p> + +The runtime for the VIC20 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> From c3d93d259b65c51ed5ac8e6cd58327af908c9501 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Tue, 4 Feb 2014 22:51:39 +0100 Subject: [PATCH 08/36] Updated linuxdoc sources from https://github.com/groessler/cc65/tree/gh-pages-sgml. --- doc/apple2.sgml | 44 ++-- doc/apple2enh.sgml | 40 +-- doc/ar65.sgml | 8 - doc/atari.sgml | 600 ++++++++++++++++++++++++++++++++++--------- doc/atmos.sgml | 17 +- doc/c128.sgml | 45 ++-- doc/c16.sgml | 16 +- doc/c64.sgml | 61 +++-- doc/ca65.sgml | 64 ++--- doc/ca65html.sgml | 9 - doc/cbm510.sgml | 37 +-- doc/cbm610.sgml | 16 +- doc/cc65.sgml | 73 +++--- doc/cl65.sgml | 9 - doc/co65.sgml | 9 - doc/da65.sgml | 9 - doc/index.sgml | 27 +- doc/intro.sgml | 10 +- doc/ld65.sgml | 70 ++--- doc/library.sgml | 19 +- doc/lynx.sgml | 15 +- doc/nes.sgml | 9 - doc/od65.sgml | 9 - doc/pet.sgml | 13 +- doc/plus4.sgml | 16 +- doc/sp65.sgml | 9 - doc/supervision.sgml | 9 - doc/vic20.sgml | 15 +- 28 files changed, 700 insertions(+), 578 deletions(-) diff --git a/doc/apple2.sgml b/doc/apple2.sgml index fb6dda7fe..ecab5c32b 100644 --- a/doc/apple2.sgml +++ b/doc/apple2.sgml @@ -87,13 +87,13 @@ on the chosen <htmlurl url="apple2-4.html" name="linker configuration">. <sect>Linker configurations<p> -The ld65 linker comes with a builtin config file for the Apple ][, -which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/). +The ld65 linker comes with a default config file for the Apple ][, +which is used via <tt/-t apple2/. The apple2 package comes with additional secondary linker config files, which -are used via <tt/-C <configfile>/. +are used via <tt/-t apple2 -C <configfile>/. -<sect1>builtin config file<p> +<sect1>default config file (<tt/apple2.cfg/)<p> Default configuration optimized for a binary program running on ProDOS 8 with BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card @@ -317,13 +317,13 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag> + <tag><tt/a2.lo.tgi (a2_lo_tgi)/</tag> This driver features a resolution of 40×48 with 16 colors. The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The function clears the corresponding area at the bottom of the screen. - <tag><tt/a2.hi.tgi (apple2_280_192_8)/</tag> + <tag><tt/a2.hi.tgi (a2_hi_tgi)/</tag> This driver features a resolution of 280×192 with 8 colors and two hires pages. Note that programs using this driver will have to be linked with <tt/--start-addr $4000/ to reserve the first hires page or with @@ -345,7 +345,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2.auxmem.emd (apple2_auxmem)/</tag> + <tag><tt/a2.auxmem.emd (a2_auxmem_emd)/</tag> Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended 80-Column Text Card. @@ -359,7 +359,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2.stdjoy.joy (apple2_stdjoy)/</tag> + <tag><tt/a2.stdjoy.joy (a2_stdjoy_joy)/</tag> Supports up to two standard analog joysticks connected to the game port of the Apple ][. @@ -370,7 +370,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag> + <tag><tt/a2.stdmou.mou (a2_stdmou_mou)/</tag> Driver for the AppleMouse II Card. Searches all Apple II slots for an AppleMouse II Card compatible firmware. The default bounding box is [0..279,0..191]. @@ -391,7 +391,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2.ssc.ser (apple2_ssc)/</tag> + <tag><tt/a2.ssc.ser (a2_ssc_ser)/</tag> Driver for the Apple II Super Serial Card. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -421,9 +421,8 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <tag>Disk File I/O</tag> There's no disk file I/O support. Any attempt to use it yields an error with <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers - are in general not functional as they depend on disk file I/O. However they - may be converted to statically linked drivers using the co65 object-file - converter. + are in general not functional as they depend on disk file I/O. Therefore the statically + linked drivers have to be used instead. <tag/Interrupts/ There's no <tt/interruptor/ support. Any attempt to use it yields the message @@ -439,14 +438,12 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <descrip> <tag/Color/ - The Apple ][ has no color text mode. Therefore the functions - <htmlurl url="funcref-205.html" name="textcolor()">, - <htmlurl url="funcref-68.html" name="bgcolor()"> and - <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + The Apple ][ has no color text mode. Therefore the functions textcolor(), + bgcolor() and bordercolor() have no effect. <tag/Cursor/ - The Apple ][ has no hardware cursor. Therefore the function - <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + The Apple ][ has no hardware cursor. Therefore the function cursor() has + no effect. </descrip><p> @@ -511,15 +508,6 @@ url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml index 667ae9ec7..f20c187fd 100644 --- a/doc/apple2enh.sgml +++ b/doc/apple2enh.sgml @@ -87,13 +87,13 @@ on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. <sect>Linker configurations<p> -The ld65 linker comes with a builtin config file for the enhanced Apple //e, -which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/). +The ld65 linker comes with a default config file for the enhanced Apple //e, +which is used via <tt/-t apple2enh/. The apple2enh package comes with additional secondary linker config files, which -are used via <tt/-C <configfile>/. +are used via <tt/-t apple2enh -C <configfile>/. -<sect1>builtin config file<p> +<sect1>default config file (<tt/apple2enh.cfg/)<p> Default configuration optimized for a binary program running on ProDOS 8 with BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card @@ -320,13 +320,13 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2e.lo.tgi (apple2_40_48_16)/</tag> + <tag><tt/a2e.lo.tgi (a2e_lo_tgi)/</tag> This driver features a resolution of 40×48 with 16 colors. The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The function clears the corresponding area at the bottom of the screen. - <tag><tt/a2e.hi.tgi (apple2_280_192_8)/</tag> + <tag><tt/a2e.hi.tgi (a2e_hi_tgi)/</tag> This driver features a resolution of 280×192 with 8 colors and two hires pages. Note that programs using this driver will have to be linked with <tt/--start-addr $4000/ to reserve the first hires page or with @@ -352,7 +352,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2e.auxmem.emd (apple2_auxmem)/</tag> + <tag><tt/a2e.auxmem.emd (a2e_auxmem_emd)/</tag> Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended 80-Column Text Card. @@ -366,7 +366,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2e.stdjoy.joy (apple2_stdjoy)/</tag> + <tag><tt/a2e.stdjoy.joy (a2e_stdjoy_joy)/</tag> Supports up to two standard analog joysticks connected to the game port of the enhanced Apple //e. @@ -377,7 +377,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag> + <tag><tt/a2e.stdmou.mou (a2e_stdmou_mou)/</tag> Driver for the AppleMouse II Card. Searches all Apple II slots for an AppleMouse II Card compatible firmware. The default bounding box is [0..279,0..191]. @@ -392,7 +392,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/a2e.ssc.ser (apple2_ssc)/</tag> + <tag><tt/a2e.ssc.ser (a2e_ssc_ser)/</tag> Driver for the Apple II Super Serial Card. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -422,9 +422,8 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <tag>Disk File I/O</tag> There's no disk file I/O support. Any attempt to use it yields an error with <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers - are in general not functional as they depend on disk file I/O. However they - may be converted to statically linked drivers using the co65 object-file - converter. + are in general not functional as they depend on disk file I/O. Therefore the statically + linked drivers have to be used instead. <tag/Interrupts/ There's no <tt/interruptor/ support. Any attempt to use it yields the message @@ -441,13 +440,11 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3: <tag/Color/ The enhanced Apple //e has no color text mode. Therefore the functions - <htmlurl url="funcref-205.html" name="textcolor()">, - <htmlurl url="funcref-68.html" name="bgcolor()"> and - <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + textcolor(), bgcolor() and bordercolor() have no effect. <tag/Cursor/ The enhanced Apple //e has no hardware cursor. Therefore the function - <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + cursor() has no effect. </descrip><p> @@ -517,15 +514,6 @@ url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/ar65.sgml b/doc/ar65.sgml index d4e19a5c5..d35bc9987 100644 --- a/doc/ar65.sgml +++ b/doc/ar65.sgml @@ -117,14 +117,6 @@ operation does update the library. This is only a warning, the linker will ignore one of the duplicate symbols (which one is unspecified). -<sect>Bugs/Feedback<p> - -If you have problems using the archiver, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - <sect>Copyright<p> ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von diff --git a/doc/atari.sgml b/doc/atari.sgml index 9fe75ec2a..8ec359654 100644 --- a/doc/atari.sgml +++ b/doc/atari.sgml @@ -26,6 +26,16 @@ with the cc65 C compiler. It describes the memory layout, Atari specific header files, available drivers, and any pitfalls specific to that platform. +The Atari runtime support comes in two flavors: <tt/atari/ and <tt/atarixl/. +The <tt/atari/ target supports all Atari 8-bit computers, the <tt/atarixl/ only +supports XL type or newer machines (excluding the 600XL). + +The <tt/atarixl/ runtime makes the whole 64K of memory available, with the +exception of the I/O area at $D000 - $D7FFF. Since the +<tt/atarixl/ runtime has some <ref name="limitations" id="limitations">, it is +recommended to use the <tt/atari/ target unless lack of memory dictates the +use of the <tt/atarixl/ target. + Please note that Atari specific functions are just mentioned here, they are described in detail in the separate <htmlurl url="funcref.html" name="function reference">. Even functions marked as "platform dependent" may be available on @@ -35,35 +45,54 @@ information. <sect>Binary format<p> -The standard binary output format generated by the linker for the +The Atari DOS executable file format supports more than one load block (<it/chunk/). + +The default binary output format generated by the linker for the Atari target is a machine language program with a standard executable -header (FF FF <2 byte start address> <2 bytes end address> -[program bytes]). These values are calculated in the crt0.s -file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep -this in mind if you create a custom linker config file and start -moving segments around (see section +header (FF FF <load chunk #1> ... <load chunk #n>). +A load chunk has the format [<2 byte start address> <2 bytes end address> +<chunk data>]. +A run vector is added to the end of the +file ($02E0 $02E1 <run vector>) and is calculated using +the <tt/start/ label in crt0.s. (Technically the run vector is also a load chunk, +but is not regarded as such here.) + +An <tt/atari/ program has two load chunks, an <tt/atarixl/ program has three load +chunks. The load chunks are defined in the linker configuration files. For more +detailed information about the load chunks see the chapter +<ref name="Technical details" id="techdetail">. For the discussion here it's +sufficient to know that the first load chunk(s) do preparation work and the +main part of the program is in the last load chunk. + +The values determining the size of the main part of the program (the only load +chunk for <tt/atari/, the third load chunk for <tt/atarixl/) are calculated in +the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values. +Be aware of that if you create a custom linker config file and start moving segments around (see section <ref name="Reserving a memory area inside the program" id="memhole">). -You can override this behaviour by creating your own crt0.s file and -linking it into your program. A run vector is added to the end of the -file ($02E0 <run vector>) and is calculated using -__STARTUP_LOAD__ in crt0.s. <sect>Memory layout<p> -The default linker script assumes that the BASIC ROM is disabled (or -the BASIC cartridge unplugged). This gives a usable memory range from -$2E00 - $BC1F. The library startup code examines the +<sect1><tt/atari/ target<p> + +The default linker config file assumes that the BASIC ROM is disabled (or +the BASIC cartridge unplugged). This gives a usable memory range of +[$2000-$BC1F]. The library startup code examines the current memory configuration, which depends on the size of the -installed memory and cartridges present, by inspecting the value in -the MEMTOP ($2E5) variable. Then the initial stack pointer, -which indicates the upper bound of memory used, is adjusted. The -default load address of $2E00 was chosen to accommodate having -a DOS loaded and a driver that resides in low memory such as the 850 -R: handler. You can override this behaviour by creating a custom +installed memory and cartridges. It does so by using the value in +the MEMTOP ($2E5) variable as highest memory address the program +can use. The initial stack pointer, which is the upper bound of +memory used by the program, is set to this value, minus an optionally +defined __RESERVED_MEMORY__ value. + +The default load address of $2000 can be changed by creating a custom linker config file or by using the "--start-addr" cl65 command line argument or the "--start-addr" or "-S" ld65 command line arguments. +Please note that the first load chunk (which checks the available memory) +will always be loaded at $2E00, regardless of the specified start +address. This address can only be changed by a custom linker config file. + Special locations: <descrip> @@ -86,6 +115,135 @@ Special locations: </descrip><p> +<sect1><tt/atarixl/ target<p> + +The startup code rearranges the memory as follows: + +<enum> +<item>Sceen memory and display list are moved below the program start address. +<item>The ROM is disabled, making the memory in the areas [$C000-$CFFF] +and [$D800-$FFF9] available. +<item>Character generator data is copied from ROM to the CHARGEN location specified in the +linker config file. This is (in the default <tt/atarixl.cfg/ file) at the same address as +where it is in ROM ($E000, it can be changed, see <ref name="atarixl chargen location" +id="chargenloc">). With the character generator at $E000, there are two upper memory +areas available, [$D800-$DFFF] and [$E400-$FFF9]. +</enum> + +With the default load address of $2400 this gives a usable memory range of +[$2400-$CFFF]. Note that the default load address for <tt/atarixl/ is +different (and lower) that the default load address for <tt/atari/. This is no problem since +on the <tt/atarixl/ target the first load chunk makes sure that the loaded prgram won't overwrite +memory below MEMLO. See <ref name="atarixl load chunks" id="xlchunks">. + + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen depends on the selected load address ($2400 + by default), and resides directly before that address, rounded to the next + lower page boundary. + The screen memory's start address can be obtained from the SAVMSC variable + ($58). + + <tag/Stack/ + The C runtime stack is located at end of the RAM memory area ($CFFF) + and grows downwards. + + <tag/Heap/ + The C heap is located at the end of the program (end of BSS segment) and + grows towards the C runtime stack. + +</descrip><p> + +<sect>Linker configurations<p> + +The ld65 linker comes with default config files for the Atari. There +are two targets for the Atari, <tt/atari/ and <tt/atarixl/. +The default config file for <tt/atari/ is selected with +<tt/-t atari/, and the default config file for <tt/atarixl/ is selected with +<tt/-t atarixl/. +The Atari package comes with additional secondary linker config files which +can be used via <tt/-t atari -C <configfile>/ (for <tt/atari/ target) or +<tt/-t atarixl -C <configfile>/ (for <tt/atarixl/ target). + +<sect1><tt/atari/ config files<p> + +<sect2>default config file (<tt/atari.cfg/)<p> + +The default configuration is tailored to C programs. It creates files +which have a default load address of $2000. + +The files generated by this config file include the +<ref name="&dquot;system check&dquot;" id="syschk"> load chunk. It can +optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">. + +<sect2><tt/atari-asm.cfg/<p> + +This config file aims to give the assembler programmer maximum +flexibility. All program segments (<tt/CODE/, <tt/DATA/, etc.) are +optional. + +By default it creates regular DOS executable files, which have a default +load address of $2E00. It's also possible to generate an image of +just the program data without EXE header, load address, or (auto-)start address. +To you so, you have to define the symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/ +when linking the program. Therefore, to generate a "plain" binary file, pass the +options "<tt/-D__AUTOSTART__=1 -D__EXEHDR__=1/" to the linker. +It's also possible to create a non auto-starting program file, by defining +only the <tt/__AUTOSTART__/ symbol. Such a program has to be run manually +after being loaded by DOS (for example by using the "M" option of DOS 2.5). +Defining only the <tt/__EXEHDR__/ symbol will create a (useless) file which +doesn't conform to the DOS executable file format (like a "plain" binary file) +but still has the "autostart" load chunk appended. + +The sections of the file which the defines refer to (<tt/__AUTOSTART__/ for +the autostart trailer, <tt/__EXEHDR__/ for the EXE header and load address) +is <it/left out/, keep this in mind. + +The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/ +don't matter. + +<sect2><tt/atari-cart.cfg/<p> + +This config file can be used to create 8K or 16K cartridges. It's suited both +for C and assembly language programs. + +By default, an 8K cartridge is generated. To create a 16K cartridge, pass the +size of the cartridge to the linker, like "<tt/-D__CARTSIZE__=0x4000/". +The only valid values for <tt/__CARTSIZE__/ are 0x2000 and 0x4000. + +The option byte of the cartridge can be set with the <tt/__CARTFLAGS__/ +value, passed to the linker. The default value is $01, which means +that the cartridge doesn't prevent the booting of DOS. + +The option byte will be located at address $BFFD. For more information +about its use, see e.g. "Mapping the Atari". + + +<sect1><tt/atarixl/ config files<p> + +<sect2>default config file (<tt/atarixl.cfg/)<p> + +The default configuration is tailored to C programs. It creates files +which have a default load address of $2400. + +The files generated by this config file include the +<ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can +optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">. + +<sect2><tt/atarixl-largehimem.cfg/<p> + +This is the same as the default config file, but it rearranges the +high memory beneath the ROM into one large block. In order for this +config file to work, the runtime library has to be recompiled with a +special define. See the file <tt/libsrc/atari/Makefile.inc/ in the +source distribution. + +The files generated by this config file include the +<ref name="&dquot;system check&dquot;" id="syschkxl"> load chunk. It can +optionally be left out, see <ref name="Getting rid of the &dquot;system check&dquot; load chunk" id="nosyschk">. <sect>Platform specific header files<p> @@ -157,48 +315,43 @@ The names in the parentheses denote the symbols to be used for static linking of <sect1>Graphics drivers<p> -<descrip> +<table><tabular ca="rrrr"> +<tt/atari/|<tt/atarixl/|screen resolution|display pages@<hline> +<tt/atr3.tgi (atr3_tgi)/|<tt/atrx3.tgi (atrx3_tgi)/|40x24x4 (CIO mode 3, ANTIC mode 8)|1@ +<tt/atr4.tgi (atr4_tgi)/|<tt/atrx4.tgi (atrx4_tgi)/|80x48x2 (CIO mode 4, ANTIC mode 9)|1@ +<tt/atr5.tgi (atr5_tgi)/|<tt/atrx5.tgi (atrx5_tgi)/|80x48x4 (CIO mode 5, ANTIC mode A)|1@ +<tt/atr6.tgi (atr6_tgi)/|<tt/atrx6.tgi (atrx6_tgi)/|160x96x2 (CIO mode 6, ANTIC mode B)|1@ +<tt/atr7.tgi (atr7_tgi)/|<tt/atrx7.tgi (atrx7_tgi)/|160x96x4 (CIO mode 7, ANTIC mode D)|1@ +<tt/atr8.tgi (atr8_tgi)/|<tt/atrx8.tgi (atrx8_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|1@ +<tt/atr8p2.tgi (atr8p2_tgi)/|<tt/atrx8p2.tgi (atrx8p2_tgi)/|320x192x2 (CIO mode 8, ANTIC mode F)|2@ +<tt/atr9.tgi (atr9_tgi)/|<tt/atrx9.tgi (atrx9_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|1@ +<tt/atr9p2.tgi (atr9p2_tgi)/|<tt/atrx9p2.tgi (atrx9p2_tgi)/|80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)|2@ +<tt/atr10.tgi (atr10_tgi)/|<tt/atrx10.tgi (atrx10_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|1@ +<tt/atr10p2.tgi (atr10p2_tgi)/|<tt/atrx10p2.tgi (atrx10p2_tgi)/|80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)|2@ +<tt/atr11.tgi (atr11_tgi)/|<tt/atrx11.tgi (atrx11_tgi)/|80x192x16h (CIO mode 11, ANTIC mode F, GTIA mode $C0)|1@ +<tt/atr14.tgi (atr14_tgi)/|<tt/atrx14.tgi (atrx14_tgi)/|160x192x2 (CIO mode 14, ANTIC mode C)|1@ +<tt/atr15.tgi (atr15_tgi)/|<tt/atrx15.tgi (atrx15_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|1@ +<tt/atr15p2.tgi (atr15p2_tgi)/|<tt/atrx15p2.tgi (atrx15p2_tgi)/|160x192x4 (CIO mode 15, ANTIC mode E)|2 +</tabular> +<!-- <caption>bla bla --> +</table> - <tag><tt/atari10.tgi (atari_10)/</tag> - - <tag><tt/atr10p2.tgi (atari_10p2)/</tag> - - <tag><tt/atari11.tgi (atari_11)/</tag> - - <tag><tt/atari14.tgi (atari_14)/</tag> - - <tag><tt/atari15.tgi (atari_15)/</tag> - - <tag><tt/atr15p2.tgi (atari_15p2)/</tag> - - <tag><tt/atari3.tgi (atari_3)/</tag> - - <tag><tt/atari4.tgi (atari_4)/</tag> - - <tag><tt/atari5.tgi (atari_5)/</tag> - - <tag><tt/atari6.tgi (atari_6)/</tag> - - <tag><tt/atari7.tgi (atari_7)/</tag> - - <tag><tt/atari8.tgi (atari_8)/</tag> - - <tag><tt/atr8p2.tgi (atari_8p2)/</tag> - - <tag><tt/atari9.tgi (atari_9)/</tag> - - <tag><tt/atr9p2.tgi (atari_9p2)/</tag> - -</descrip><p> Many graphics modes require more memory than the text screen which is in effect when the program starts up. Therefore the programmer has to tell the program beforehand the memory requirements of the graphics modes the program intends to use. -This can be done by using the __RESERVED_MEMORY__ linker config -variable. The number specified there describes the number of bytes to -subtract from the top of available memory as seen from the runtime -library. This memory is then used by the screen buffer. + +On the <tt/atari/ target his can be done by using the __RESERVED_MEMORY__ +linker config variable. The number specified there describes the number +of bytes to subtract from the top of available memory as seen from the +runtime library. This memory is then used by the screen buffer. + +On the <tt/atarixl/ target the screen memory resides below the program +load address. In order to reserve memory for a graphics mode, one +simply uses a higher program load address. There are restrictions on +selectable load addresses, +see <ref name="Selecting a good program load address" id="loadaddr">. The numbers for the different graphics modes presented below should only be seen as a rule of thumb. Since the screen buffer memory needs @@ -251,41 +404,74 @@ the Atari ROM code. <sect1>Extended memory drivers<p> -<descrip> - - <tag><tt/atr130xe.emd (atari_130xe)/</tag> - -</descrip><p> +Currently there is only one extended memory driver. It manages the second 64K of a 130XE. +<table> +<tabular ca="rr"> +<tt/atari/|<tt/atarixl/@<hline> +<tt/atr130.emd (atr130_emd)/|<tt/atrx130.emd (atrx130_emd)/ +</tabular> +</table> <sect1>Joystick drivers<p> -<descrip> +Currently there are two joystick drivers available: - <tag><tt/ataristd.joy (atari_stdjoy)/</tag> - Supports up to four standard joysticks connected to the joystick ports of - the Atari. - - <tag><tt/atarim8.joy (atari_multijoy)/</tag> - Supports up to eight standard joysticks connected to a MultiJoy adapter. - -</descrip><p> +<table> +<tabular ca="rrr"> +<tt/atari/|<tt/atarixl/|description@<hline> +<tt/atrstd.joy (atrstd_joy)/|<tt/atrxstd.joy (atrxstd_joy)/|Supports up to two/four standard joysticks connected to the joystick ports of the Atari. (Four on the pre-XL systems, two on XL or newer.)@ +<tt/atrmj8.joy (atrmj8_joy)/|<tt/atrxmj8.joy (atrxmj8_joy)/|Supports up to eight standard joysticks connected to a MultiJoy adapter. +</tabular> +<caption> +</table> <sect1>Mouse drivers<p> -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). There is a static driver you can use. +Currently there are five mouse drivers available: + +<table> +<tabular ca="rrr"> +<tt/atari/|<tt/atarixl/|description@<hline> +<tt/atrjoy.mou (atrjoy_mou)/|<tt/atrxjoy.mou (atrxjoy_mou)/|Supports a mouse emulated by a standard joystick.@ +<tt/atrst.mou (atrst_mou)/|<tt/atrxst.mou (atrxst_mou)/|Supports an Atari ST mouse.@ +<tt/atrami.mou (atrami_mou)/|<tt/atrxami.mou (atrxami_mou)/|Supports an Amiga mouse.@ +<tt/atrtrk.mou (atrtrk_mou)/|<tt/atrxtrk.mou (atrxtrk_mou)/|Supports an Atari trakball.@ +<tt/atrtt.mou (atrtt_mou)/|<tt/atrxtt.mou (atrxtt_mou)/|Supports an Atari touch tablet. +</tabular> +<caption> +</table> + +All mouse devices connect to joystick port #0. <sect1>RS232 device drivers<p> -Currently there are no RS232 loadable drivers available for the Atari -platform. There is a static driver you can use. +Currently there is one RS232 driver. It uses the R: device (therefore +a R: driver needs to be installed) and was tested with the 850 +interface module. + +<table> +<tabular ca="rr"> +<tt/atari/|<tt/atarixl/@<hline> +<tt/atrrdev.ser (atrrdev_ser)/|<tt/atrxrdev.ser (atrxrdev_ser)/ +</tabular> +</table> <sect>Limitations<p> +<sect1><tt/atarixl/<label id="limitations"<p> + +<itemize> +<item>The display is cleared at program start and at program termination. This is a side +effect of relocating the display memory below the program start address. +<item>Not all possible CIO and SIO functions are handled by the runtime stub code which banks +the ROM in and out. All functions used by the runtime library are handled, though. +<item>The <tt/_sys()/ function is not supported. +<item>It is not compatible with DOSes or other programs using the memory below the ROM. +</itemize> <sect>DIO implementation<label id="dio"><p> @@ -303,6 +489,143 @@ The console I/O is speed optimized therefore support for XEP80 hardware or f80.com software is missing. Of course you may use stdio.h functions. +<sect>Technical details<label id="techdetail"><p> + +<sect1><tt/atari/<p> + +<sect2>Load chunks<p> + +An <tt/atari/ program contains two load chunks. + +<enum> +<item>"system check"<label id="syschk">&nl; +This load chunk is always loaded at address $2E00, and checks if the system has +enough memory to run the program. It also checks if the program start address is not +below MEMLO. If any of the checks return false, the loading of the program is aborted.&nl; +The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file. +<item>main program&nl; +This load chunk is loaded at the selected program start address (default $2000) and +contains all of the code and data of the program.&nl; +The contents of this chunk come from the RAM memory area of the linker config file. +</enum> + + +<sect1><tt/atarixl/<p> + +<sect2>General operation<p> + +The <tt/atarixl/ target banks out the ROM while the program is running in +order to make more memory available to the program. + +The screen memory is by default located at the top of available memory, +$BFFF if BASIC is not enabled, $9FFF if BASIC is enabled. +Therefore, in order to create a largest possible continuous memory area, +the screen memory is moved below the program load address. This gives +a memory area from <program load addr> to $CFFF. + +The startup code installs wrappers for interrupt handlers and ROM routines. +When an interrupt or call to a ROM routine happens, the wrappers enable the +ROM, call the handler or routine, and disable the ROM again. + +The "wrapping" of the ROM routines is done by changing the ROM entry +point symbols in <tt/atari.inc/ to point to the wrapper functions. + +For ROM functions which require input or output buffers, the wrappers +copy the data as required to buffers in low memory. + +<sect2>Load chunks<label id="xlchunks"><p> + +An <tt/atarixl/ program contains three load chunks. + +<enum> +<item>"system check"<label id="syschkxl">&nl; +This load chunk is always loaded at address $2E00, and checks if the system is +suitable for running the program. It also checks if there is enough room between MEMLO +and the program start address to move the text mode screen buffer there. If any of the +checks return false, the loading of the program is aborted.&nl; +The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file. +<item>"shadow RAM prepare"&nl; +The second load chunk gets loaded to the selected program load address (default $2400). +It moves the screen memory below the program load address, copies the character generator +from ROM to its new place in RAM, and copies the parts of the program which reside in +high memory below the ROM to their place. The high memory parts are included in this load chunk.&nl; +At the beginning of this load chunk there is a .bss area, which is not part of the +EXE file. Therefore the on-disk start address of this load chunk will be higher than the +selected start address. This .bss area (segment LOWBSS) contains the buffers for the +double buffering of ROM input and output data. If you add contents to this segment be aware +that the contents won't be zero initialized by the startup code.&nl; +The contents of this chunk come from the SRPREPCHNK memory area of the linker config file. +<item>main program&nl; +This load chunk is loaded just above the LOWBSS segment, replacing the code of +the previous load chunk. It contains all remaining code and data sections of the program, +including the startup code.&nl; +The contents of this chunk come from the RAM memory area of the linker config file. +</enum> + +<sect2>Moving screen memory below the program start address<p> + +When setting a graphics mode, the ROM looks at the RAMTOP location. RAMTOP +describes the amount of installed memory in pages (RAMTOP is only one byte). +The screen memory and display list are placed immediately below RAMTOP. + +Now in order to relocate the screen memory to lower memory, the startup code +puts a value into RAMTOP which causes the ROM routines to allocate the display +memory below the program start address and then it issues a ROM call to setup +the regular text mode. + +<sect2>Selecting a good program load address<label id="loadaddr"><p> + +Due to the movement of the screen memory below the program start, there are some +load addresses which are sub-optimal because they waste memory or prevent a +higher resolution graphics mode from being enabled. + +There are restrictions at which addresses screen memory (display buffer and display +list) can be placed. The display buffer cannot cross a 4K boundary and a display +list cannot cross a 1K boundary. + +The startup code takes this into account when moving the screen memory down. +If the program start address (aligned to the next lower page boundary) minus +the screen buffer size would result in a screen buffer which spans a 4K +boundary, the startup code lowers RAMTOP to this 4K boundary.&nl; +The size of the screen buffer in text mode is 960 ($3C0) bytes. So, for +example, a selected start address of $2300 would span the 4K boundary +at $2000. The startup code would adjust the RAMTOP value in such way that +the screen memory would be located just below this boundary (at $1C40). +This results in the area [$2000-$22FF] being wasted. +Additionally, the program might fail to load since the lowest address used +by the screen memory could be below MEMLO. (The lowest address used in this +example would be at $1C20, where the display list would allocated.) + +These calculations are performed by the startup code (in the first two +load chunks), but the startup code only takes the default 40x24 text mode +into account. If the program later wants to load TGI drivers which set +a more memory consuming graphics mode, the user has to pick a higher +load address. +Using higher resolution modes there is a restriction in the ROM that it +doesn't expect RAMTOP to be at arbitrary values. The Atari memory modules +came only in 8K or 16K sizes, so the ROM expects RAMTOP to only have +values in 8K steps. Therefore, when using the highest resolution modes +the program start address must be at an 8K boundary. + + +<sect2>Character generator location<label id="chargenloc"><p> + +The default <tt/atarixl/ linker config file (<tt/atarixl.cfg/) leaves the +character generator location at the same address where it is in ROM +($E000). This has the disadvatage to split the upper memory into +two parts ([$D800-$DFFF] and +[$E400-$FFF9]). For applications which +require a large continuous upper memory area, an alternative linker +config file (<tt/atarixl-largehimem.cfg/) is provided. It relocates the +character generator to $D800, providing a single big upper +memory area at [$DC00-$FFF9]. + +With the character generator at a different address than in ROM, the routines +which enable and disable the ROM also have to update the chargen pointer. +This code is not enabled by default. In order to enable it, +uncomment the line which sets CHARGEN_RELOC in <tt/libsrc/atari/Makefile.inc/ +and recompile the <tt/atarixl/ runtime library. + <sect>Other hints<p> @@ -335,6 +658,9 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. <sect1>Reserving a memory area inside a program<label id="memhole"><p> +(This section is primarily applicable to the <tt/atari/ target, but the +principles apply to <tt/atatixl/ as well.) + The Atari 130XE maps its additional memory into CPU memory in 16K chunks at address $4000 to $7FFF. One might want to prevent this memory area from being used by cc65. Other reasons to @@ -348,7 +674,7 @@ memory area (assuming a reserved area from $4000 to $BC1F. <p> Each load chunk of the executable starts with a 4 byte header which -defines its load address and size. In the following linker scripts +defines its load address and size. In the following linker config files these headers are named HEADER and SECHDR (for the MEMORY layout), and accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout). <p> @@ -360,30 +686,34 @@ segments should go above $7FFF. <p> The main problem is that the EXE header generated by the cc65 runtime lib is wrong. It defines a single load chunk with the sizes/addresses -of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user -program). +of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments, in +fact, the whole user program (we're disregarding the "system check" +load chunk here). <p> -The contents of the EXE header come from the EXEHDR segment, which is -defined in crt0.s. This cannot be changed without modifying and -recompiling the cc65 atari runtime lib. Therefore the original EXE -header must be discarded. It will be replaced by a user created -one. The discarding is done by assigning the EXEHDR segment to the -BANK memory area. The BANK memory area is discarded in the new linker -script (written to file ""). +The contents of the EXE header come from the EXEHDR and MAINHDR segments. +The EXEHDR segment just contains the $FFFF value which is required +to be the first bytes of the EXE file.&nl; +The MAINHDR are defined in in crt0.s. This cannot be changed without +modifying and recompiling the cc65 atari runtime library. Therefore +the original contents of this segment must be discarded and be +replaced by a user created one. This discarding is done by assigning the +MAINHDR segment to the (new introduced) DISCARD memory area. The DISCARD memory area is +thrown away in the new linker config file (written to file ""). +We add a new FSTHDR segment for the chunk header of the first chunk. <p> The user needs to create a customized linker config file which adds -new memory areas and segments to hold the new EXE header and the -header data for the second load chunk. Also an assembly source file -needs to be created which defines the contents of the new EXE header -and the second load chunk header. +new memory areas and segments to hold the new header data for the first load +chunk and the header data for the second load chunk. Also an assembly source file +needs to be created which defines the contents of the new header data +for the two load chunks. <p> <p> This is an example of a modified cc65 Atari linker configuration file (split.cfg): <tscreen><verb> SYMBOLS { - __STACKSIZE__ = $800; # 2K stack - __RESERVED_MEMORY__: value = $0000, weak = yes; + __STACKSIZE__: value = $800 type = weak; # 2K stack + __RESERVED_MEMORY__: value = $0000, type = weak; } FEATURES { STARTADDRESS: default = $2E00; @@ -391,18 +721,22 @@ FEATURES { MEMORY { ZP: start = $82, size = $7E, type = rw, define = yes; - HEADER: start = $0000, size = $6, file = %O; # first load chunk + HEADER: start = $0000, size = $2, file = %O; # first load chunk + + FSTHDR: start = $0000, size = $4, file = %O; # second load chunk RAMLO: start = %S, size = $4000 - %S, file = %O; - BANK: start = $4000, size = $4000, file = ""; + DISCARD: start = $4000, size = $4000, file = ""; SECHDR: start = $0000, size = $4, file = %O; # second load chunk RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F } SEGMENTS { - EXEHDR: load = BANK, type = ro; + EXEHDR: load = HEADER, type = ro; - NEXEHDR: load = HEADER, type = ro; # first load chunk + MAINHDR: load = DISCARD, type = ro; + + NEXEHDR: load = FSTHDR, type = ro; # first load chunk STARTUP: load = RAMLO, type = ro, define = yes; LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes; INIT: load = RAMLO, type = ro, optional = yes; @@ -412,7 +746,6 @@ SEGMENTS { RODATA: load = RAM, type = ro, define = yes; DATA: load = RAM, type = rw, define = yes; BSS: load = RAM, type = bss, define = yes; - ZPSAVE: load = RAM, type = bss, define = yes; ZEROPAGE: load = ZP, type = zp; AUTOSTRT: load = RAM, type = ro; # defines program entry point @@ -430,12 +763,13 @@ FEATURES { </verb></tscreen> <p> -A new memory area BANK was added which describes the reserved area. -It gets loaded with the contents of the old EXEHDR segment. But the +A new memory area DISCARD was added. +It gets loaded with the contents of the (now unused) MAINHDR segment. But the memory area isn't written to the output file. This way the contents of -the EXEHDR segment get discarded. +the MAINHDR segment get discarded. <p> -The newly added NEXEHDR segment defines the correct EXE header. It +The newly added NEXEHDR segment defines the correct chunk header for the +first intended load chunk. It puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the segments containing only code, into load chunk #1 (RAMLO memory area). <p> @@ -451,7 +785,6 @@ file (split.s): .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__ .segment "NEXEHDR" - .word $FFFF .word __STARTUP_LOAD__ .word __CODE_LOAD__ + __CODE_SIZE__ - 1 @@ -473,8 +806,8 @@ CODE, BSS, ZPSAVE into high memory (split2.cfg): <tscreen><verb> SYMBOLS { - __STACKSIZE__ = $800; # 2K stack - __RESERVED_MEMORY__: value = $0000, weak = yes; + __STACKSIZE__: value = $800 type = weak; # 2K stack + __RESERVED_MEMORY__: value = $0000, type = weak; } FEATURES { STARTADDRESS: default = $2E00; @@ -482,18 +815,22 @@ FEATURES { MEMORY { ZP: start = $82, size = $7E, type = rw, define = yes; - HEADER: start = $0000, size = $6, file = %O; # first load chunk + HEADER: start = $0000, size = $2, file = %O; # first load chunk + + FSTHDR: start = $0000, size = $4, file = %O; # second load chunk RAMLO: start = %S, size = $4000 - %S, file = %O; - BANK: start = $4000, size = $4000, file = ""; + DISCARD: start = $4000, size = $4000, file = ""; SECHDR: start = $0000, size = $4, file = %O; # second load chunk RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F } SEGMENTS { - EXEHDR: load = BANK, type = ro; # discarded old EXE header + EXEHDR: load = HEADER, type = ro; # discarded old EXE header - NEXEHDR: load = HEADER, type = ro; # first load chunk + MAINHDR: load = DISCARD, type = ro; + + NEXEHDR: load = FSTHDR, type = ro; # first load chunk RODATA: load = RAMLO, type = ro, define = yes; DATA: load = RAMLO, type = rw, define = yes; @@ -501,7 +838,6 @@ SEGMENTS { STARTUP: load = RAM, type = ro, define = yes; INIT: load = RAM, type = ro, optional = yes; CODE: load = RAM, type = ro, define = yes; - ZPSAVE: load = RAM, type = bss, define = yes; BSS: load = RAM, type = bss, define = yes; ZEROPAGE: load = ZP, type = zp; @@ -521,17 +857,16 @@ FEATURES { New contents for NEXEHDR and CHKHDR are needed (split2.s): <tscreen><verb> - .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__ + .import __STARTUP_LOAD__, __BSS_LOAD__, __DATA_SIZE__ .import __DATA_LOAD__, __RODATA_LOAD__ .segment "NEXEHDR" - .word $FFFF .word __RODATA_LOAD__ .word __DATA_LOAD__ + __DATA_SIZE__ - 1 .segment "CHKHDR" .word __STARTUP_LOAD__ - .word __ZPSAVE_LOAD__ - 1 + .word __BSS_LOAD__ - 1 </verb></tscreen> Compile with @@ -542,7 +877,7 @@ cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s <sect2>Final note<label id="memhole_final_note"><p> There are two other memory areas which don't appear directly in the -linker script. They are the stack and the heap. +linker config file. They are the stack and the heap. The cc65 runtime lib places the stack location at the end of available memory. This is dynamically set from the MEMTOP system variable at @@ -556,14 +891,47 @@ common/_heap.s defines the location of the heap and atari/crt0.s defines the location of the stack by initializing sp. -<sect>Bugs/Feedback<p> +<sect1>Upgrading from an older cc65 version<p> -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org"> or <htmlurl url="mailto:chris@groessler.org" -name="chris@groessler.org"> ). +If you are using a customized linker config file you might get some errors +regarding the MAINHDR segment. Like this: +<tscreen><verb> +ld65: Error: Missing memory area assignment for segment `MAINHDR' +</verb></tscreen> + +The old "HEADER" memory description contained six bytes: $FFFF +and the first and last memory addess of the program. For the "system +check" load chunk this had to be split into two memory assigments. The +"HEADER" now only contains the $FFFF. The main program's first +and last memory address were moved to a new segment, called "MAINHDR", +which in the new linker config file goes into its own memory area (also +called "MAINHDR").&nl;&nl; +A simple way to adapt your old linker config file is to add the +following line to the "SEGMENTS" section: + +<tscreen><verb> +MAINHDR: load = HEADER, type = ro; +</verb></tscreen> + + + +<sect1>Getting rid of the "system check" load chunk<label id="nosyschk"><p> + +If, for some reason, you don't want to include the "system check" load +chunk, you can do so by defining the symbol <tt/__SYSTEM_CHECK__/ when linking the +program. The "system check" chunk doesn't include vital parts of the +program. So if you don't want the system checks, it is save to leave them out. +This is probably mostly interesting for debugging. + +When using cl65, you can leave it out with this command line: + +<tscreen><verb> +cl65 -Wl -D__SYSTEM_CHECK__=1 <arguments> +</verb></tscreen> + +The value you assign to <tt/__SYSTEM_CHECK_/ doesn't matter. If the +<tt/__SYSTEM_CHECK__/ symbol is defined, the load chunk won't be included. <sect>License<p> diff --git a/doc/atmos.sgml b/doc/atmos.sgml index 8e24c92a1..82aef6c31 100644 --- a/doc/atmos.sgml +++ b/doc/atmos.sgml @@ -112,14 +112,14 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3)/</tag> + <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3_tgi)/</tag> This driver was written by Greg King and Stefan Haubenthal. It features a resolution of 228×200 with a palette of two colors that can be chosen from the Atmos's eight colors. The driver supports a third palette-"color" that actually "flips" the pixel (it becomes the other color) that is on the screen under the graphics cursor. - <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag> + <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2_tgi)/</tag> This driver was written by Stefan Haubenthal and Greg King. It features a resolution of 240×200 with black and white colors. It is the default graphics driver for the Atmos. @@ -136,7 +136,7 @@ No extended memory drivers are currently available for the Atmos. <descrip> - <tag><tt/atmos-pase.joy (atmos_pase)/</tag> + <tag><tt/atmos-pase.joy (atmos_pase_joy)/</tag> Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos. </descrip><p> @@ -151,7 +151,7 @@ No mouse drivers are currently available for the Atmos. <descrip> - <tag><tt/atmos-acia.ser (atmos_acia)/</tag> + <tag><tt/atmos-acia.ser (atmos_acia_ser)/</tag> Driver for the Telestrat integrated serial controller and the Atmos with a serial add-on. Note that because of the peculiarities of the 6551 chip together with the @@ -224,15 +224,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/c128.sgml b/doc/c128.sgml index 37cdd25f8..5ea44b970 100644 --- a/doc/c128.sgml +++ b/doc/c128.sgml @@ -168,13 +168,13 @@ Note: The graphics drivers for the VDC are incompatible with the extended memory drivers using the VDC memory! <descrip> - <tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag> + <tag><tt/c128-vdc.tgi (c128_vdc_tgi)/</tag> This driver was written by Maciej Witkowiak. It uses the 80 column display and features a resolution of 640*200 with two colors and an adjustable palette (that means that the two colors can be chosen out of the 16 VDC colors). - <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag> + <tag><tt/c128-vdc2.tgi (c128_vdc2_tgi)/</tag> This driver was written by Maciej Witkowiak. This driver uses the 80 column display and features a resolution of 640*480 with two colors and an adjustable palette (that means that the two colors can be chosen out of the @@ -189,17 +189,16 @@ missing on VDC and are translated to the two colors missing from VIC palette. <descrip> - <tag><tt/c128-georam.emd (c128_georam)/</tag> + <tag><tt/c128-georam.emd (c128_georam_emd)/</tag> A driver for the GeoRam cartridge. The driver will always assume 2048 pages of 256 bytes each. There are no checks, so if your program knows better, just go ahead. - <tag><tt/c128-ram.emd (c128_ram)/</tag> + <tag><tt/c128-ram.emd (c128_ram_emd)/</tag> An extended memory driver for the RAM in page 1. The common memory area is excluded, so this driver supports 251 pages of 256 bytes each. - <tag><tt/c128-ram2.emd (c128_ram2)/</tag> - + <tag><tt/c128-ram2.emd (c128_ram2_emd)/</tag> An extended memory driver for the RAM in pages 1-3. The common memory area is excluded, so this driver supports up to 731 pages of 256 bytes each. The driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM @@ -207,17 +206,17 @@ missing on VDC and are translated to the two colors missing from VIC palette. machines with RAM in banks 2+3, so it has been made a separate driver. The additional code was contributed by Marco van den Heuvel. - <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag> + <tag><tt/c128-ramcart.emd (c128_ramcart_emd)/</tag> A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. Will test the hardware for the available RAM. - <tag><tt/c128-reu.emd (c128_reu)/</tag> + <tag><tt/c128-reu.emd (c128_reu_emd)/</tag> A driver for the CBM REUs. The driver will determine from the connected REU if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, but since there are no range checks, the application can use more memory if it has better knowledge about the hardware than the driver. - <tag><tt/c128-vdc.emd (c128_vdc)/</tag> + <tag><tt/c128-vdc.emd (c128_vdc_emd)/</tag> A driver for the VDC memory of the C128 written and contributed by Maciej Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers 64 or 256 pages of 256 bytes each. Note: This driver is incompatible with @@ -230,14 +229,14 @@ missing on VDC and are translated to the two colors missing from VIC palette. <descrip> - <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag> + <tag><tt/c128-ptvjoy.joy (c128_ptvjoy_joy)/</tag> Driver for the Protovision 4-player adapter originally written by Groepaz for the C64 and converted for the C128 by me. See <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and building instructions. Up to four joysticks are supported. - <tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag> + <tag><tt/c128-stdjoy.joy (c128_stdjoy_joy)/</tag> Supports up to two joysticks connected to the standard joysticks port of the C128. @@ -249,14 +248,21 @@ missing on VDC and are translated to the two colors missing from VIC palette. <descrip> - <tag><tt/c128-1351.mou (c128_1351)/</tag> + <tag><tt/c128-1351.mou (c128_1351_mou)/</tag> Supports a standard mouse connected to port #0 of the C128. - <tag><tt/c128-joy.mou (c128_joymouse)/</tag> + <tag><tt/c128-inkwell.mou (c128_inkwell_mou)/</tag> + Supports the Inkwell Systems lightpens, connected to port #0 of the + C128. It can read both the one-button 170-C and the two-button 184-C pens. + (It can read other lightpens and light-guns that send their button signal to + the joystick left-button pin or the paddle Y [up/down] pin.) It works on + only the 40-column screen. + + <tag><tt/c128-joy.mou (c128_joy_mou)/</tag> Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port #1 of the C128. - <tag><tt/c128-pot.mou (c128_potmouse)/</tag> + <tag><tt/c128-pot.mou (c128_pot_mou)/</tag> Supports a potentiometer device e.g. Koala Pad connected to port #1 of the C128. @@ -267,7 +273,7 @@ missing on VDC and are translated to the two colors missing from VIC palette. <descrip> - <tag><tt/c128-swlink.ser (c128_swlink)/</tag> + <tag><tt/c128-swlink.ser (c128_swlink_ser)/</tag> Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip together with the use of the NMI, transmits @@ -323,15 +329,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/c16.sgml b/doc/c16.sgml index 110082a19..5d4a5d372 100644 --- a/doc/c16.sgml +++ b/doc/c16.sgml @@ -160,7 +160,7 @@ No graphics drivers are currently available for the C16/C116. <descrip> - <tag><tt/c16-ram.emd (c16_ram)/</tag> + <tag><tt/c16-ram.emd (c16_ram_emd)/</tag> A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125 pages with 256 bytes each if the machine is equipped with 64K of memory (a Plus/4 or a memory extended C16/116). @@ -173,7 +173,7 @@ No graphics drivers are currently available for the C16/C116. <descrip> - <tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag> + <tag><tt/c16-stdjoy.joy (c16_stdjoy_joy)/</tag> Supports up to two joysticks connected to the standard joysticks port of the Commodore 16/116. @@ -183,8 +183,7 @@ No graphics drivers are currently available for the C16/C116. <sect1>Mouse drivers<p> -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). +No mouse drivers are currently available for the C16/C116. <sect1>RS232 device drivers<p> @@ -237,15 +236,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/c64.sgml b/doc/c64.sgml index 2e6a37e77..a5014414c 100644 --- a/doc/c64.sgml +++ b/doc/c64.sgml @@ -65,15 +65,15 @@ Special locations: <sect>Linker configurations<p> -The ld65 linker comes with a builtin config file for the Commodore 64, -which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The +The ld65 linker comes with a default config file for the Commodore 64, +which is used via <tt/-t c64/. The c64 package comes with additional secondary linker config files, which are -used via <tt/-C <configfile>/. +used via <tt/-t c64 -C <configfile>/. -<sect1>builtin config file<p> +<sect1>default config file (<tt/c64.cfg/)<p> -The builtin configuration is tailored to C programs. It supplies the load +The default configuration is tailored to C programs. It supplies the load address and a small BASIC stub that starts the compiled program using a SYS command. @@ -210,7 +210,7 @@ the standard setup without any memory loss or need for a changed configuration. <descrip> - <tag><tt/c64-hi.tgi (c64_320_200_2)/</tag> + <tag><tt/c64-hi.tgi (c64_hi_tgi)/</tag> This driver features a resolution of 320*200 with two colors and an adjustable palette (that means that the two colors can be chosen out of a palette of the 16 C64 colors). @@ -221,45 +221,45 @@ configuration. <descrip> - <tag><tt/c64-c256k.emd (c64_c256k)/</tag> + <tag><tt/c64-c256k.emd (c64_c256k_emd)/</tag> A driver for the C64 256K memory expansion. This driver offers 768 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. - <tag><tt/c64-dqbb.emd (c64_dqbb)/</tag> + <tag><tt/c64-dqbb.emd (c64_dqbb_emd)/</tag> A driver for the Double Quick Brown Box cartridge. This driver offers 64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. - <tag><tt/c64-georam.emd (c64_georam)/</tag> + <tag><tt/c64-georam.emd (c64_georam_emd)/</tag> A driver for the Berkeley Softworks GeoRam cartridge. The driver will determine the available RAM from the connected cartridge. It supports 64KB up to 2048KB of RAM. - <tag><tt/c64-isepic.emd (c64_isepic)/</tag> + <tag><tt/c64-isepic.emd (c64_isepic_emd)/</tag> A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. - <tag><tt/c64-ram.emd (c64_ram)/</tag> + <tag><tt/c64-ram.emd (c64_ram_emd)/</tag> A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 256 byte pages. Please note that this driver is incompatible with any of the graphics drivers! - <tag><tt/c64-ramcart.emd (c64_ramcart)/</tag> + <tag><tt/c64-ramcart.emd (c64_ramcart_emd)/</tag> A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. Will test the hardware for the available RAM. - <tag><tt/c64-reu.emd (c64_reu)/</tag> + <tag><tt/c64-reu.emd (c64_reu_emd)/</tag> A driver for the CBM REUs. The driver will determine from the connected REU if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, but since there are no range checks, the application can use more memory if it has better knowledge about the hardware than the driver. - <tag><tt/c64-vdc.emd (c64_vdc)/</tag> + <tag><tt/c64-vdc.emd (c64_vdc_emd)/</tag> A driver for the VDC memory of the C128. Written and contributed by Maciej Witkowiak. Can be used if the program is running in C64 mode of the C128. Autodetects the amount of memory available (16 or 64K) and offers 64 or 256 pages of 256 bytes each. - <tag><tt/dtv-himem.emd (dtv_himem)/</tag> + <tag><tt/dtv-himem.emd (dtv_himem_emd)/</tag> A driver for the C64 D2TV (the second or PAL version). This driver offers indeed 7680 pages of 256 bytes each. @@ -270,23 +270,23 @@ configuration. <descrip> - <tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag> + <tag><tt/c64-hitjoy.joy (c64_hitjoy_joy)/</tag> Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See <htmlurl url="http://www.digitalexcess.de/downloads/productions.php" name="http://www.digitalexcess.de/downloads/productions.php"> on instructions how to build one. Up to four joysticks are supported. - <tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag> + <tag><tt/c64-ptvjoy.joy (c64_ptvjoy_joy)/</tag> Driver for the Protovision 4-player adapter contributed by Groepaz. See <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and building instructions. Up to four joysticks are supported. - <tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag> + <tag><tt/c64-stdjoy.joy (c64_stdjoy_joy)/</tag> Supports up to two standard joysticks connected to the joysticks port of the C64. - <tag><tt/c64-numpad.joy (c64_numpad)/</tag> + <tag><tt/c64-numpad.joy (c64_numpad_joy)/</tag> Supports one joystick emulated by the numberpad of the C128 in C64 mode, the firebutton is labeled &dquot;5&dquot; and ENTER. @@ -297,14 +297,20 @@ configuration. <descrip> - <tag><tt/c64-1351.mou (c64_1351)/</tag> + <tag><tt/c64-1351.mou (c64_1351_mou)/</tag> Supports a standard mouse connected to port #0 of the C64. - <tag><tt/c64-joy.mou (c64_joymouse)/</tag> + <tag><tt/c64-inkwell.mou (c64_inkwell_mou)/</tag> + Supports the Inkwell Systems lightpens, connected to port #0 of the C64. + It can read both the one-button 170-C and the two-button 184-C pens. (It can + read other lightpens and light-guns that send their button signal to the + joystick left-button pin or the paddle Y [up/down] pin.) + + <tag><tt/c64-joy.mou (c64_joy_mou)/</tag> Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port #1 of the C64. - <tag><tt/c64-pot.mou (c64_potmouse)/</tag> + <tag><tt/c64-pot.mou (c64_pot_mou)/</tag> Supports a potentiometer device e.g. Koala Pad connected to port #1 of the C64. @@ -315,7 +321,7 @@ configuration. <descrip> - <tag><tt/c64-swlink.ser (c64_swlink)/</tag> + <tag><tt/c64-swlink.ser (c64_swlink_ser)/</tag> Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip together with the use of the NMI, transmits @@ -372,15 +378,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 00d72db56..c1c314a2c 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -112,14 +112,12 @@ Long options: --debug Debug mode --debug-info Add debug info to object file --feature name Set an emulation feature - --forget-inc-paths Forget include search paths --help Help (this text) --ignore-case Ignore case of symbols --include-dir dir Set an include directory search path --large-alignment Don't warn about large alignments --listing name Create a listing file if assembly was ok --list-bytes n Maximum number of bytes per listing line - --macpack-dir dir Set a macro package directory --memory-model model Set the memory model --pagelength n Set the page length for the listing --relax-checks Relax some checks (see docs) @@ -195,14 +193,6 @@ Here is a description of all the command line options: command for a list of emulation features. - <label id="option--forget-inc-paths"> - <tag><tt>--forget-inc-paths</tt></tag> - - Forget the builtin include paths. This is most useful when building - customized assembler modules, in which case the standard header files should - be ignored. - - <label id="option-g"> <tag><tt>-g, --debug-info</tt></tag> @@ -251,17 +241,6 @@ Here is a description of all the command line options: number of printed bytes. - <label id="option--macpack-dir"> - <tag><tt>--macpack-dir dir</tt></tag> - - This options allows to specify a directory containing macro files that are - used instead of the builtin images when a <tt><ref id=".MACPACK" - name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt> - was specified, a <tt>.mac</tt> extension is added to the package name and - the resulting file is loaded from the given directory. This is most useful - when debugging the builtin macro packages. - - <label id="option-mm"> <tag><tt>-mm model, --memory-model model</tt></tag> @@ -393,20 +372,19 @@ Here is a description of all the command line options: Normal include files are searched in the following places: <enum> -<item>The current directory. -<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt> - on Linux systems. +<item>The current file's directory. +<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option +on the command line. <item>The value of the environment variable <tt/CA65_INC/ if it is defined. <item>A subdirectory named <tt/asminc/ of the directory defined in the environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option -on the command line. +<item>An optionally compiled-in directory. </enum> Binary include files are searched in the following places: <enum> -<item>The current directory. +<item>The current file's directory. <item>Any directory added with the <tt/<ref id="option--bin-include-dir" name="--bin-include-dir">/ option on the command line. </enum> @@ -4319,6 +4297,15 @@ Currently defined macros are: beq Arg bcc Arg .endmacro + + .macro bnz Arg + bne Arg + .endmacro + + .macro bze Arg + beq Arg + .endmacro + </verb></tscreen> @@ -4430,22 +4417,28 @@ For better orthogonality, the assembler defines similar symbols as the compiler, depending on the target system selected: <itemize> -<item><tt/__APPLE2__/ - Target system is <tt/apple2/ +<item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/ <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ -<item><tt/__ATARI__/ - Target system is <tt/atari/ +<item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/ +<item><tt/__ATARIXL__/ - Target system is <tt/atarixl/ <item><tt/__ATMOS__/ - Target system is <tt/atmos/ <item><tt/__BBC__/ - Target system is <tt/bbc/ <item><tt/__C128__/ - Target system is <tt/c128/ -<item><tt/__C16__/ - Target system is <tt/c16/ +<item><tt/__C16__/ - Target system is <tt/c16/ or <tt/plus4/ <item><tt/__C64__/ - Target system is <tt/c64/ <item><tt/__CBM__/ - Target is a Commodore system <item><tt/__CBM510__/ - Target system is <tt/cbm510/ <item><tt/__CBM610__/ - Target system is <tt/cbm610/ -<item><tt/__GEOS__/ - Target system is <tt/geos/ +<item><tt/__GEOS__/ - Target is a GEOS system +<item><tt/__GEOS_APPLE__/ - Target system is <tt/geos-apple/ +<item><tt/__GEOS_CBM__/ - Target system is <tt/geos-cbm/ <item><tt/__LUNIX__/ - Target system is <tt/lunix/ +<item><tt/__LYNX__/ - Target system is <tt/lynx/ <item><tt/__NES__/ - Target system is <tt/nes/ <item><tt/__PET__/ - Target system is <tt/pet/ <item><tt/__PLUS4__/ - Target system is <tt/plus4/ +<item><tt/__SIM6502__/ - Target system is <tt/sim6502/ +<item><tt/__SIM65C02__/ - Target system is <tt/sim65c02/ <item><tt/__SUPERVISION__/ - Target system is <tt/supervision/ <item><tt/__VIC20__/ - Target system is <tt/vic20/ </itemize> @@ -4744,15 +4737,6 @@ are used for the cbm load address. </enum> -<sect>Bugs/Feedback<p> - -If you have problems using the assembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to -hear from you. Feel free to contact me by email -(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - <sect>Copyright<p> ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml index 8b26be44c..68dd2507f 100644 --- a/doc/ca65html.sgml +++ b/doc/ca65html.sgml @@ -248,15 +248,6 @@ that you have to pay for color. </enum> -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the assembler, I would be glad to hear from -you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml index 0dc842bc1..75497d977 100644 --- a/doc/cbm510.sgml +++ b/doc/cbm510.sgml @@ -3,9 +3,10 @@ <article> <title>Commodore 510 (aka P500) specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> -<date>2006-05-22 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">&nl; +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">&nl; +<htmlurl url="mailto:greg.king5@verizon.net" name="Greg King"> +<date>2013-08-23 <abstract> An overview over the Commodore 510 runtime system as it is implemented for the @@ -184,7 +185,7 @@ No graphics drivers are currently available for the Commodore 510. <sect1>Extended memory drivers<p> <descrip> - <tag><tt/cbm510-ram.emd (cbm510_ram)/</tag> + <tag><tt/cbm510-ram.emd (cbm510_ram_emd)/</tag> A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes each. </descrip><p> @@ -194,7 +195,7 @@ No graphics drivers are currently available for the Commodore 510. <descrip> - <tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag> + <tag><tt/cbm510-std.joy (cbm510_std_joy)/</tag> Supports up to two standard joysticks connected to the joysticks port of the Commodore 510. @@ -203,14 +204,27 @@ No graphics drivers are currently available for the Commodore 510. <sect1>Mouse drivers<p> -No mouse drivers are currently available for the Commodore 510. +<descrip> + <tag><tt/cbm510-joy.mou (cbm510_joy_mou)/</tag> + Supports a mouse that is emulated by a standard joystick, e.g. 1350 + mouse, in joystick port #2 of the CBM510. That stick's fire button acts as + the left mouse button. The fire button of a stick in joystick port #1 can + act as the right mouse button. + + <tag><tt/cbm510-inkwl.mou (cbm510_inkwl_mou)/</tag> + Supports the Inkwell Systems lightpens, connected to port #1 of the CBM510. + It can read both the 170-C and one button of the 184-C pens. (It can + read other lightpens and light-guns that send their button signal to the + joystick left-button pin.) + +</descrip><p> <sect1>RS232 device drivers<p> <descrip> - <tag><tt/cbm510-std.ser (cbm510_stdser)/</tag> + <tag><tt/cbm510-std.ser (cbm510_std_ser)/</tag> Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -268,15 +282,6 @@ code when they are linked into a program. See the discussion of the -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml index 5acb38a1a..a6ec4650b 100644 --- a/doc/cbm610.sgml +++ b/doc/cbm610.sgml @@ -186,7 +186,7 @@ really good:-). <sect1>Extended memory drivers<p> <descrip> - <tag><tt/cbm610-ram.emd (cbm610_ram)/</tag> + <tag><tt/cbm610-ram.emd (cbm610_ram_emd)/</tag> A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes each. </descrip><p> @@ -201,15 +201,14 @@ are no drivers for the non existing ports available. <sect1>Mouse drivers<p> -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). +No mouse drivers are currently available for the Commodore 610. <sect1>RS232 device drivers<p> <descrip> - <tag><tt/cbm610-std.ser (cbm610_stdser)/</tag> + <tag><tt/cbm610-std.ser (cbm610_std_ser)/</tag> Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -267,15 +266,6 @@ code when they are linked into a program. See the discussion of the -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/cc65.sgml b/doc/cc65.sgml index bb1303909..ab7632718 100644 --- a/doc/cc65.sgml +++ b/doc/cc65.sgml @@ -88,7 +88,6 @@ Long options: --dep-target target Use this dependency target --disable-opt name Disable an optimization step --enable-opt name Enable an optimization step - --forget-inc-paths Forget include search paths --help Help (this text) --include-dir dir Set an include directory search path --list-opt-steps List all optimizer steps and exit @@ -204,13 +203,6 @@ Here is a description of all the command line options: is defined to the value "1". - <tag><tt>--forget-inc-paths</tt></tag> - - Forget the builtin include paths. This is most useful when building - customized C or runtime libraries, in which case the standard header - files should be ignored. - - <tag><tt>-g, --debug-info</tt></tag> This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the @@ -344,6 +336,7 @@ Here is a description of all the command line options: <item>apple2 <item>apple2enh <item>atari + <item>atarixl <item>atmos <item>c16 (works also for the c116 with memory up to 32K) <item>c64 @@ -357,6 +350,8 @@ Here is a description of all the command line options: <item>nes <item>pet (all CBM PET systems except the 2001) <item>plus4 + <item>sim6502 + <item>sim65c02 <item>supervision <item>vic20 </itemize> @@ -514,24 +509,23 @@ Here is a description of all the command line options: The compiler will accept one C file per invocation and create a file with the same base name, but with the extension replaced by ".s". The output -file contains assembler code suitable for the use with the ca65 macro +file contains assembler code suitable for use with the ca65 macro assembler. -Include files in single quotes are searched in the following places: +Include files in quotes are searched in the following places: <enum> -<item>The current directory. -<item>The value of the environment variable <tt/CC65_INC/ if it is defined. +<item>The current file's directory. <item>Any directory added with the <tt/-I/ option on the command line. +<item>The value of the environment variable <tt/CC65_INC/ if it is defined. </enum> Include files in angle brackets are searched in the following places: <enum> -<item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on - Linux systems. +<item>Any directory added with the <tt/-I/ option on the command line. <item>The value of the environment variable <tt/CC65_INC/ if it is defined. <item>A subdirectory named <tt/include/ of the directory defined in the environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt/-I/ option on the command line. +<item>An optionally compiled-in directory. </enum> @@ -709,7 +703,7 @@ The compiler defines several macros at startup: <descrip> <tag><tt>__APPLE2__</tt></tag> - This macro is defined if the target is the Apple ][ (-t apple2). + This macro is defined if the target is the Apple ][ (-t apple2) or the enhanced Apple //e (-t apple2enh). <tag><tt>__APPLE2ENH__</tt></tag> @@ -717,8 +711,11 @@ The compiler defines several macros at startup: <tag><tt>__ATARI__</tt></tag> - This macro is defined if the target is one of the Atari computers - (400/800/130XL/800XL). + This macro is defined if the target is the Atari 400/800 (-t atari) or the Atari 800XL/130XE (-t atarixl). + + <tag><tt>__ATARIXL__</tt></tag> + + This macro is defined if the target is the Atari 800XL/130XE (-t atarixl). <tag><tt>__ATMOS__</tt></tag> @@ -726,15 +723,15 @@ The compiler defines several macros at startup: <tag><tt>__C128__</tt></tag> - This macro is defined if the target is the c128 (-t c128). + This macro is defined if the target is the Commodore 128 (-t c128). <tag><tt>__C16__</tt></tag> - This macro is defined if the target is the c16 (-t c16). + This macro is defined if the target is the Commodore 16/116 (-t c16) or the Commodore Plus/4 (-t plus4). <tag><tt>__C64__</tt></tag> - This macro is defined if the target is the c64 (-t c64). + This macro is defined if the target is the Commodore 64 (-t c64). <tag><tt>__CBM__</tt></tag> @@ -776,7 +773,15 @@ The compiler defines several macros at startup: <tag><tt>__GEOS__</tt></tag> - This macro is defined if you are compiling for the GEOS system (-t geos). + This macro is defined if you are compiling for one of the GEOS systems. + + <tag><tt>__GEOS_APPLE__</tt></tag> + + This macro is defined if you are compiling for the Apple GEOS system (-t geos-apple). + + <tag><tt>__GEOS_CBM__</tt></tag> + + This macro is defined if you are compiling for the GEOS 64/128 system (-t geos-cbm). <tag><tt>__LINE__</tt></tag> @@ -792,7 +797,7 @@ The compiler defines several macros at startup: <tag><tt>__NES__</tt></tag> - This macro is defined if the target is the NES (-t nes). + This macro is defined if the target is the Nintendo Entertainment System (-t nes). <tag><tt>__OPT__</tt></tag> @@ -816,15 +821,22 @@ The compiler defines several macros at startup: <tag><tt>__PLUS4__</tt></tag> - This macro is defined if the target is the plus/4 (-t plus4). + This macro is defined if the target is the Commodore Plus/4 (-t plus4). <tag><tt>__STDC_HOSTED__</tt></tag> This macro is expands to the integer constant 1. + <tag><tt>__SIM6502__</tt></tag> + + This macro is defined if the target is sim65 in 6502 mode (-t sim6502). + + <tag><tt>__SIM65C02__</tt></tag> + This macro is defined if the target is sim65 in 65C02 mode (-t sim65c02). + <tag><tt>__SUPERVISION__</tt></tag> - This macro is defined if the target is the supervision (-t supervision). + This macro is defined if the target is the Supervision (-t supervision). <tag><tt>__TIME__</tt></tag> @@ -833,7 +845,7 @@ The compiler defines several macros at startup: <tag><tt>__VIC20__</tt></tag> - This macro is defined if the target is the vic20 (-t vic20). + This macro is defined if the target is the Commodore VIC20 (-t vic20). </descrip> @@ -1308,15 +1320,6 @@ behavior as implementation-defined. (to be done) -<sect>Bugs/Feedback<p> - -If you have problems using the compiler, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> This is the original compiler copyright: diff --git a/doc/cl65.sgml b/doc/cl65.sgml index a574049cc..2667ab555 100644 --- a/doc/cl65.sgml +++ b/doc/cl65.sgml @@ -88,7 +88,6 @@ Long options: --debug-info Add debug info --feature name Set an emulation feature --force-import sym Force an import of symbol `sym' - --forget-inc-paths Forget include search paths (compiler) --help Help (this text) --include-dir dir Set a compiler include directory path --ld-args options Pass options to the linker @@ -277,14 +276,6 @@ to do this. -<sect>Bugs/Feedback<p> - -If you have problems using the utility, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - <sect>Copyright<p> cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von diff --git a/doc/co65.sgml b/doc/co65.sgml index 126ed56fd..ea75dcf7c 100644 --- a/doc/co65.sgml +++ b/doc/co65.sgml @@ -316,15 +316,6 @@ will get an "undefined external" error for the _c64_hi symbol. -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the code, I would be glad to hear from you. -Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries diff --git a/doc/da65.sgml b/doc/da65.sgml index 58d031eff..4dd6800d5 100644 --- a/doc/da65.sgml +++ b/doc/da65.sgml @@ -651,15 +651,6 @@ directives explained above: -<sect>Bugs/Feedback<p> - -If you have problems using the disassembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to hear -from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von diff --git a/doc/index.sgml b/doc/index.sgml index e0b110ead..ef8e56327 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -2,12 +2,8 @@ <article> <title>cc65 Documentation Overview -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2005-8-6 - -<abstract> -Main documentation page, contains links to other available stuff. -</abstract> +<author><htmlurl url="https://github.com/oliverschmidt/cc65" name=""> +<date> <sect>Program documentation<p> @@ -60,9 +56,6 @@ Main documentation page, contains links to other available stuff. <tag><htmlurl url="coding.html" name="coding.html"></tag> Contains hints on creating the most effective code with cc65. - <tag><htmlurl url="compile.txt" name="compile.txt"></tag> - How to compile cc65 and the support tools. - <tag><htmlurl url="using-make.html" name="using-make.html"></tag> Build programs, using the GNU Make utility. @@ -159,21 +152,5 @@ Main documentation page, contains links to other available stuff. </descrip> -<sect>Miscellaneous<p> - -<descrip> - - <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> - Somewhat outdated. Lists the differences between my cc65 releases - and the original Atari version that was created by J. R. Dunning. - - <tag><htmlurl url="BUGS" name="BUGS"></tag> - Known cc65 bugs. - - <tag><htmlurl url="CREDITS" name="CREDITS"></tag> - Here is who helped with the compiler and other tools. - -</descrip> - </article> diff --git a/doc/intro.sgml b/doc/intro.sgml index c5ef7956a..1db4c0c04 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -371,12 +371,12 @@ The emulation, also, supports that method. <sect2>VICE<p> Available at <url -url="http://www.viceteam.org/">: +url="http://vice-emu.sourceforge.net/">: Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports -printers, serial port and adapters, stereo sound, disk drives and images, RAM -expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, -and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2, +printers, serial port and adapters, stereo sound, disk drives and images, RAM expansions, +cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, graphics tablet, +lightpens, and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2, BeOS x86, Acorn RISC OS, and most Unixes. Compile the tutorial with @@ -395,7 +395,7 @@ Substitute the name of a Commodore computer for that <tt/<sys>/: <item><tt/vic20/ </itemize> -Start the desired version of the emulator (CBM510 and CBM610 programs run on +Start the desired version of the emulator (CBM610 programs run on the CBM II [<tt/xcbm2/] emulator). In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape diff --git a/doc/ld65.sgml b/doc/ld65.sgml index 5330a21d9..4f74b04c1 100644 --- a/doc/ld65.sgml +++ b/doc/ld65.sgml @@ -76,7 +76,6 @@ Long options: --config name Use linker config file --dbgfile name Generate debug information --define sym=val Define a symbol - --dump-config name Dump a builtin configuration --end-group End a library group --force-import sym Force an import of symbol `sym' --help Help (this text) @@ -140,7 +139,7 @@ Here is a description of all the command line options: The -o switch is used to give the name of the default output file. Depending on your output configuration, this name may NOT be used as - name for the output file. However, for the builtin configurations, this + name for the output file. However, for the default configurations, this name is used for the output file name. @@ -148,7 +147,7 @@ Here is a description of all the command line options: <tag><tt>-t sys, --target sys</tt></tag> The argument for the -t switch is the name of the target system. Since this - switch will activate a builtin configuration, it may not be used together + switch will activate a default configuration, it may not be used together with the <tt><ref id="option-C" name="-C"></tt> option. The following target systems are currently supported: @@ -158,6 +157,7 @@ Here is a description of all the command line options: <item>apple2 <item>apple2enh <item>atari + <item>atarixl <item>atmos <item>c16 (works also for the c116 with memory up to 32K) <item>c64 @@ -171,6 +171,8 @@ Here is a description of all the command line options: <item>nes <item>pet (all CBM PET systems except the 2001) <item>plus4 + <item>sim6502 + <item>sim65c02 <item>supervision <item>vic20 </itemize> @@ -252,9 +254,9 @@ Here is a description of all the command line options: <tag><tt>-S addr, --start-addr addr</tt></tag> Using -S you may define the default starting address. If and how this - address is used depends on the config file in use. For the builtin + address is used depends on the config file in use. For the default configurations, only the "none", "apple2" and "apple2enh" systems honor an - explicit start address, all other builtin config provide their own. + explicit start address, all other default configs provide their own. <tag><tt>-V, --version</tt></tag> @@ -313,56 +315,53 @@ Here is a description of all the command line options: <sect>Search paths<p> -Starting with version 2.10 there are now several search paths for files needed -by the linker: One for libraries, one for object files and one for config +Starting with version 2.10, there are now several search-path lists for files needed +by the linker: one for libraries, one for object files, and one for config files. <sect1>Library search path<p> -The library search path contains in this order: +The library search-path list contains in this order: <enum> <item>The current directory. -<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on - Linux systems. +<item>Any directory added with the <tt><ref id="option--lib-path" + name="--lib-path"></tt> option on the command line. <item>The value of the environment variable <tt/LD65_LIB/ if it is defined. <item>A subdirectory named <tt/lib/ of the directory defined in the environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--lib-path" - name="--lib-path"></tt> option on the command line. +<item>An optionally compiled-in library path. </enum> <sect1>Object file search path<p> -The object file search path contains in this order: +The object file search-path list contains in this order: <enum> <item>The current directory. -<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on - Linux systems. +<item>Any directory added with the <tt><ref id="option--obj-path" + name="--obj-path"></tt> option on the command line. <item>The value of the environment variable <tt/LD65_OBJ/ if it is defined. <item>A subdirectory named <tt/obj/ of the directory defined in the environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--obj-path" - name="--obj-path"></tt> option on the command line. +<item>An optionally compiled-in directory. </enum> <sect1>Config file search path<p> -The config file search path contains in this order: +The config file search-path list contains in this order: <enum> <item>The current directory. -<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on - Linux systems. +<item>Any directory added with the <tt><ref id="option--cfg-path" + name="--cfg-path"></tt> option on the command line. <item>The value of the environment variable <tt/LD65_CFG/ if it is defined. <item>A subdirectory named <tt/cfg/ of the directory defined in the environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--cfg-path" - name="--cfg-path"></tt> option on the command line. +<item>An optionally compiled-in directory. </enum> @@ -1025,24 +1024,6 @@ __STACKSIZE__=xxx/ on the command line. -<sect1>Builtin configurations<p> - -The builtin configurations are part of the linker source. They can be retrieved -with <tt/--dump-config/ and don't have a special format. So if you need a -special configuration, it's a good idea to start with the builtin configuration -for your system. In a first step, just replace <tt/-t target/ by <tt/-C -configfile/. Then go on and modify the config file to suit your needs. - - - -<sect1>Secondary configurations<p> - -Several machine specific binary packages are distributed together with secondary -configurations (in the cfg directory). These configurations can be used with -<tt/-C configfile/ too. - - - <sect>Special segments<p> The builtin config files do contain segments that have a special meaning for @@ -1075,15 +1056,6 @@ initialized. -<sect>Bugs/Feedback<p> - -If you have problems using the linker, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von diff --git a/doc/library.sgml b/doc/library.sgml index 29a8ca063..6c2ced433 100644 --- a/doc/library.sgml +++ b/doc/library.sgml @@ -164,6 +164,7 @@ portable. conio implementations exist for the following targets: <item>apple2 <item>apple2enh <item>atari + <item>atarixl <item>atmos <item>c16 (works also for the c116 with up to 32K memory) <item>c64 @@ -187,8 +188,7 @@ which define constants for special characters and keys. For systems that have a joystick, <tt/joystick.h/ will define a subroutine to read the current value, including constants to evaluate the result of this -function. To help in writing portable code, the header file will define the -symbol <tt/__JOYSTICK__/ on systems that have a joystick. +function. @@ -201,23 +201,12 @@ the following targets: <item>apple2 <item>apple2enh <item>atari + <item>atarixl <item>c64 <item>c128 - <item>cbm510 </itemize> -The available functions are declared in <tt/mouse.h/ To help writing portable -code, the header file will define the symbol <tt/__MOUSE__/ in systems that -support a mouse. - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - +The available functions are declared in <tt/mouse.h/. <sect>Copyright<p> diff --git a/doc/lynx.sgml b/doc/lynx.sgml index 48c3d7d4a..f83552e50 100644 --- a/doc/lynx.sgml +++ b/doc/lynx.sgml @@ -194,7 +194,7 @@ The names in the parentheses denote the symbols to be used for static linking of <descrip> - <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16)/</tag> + <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16_tgi)/</tag> A TGI driver for the standard graphics mode (160×102 in 16 colors). The TGI driver is implemented as an interrupt driven dual buffering device. @@ -243,7 +243,7 @@ No extended memory drivers are currently available for the Lynx. <descrip> - <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag> + <tag><tt/lynx-stdjoy.joy (lynx_stdjoy_joy)/</tag> A joystick driver for the standard buttons. </descrip><p> @@ -258,7 +258,7 @@ No mouse drivers are currently available for the Lynx. <descrip> - <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag> + <tag><tt/lynx-comlynx.ser (lynx_comlynx_ser)/</tag> A serial driver for the ComLynx port. The ComLynx port has Tx and Rx wired together. Every byte is sent @@ -327,15 +327,6 @@ cc65 drivers require. But for the time being you can create less portable applications using these Lynx specific modules in <tt/lynx-cart-demo/. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/nes.sgml b/doc/nes.sgml index c66b1f2ba..5d465c813 100644 --- a/doc/nes.sgml +++ b/doc/nes.sgml @@ -161,15 +161,6 @@ following functions (and a few others): -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/od65.sgml b/doc/od65.sgml index 2668b0b86..a1960109d 100644 --- a/doc/od65.sgml +++ b/doc/od65.sgml @@ -187,15 +187,6 @@ t.o: </verb></tscreen> -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the code, I would be glad to hear from you. -Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>Copyright<p> od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the diff --git a/doc/pet.sgml b/doc/pet.sgml index 35e794db5..6d816ad77 100644 --- a/doc/pet.sgml +++ b/doc/pet.sgml @@ -150,13 +150,13 @@ No extended memory drivers are currently available for the PET. <descrip> - <tag><tt/pet-ptvjoy.joy (pet_ptvjoy)/</tag> + <tag><tt/pet-ptvjoy.joy (pet_ptvjoy_joy)/</tag> Driver for the Protovision 4-player adapter contributed by Groepaz. See <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and building instructions. Up to two joysticks are supported. - <tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag> + <tag><tt/pet-stdjoy.joy (pet_stdjoy_joy)/</tag> Driver for the standard PET userport joystick. </descrip><p> @@ -228,15 +228,6 @@ the following code: </verb></tscreen> -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/plus4.sgml b/doc/plus4.sgml index eefb85e21..a16eef9d3 100644 --- a/doc/plus4.sgml +++ b/doc/plus4.sgml @@ -163,7 +163,7 @@ No extended memory drivers are currently available for the Plus/4. <descrip> - <tag><tt/plus4-stdjoy.joy (plus4_stdjoy)/</tag> + <tag><tt/plus4-stdjoy.joy (plus4_stdjoy_joy)/</tag> Supports up to two joysticks connected to the standard joysticks port of the Plus/4. @@ -172,15 +172,14 @@ No extended memory drivers are currently available for the Plus/4. <sect1>Mouse drivers<p> -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). +No mouse drivers are currently available for the Plus/4. <sect1>RS232 device drivers<p> <descrip> - <tag><tt/plus4-stdser.ser (plus4_stdser)/</tag> + <tag><tt/plus4-stdser.ser (plus4_stdser_ser)/</tag> Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note that because of the peculiarities of the 6551 chip transmits are not @@ -237,15 +236,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/sp65.sgml b/doc/sp65.sgml index 32dead645..3cf749e20 100644 --- a/doc/sp65.sgml +++ b/doc/sp65.sgml @@ -382,15 +382,6 @@ Possible attributes for this format are: -<sect>Bugs/Feedback<p> - -If you have problems using the assembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to -hear from you. Feel free to contact me by email -(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - <sect>Copyright<p> sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz diff --git a/doc/supervision.sgml b/doc/supervision.sgml index 504ba5194..0aa990ac5 100644 --- a/doc/supervision.sgml +++ b/doc/supervision.sgml @@ -146,15 +146,6 @@ following functions (and a few others): -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied diff --git a/doc/vic20.sgml b/doc/vic20.sgml index 1227ee667..562ea002a 100644 --- a/doc/vic20.sgml +++ b/doc/vic20.sgml @@ -153,10 +153,10 @@ No extended memory drivers are currently available for the VIC20. <descrip> - <tag><tt/vic20-stdjoy.joy (vic20_stdjoy)/</tag> + <tag><tt/vic20-stdjoy.joy (vic20_stdjoy_joy)/</tag> Supports one standard joystick connected to the joysticks port of the VIC20. - <tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy)/</tag> + <tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy_joy)/</tag> Driver for the Protovision 4-player adapter contributed by Groepaz. See <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and @@ -219,7 +219,7 @@ code: <tscreen><verb> /* Check for the existence of RAM */ - if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {<br> + if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) { /* Add it to the heap */ _heapadd ((void *) 0xA000, 0x2000); } @@ -236,15 +236,6 @@ feature in the <htmlurl url="ca65.html" name="assembler manual">. -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - <sect>License<p> This software is provided 'as-is', without any expressed or implied From 37c923815c84a16e2c6e9341ff8c37ce9fe3a9eb Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 00:20:43 +0100 Subject: [PATCH 09/36] First test of actual html page push. --- doc/Makefile | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index d4860ca40..aabe59d49 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,10 +1,34 @@ +.PHONY: all html gh-pages + +.SUFFIXES: + +all: html + +html: $(addprefix ../html/,$(subst .sgml,.html,$(wildcard *.sgml))) + +../html: + mkdir $@ + +../html/%.html: %.sgml | ../html + linuxdoc -B html --split=0 --toc=2 $< + mv *.html $(@D) + +../html/coding.html: coding.sgml | ../html + linuxdoc -B html --split=0 $< + mv *.html $(@D) + +../html/index.html: index.sgml | ../html + linuxdoc -B html --split=0 $< + mv *.html $(@D) + GH_PAGES = ../../gh-pages -gh-pages: +gh-pages: html git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES) git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" - echo date > $(GH_PAGES)/testfile.txt + rm -rf $(GH_PAGES)/test + cp -R ../html/* $(GH_PAGES)/test git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From 95a401b9aa9f8d61629c53424d46852b5df0b3e9 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 00:29:27 +0100 Subject: [PATCH 10/36] Fixed missing target directory. --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index aabe59d49..9ca213a6c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -28,6 +28,7 @@ gh-pages: html git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" rm -rf $(GH_PAGES)/test + mkdir $(GH_PAGES)/test cp -R ../html/* $(GH_PAGES)/test git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." From 2276777817c43afa92ae8565ca3b9f4ec6798633 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 17:55:10 +0100 Subject: [PATCH 11/36] Added doc goal to top level Makefile. --- Makefile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index b4882cc31..d00136784 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,7 @@ +.PHONY: all mostlyclean clean install avail unavail bin lib doc + +.SUFFIXES: + all mostlyclean clean install: @$(MAKE) -C src --no-print-directory $@ @$(MAKE) -C libsrc --no-print-directory $@ @@ -8,12 +12,11 @@ avail unavail bin: lib: @$(MAKE) -C libsrc --no-print-directory $@ +doc: + @$(MAKE) -C doc --no-print-directory $@ + %65: @$(MAKE) -C src --no-print-directory $@ %: @$(MAKE) -C libsrc --no-print-directory $@ - -.PHONY: all mostlyclean clean install avail unavail bin lib - -.SUFFIXES: From a79a1469fefa334b32f924455c859baccfd1e573 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 18:40:03 +0100 Subject: [PATCH 12/36] Test --allow-empty flag. --- doc/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 9ca213a6c..a600f375c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -30,6 +30,6 @@ gh-pages: html rm -rf $(GH_PAGES)/test mkdir $(GH_PAGES)/test cp -R ../html/* $(GH_PAGES)/test - git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A - git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A . + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit --allow-empty -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From 46d9b72d7df897a0e5df5fb7a74cc8f1658a35d2 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 18:49:22 +0100 Subject: [PATCH 13/36] Maybe rather ignore the git commit status (?) --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index a600f375c..7fb0155f6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -31,5 +31,5 @@ gh-pages: html mkdir $(GH_PAGES)/test cp -R ../html/* $(GH_PAGES)/test git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A . - git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit --allow-empty -m "Updated doc from commit $(TRAVIS_COMMIT)." + -git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From 5dd5f7cd1b72182d687b2b120eabb585e31eb324 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 20:55:17 +0100 Subject: [PATCH 14/36] Some polishing. --- doc/Makefile | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 7fb0155f6..a601d4426 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,35 +1,46 @@ -.PHONY: all html gh-pages +.PHONY: all doc html gh-pages mostlyclean clean install .SUFFIXES: -all: html +ifeq ($(shell echo),) -html: $(addprefix ../html/,$(subst .sgml,.html,$(wildcard *.sgml))) +SGMLS := $(wildcard *.sgml) + +GH_PAGES = ../../gh-pages + +all: + +doc: html + +mostlyclean: + +clean: + $(RM) -r ../html + +html: $(addprefix ../html/,$(SGMLS:.sgml=.html)) ../html: mkdir $@ ../html/%.html: %.sgml | ../html linuxdoc -B html --split=0 --toc=2 $< - mv *.html $(@D) - -../html/coding.html: coding.sgml | ../html - linuxdoc -B html --split=0 $< - mv *.html $(@D) - -../html/index.html: index.sgml | ../html - linuxdoc -B html --split=0 $< - mv *.html $(@D) - -GH_PAGES = ../../gh-pages + mv $(@F) ../html gh-pages: html +ifdef GH_TOKEN git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES) git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" - rm -rf $(GH_PAGES)/test + $(RM) -r $(GH_PAGES)/test mkdir $(GH_PAGES)/test cp -R ../html/* $(GH_PAGES)/test git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A . -git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push +endif + +else # cmd.exe + +all doc mostlyclean clean install: + +endif # cmd.exe From a0b5bc523dadad87f0f56594d396cdc8690b677e Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 22:30:28 +0100 Subject: [PATCH 15/36] Re-introduced toc removal for coding.html and index.html. --- doc/Makefile | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index a601d4426..3e3cc5b7e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,6 +6,11 @@ ifeq ($(shell echo),) SGMLS := $(wildcard *.sgml) +../html/coding.html ../html/index.html: \ +TOC_LEVEL = 0 + +TOC_LEVEL = 2 + GH_PAGES = ../../gh-pages all: @@ -23,7 +28,7 @@ html: $(addprefix ../html/,$(SGMLS:.sgml=.html)) mkdir $@ ../html/%.html: %.sgml | ../html - linuxdoc -B html --split=0 --toc=2 $< + linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) $< mv $(@F) ../html gh-pages: html From 74ece8256e8f67702ab4dbbfb7f90a24f6f7683d Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 22:31:46 +0100 Subject: [PATCH 16/36] Goals from top level Makefile should be known even if empty. --- src/Makefile | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/Makefile b/src/Makefile index 051c7eb1f..9a8807e37 100644 --- a/src/Makefile +++ b/src/Makefile @@ -1,3 +1,7 @@ +.SUFFIXES: + +.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail + ifeq ($(shell echo),) PROGS = ar65 \ @@ -30,10 +34,6 @@ LDLIBS += -lm INSTALL = install -.SUFFIXES: - -.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail - all bin: $(PROGS) mostlyclean: @@ -116,10 +116,6 @@ $(foreach prog,$(PROGS),$(eval $(call PROG_template,$(prog)))) else # cmd.exe -.SUFFIXES: - -.PHONY: all bin mostlyclean clean - all bin: msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor @@ -129,4 +125,6 @@ mostlyclean: clean: msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor /target:$@ +install avail unavail: + endif # cmd.exe From 88247613d29d229533833af9ee071e095ec0b97e Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 22:36:43 +0100 Subject: [PATCH 17/36] Route standard goals to doc Makefile. - mostlyclean is empty as there are no intermedite files. - all is empty as I don't want to have if depend on linuxdoc. --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index d00136784..5db00e7ad 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,7 @@ all mostlyclean clean install: @$(MAKE) -C src --no-print-directory $@ @$(MAKE) -C libsrc --no-print-directory $@ + @$(MAKE) -C doc --no-print-directory $@ avail unavail bin: @$(MAKE) -C src --no-print-directory $@ From c9fcfe85490d29935bf226c694f192c91958212c Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 23:02:01 +0100 Subject: [PATCH 18/36] The content in internal.txt is now fully present in the Wiki. --- doc/index.sgml | 3 - doc/internal.txt | 207 ----------------------------------------------- 2 files changed, 210 deletions(-) delete mode 100644 doc/internal.txt diff --git a/doc/index.sgml b/doc/index.sgml index ef8e56327..f0faf5073 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -82,9 +82,6 @@ <tag><htmlurl url="geos.html" name="geos.html"></tag> The GEOSLib manual. - <tag><htmlurl url="internal.txt" name="internal.txt"></tag> - A somewhat older text describing several cc65 internals. - <tag><htmlurl url="library.html" name="library.html"></tag> An overview over the cc65 runtime and C libraries. diff --git a/doc/internal.txt b/doc/internal.txt deleted file mode 100644 index 0dca618ea..000000000 --- a/doc/internal.txt +++ /dev/null @@ -1,207 +0,0 @@ - - - Internals doc for CC65 - - - -Stacks: -------- - -The program stack used by programs compiled with CC65 is located in high -memory. The stack starts there and grows down. Arguments to functions, local -data etc are allocated on this stack, and deallocated when functions exit. - -The program code and data is located in low memory. The heap is located -between the program code and the stack. The default size for the parameter -stack is 2K, you may change this for most platforms in the linker -configuration. - -Note: The size of the stack is only needed if you use the heap, or if you -call the stack checking routine (_stkcheck) from somewhere in your program. - -When calling other functions, the return address goes on the normal 6502 -stack, *not* on the parameter stack. - - - -Registers: ----------- - -Since CC65 is a member of the Small-C family of compilers, it uses the notion -of a 'primary register'. In the CC65 implementation, I used the AX register -pair as the primary register. Just about everything interesting that the -library code does is done by somehow getting a value into AX, and then calling -some routine or other. In places where Small-C would use a secondary -register, top-of-stack is used, so for instance two argument function like -integer-multiply work by loading AX, pushing it on the stack, loading the -second value, and calling the internal function. The stack is popped, and the -result comes back in AX. - - - -Calling sequences: ------------------- - -C functions are called by pushing their args on the stack, and JSR'ing to the -entry point. (See ex 1, below) If the function returns a value, it comes back -in AX. NOTE!!! A potentially significant difference between the CC65 -environment and other C environments is that the CALLEE pops arguments, not -the CALLER. (This is done so as to generate more compact code) In normal use, -this doesn't cause any problems, as the normal function entry/exit conventions -take care of popping the right number of things off the stack, but you may -have to worry about it when doing things like writing hand-coded assembly -language routines that take variable numbers of arguments. More about that -later. - -Ex 1: Function call: Assuming 'i' declared int and 'c' declared - char, the following C code - - i = baz(i, c); - - in absence of a prototype generates this assembler code. I've added - the comments. - - lda _i ; get 'i', low byte - ldx _i+1 ; get 'i', hi byte - jsr pushax ; push it - lda _c ; get 'c' - ldx #0 ; fill hi byte with 0 - jsr pushax ; push it - ldy #4 ; arg size - jsr _baz ; call the function - sta _i ; store the result - stx _i+1 - - In presence of a prototype, the picture changes slightly, since the - compiler is able to do some optimizations: - - lda _i ; get 'i', low byte - ldx _i+1 ; get 'i', hi byte - jsr pushax ; push it - lda _c ; get 'c' - jsr pusha ; push it - jsr _baz ; call the function - sta _i ; store the result - stx _i+1 - - -Note that the two words of arguments to baz were popped before it exitted. -The way baz could tell how much to pop was by the argument count in Y at call -time. Thus, even if baz had been called with 3 args instead of the 2 it was -expecting, that would not cause stack corruption. - -There's another tricky part about all this, though. Note that the args to baz -are pushed in FORWARD order, ie the order they appear in the C statement. -That means that if you call a function with a different number of args than it -was expecting, they wont end up in the right places, ie if you call baz, as -above, with 3 args, it'll operate on the LAST two, not the first two. - - - -Symbols: --------- - -CC65 does the usual trick of prepending an underbar ('_') to symbol names when -compiling them into assembler. Therefore if you have a C function named -'bar', CC65 will define and refer to it as '_bar'. - - - -Systems: --------- - -Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700, -the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to -Kevin Ruland, who did the port). - -C16: Works with unexpanded or memory expanded C16 and C116 machines. - However, a maximum of 32KB from the total memory is used. The Plus/4 - target supports up to 64K of memory, but has a small code overhead - because of the banking routines involved. Apart from this additional - overhead, the Plus/4 target and the C16 target are the same. 16K - machines (unexpanded C16) have 12K of memory for C programs available, - machines with 32K or more have 28K available. The actual amount of - memory is auto detected. - -C64: The program runs in a memory configuration, where only the kernal ROM - is enabled. The text screen is expected at the usual place ($400), so - 50K of memory are available to the program. - -C128: The startup code will reprogram the MMU, so that only the kernal ROM - is enabled. This means, there are 41K of memory available to the - program. - -Plus/4: Works with bank switching so 59K of memory are available to the - program. - -CBM 500: - The C program runs in bank #0 and has a total of 48K memory available. - This is less than what is available on its bigger brothers (CBM - 600/700) because the character data and video RAM is placed in the - execution bank (#0) to allow the use of sprites. - -CBM 600/700: - The C program runs in a separate segment and has almost full 64K of - memory available. - -PET: The startup code will adjust the upper memory limit to the installed - memory. However, only linear memory is used, this limits the top to - $8000, so on a 8032 or similar machine, 31K of memory are available to - the program. - -Apple ][: - The program starts at $803, end of RAM is $95FF, so 35.5K of memory - (including stack) are available to the program. - -Atari: The startup code will adjust the upper memory limit to the installed - memory detected at runtime. The programmer can adjust the upper memory - limit by setting the __RESERVED_MEMORY__ variable at link time. The - given __RESERVED_MEMORY__ value will be subtracted from the upper - memory limit used by the runtine. This memory could be used as graphics - memory, for example. - In the default case (no setting of __RESERVED_MEMORY__) the upper - memory limit is $9C1F (with Basic cartridge) and $BC1F (without - cartridge). The program starts at $2E00 by default. - These values are for a 48K or 64K machine. - -Note: The above numbers do not mean that the remaining memory is unusable. -However, it is not linear memory and must be accessed by other, nonportable -methods. I'm thinking about a library extension that allows access to the -additional memory as a far heap, but these routines do not exist until now. - - - -Inline Assembly: ----------------- - -CC65 allows inline assembly by a special keyword named "asm". Inline assembly -looks like a function call. The string in parenthesis is output in the -assembler file. - -Example, insert a break instruction into the code: - - asm ("brk") - -Beware: Be careful when inserting inline code since this may collide with -the work of the optimizer. - - - -Pseudo variables: ------------------ - -There are two special variables available named __AX__ and __EAX__. These -variables must never be declared (this gives an error), but may be used as any -other variable. However, accessing these variables will access the primary -register that is used by the compiler to evaluate expressions, return -functions results and pass parameters. - -This feature is useful with inline assembly and macros. For example, a macro -that reads a CRTC register may be written like this: - -#define wr(idx) (__AX__=(idx), \ - asm ("sta $2000"), \ - asm ("lda $2000"), \ - asm ("ldx #$00"), \ - __AX__) - From 3394033d8687004039ef14d74d4eb253922df5ae Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 23:20:03 +0100 Subject: [PATCH 19/36] The gh-pages push seems ready for prime time. --- doc/Makefile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 3e3cc5b7e..53ec0cff5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,28 +17,28 @@ all: doc: html +html: $(addprefix ../html/,$(SGMLS:.sgml=.html)) + mostlyclean: clean: $(RM) -r ../html -html: $(addprefix ../html/,$(SGMLS:.sgml=.html)) - ../html: - mkdir $@ + @mkdir $@ ../html/%.html: %.sgml | ../html - linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) $< - mv $(@F) ../html + @linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) $< + @mv $(@F) ../html gh-pages: html ifdef GH_TOKEN git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES) git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" - $(RM) -r $(GH_PAGES)/test - mkdir $(GH_PAGES)/test - cp -R ../html/* $(GH_PAGES)/test + $(RM) -r $(GH_PAGES)/doc + mkdir $(GH_PAGES)/doc + cp -R ../html/* $(GH_PAGES)/doc git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A . -git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From 0bf5111500e9e115a30acbcc8e3bb0c45ffafa69 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Wed, 5 Feb 2014 23:41:52 +0100 Subject: [PATCH 20/36] Adjusted doc to commit 9aa17b4c537f77fc01d49ab7167b1b3c179c7b9 --- doc/ca65html.sgml | 280 ---------------------------------------------- doc/index.sgml | 3 - 2 files changed, 283 deletions(-) delete mode 100644 doc/ca65html.sgml diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml deleted file mode 100644 index 68dd2507f..000000000 --- a/doc/ca65html.sgml +++ /dev/null @@ -1,280 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>ca65html Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2007-10-2 - -<abstract> -ca65html is an assembly-source-to-HTML converter. It is very useful if you -want to publish your assembler sources in the web. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -ca65html converts assembly source files written for use with the <tt/<url -url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone -tool written in PERL; and as such, it does not understand the structure of -assembler sources in the same depth as ca65 does, so it may fail in very rare -cases. In all other cases, it generates very nice output. - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The HTML converter accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: ca65html [options] file ... -Options: - --bgcolor c Use background color c instead of #FFFFFF - --colorize Add color highlights to the output - --commentcolor c Use color c for comments instead of #B22222 - --crefs Generate references to the C source file(s) - --ctrlcolor c Use color c for directives instead of #228B22 - --cvttabs Convert tabs to spaces in the output - --help This text - --htmldir dir Specify directory for HTML files - --indexcols n Use n columns on index page (default 6) - --indexname file Use file for the index file instead of index.html - --indexpage Create an index page - --indextitle title Use title as the index title instead of Index - --keywordcolor c Use color c for keywords instead of #A020F0 - --linelabels Generate a linexxx HTML label for each line - --linenumbers Add line numbers to the output - --linkstyle style Use the given link style - --replaceext Replace source extension instead of appending .html - --textcolor c Use text color c instead of #000000 - --verbose Be more verbose ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <tag><tt>--bgcolor c</tt></tag> - - Set the background color. The argument c must be a valid HTML color, usually - given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the - respective red, green, and blue parts as two-digit hex values. The default is - <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the - generated HTML output. - - - <tag><tt>--colorize</tt></tag> - - Colorize the output. The converter outputs processor instructions, assembler - control commands, and comments in different colors. - - - <tag><tt>--commentcolor c</tt></tag> - - Set the color used for comments. The argument c must be a valid HTML color, - usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are - the respective red, green, and blue parts as two-digit hex values. The - default is <tt/#B22222/ (red). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - - <tag><tt>--crefs</tt></tag> - - Generate references to the C file, when a <tt/.dbg/ command is found with a - file name. The converter assumes that the C source was also converted into - HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and - lives in the same directory as the assembler file. If the <tt/.dbg/ - directive specifies a line, a link to the correct line in the C file is - generated, using a label in the form <tt/linexxx/, as it is created by - <tt/c2html/ by use of the <tt/-n/ option. - - - <tag><tt>--commentcolor c</tt></tag> - - Set the color used for assembler control commands. The argument c must be a - valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, - where r, g, and b are the respective red, green, and blue parts as two-digit - hex values. The default is <tt/#228B22/ (green). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - - <tag><tt>--cvttabs</tt></tag> - - Convert tabs in the input into spaces in the output, assuming the standard - tab width of 8. This is useful if the <tt/--linenumbers/ option is used to - retain the indentation. - - - <tag><tt>--help</tt></tag> - - Print the command line option summary shown above. - - - <tag><tt>--htmldir dir</tt></tag> - - Specify an output directory for the generated HTML files. - - - <tag><tt>--indexcols n</tt></tag> - - Use n columns on the index page. This option has no effect if used without - <tt/--indexpage/. - - - <tag><tt>--indexname name</tt></tag> - - Use another index file name instead of <tt/index.html/. This option has no - effect if used without <tt/--indexpage/. - - - <tag><tt>--indexpage</tt></tag> - - Causes the converter to generate an index page listing file names, and all - exports found in the converted files. - - - <tag><tt>--indextitle title</tt></tag> - - Use "title" as the title of the index page. This option has no effect if - used without <tt/--indexpage/. - - - <tag><tt>--keywordcolor c</tt></tag> - - Set the color used for processor instructions. The argument c must be a - valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, - where r, g, and b are the respective red, green, and blue parts as two-digit - hex values. The default is <tt/#A020F0/ (purple). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - <tag><tt>--linelabels</tt></tag> - - Generate a label for each line using the name <tt/linexxx/ where xxx is the - number of the line. - - Note: The converter will not make use of this label. Use this option if you - have other HTML pages referencing the converted assembler file. - - - <tag><tt>--linenumbers</tt></tag> - - Generate line numbers on the left side of the output. - - - <tag><tt>--linkstyle n</tt></tag> - - Influences the style used when generating links for imports. If n is zero - (the default), the converter creates a link to the actual symbol if it is - defined somewhere in the input files. If not, it creates a link to the - <tt/.import/ statement. If n is one, the converter will always generate a - HTML link to the <tt/.import/ statement. - - - <tag><tt>--replaceext</tt></tag> - - Replace the file extension of the input file instead of appending <tt/.html/ - when generating the output file name. - - - <tag><tt>--textcolor c</tt></tag> - - Set the color for normal text. The argument c must be a valid HTML color, - usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are - the respective red, green, and blue parts as two-digit hex values. The - default is <tt/#000000/ (black). This color is used in the <tt/<body>/ - of the generated HTML output. - - - <tag><tt>--verbose</tt></tag> - - Increase the converter verbosity. Without this option, ca65html is quiet - when working. If you have a slow machine and lots of files to convert, you - might like a little bit more progress information. - -</descrip> -<p> - - -<sect>Peculiarities<p> - -<sect1>Cross links<p> - -Since ca65html is able to generate links between modules, the best way to use -it is to supply all modules to it in one run, instead of running each file -separately through it. - - -<sect1>Include files<p> - -For now, ca65html will not read files included with <tt/.include/. Specifying -the include files as normal input files on the command line works in many -cases. - - -<sect1>Conversion errors<p> - -Since ca65html does not really parse the input, but does most of its work -applying text patterns, it doesn't know anything about scoping and advanced -features of the assembler. This means that it might miss a label. And, it -might choose the wrong color for an item, in rare cases. Because it's just a -tool for displaying sources in a nice form, I think that's OK. Anyway, if you -find a conversion problem, you can send me a short piece of example input code. -If possible, I will fix it. - - -<sect1>Colorization<p> - -While having colors in the output looks really nice, it has one drawback: - -<enum> - -<item>Because lots of <tt/<span>/ tags are created in the output, -the size of the output file literally will explode. It seems to be the price -that you have to pay for color. - -</enum> - - -<sect>Copyright<p> - -ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the -following conditions apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - - - diff --git a/doc/index.sgml b/doc/index.sgml index f0faf5073..1e78a2cdc 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -15,9 +15,6 @@ <tag><htmlurl url="ca65.html" name="ca65.html"></tag> Describes the ca65 macro assembler. - <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag> - Describes the ca65html assembler-source-to-HTML converter. - <tag><htmlurl url="cc65.html" name="cc65.html"></tag> Describes the cc65 C compiler. From 1a4bbecaa640b224ec6197f62debd5999d95109c Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Thu, 6 Feb 2014 12:44:46 +0100 Subject: [PATCH 21/36] Limit 'git add' to doc directory just to be sure. --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 53ec0cff5..518d3c9c3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -39,7 +39,7 @@ ifdef GH_TOKEN $(RM) -r $(GH_PAGES)/doc mkdir $(GH_PAGES)/doc cp -R ../html/* $(GH_PAGES)/doc - git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A . + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A doc -git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push endif From 99ecbc60f87c61cd237f707c76b0822615a5721a Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Thu, 6 Feb 2014 12:54:53 +0100 Subject: [PATCH 22/36] Actually the '-R' flag isn't necessary. --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 518d3c9c3..eb9d82541 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -38,7 +38,7 @@ ifdef GH_TOKEN git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" $(RM) -r $(GH_PAGES)/doc mkdir $(GH_PAGES)/doc - cp -R ../html/* $(GH_PAGES)/doc + cp ../html/* $(GH_PAGES)/doc git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git add -A doc -git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git commit -m "Updated doc from commit $(TRAVIS_COMMIT)." git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git push From 6a4a18ed624026b2cf2e1690a6d9a617c121a4f1 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Fri, 7 Feb 2014 14:30:52 +0100 Subject: [PATCH 23/36] Fixed typo. --- doc/atari.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/atari.sgml b/doc/atari.sgml index 8ec359654..9f7a3fbc4 100644 --- a/doc/atari.sgml +++ b/doc/atari.sgml @@ -449,7 +449,7 @@ All mouse devices connect to joystick port #0. <sect1>RS232 device drivers<p> Currently there is one RS232 driver. It uses the R: device (therefore -a R: driver needs to be installed) and was tested with the 850 +an R: driver needs to be installed) and was tested with the 850 interface module. <table> From c524dd0f08a3165f530a6373f3a3537950b9f4e1 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sat, 8 Feb 2014 21:52:23 +0100 Subject: [PATCH 24/36] Avoid writing (temporarily) into source directory. --- doc/Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index eb9d82541..dc6c451cf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -28,8 +28,7 @@ clean: @mkdir $@ ../html/%.html: %.sgml | ../html - @linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) $< - @mv $(@F) ../html + @cd ../html && linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) ../doc/$< gh-pages: html ifdef GH_TOKEN From f155efa3e7d283e2aa7b3fca412db160e086bb7b Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sat, 8 Feb 2014 22:47:24 +0100 Subject: [PATCH 25/36] Keep git push happy. --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index dc6c451cf..1e2bf435f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -35,6 +35,7 @@ ifdef GH_TOKEN git clone --branch=gh-pages https://$(GH_TOKEN)@github.com/oliverschmidt/cc65.git $(GH_PAGES) git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.name "Oliver Schmidt" git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config user.email "ol.sc@web.de" + git --work-tree=$(GH_PAGES) --git-dir=$(GH_PAGES)/.git config push.default simple $(RM) -r $(GH_PAGES)/doc mkdir $(GH_PAGES)/doc cp ../html/* $(GH_PAGES)/doc From a7b84bb618390cceb87d0062abb4fd28a38a365c Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sat, 8 Feb 2014 22:48:49 +0100 Subject: [PATCH 26/36] Removed references to SunPlus. --- asminc/cpu.mac | 9 ++------- doc/ca65.sgml | 25 ++----------------------- src/ca65/instr.c | 10 ---------- src/ca65/pseudo.c | 9 --------- src/ca65/scanner.c | 1 - src/ca65/token.h | 1 - src/common/cpu.c | 2 -- src/common/cpu.h | 2 -- 8 files changed, 4 insertions(+), 55 deletions(-) diff --git a/asminc/cpu.mac b/asminc/cpu.mac index 43c9e160f..6b8aa6d7b 100644 --- a/asminc/cpu.mac +++ b/asminc/cpu.mac @@ -1,4 +1,3 @@ - ; CPU bitmask constants CPU_ISET_NONE = $0001 CPU_ISET_6502 = $0002 @@ -6,9 +5,8 @@ CPU_ISET_6502X = $0004 CPU_ISET_65SC02 = $0008 CPU_ISET_65C02 = $0010 CPU_ISET_65816 = $0020 -CPU_ISET_SUNPLUS = $0040 -CPU_ISET_SWEET16 = $0080 -CPU_ISET_HUC6280 = $0100 +CPU_ISET_SWEET16 = $0040 +CPU_ISET_HUC6280 = $0080 ; CPU capabilities CPU_NONE = CPU_ISET_NONE @@ -17,8 +15,5 @@ CPU_6502X = CPU_ISET_6502|CPU_ISET_6502X CPU_65SC02 = CPU_ISET_6502|CPU_ISET_65SC02 CPU_65C02 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65C02 CPU_65816 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65816 -CPU_SUNPLUS = CPU_ISET_SUNPLUS CPU_SWEET16 = CPU_ISET_SWEET16 CPU_HUC6280 = CPU_ISET_6502|CPU_ISET_65SC02|CPU_ISET_65C02|CPU_ISET_HUC6280 - - diff --git a/doc/ca65.sgml b/doc/ca65.sgml index c1c314a2c..75cba986e 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -151,10 +151,7 @@ Here is a description of all the command line options: Set the default for the CPU type. The option takes a parameter, which may be one of - 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280 - - The sunplus cpu is not available in the freeware version, because the - instruction set is "proprietary and confidential". + 6502, 65SC02, 65C02, 65816, sweet16, HuC6280 <label id="option-create-dep"> @@ -428,8 +425,6 @@ The assembler accepts <tt><ref id=".PC02" name=".PC02"></tt> command was given). <item>all valid 65618 mnemonics when in 65816 mode (after the <tt><ref id=".P816" name=".P816"></tt> command was given). -<item>all valid SunPlus mnemonics when in SunPlus mode (after the - <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given). </itemize> @@ -3652,10 +3647,7 @@ Here's a list of all control commands and a description, what they do: Switch the CPU instruction set. The command is followed by a string that specifies the CPU. Possible values are those that can also be supplied to the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, - namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please - note that support for the sunplus CPU is not available in the freeware - version, because the instruction set of the sunplus CPU is "proprietary - and confidential". + namely: 6502, 6502X, 65SC02, 65C02, 65816and HuC6280. See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".IFP02" name=".IFP02"></tt>, @@ -3714,17 +3706,6 @@ Here's a list of all control commands and a description, what they do: <tt><ref id=".UNION" name=".UNION"></tt> -<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p> - - Enable the SunPlus instructions set. This command will not work in the - freeware version of the assembler, because the instruction set is - "proprietary and confidential". - - See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and - <tt><ref id=".P816" name=".P816"></tt> - - <sect1><tt>.TAG</tt><label id=".TAG"><p> Allocate space for a struct or union. @@ -4365,7 +4346,6 @@ each supported CPU a constant similar to CPU_65SC02 CPU_65C02 CPU_65816 - CPU_SUNPLUS CPU_SWEET16 CPU_HUC6280 </verb></tscreen> @@ -4379,7 +4359,6 @@ another constant is defined: CPU_ISET_65SC02 CPU_ISET_65C02 CPU_ISET_65816 - CPU_ISET_SUNPLUS CPU_ISET_SWEET16 CPU_ISET_HUC6280 </verb></tscreen> diff --git a/src/ca65/instr.c b/src/ca65/instr.c index 277676614..777affdee 100644 --- a/src/ca65/instr.c +++ b/src/ca65/instr.c @@ -585,11 +585,6 @@ static const struct { } }; -#ifdef SUNPLUS -/* Table for the SUNPLUS CPU */ -#include "sunplus.inc" -#endif - /* Instruction table for the SWEET16 pseudo CPU */ static const struct { unsigned Count; @@ -781,11 +776,6 @@ static const InsTable* InsTabs[CPU_COUNT] = { (const InsTable*) &InsTab65SC02, (const InsTable*) &InsTab65C02, (const InsTable*) &InsTab65816, -#ifdef SUNPLUS - (const InsTable*) &InsTabSunPlus, -#else - 0, -#endif (const InsTable*) &InsTabSweet16, (const InsTable*) &InsTabHuC6280, 0, /* Mitsubishi 740 */ diff --git a/src/ca65/pseudo.c b/src/ca65/pseudo.c index 5c534b29c..3af192610 100644 --- a/src/ca65/pseudo.c +++ b/src/ca65/pseudo.c @@ -1810,14 +1810,6 @@ static void DoSmart (void) -static void DoSunPlus (void) -/* Switch to the SUNPLUS CPU */ -{ - SetCPU (CPU_SUNPLUS); -} - - - static void DoTag (void) /* Allocate space for a struct */ { @@ -2093,7 +2085,6 @@ static CtrlDesc CtrlCmdTab [] = { { ccNone, DoUnexpected }, /* .STRING */ { ccNone, DoUnexpected }, /* .STRLEN */ { ccNone, DoStruct }, - { ccNone, DoSunPlus }, { ccNone, DoTag }, { ccNone, DoUnexpected }, /* .TCOUNT */ { ccNone, DoUnexpected }, /* .TIME */ diff --git a/src/ca65/scanner.c b/src/ca65/scanner.c index aadb91d54..1a1127778 100644 --- a/src/ca65/scanner.c +++ b/src/ca65/scanner.c @@ -276,7 +276,6 @@ struct DotKeyword { { ".STRING", TOK_STRING }, { ".STRLEN", TOK_STRLEN }, { ".STRUCT", TOK_STRUCT }, - { ".SUNPLUS", TOK_SUNPLUS }, { ".TAG", TOK_TAG }, { ".TCOUNT", TOK_TCOUNT }, { ".TIME", TOK_TIME }, diff --git a/src/ca65/token.h b/src/ca65/token.h index 5214771fd..6499a14bd 100644 --- a/src/ca65/token.h +++ b/src/ca65/token.h @@ -244,7 +244,6 @@ typedef enum token_t { TOK_STRING, TOK_STRLEN, TOK_STRUCT, - TOK_SUNPLUS, TOK_TAG, TOK_TCOUNT, TOK_TIME, diff --git a/src/common/cpu.c b/src/common/cpu.c index 59353a6a1..7b61ccdcc 100644 --- a/src/common/cpu.c +++ b/src/common/cpu.c @@ -58,7 +58,6 @@ const char* CPUNames[CPU_COUNT] = { "65SC02", "65C02", "65816", - "sunplus", "sweet16", "huc6280", "m740", @@ -72,7 +71,6 @@ const unsigned CPUIsets[CPU_COUNT] = { CPU_ISET_6502 | CPU_ISET_65SC02, CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02, CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02 | CPU_ISET_65816, - CPU_ISET_SUNPLUS, CPU_ISET_SWEET16, CPU_ISET_6502 | CPU_ISET_65SC02 | CPU_ISET_65C02 | CPU_ISET_HUC6280, CPU_ISET_6502 | CPU_ISET_M740, diff --git a/src/common/cpu.h b/src/common/cpu.h index 424053cf9..121a54b7a 100644 --- a/src/common/cpu.h +++ b/src/common/cpu.h @@ -53,7 +53,6 @@ typedef enum { CPU_65SC02, CPU_65C02, CPU_65816, - CPU_SUNPLUS, /* Not in the freeware version - sorry */ CPU_SWEET16, CPU_HUC6280, /* Used in PC engine */ CPU_M740, /* Mitsubishi 740 series MCUs */ @@ -68,7 +67,6 @@ enum { CPU_ISET_65SC02 = 1 << CPU_65SC02, CPU_ISET_65C02 = 1 << CPU_65C02, CPU_ISET_65816 = 1 << CPU_65816, - CPU_ISET_SUNPLUS = 1 << CPU_SUNPLUS, CPU_ISET_SWEET16 = 1 << CPU_SWEET16, CPU_ISET_HUC6280 = 1 << CPU_HUC6280, CPU_ISET_M740 = 1 << CPU_M740, From 7b6a6d168cf158817985370a7b95078b8b08e612 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sat, 8 Feb 2014 23:01:15 +0100 Subject: [PATCH 27/36] Fixed typo. --- doc/ca65.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 75cba986e..4d4b73d38 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -3647,7 +3647,7 @@ Here's a list of all control commands and a description, what they do: Switch the CPU instruction set. The command is followed by a string that specifies the CPU. Possible values are those that can also be supplied to the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, - namely: 6502, 6502X, 65SC02, 65C02, 65816and HuC6280. + namely: 6502, 6502X, 65SC02, 65C02, 65816 and HuC6280. See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".IFP02" name=".IFP02"></tt>, From bec75d9e62122e562931b4e41b164b3003ddaf12 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 01:11:11 +0100 Subject: [PATCH 28/36] Avoid tmpfile(). - tmpfile() tries to create files in the C: root dir on Windows where users usually don't have access. - tmpnam() uses the curent dir which doesn't seem to be a good idea either. - tempnam(NULL,NULL) is supposed to be cleverer. --- src/ar65.vcxproj | 4 ++-- src/ar65/library.c | 17 ++++++++++++++--- src/ar65/library.h | 3 --- src/ca65.vcxproj | 4 ++-- src/cc65.vcxproj | 4 ++-- src/cl65.vcxproj | 4 ++-- src/co65.vcxproj | 4 ++-- src/common.vcxproj | 4 ++-- src/da65.vcxproj | 4 ++-- src/grc65.vcxproj | 4 ++-- src/ld65.vcxproj | 4 ++-- src/od65.vcxproj | 4 ++-- src/sim65.vcxproj | 4 ++-- src/sp65.vcxproj | 4 ++-- 14 files changed, 38 insertions(+), 30 deletions(-) diff --git a/src/ar65.vcxproj b/src/ar65.vcxproj index e83f0f984..baf3efd6b 100644 --- a/src/ar65.vcxproj +++ b/src/ar65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/ar65/library.c b/src/ar65/library.c index 9046e315f..1f8a2425e 100644 --- a/src/ar65/library.c +++ b/src/ar65/library.c @@ -64,10 +64,11 @@ /* Name of the library file */ const char* LibName = 0; +static const char* NewLibName = 0; /* File descriptor for the library file */ -FILE* NewLib = 0; static FILE* Lib = 0; +static FILE* NewLib = 0; /* The library header */ static LibHeader Header = { @@ -246,10 +247,17 @@ void LibOpen (const char* Name, int MustExist, int NeedTemp) } if (NeedTemp) { + + /* Create the temporary library name */ + NewLibName = tempnam (NULL, NULL); + if (NewLibName == 0) { + Error ("Cannot create temporary library file name: %s", strerror (errno)); + } + /* Create the temporary library */ - NewLib = tmpfile (); + NewLib = fopen (NewLibName, "w+b"); if (NewLib == 0) { - Error ("Cannot create temporary file: %s", strerror (errno)); + Error ("Cannot create temporary library file: %s", strerror (errno)); } /* Write a dummy header to the temp file */ @@ -394,6 +402,9 @@ void LibClose (void) if (NewLib && fclose (NewLib) != 0) { Error ("Problem closing temporary library file: %s", strerror (errno)); } + if (NewLibName && remove (NewLibName) != 0) { + Error ("Problem deleting temporary library file: %s", strerror (errno)); + } } diff --git a/src/ar65/library.h b/src/ar65/library.h index abb8c475f..3453f1ea5 100644 --- a/src/ar65/library.h +++ b/src/ar65/library.h @@ -51,9 +51,6 @@ /* Name of the library file */ extern const char* LibName; -/* File descriptor for the new library file */ -extern FILE* NewLib; - /*****************************************************************************/ diff --git a/src/ca65.vcxproj b/src/ca65.vcxproj index 747b836cd..cb9727a81 100644 --- a/src/ca65.vcxproj +++ b/src/ca65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <TreatWarningAsError>true</TreatWarningAsError> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <TreatWarningAsError>true</TreatWarningAsError> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> </ClCompile> diff --git a/src/cc65.vcxproj b/src/cc65.vcxproj index 888fa53b7..62d4bb416 100644 --- a/src/cc65.vcxproj +++ b/src/cc65.vcxproj @@ -46,7 +46,7 @@ <ClCompile> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <WarningLevel>Level3</WarningLevel> <TreatWarningAsError>true</TreatWarningAsError> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/cl65.vcxproj b/src/cl65.vcxproj index ee348830d..8e11b90d3 100644 --- a/src/cl65.vcxproj +++ b/src/cl65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/co65.vcxproj b/src/co65.vcxproj index 7560cb866..ed63b91b0 100644 --- a/src/co65.vcxproj +++ b/src/co65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/common.vcxproj b/src/common.vcxproj index a386d0c06..938e4f032 100644 --- a/src/common.vcxproj +++ b/src/common.vcxproj @@ -143,7 +143,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_LIB;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_LIB;_DEBUG</PreprocessorDefinitions> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> <Link> @@ -161,7 +161,7 @@ <PrecompiledHeader> </PrecompiledHeader> <FunctionLevelLinking>true</FunctionLevelLinking> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_LIB;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_LIB;NDEBUG</PreprocessorDefinitions> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> <Link> diff --git a/src/da65.vcxproj b/src/da65.vcxproj index a71e46a65..8ca8935c1 100644 --- a/src/da65.vcxproj +++ b/src/da65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/grc65.vcxproj b/src/grc65.vcxproj index 29a8ca4b5..f41dafee3 100644 --- a/src/grc65.vcxproj +++ b/src/grc65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/ld65.vcxproj b/src/ld65.vcxproj index b837e1873..1674f0cd5 100644 --- a/src/ld65.vcxproj +++ b/src/ld65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/od65.vcxproj b/src/od65.vcxproj index abb2e7c8a..41639229a 100644 --- a/src/od65.vcxproj +++ b/src/od65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/sim65.vcxproj b/src/sim65.vcxproj index 7a65f9384..f8e9fd604 100644 --- a/src/sim65.vcxproj +++ b/src/sim65.vcxproj @@ -48,7 +48,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -63,7 +63,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> diff --git a/src/sp65.vcxproj b/src/sp65.vcxproj index 1651ab007..477e80859 100644 --- a/src/sp65.vcxproj +++ b/src/sp65.vcxproj @@ -47,7 +47,7 @@ <PrecompiledHeader> </PrecompiledHeader> <WarningLevel>Level3</WarningLevel> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;_DEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> @@ -62,7 +62,7 @@ <WarningLevel>Level3</WarningLevel> <PrecompiledHeader> </PrecompiledHeader> - <PreprocessorDefinitions>_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> + <PreprocessorDefinitions>_CRT_NONSTDC_NO_WARNINGS;_CRT_SECURE_NO_WARNINGS;_CONSOLE;NDEBUG</PreprocessorDefinitions> <AdditionalIncludeDirectories>common</AdditionalIncludeDirectories> <TreatWarningAsError>true</TreatWarningAsError> </ClCompile> From 47828e1059d3cc857b14849f8d166468b03999b8 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 01:19:40 +0100 Subject: [PATCH 29/36] Define _SVID_SOURCE to get tempnam(). --- src/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Makefile b/src/Makefile index 9a8807e37..66b64d732 100644 --- a/src/Makefile +++ b/src/Makefile @@ -25,7 +25,7 @@ LD65_LIB = $(datadir)/lib LD65_OBJ = $(datadir)/lib LD65_CFG = $(datadir)/cfg -CFLAGS += -MMD -MP -O -std=c89 -I common \ +CFLAGS += -MMD -MP -O -std=c89 -D_SVID_SOURCE -I common \ -Wall -Wextra -Wno-char-subscripts -Werror $(USER_CFLAGS) \ -DCA65_INC=$(CA65_INC) -DCC65_INC=$(CC65_INC) \ -DLD65_LIB=$(LD65_LIB) -DLD65_OBJ=$(LD65_OBJ) -DLD65_CFG=$(LD65_CFG) From 0d3a652544836c66243728b41899c55363c1f941 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 19:48:30 +0100 Subject: [PATCH 30/36] Use -Werror only on Travis CI builds. There's no need to intentionally break things for people trying to build cc65 with some obscure compiler. It's enough to make sure that no new warnings sneak into the code base by having Travis CI builds fail. --- src/Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Makefile b/src/Makefile index 66b64d732..5ac8ed7bd 100644 --- a/src/Makefile +++ b/src/Makefile @@ -26,10 +26,12 @@ LD65_OBJ = $(datadir)/lib LD65_CFG = $(datadir)/cfg CFLAGS += -MMD -MP -O -std=c89 -D_SVID_SOURCE -I common \ - -Wall -Wextra -Wno-char-subscripts -Werror $(USER_CFLAGS) \ + -Wall -Wextra -Wno-char-subscripts $(USER_CFLAGS) \ -DCA65_INC=$(CA65_INC) -DCC65_INC=$(CC65_INC) \ -DLD65_LIB=$(LD65_LIB) -DLD65_OBJ=$(LD65_OBJ) -DLD65_CFG=$(LD65_CFG) +CFLAGS += $(if $(TRAVIS),-Werror) + LDLIBS += -lm INSTALL = install From aa7f7f107a36374f62647bf729b535f182ca3fef Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 21:31:00 +0100 Subject: [PATCH 31/36] Switched to Markdown in order to allow to add links. --- .gitignore | 1 + README | 32 -------------------------------- README.md | 29 +++++++++++++++++++++++++++++ 3 files changed, 30 insertions(+), 32 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/.gitignore b/.gitignore index 150806c6c..5de976c32 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /bin/ /emd/ +/html/ /joy/ /lib/ /mou/ diff --git a/README b/README deleted file mode 100644 index 0bb161677..000000000 --- a/README +++ /dev/null @@ -1,32 +0,0 @@ -cc65 is a complete cross development package for 65(C)02 systems, including -a powerful macro assembler, a C compiler, linker, librarian and several -other tools. - -cc65 has C and runtime library support for many of the old 6502 machines, -including - - - the following Commodore machines: - VIC20 - C16/C116 and Plus/4 - C64 - C128 - CBM 510 (aka P500) - the 600/700 family - newer PET machines (not 2001). - - - the Apple ][+ and successors. - - - the Atari 8 bit machines. - - - GEOS for the C64 and C128. - - - the Nintendo Entertainment System (NES). - - - the Supervision console. - - - the Oric Atmos. - - - the Lynx console. - -The libraries are fairly portable, so creating a version for other 6502s -shouldn't be too much work. diff --git a/README.md b/README.md new file mode 100644 index 000000000..5955a69b6 --- /dev/null +++ b/README.md @@ -0,0 +1,29 @@ +[documentation](http://oliverschmidt.github.io/cc65/) + +[![build status](https://travis-ci.org/oliverschmidt/cc65.png)](https://travis-ci.org/oliverschmidt/cc65/builds) + +cc65 is a complete cross development package for 65(C)02 systems, including +a powerful macro assembler, a C compiler, linker, librarian and several +other tools. + +cc65 has C and runtime library support for many of the old 6502 machines, +including + +- the following Commodore machines: + - VIC20 + - C16/C116 and Plus/4 + - C64 + - C128 + - CBM 510 (aka P500) + - the 600/700 family + - newer PET machines (not 2001). +- the Apple ][+ and successors. +- the Atari 8 bit machines. +- GEOS for the C64 and C128. +- the Nintendo Entertainment System (NES). +- the Supervision console. +- the Oric Atmos. +- the Lynx console. + +The libraries are fairly portable, so creating a version for other 6502s +shouldn't be too much work. From c78e8d194540a085fbe57152c0b57b276ade1aa2 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 21:33:59 +0100 Subject: [PATCH 32/36] Fixed URL. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5955a69b6..54e6028a6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[documentation](http://oliverschmidt.github.io/cc65/) +[documentation](http://oliverschmidt.github.io/cc65/doc) [![build status](https://travis-ci.org/oliverschmidt/cc65.png)](https://travis-ci.org/oliverschmidt/cc65/builds) From 1968e87cc2f9a3b7099c22b514bd1248cb2a6094 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 22:43:55 +0100 Subject: [PATCH 33/36] Made html doc look a little less boring. --- doc/Makefile | 7 +++++-- doc/doc.css | 33 +++++++++++++++++++++++++++++++++ doc/doc.png | Bin 0 -> 1307 bytes doc/header.html | 4 ++++ 4 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/doc.css create mode 100644 doc/doc.png create mode 100644 doc/header.html diff --git a/doc/Makefile b/doc/Makefile index 1e2bf435f..19dd8836c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,7 +17,7 @@ all: doc: html -html: $(addprefix ../html/,$(SGMLS:.sgml=.html)) +html: $(addprefix ../html/,$(SGMLS:.sgml=.html) doc.css doc.png) mostlyclean: @@ -28,7 +28,10 @@ clean: @mkdir $@ ../html/%.html: %.sgml | ../html - @cd ../html && linuxdoc -B html --split=0 --toc=$(TOC_LEVEL) ../doc/$< + @cd ../html && linuxdoc -B html -s=0 -T=$(TOC_LEVEL) -H ../doc/header.html ../doc/$< + +../html/doc.%: doc.% | ../html + cp $< ../html gh-pages: html ifdef GH_TOKEN diff --git a/doc/doc.css b/doc/doc.css new file mode 100644 index 000000000..232599a75 --- /dev/null +++ b/doc/doc.css @@ -0,0 +1,33 @@ +body { + font-family: arial, helvetica, sans-serif; + font-size: 100%; + text-align: justify; + margin-left: 110px; + margin-top: 10px; + margin-right: 30px; + margin-bottom: 10px; + background-image: url(doc.png); + background-repeat: repeat-y; +} + +h1, h2, h2 a:link, h2 a:active, h2 a:visited { + font-weight: bold; + font-style: italic; + text-align: left; + color: #DB3232; +} + +h1 { + font-size: 250%; + text-shadow: 2px 2px 6px #505050; + letter-spacing: 2px; + padding-top: 40px; +} + +h2 { + font-size: 160%; + text-shadow: 2px 2px 6px #303030; + letter-spacing: 1px; + margin-top: 2em; + margin-bottom: 1em; +} diff --git a/doc/doc.png b/doc/doc.png new file mode 100644 index 0000000000000000000000000000000000000000..91af80d31d21a4e05154827d3f4991ea80c0628a GIT binary patch literal 1307 zcmV+$1?2jPP)<h;3K|Lk000e1NJLTq00p1`001Kh0{{R3RbpK$00004XF*Lt006O% z3;baP0002kP)t-sW)>8Zl9WzPOrj<v(k?9OHZ*b?9P&OqiXI%gDlGOkG}6-4-ZC_P z9vqe;B*rc*K0Z9ICM5DUH2OX~a&mOqGBob)>~0zyva+<&GBoNsJbD@&k|HF+DlGmw zJmxku`a(o%8XRI`WU3}4iXtTTIy~Oq+~PJgh8`TACM3=-EVe2vY8DitqNG+<RHh~* z)-EjWHZ*n`9QHmuzA7x@GBko79GW5|$}TKMMntkIEb=-${ysc{f`tD5{KCS-)-p8a z=Hz-F9KtRv?m9gFLPU-tB>Fl$i{xf^000B-Nkl<Zc-rmVZC4sc7{+m1S+kH^E!YWF z*d>;1Aq%ZT%BtYB-JS&f{@<uG%fmi2eUY3o^~L|E0{6n}>)hvJz$4|^53BEg`}xN| zzWep3zh3|H_nSWf0AJ@w{8FoGK))fN0pP0x`Z+h~*KE)L@KOR=s5k)Ng>KM7Km&lM zfcD!!H#TTGXaIOI8+5&cCZGY}WdyX?zZDe+0Q?UD9o;+*hsWpJ;p6P!zD#I3XaMjO z&|lCnANNnfakt&gvSK_657fSa<`f42eESW0c{Et(i>FSeOfjeZTrx+bXFh+5gAN)1 zzCl2DukR!_=AoB7ZHf!)sqUDa-}enP8#DksTR^X8v-W4E`}tVK7gz4#WKvw29xL<8 zWwKP?BP5^!z*j)mTIS`4`5+A6O}nZ&-3~81o5?PVi`UL06=%C(J~YsLPz3;<V}riG z?Z21g$);``G^VH@sYKH8V|cSWu_67I8nu?~<~ch88UVZpbUGiVu}L0!nKD^p8lKtx zI2wlIcK2?%Ek6cI>7_fukxJP>vq1yEGX(T)*oxmyT&J9En$vuyvp9}>+YolYcimpH zm?$l2J1-k(HfR9w7SLt?+&^DzCPn(nq%ldqB~KT@C~KuQk~{8w!FHTHB)!arvkuAz znhhEN{BO|HI~70t$J9Ml+FZF@9_K2L_ZzeQUA9Cgqw*970Sy4Y16ocZZAP-ID(aJJ zhf3TVhoa8TRc6$7Uv{rs&XhaMA&0~!paH=527R5Yc(hO2+9WQZ-Dn?$ZIxU|**UL= zN}182fo6jS0B-@k|0ZX3qIHlJowLdtlgu7PF9JKJ*O4-x>`J}dZP9}p)!CE{G#fMk z_}`$1mm;Zl$L-GY+SGE3v(j?uPI?SgY-|iq-yOHbowb{$;sX0{&W;Tl0Q?5DJH^q} zdAfcdp7zs4ZL;|*-E+}tH~bJr9dl)K_&Q3*r~Uch#^&>dlnu1opjQMm0C?S?<zA~? zr|l@%jH;6f?34PV%2ggknc2883hgB=qO;h%o#bT$O~nBK-U52pKs#Bl6B}bLKGmjI z#iX-NY{yM9*;dUR`=q;&Topa_zJaFV007?`^fqI&!2UF+;;lk^lLbK_<<}(zqmiBW z%k%!c$Ao|e0FME^+oAVI?CR5QmP(INyIlFy3LP{6JjVvT&snKXs#-7q`>qzv#XTD| z0Qd^%Ljx_9o%t|{H1fE3LZq6|l?IwGO9BAT8?>lui&2}T64p{*oTb@73jqxPJ_EYa zK&x5<t-iQ{wzn%fXaMlKLHlW-IR^~@{sP)>1I>T+1^}NMw8sXTQyc)`%Rj&j!&QpN REwKOq002ovPDHLkV1oKrUIYLD literal 0 HcmV?d00001 diff --git a/doc/header.html b/doc/header.html new file mode 100644 index 000000000..a2cb2f194 --- /dev/null +++ b/doc/header.html @@ -0,0 +1,4 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> + <LINK REL="stylesheet" TYPE="text/css" HREF="doc.css"/> From 0891b8515d6eeb11ee01e4eb8aee4712b5b85fa1 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 22:50:01 +0100 Subject: [PATCH 34/36] Adjusted linuxdoc parameters. --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 19dd8836c..0211a4de9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -28,7 +28,7 @@ clean: @mkdir $@ ../html/%.html: %.sgml | ../html - @cd ../html && linuxdoc -B html -s=0 -T=$(TOC_LEVEL) -H ../doc/header.html ../doc/$< + @cd ../html && linuxdoc -B html -s 0 -T $(TOC_LEVEL) -H ../doc/header.html ../doc/$< ../html/doc.%: doc.% | ../html cp $< ../html From c3434817dafc2bfa09ba901bf8a20ae1dbc2bf72 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Sun, 9 Feb 2014 22:57:38 +0100 Subject: [PATCH 35/36] Some minor fine tuning. --- doc/Makefile | 2 +- doc/header.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 0211a4de9..dcb2af8e0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -27,7 +27,7 @@ clean: ../html: @mkdir $@ -../html/%.html: %.sgml | ../html +../html/%.html: %.sgml header.html | ../html @cd ../html && linuxdoc -B html -s 0 -T $(TOC_LEVEL) -H ../doc/header.html ../doc/$< ../html/doc.%: doc.% | ../html diff --git a/doc/header.html b/doc/header.html index a2cb2f194..38a943e5b 100644 --- a/doc/header.html +++ b/doc/header.html @@ -1,4 +1,4 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> - <LINK REL="stylesheet" TYPE="text/css" HREF="doc.css"/> + <LINK REL="stylesheet" TYPE="text/css" HREF="doc.css"> From e22fc15589ff902f8b161fe6b25bfc929bd4bf49 Mon Sep 17 00:00:00 2001 From: Oliver Schmidt <ol.sc@web.de> Date: Mon, 10 Feb 2014 21:28:03 +0100 Subject: [PATCH 36/36] Deduct temporary library path name from library path name. Actually there's no need to fiddle with any automatic temp file name generation as we can just modify the library path name to generate a perfect temporary library path name. --- src/Makefile | 2 +- src/ar65/library.c | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/src/Makefile b/src/Makefile index 5ac8ed7bd..7bdd5206a 100644 --- a/src/Makefile +++ b/src/Makefile @@ -25,7 +25,7 @@ LD65_LIB = $(datadir)/lib LD65_OBJ = $(datadir)/lib LD65_CFG = $(datadir)/cfg -CFLAGS += -MMD -MP -O -std=c89 -D_SVID_SOURCE -I common \ +CFLAGS += -MMD -MP -O -std=c89 -I common \ -Wall -Wextra -Wno-char-subscripts $(USER_CFLAGS) \ -DCA65_INC=$(CA65_INC) -DCC65_INC=$(CC65_INC) \ -DLD65_LIB=$(LD65_LIB) -DLD65_OBJ=$(LD65_OBJ) -DLD65_CFG=$(LD65_CFG) diff --git a/src/ar65/library.c b/src/ar65/library.c index 1f8a2425e..e68f23d3d 100644 --- a/src/ar65/library.c +++ b/src/ar65/library.c @@ -64,7 +64,7 @@ /* Name of the library file */ const char* LibName = 0; -static const char* NewLibName = 0; +static char* NewLibName = 0; /* File descriptor for the library file */ static FILE* Lib = 0; @@ -249,10 +249,9 @@ void LibOpen (const char* Name, int MustExist, int NeedTemp) if (NeedTemp) { /* Create the temporary library name */ - NewLibName = tempnam (NULL, NULL); - if (NewLibName == 0) { - Error ("Cannot create temporary library file name: %s", strerror (errno)); - } + NewLibName = xmalloc (strlen (Name) + strlen (".temp") + 1); + strcpy (NewLibName, Name); + strcat (NewLibName, ".temp"); /* Create the temporary library */ NewLib = fopen (NewLibName, "w+b"); @@ -386,7 +385,7 @@ void LibClose (void) LibName, strerror (errno)); } - /* Copy the new library to the new one */ + /* Copy the temporary library to the new one */ fseek (NewLib, 0, SEEK_SET); while ((Count = fread (Buf, 1, sizeof (Buf), NewLib)) != 0) { if (fwrite (Buf, 1, Count, Lib) != Count) {