/bin/
/emd/
+/html/
/joy/
/lib/
/mou/
- sudo apt-get install linuxdoc-tools
script:
- make
+ - make -C doc gh-pages
env:
global:
- secure: "h+hoQdEHGPLNwaqGKmSaM8NBRDLc2X+W05VsnNG2Feq/wPv/AiBjONNlzN7jRf6D6f3aoPXaQ2Lc3bYWdxGvFRCmwiofdxkJI9n5L8HPHLZ2lf37MQsXmGJzoTFOvjPLj73H6HlbI9Ux0El3zO6hvalxiXj6TfoZ41dbhNyvpYk="
+.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 $@
+ @$(MAKE) -C doc --no-print-directory $@
avail unavail bin:
@$(MAKE) -C src --no-print-directory $@
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:
+++ /dev/null
-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.
--- /dev/null
+[documentation](http://oliverschmidt.github.io/cc65/doc)
+
+[](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.
-
; CPU bitmask constants
CPU_ISET_NONE = $0001
CPU_ISET_6502 = $0002
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
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
-
-
--- /dev/null
+.PHONY: all doc html gh-pages mostlyclean clean install
+
+.SUFFIXES:
+
+ifeq ($(shell echo),)
+
+SGMLS := $(wildcard *.sgml)
+
+../html/coding.html ../html/index.html: \
+TOC_LEVEL = 0
+
+TOC_LEVEL = 2
+
+GH_PAGES = ../../gh-pages
+
+all:
+
+doc: html
+
+html: $(addprefix ../html/,$(SGMLS:.sgml=.html) doc.css doc.png)
+
+mostlyclean:
+
+clean:
+ $(RM) -r ../html
+
+../html:
+ @mkdir $@
+
+../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
+ cp $< ../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"
+ 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
+ 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
+
+else # cmd.exe
+
+all doc mostlyclean clean install:
+
+endif # cmd.exe
--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+
+<title>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 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/-t apple2 -C <configfile>/.
+
+
+<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
+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 (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 (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
+ <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 (a2_auxmem_emd)/</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 (a2_stdjoy_joy)/</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 (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].
+
+ 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 (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
+ 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. 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
+ '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 textcolor(),
+ bgcolor() and bordercolor() have no effect.
+
+ <tag/Cursor/
+ The Apple ][ has no hardware cursor. Therefore the function 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>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>
--- /dev/null
+<!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 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/-t apple2enh -C <configfile>/.
+
+
+<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
+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 (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 (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
+ <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 (a2e_auxmem_emd)/</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 (a2e_stdjoy_joy)/</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 (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].
+
+ 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 (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
+ 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. 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
+ '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
+ textcolor(), bgcolor() and bordercolor() have no effect.
+
+ <tag/Cursor/
+ The enhanced Apple //e has no hardware cursor. Therefore the function
+ 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>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>
--- /dev/null
+<!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>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>
+
+
+
--- /dev/null
+<!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.
+
+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
+more than one platform. Please see the function reference for more
+information.
+
+
+<sect>Binary format<p>
+
+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 <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">).
+
+
+<sect>Memory layout<p>
+
+<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. 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>
+ <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>
+
+<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>
+
+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>
+
+<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>
+
+
+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.
+
+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
+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>
+
+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>
+
+Currently there are two joystick drivers available:
+
+<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 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 is one RS232 driver. It uses the R: device (therefore
+an 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>
+
+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>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>
+
+
+<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>
+
+(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
+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 config files
+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, 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 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 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__: value = $800 type = weak; # 2K stack
+ __RESERVED_MEMORY__: value = $0000, type = weak;
+}
+FEATURES {
+ STARTADDRESS: default = $2E00;
+}
+MEMORY {
+ ZP: start = $82, size = $7E, type = rw, define = yes;
+
+ 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;
+
+ 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 = HEADER, type = ro;
+
+ 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;
+ 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;
+
+ 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 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 MAINHDR segment get discarded.
+<p>
+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>
+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 __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__: value = $800 type = weak; # 2K stack
+ __RESERVED_MEMORY__: value = $0000, type = weak;
+}
+FEATURES {
+ STARTADDRESS: default = $2E00;
+}
+MEMORY {
+ ZP: start = $82, size = $7E, type = rw, define = yes;
+
+ 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;
+
+ 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 = HEADER, type = ro; # discarded old EXE header
+
+ 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;
+
+ 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;
+ 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__, __BSS_LOAD__, __DATA_SIZE__
+ .import __DATA_LOAD__, __RODATA_LOAD__
+
+ .segment "NEXEHDR"
+ .word __RODATA_LOAD__
+ .word __DATA_LOAD__ + __DATA_SIZE__ - 1
+
+ .segment "CHKHDR"
+ .word __STARTUP_LOAD__
+ .word __BSS_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 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
+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.
+
+
+<sect1>Upgrading from an older cc65 version<p>
+
+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>
+
+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>
--- /dev/null
+<!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_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_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.
+
+</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_joy)/</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_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
+ 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>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>
+
+
+
--- /dev/null
+<!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_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_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
+ 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_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_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_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
+ 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_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_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_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
+ any of the graphics drivers using the VDC!
+
+</descrip><p>
+
+
+<sect1>Joystick drivers<p>
+
+<descrip>
+
+ <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_joy)/</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_mou)/</tag>
+ Supports a standard mouse connected to port #0 of the C128.
+
+ <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_pot_mou)/</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_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
+ 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>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>
--- /dev/null
+<!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_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).
+
+</descrip><p>
+
+
+
+<sect1>Joystick drivers<p>
+
+<descrip>
+
+ <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.
+
+</descrip><p>
+
+
+
+<sect1>Mouse drivers<p>
+
+No mouse drivers are currently available for the C16/C116.
+
+
+<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>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>
+
+
+
+
--- /dev/null
+<!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 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/-t c64 -C <configfile>/.
+
+
+<sect1>default config file (<tt/c64.cfg/)<p>
+
+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.
+
+
+<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_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).
+</descrip><p>
+
+
+<sect1>Extended memory drivers<p>
+
+<descrip>
+
+ <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_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_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_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_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_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_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_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_emd)/</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_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_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_joy)/</tag>
+ Supports up to two standard joysticks connected to the joysticks port of
+ the C64.
+
+ <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.
+
+</descrip><p>
+
+
+<sect1>Mouse drivers<p>
+
+<descrip>
+
+ <tag><tt/c64-1351.mou (c64_1351_mou)/</tag>
+ Supports a standard mouse connected to port #0 of the C64.
+
+ <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_pot_mou)/</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_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
+ 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>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>
--- /dev/null
+<!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
+ --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
+ --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, sweet16, HuC6280
+
+
+ <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-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-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 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>An optionally compiled-in directory.
+</enum>
+
+Binary include files are searched in the following places:
+
+<enum>
+<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>
+
+
+
+<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).
+</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 and HuC6280.
+
+ 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>.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
+
+ .macro bnz Arg
+ bne Arg
+ .endmacro
+
+ .macro bze Arg
+ beq 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_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_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/ or <tt/apple2enh/
+<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
+<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/ 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 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>
+
+
+<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>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>
+
+
+
--- /dev/null
+<!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">&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
+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_emd)/</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_std_joy)/</tag>
+ Supports up to two standard joysticks connected to the joysticks port of
+ the Commodore 510.
+
+</descrip><p>
+
+
+<sect1>Mouse drivers<p>
+
+<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_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
+ 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>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>
--- /dev/null
+<!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_emd)/</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>
+
+No mouse drivers are currently available for the Commodore 610.
+
+
+<sect1>RS232 device drivers<p>
+
+<descrip>
+
+ <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
+ 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>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>
--- /dev/null
+<!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
+ --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>-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>atarixl
+ <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>sim6502
+ <item>sim65c02
+ <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 use with the ca65 macro
+assembler.
+
+Include files in quotes are searched in the following places:
+<enum>
+<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>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>An optionally compiled-in directory.
+</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) or the enhanced Apple //e (-t apple2enh).
+
+ <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 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>
+
+ 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 Commodore 128 (-t c128).
+
+ <tag><tt>__C16__</tt></tag>
+
+ 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 Commodore 64 (-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 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>
+
+ 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 Nintendo Entertainment System (-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 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).
+
+ <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 Commodore 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>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>
+
--- /dev/null
+<!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'
+ --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>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>
+
--- /dev/null
+<!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>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>
+
--- /dev/null
+<!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>
+
--- /dev/null
+<!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>
--- /dev/null
+<!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>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>
+
+
+
+
--- /dev/null
+<!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>
--- /dev/null
+<!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>
--- /dev/null
+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;
+}
--- /dev/null
+<!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>
--- /dev/null
+<!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>
--- /dev/null
+<!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>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+<title>cc65 Documentation Overview
+<author><htmlurl url="https://github.com/oliverschmidt/cc65" name="">
+<date>
+
+<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="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="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="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>
+
+
+</article>
+
--- /dev/null
+<!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://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, 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
+<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 (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>
--- /dev/null
+<!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
+ --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 default 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 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:
+
+ <itemize>
+ <item>none
+ <item>module
+ <item>apple2
+ <item>apple2enh
+ <item>atari
+ <item>atarixl
+ <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>sim6502
+ <item>sim65c02
+ <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 default
+ configurations, only the "none", "apple2" and "apple2enh" systems honor an
+ explicit start address, all other default configs 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-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 list contains in this order:
+
+<enum>
+<item>The current directory.
+<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>An optionally compiled-in library path.
+</enum>
+
+
+<sect1>Object file search path<p>
+
+The object file search-path list contains in this order:
+
+<enum>
+<item>The current directory.
+<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>An optionally compiled-in directory.
+</enum>
+
+
+<sect1>Config file search path<p>
+
+The config file search-path list contains in this order:
+
+<enum>
+<item>The current directory.
+<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>An optionally compiled-in directory.
+</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>
+
+
+
+<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>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>
--- /dev/null
+<!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>atarixl
+ <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.
+
+
+
+<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>atarixl
+ <item>c64
+ <item>c128
+ </itemize>
+
+The available functions are declared in <tt/mouse.h/.
+
+
+<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>
+
+
+
--- /dev/null
+<!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_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.
+ 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_joy)/</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_ser)/</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>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>
--- /dev/null
+<!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>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>
+
+
+
--- /dev/null
+<!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>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>
+
--- /dev/null
+<!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_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_joy)/</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>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>
--- /dev/null
+<!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_joy)/</tag>
+ Supports up to two joysticks connected to the standard joysticks port of
+ the Plus/4.
+
+</descrip><p>
+
+
+<sect1>Mouse drivers<p>
+
+No mouse drivers are currently available for the Plus/4.
+
+
+<sect1>RS232 device drivers<p>
+
+<descrip>
+
+ <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
+ 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>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>
--- /dev/null
+<!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>
+
--- /dev/null
+<!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>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>
+
+
+
--- /dev/null
+<!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>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>
--- /dev/null
+<!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>
--- /dev/null
+<!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_joy)/</tag>
+ Supports one standard joystick connected to the joysticks port of the VIC20.
+
+ <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
+ 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)) {
+ /* 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>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>
; is being built.
;
+;DEBUG = 1
+
+DISABLE_TIMEOUT = 30 ; # of vertical blank interrupts after which, if
+ ; no mouse motion occurred, the polling IRQ gets
+ ; disabled.
+ ; VBI frequency is 50Hz for PAL and 60Hz for NTSC
+
.include "zeropage.inc"
.include "mouse-kernel.inc"
.include "atari.inc"
XPosWrk: .res 2
YPosWrk: .res 2
+irq_enabled: .res 1 ; flag indicating that the high frequency polling interrupt is enabled
+old_porta_vbi: .res 1 ; previous PORTA value of the VBI interrupt (IRQ)
+how_long: .res 1 ; counter for how many VBI interrupts the mouse hasn't been moved
+
.if .defined (AMIGA_MOUSE) .or .defined (ST_MOUSE)
dumx: .res 1
dumy: .res 1
sta AUDF1
sta STIMER
+.if 0 ; the IRQ will now be dynamically enabled when the mouse is moved
lda POKMSK
ora #%00000001 ; timer 1 enable
sta POKMSK
sta IRQEN
+ sta irq_enabled
+.endif
+
+ lda PORTA
+ and #$0f
+ sta old_porta_vbi
; Done, return zero (= MOUSE_ERR_OK)
; MUST return carry clear.
;
-IRQ:
+IRQ: lda PORTA ; mouse port contents
+ and #$0f ; check port 1 only
+ ldx irq_enabled
+ bne @L1
+
+; IRQ is disabled, check for mouse motion and enable IRQ if mouse motion detected
-; Turn mouse polling IRQ back on in case it disabled itself due to CRITIC
-; flag being set.
+ cmp old_porta_vbi
+ beq @L3 ; no motion
+
+; Turn mouse polling IRQ back on
lda POKMSK
ora #%00000001 ; timer 1 enable
sta POKMSK
sta IRQEN
+ sta irq_enabled
+ bne @L3
+ ; not reached
+
+; IRQ is enabled
+
+@L1: cmp old_porta_vbi ; mouse motion since last VBI?
+ sta old_porta_vbi
+ beq @L2 ; no, increment timeout to disable IRQ
+
+ lda #0
+ sta how_long ; yes, reinitialize wait counter
+ beq @L3
+ ; not reached
+
+@L2: inc how_long ; no motion, increment wait counter
+ lda how_long
+ cmp #DISABLE_TIMEOUT ; timeout?
+ bcc @L3 ; no
+
+ lda #0 ; yes, turn off IRQ
+ sta how_long
+
+; no mouse input -- turn IRQ off
+
+ sta irq_enabled
+ lda POKMSK
+ and #%11111110 ; timer 1 disable
+ sta IRQEN
+ sta POKMSK
; Check for a pressed button and place the result into Buttons
- ldx #0
+@L3: ldx #0
lda TRIG0 ; joystick #0 trigger
- bne @L0 ; not pressed
+ bne @L4 ; not pressed
ldx #MOUSE_BTN_LEFT
-@L0: stx Buttons
+@L4: stx Buttons
jsr CPREP
tax
cpy XMin
sbc XMin+1
- bpl @L2
+ bpl @L5
ldy XMin
ldx XMin+1
- jmp @L3
-@L2: txa
+ jmp @L6
+@L5: txa
cpy XMax
sbc XMax+1
- bmi @L3
+ bmi @L6
ldy XMax
ldx XMax+1
-@L3: sty XPos
+@L6: sty XPos
stx XPos+1
-
tya
jsr CMOVEX
tax
cpy YMin
sbc YMin+1
- bpl @L4
+ bpl @L7
ldy YMin
ldx YMin+1
- jmp @L5
-@L4: txa
+ jmp @L8
+@L7: txa
cpy YMax
sbc YMax+1
- bmi @L5
+ bmi @L8
ldy YMax
ldx YMax+1
-@L5: sty YPos
+@L8: sty YPos
stx YPos+1
-
tya
jsr CMOVEY
jsr CDRAW
+.ifdef DEBUG
+ ; print on upper right corner 'E' or 'D', indicating the IRQ is enabled or disabled
+ ldy irq_enabled
+ beq @L9
+ lda #37 ; screen code for 'E'
+ .byte $2c ; bit opcode, eats next 2 bytes
+@L9: lda #36 ; screen code for 'D'
+ ldy #39
+ sta (SAVMSC),y
+.endif
+
clc
rts
and #%11111110 ; timer 1 disable
sta IRQEN
sta POKMSK
+ lda #0
+ sta irq_enabled
+ lda PORTA
+ and #$0f
+ sta old_porta_vbi
.ifdef __ATARIXL__
rts
.else
+.SUFFIXES:
+
+.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail
+
ifeq ($(shell echo),)
PROGS = ar65 \
LD65_CFG = $(datadir)/cfg
CFLAGS += -MMD -MP -O -std=c89 -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
-.SUFFIXES:
-
-.PHONY: all bin $(PROGS) mostlyclean clean install avail unavail
-
all bin: $(PROGS)
mostlyclean:
else # cmd.exe
-.SUFFIXES:
-
-.PHONY: all bin mostlyclean clean
-
all bin:
msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor
clean:
msbuild cc65.sln /p:configuration=release /consoleloggerparameters:disableconsolecolor /target:$@
+install avail unavail:
+
endif # cmd.exe
<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>
<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>
/* Name of the library file */
const char* LibName = 0;
+static 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 = {
}
if (NeedTemp) {
+
+ /* Create the temporary library name */
+ NewLibName = xmalloc (strlen (Name) + strlen (".temp") + 1);
+ strcpy (NewLibName, Name);
+ strcat (NewLibName, ".temp");
+
/* 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 */
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) {
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));
+ }
}
/* Name of the library file */
extern const char* LibName;
-/* File descriptor for the new library file */
-extern FILE* NewLib;
-
/*****************************************************************************/
<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>
<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>
}
};
-#ifdef SUNPLUS
-/* Table for the SUNPLUS CPU */
-#include "sunplus.inc"
-#endif
-
/* Instruction table for the SWEET16 pseudo CPU */
static const struct {
unsigned 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 */
-static void DoSunPlus (void)
-/* Switch to the SUNPLUS CPU */
-{
- SetCPU (CPU_SUNPLUS);
-}
-
-
-
static void DoTag (void)
/* Allocate space for a struct */
{
{ ccNone, DoUnexpected }, /* .STRING */
{ ccNone, DoUnexpected }, /* .STRLEN */
{ ccNone, DoStruct },
- { ccNone, DoSunPlus },
{ ccNone, DoTag },
{ ccNone, DoUnexpected }, /* .TCOUNT */
{ ccNone, DoUnexpected }, /* .TIME */
{ ".STRING", TOK_STRING },
{ ".STRLEN", TOK_STRLEN },
{ ".STRUCT", TOK_STRUCT },
- { ".SUNPLUS", TOK_SUNPLUS },
{ ".TAG", TOK_TAG },
{ ".TCOUNT", TOK_TCOUNT },
{ ".TIME", TOK_TIME },
TOK_STRING,
TOK_STRLEN,
TOK_STRUCT,
- TOK_SUNPLUS,
TOK_TAG,
TOK_TCOUNT,
TOK_TIME,
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
"65SC02",
"65C02",
"65816",
- "sunplus",
"sweet16",
"huc6280",
"m740",
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,
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 */
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,
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
projects / cc65 / commitdiff
