+++ /dev/null
-Introduced with version 2.5:
-
- * Use of "goto" to jump into or out of blocks that declare local variables
- will create programs that crash, since the stack is not corrected. The old
- stack correction code was removed because of the restructuring of the
- symbol table stuff and was not reintroduced because it was ugly anyway,
- did not work with the new symbol table code, and should be unnecessary as
- soon as local variables are allocated in one chunk on function entry.
+++ /dev/null
-
-Many special thanks go to the guy who started it all:
-
- John R. Dunning
-
-Without his great work, there would not be a single freeware C crosscompiler
-for the 6502 out there. He built the grounds for this cc65 and some other cc65
-implementations and a lot of his code is still in the current compiler.
-
-
-
-More special thanks to:
-
- * Keith W. Gerdes <kwg@netzero.net>
-
- Without his outstanding help, the assembler/compiler wouldn't be, what it
- is now. He helped with suggestions, bug reports and even kicked me here
- and then, when I started to get too lazy:-)
-
- * Kevin Ruland <kevin@rodin.wustl.edu>
-
- Kevin did the Apple 2 port and found at least one serious error in the
- C library while doing so.
-
- * Christian Groessler <chris@groessler.org>
- Mark Keates <Mark.Keates@dendrite.com>
- Freddy Offenga <taf_offenga@yahoo.com>
- David Lloyd <dmlloyd@atari-central.com>
-
- The team that added support for the Atari 8 bit machines.
- Christian Groessler also sent me several fixes for 64 bit machines.
-
- * Sidney Cadot <sidney@ch.twi.tudelft.nl>
-
- Sidney rewrote the random number generator.
-
- * Maciej Witkowiak <ytm@friko.onet.pl>
-
- Maciej wrote the GEOS support libraries for cc65.
-
- * Eric Au <eric_au@hotmail.com>
-
- Eric is one of the most active testers, and supplied me with dozens of
- bug reports.
-
- * MicroSystems Development Technologies Inc. located in San Jose,
- California payed me for the addition of several assembler features,
- which went also into the freeware version. These guys are selling
- nice hardware devices like EPROM emulators. If you are developing
- hardware or embedded microcontroller applications, you should have
- a look at their web site at www.msd.com.
-
- * Mirco Miranda <mircomir@libero.it>
-
- Miroc contributed Makefile additions, docs and patches to compile cc65
- cleanly under OS/2 using the EMX toolkit.
-
- * Marc 'BlackJack' Rintsch <blackjack@civitas64.de>
-
- Marc wrote and contributed BASIC compatible file I/O routines for the
- Commodore machines.
-
- * Groepaz <groepaz@gmx.net>
-
- Thanks for several nice samples programs, the NES port, and a lot of other
- code.
-
- * Craig Bruce
-
- ...for his public domain Swiftlink/Turbo232 drivers which are part
- of the cc65 library in modified form.
-
- * Steve Schmidtke <steve_schmidtke@hotmail.com>
-
- Steve contributed the VIC20 port.
-
- * Michael Klein <michael.klein@puffin.lb.shuttle.de>
-
- for the Debian support files.
-
- * Greg King <gngking@erols.com>
-
- reported quite some bugs and helped with lots of code and suggestions.
-
- * MagerValp <magervalp@cling.gu.se>
-
- for sample code regarding the Plus/4 banking, the base for the new C128
- conio library supporting 80 column mode and much more.
-
- * Piotr Fusik <P.Fusik@elka.pw.edu.pl>
-
- for the zlib routines, lots of bug reports, code snippets and
- suggestions.
-
- * Josef Soucek <josef.soucek@ct.cz>
-
- Josef contributed the CBM directory routines.
-
- * Stephen L. Judd
-
- for his GRLIB code which is the base of the C64 320x200 TGI driver.
-
- * Stefan A. Haubenthal <polluks@web.de>
-
- Stefan contributed several code snippets for the C64 and Apple ][.
-
- * Peter Trauner <peter.trauner@utanet.at>
-
- Peter added minimal Supervision support.
-
- * The Lynx guys: Bastian Schick, who contributed the code from his own,
- lynx-only version of cc65, and Karri Kaksonen <karri@sipo.fi> and Shawn
- Jefferson <jefferson_shawn_a8bit@yahoo.com> who built on this foundation.
-
- * Oliver Schmidt <ol.sc@web.de> ...
-
- ... for quite some Apple ][ contributions.
-
-
-
-Thanks to
-
- da Blondie <db@tvnet.hu>
- Adam Dunkels <adam@sics.se>
- Bill Craig <craigw@gusun.georgetown.edu>
- C. N. Wong <superufo@netvigator.com>
- Carsten Strotmann <cas@strotmann.de>
- Chris Ward <chris.ward@freenet.co.uk>
- Dagan Galarneau <dagan@dnai.com>
- Darrell Krulce <dkrulce@atcomm.com>
- Dennis Lin <dennis@mosart.com.tw>
- Eric Bacher <ebacher@teaser.fr>
- Gábor Lénárt <lgb@lgb.hu>
- Ingo Korb <unseen@gmx.net>
- Jacek Jozwiak <jacek.jozwiak@interia.pl>
- Jaleco <jaleco@gameone.com.tw>
- Jari Tuominen <jer64@kolumbus.fi>
- Jesse Beach <agmorion@erols.com>
- Joerg Schwedes <joerg.schwedes@siemens.com>
- John Weidman <jweidman@slip.net>
- Jonathan Wright <jonathan.wright@adtran.com>
- Kevin Schuetz <scrapdog@runbox.com>
- Mark Nasgowitz <MNasgowitz@NAZdesign.com>
- Peter Karlsson <peter@softwolves.pp.se>
- Peter Wendrich <pwsoft@syntiac.com>
- Robert R. Wal <rrw@reptile.eu.org>
- Shawn Jefferson <sjefferson@sd62.bc.ca>
- Stefan Andree <sandree@physik.tu-berlin.de>
- Stephan Lesch <slesch@studcs.uni-sb.de>
- Tim Vanderhoek <hoek@FreeBSD.org>
- Todd Elliott <eyeth@videocam.net.au>
- Johan Kotlinski <kotlinski@gmail.com>
-
-for bug reports and suggestions.
-
-
-This list is probably incomplete. So, if you think you should be mentioned
-here, but cannot find yourself, please drop me a mail.
-
-
+++ /dev/null
-# -*- makefile -*-
-#
-# Makefile for the cc65 documentation
-#
-
-# You can put navigation-arrow pictures (next, back, contents) into HTML files
-# by setting this variable, either here or on make's command-line.
-# (You will need to copy the .png files from "share/doc/linuxdoc-tools*/html/".)
-#
-#BUTTONS=-I
-
-# These options decide how text files are made:
-# -f -- removes the backspace-overtyping that makes bold text
-# in the more/less commands and on typewriter-printers
-# -m -- makes Unix manual pages
-#
-#TXT_OPTIONS=-f -m
-
-SGML = apple2.sgml \
- apple2enh.sgml \
- ar65.sgml \
- atari.sgml \
- atmos.sgml \
- c128.sgml \
- c16.sgml \
- c64.sgml \
- ca65.sgml \
- ca65html.sgml \
- cbm510.sgml \
- cbm610.sgml \
- cc65.sgml \
- cl65.sgml \
- co65.sgml \
- coding.sgml \
- customizing.sgml\
- da65.sgml \
- debugging.sgml \
- dio.sgml \
- funcref.sgml \
- geos.sgml \
- grc65.sgml \
- index.sgml \
- intro.sgml \
- ld65.sgml \
- library.sgml \
- lynx.sgml \
- using-make.sgml \
- nes.sgml \
- od65.sgml \
- pet.sgml \
- plus4.sgml \
- smc.sgml \
- sp65.sgml \
- supervision.sgml\
- vic20.sgml
-
-TXT = $(SGML:.sgml=.txt)
-HTML = $(SGML:.sgml=.html)
-INFO = $(SGML:.sgml=.info)
-DVI = $(SGML:.sgml=.dvi)
-TEX = $(SGML:.sgml=.tex)
-
-# ------------------------------------------------------------------------------
-# Pattern-rules, to make targets
-
-%.txt: %.sgml
- linuxdoc -B txt -f $(TXT_OPTIONS) $<
-
-%.html: %.sgml
- linuxdoc -B html --split=1 $(BUTTONS) $<
-
-%.info: %.sgml
- linuxdoc -B info $<
-
-%.dvi: %.sgml
- linuxdoc -B latex --output=dvi $<
-
-%.tex: %.sgml
- linuxdoc -B latex --output=tex $<
-
-# ------------------------------------------------------------------------------
-# Targets
-
-.PHONY: all
-all: txt html info dvi
-
-.PHONY: txt
-txt: linuxdoc $(TXT)
-
-.PHONY: html
-html: linuxdoc $(HTML)
-
-.PHONY: info
-info: linuxdoc $(INFO)
-
-.PHONY: dvi
-dvi: linuxdoc $(DVI)
-
-.PHONY: tex
-tex: linuxdoc $(TEX)
-
-.PHONY: linuxdoc
-linuxdoc:
- @sgmlcheck index >/dev/null 2>&1 || { \
- echo; \
- echo '"LinuxDoc Tools" does not exist on this system.'; \
- echo 'So, most of the documentation might not have been built.'; \
- echo; \
- false;}
-
-.PHONY: clean
-clean:
- $(RM) *~
-
-.PHONY: zap
-zap: clean
- $(RM) $(TXT) $(TEX) $(DVI) *.htm* *.inf* *.man
-
-# ------------------------------------------------------------------------------
-# Special target rules
-
-coding.html: coding.sgml
- sgml2html --split=0 $<
-
-# funcref.sgml's third section is huge.
-# So, funcref.html is split into sub-section files.
-#
-funcref.html: funcref.sgml
- sgml2html --split=2 $(BUTTONS) $<
-
-# The index.html target is special:
-# It is only a table of contents. So, it should not be split.
-#
-index.html: index.sgml
- sgml2html --split=0 $<
+++ /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 builtin config file for the Apple ][,
-which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/).
-The apple2 package comes with additional secondary linker config files, which
-are used via <tt/-C <configfile>/.
-
-
-<sect1>builtin config file<p>
-
-Default configuration optimized for a binary program running on ProDOS 8 with
-BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card
-bank 2 memory from $D400 to $DFFF.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $803 to $95FF (35.5 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $803)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2-dos33.cfg/<p>
-
-Configuration optimized for a binary program running on DOS 3.3. A plain
-vanilla DOS 3.3 doesn't make use of the Language Card at all.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $803 to $95FF (35.5 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D000 to $FFFF (12 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $803)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2-system.cfg/<p>
-
-Configuration for a system program running on ProDOS 8.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $2000 to $BEFF (39.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Fixed ($2000)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- None
-
-</descrip><p>
-
-
-<sect1><tt/apple2-loader.cfg/<p>
-
-Configuration optimized for a binary program running on ProDOS 8 without
-BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
-Apple ][ ProDOS 8 loader for cc65 programs/, which is available
-in the cc65 User Contributions section.
-
-A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but
-isn't tied to the start address $2000. Thus with the default start
-address $800 the main memory area is increased by 6 KB.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $800 to $BEFF (45.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $800)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2-reboot.cfg/<p>
-
-Configuration optimized for a binary program running on ProDOS 8 without
-BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
-Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together
-with the function <tt/rebootafterexit()/.
-
-If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather
-reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of
-the Language Card bank 2 at all.
-
-This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine!
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $800 to $BEFF (45.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D000 to $DFFF (4 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $800)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-
-<sect>ProDOS 8 system programs<p>
-
-ProDOS 8 system programs are always loaded to the start address $2000.
-For cc65 programs this means that the 6 KB from $800 to $2000 are
-by default unused. There are however several options to make use of that memory
-range.
-
-
-<sect1>LOADER.SYSTEM<p>
-
-The easiest (and for really large programs in fact the only) way to have a cc65
-program use the memory from $800 to $2000 is to link it as binary
-(as opposed to system) program using the linker configuration
-<htmlurl url="apple2-4.html#ss4.4" name="apple2-loader.cfg"> with start address
-$800 and load it with <bf/LOADER.SYSTEM - an Apple ][
-ProDOS 8 loader for cc65 programs/. The program then works like a system program
-(i.e. quits to the ProDOS dispatcher).
-
-Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
-program to load under name <program>.SYSTEM as a system program. For
-example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
-
-
-<sect1>Heap<p>
-
-If the cc65 program can be successfully linked as system program using the linker
-configuration <htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> but
-uses the heap either explicitly or implicitly (i.e. by loading a driver) then
-the memory from $800 to $2000 can be added to the heap by calling
-<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
-
-
-<sect1>ProDOS 8 I/O buffers<p>
-
-ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
-these buffers are allocated by the cc65 runtime system on the heap using
-<tt/posix_memalign()/. While this is generally the best solution it means quite
-some overhead for (especially rather small) cc65 programs which do open files
-but don't make use of the heap otherwise.
-
-The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation
-module <tt/apple2-iobuf-0800.o/ which uses the memory between $800 and
-the program start address for the 1 KB I/O buffers. For system programs (with
-start address $2000) this results in up to 6 I/O buffers and thus up to 6
-concurrently open files.
-
-While using <tt/_heapadd()/ as described in the section above together with the
-default I/O buffer allocation basically yields the same placement of I/O buffers
-in memory the primary benefit of <tt/apple2-iobuf-0800.o/ is a reduction in code
-size - and thus program file size - of more than 1400 bytes.
-
-Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command
-line like this:
-
-<tscreen><verb>
-cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o
-</verb></tscreen>
-
-
-
-<sect>Platform specific header files<p>
-
-Programs containing Apple ][ specific code may use the
-<tt/apple2.h/ header file.
-
-
-<sect1>Apple ][ specific functions<p>
-
-The functions listed below are special for the Apple ][. See
-the <htmlurl url="funcref.html" name="function reference"> for declaration and
-usage.
-
-<itemize>
-<item>_auxtype
-<item>_dos_type
-<item>_filetype
-<item>get_ostype
-<item>rebootafterexit
-<item>ser_apple2_slot
-<item>tgi_apple2_mix
-</itemize>
-
-
-<sect1>Hardware access<p>
-
-There's currently no support for direct hardware access. This does not mean
-you cannot do it, it just means that there's no help.
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-<descrip>
-
- <tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag>
- This driver features a resolution of 40×48 with 16 colors.
-
- The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
- function clears the corresponding area at the bottom of the screen.
-
- <tag><tt/a2.hi.tgi (apple2_280_192_8)/</tag>
- This driver features a resolution of 280×192 with 8 colors and two
- hires pages. Note that programs using this driver will have to be linked
- with <tt/--start-addr $4000/ to reserve the first hires page or with
- <tt/--start-addr $6000/ to reserve both hires pages.
-
- The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
- function doesn't clear the corresponding area at the bottom of the screen.
-
- In memory constrained situations the memory from $803 to $1FFF
- can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/
- at the beginning of <tt/main()/. Doing so is beneficial even if the program
- doesn't use the the heap explicitly because loading the driver (and in fact
- already opening the driver file) uses the heap implicitly.
-
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
-
- <tag><tt/a2.auxmem.emd (apple2_auxmem)/</tag>
- Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended
- 80-Column Text Card.
-
- Note that this driver doesn't check for the actual existence of the memory
- and that it doesn't check for ProDOS 8 RAM disk content!
-
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/a2.stdjoy.joy (apple2_stdjoy)/</tag>
- Supports up to two standard analog joysticks connected to the game port of
- the Apple ][.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-<descrip>
-
- <tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag>
- Driver for the AppleMouse II Card. Searches all Apple II slots
- for an AppleMouse II Card compatible firmware. The default bounding
- box is [0..279,0..191].
-
- Programs using this driver will have to be linked with <tt/--start-addr $4000/
- to reserve the first hires page if they are intended to run on an
- Apple ][ (in contrast to an Apple //e) because the
- AppleMouse II Card firmware writes to the hires page when initializing
- on that machine.
-
- Note that the Apple ][ default mouse callbacks support text
- mode only.
-
-</descrip><p>
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/a2.ssc.ser (apple2_ssc)/</tag>
- Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
- hardware flow control (RTS/CTS) and interrupt driven receives. Note
- that because of the peculiarities of the 6551 chip transmits are not
- interrupt driven, and the transceiver blocks if the receiver asserts
- flow control because of a full buffer.
-
- The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to
- <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
- succeeds for all Apple II slots, but <tt/ser_open()/ fails with
- <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
-
-</descrip><p>
-
-
-
-<sect>Limitations<p>
-
-
-<sect1>DOS 3.3<p>
-
-Although the standard binaries generated by the linker for the Apple ][
-generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
-BASIC.SYSTEM) there are some limitations for DOS 3.3:
-
-<descrip>
-
- <tag>Disk File I/O</tag>
- There's no disk file I/O support. Any attempt to use it yields an error with
- <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers
- are in general not functional as they depend on disk file I/O. However they
- may be converted to statically linked drivers using the co65 object-file
- converter.
-
- <tag/Interrupts/
- There's no <tt/interruptor/ support. Any attempt to use it yields the message
- 'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
- <tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on
- interrupts.
-
-</descrip><p>
-
-
-<sect1>Direct console I/O<p>
-
-<descrip>
-
- <tag/Color/
- The Apple ][ has no color text mode. Therefore the functions
- <htmlurl url="funcref-205.html" name="textcolor()">,
- <htmlurl url="funcref-68.html" name="bgcolor()"> and
- <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect.
-
- <tag/Cursor/
- The Apple ][ has no hardware cursor. Therefore the function
- <htmlurl url="funcref-88.html" name="cursor()"> has no effect.
-
-</descrip><p>
-
-
-
-<sect>Other hints<p>
-
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
-]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Interrupts<p>
-
-The runtime for the Apple ][ uses routines marked as
-<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be
-written as simple machine language subroutines and will be called
-automatically by the interrupt handler code when they are linked into a
-program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl
-url="ca65.html" name="assembler manual">.
-
-
-<sect1>DIO<p>
-
-<descrip>
-
- <tag/Drive ID/
- The function <htmlurl url="dio-1.html" name="dio_open()"> has the single
- parameter <tt/device/ to identify the device to be opened. Therefore an
- Apple II slot and drive pair is mapped to that <tt/device/ according
- to the formula
-
- <tscreen>
- device = slot + (drive - 1) * 8
- </tscreen>
-
- so that for example slot 6 drive 2 is mapped to <tt/device/ 14.
-
- <tag/Sector count/
- The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns
- the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
- disk it simply always returns 280 (which is only correct for a 140 KB disk).
- This condition is indicated by the <tt/_oserror/ value 82.
-
-</descrip><p>
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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 builtin config file for the enhanced Apple //e,
-which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/).
-The apple2enh package comes with additional secondary linker config files, which
-are used via <tt/-C <configfile>/.
-
-
-<sect1>builtin config file<p>
-
-Default configuration optimized for a binary program running on ProDOS 8 with
-BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card
-bank 2 memory from $D400 to $DFFF.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $803 to $95FF (35.5 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $803)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2enh-dos33.cfg/<p>
-
-Configuration optimized for a binary program running on DOS 3.3. A plain
-vanilla DOS 3.3 doesn't make use of the Language Card at all.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $803 to $95FF (35.5 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D000 to $FFFF (12 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $803)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2enh-system.cfg/<p>
-
-Configuration for a system program running on ProDOS 8.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $2000 to $BEFF (39.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Fixed ($2000)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- None
-
-</descrip><p>
-
-
-<sect1><tt/apple2enh-loader.cfg/<p>
-
-Configuration optimized for a binary program running on ProDOS 8 without
-BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
-Apple ][ ProDOS 8 loader for cc65 programs/, which is available
-in the cc65 User Contributions section.
-
-A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but
-isn't tied to the start address $2000. Thus with the default start
-address $800 the main memory area is increased by 6 KB.
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $800 to $BEFF (45.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D400 to $DFFF (3 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $800)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-<sect1><tt/apple2enh-reboot.cfg/<p>
-
-Configuration optimized for a binary program running on ProDOS 8 without
-BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an
-Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together
-with the function <tt/rebootafterexit()/.
-
-If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather
-reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of
-the Language Card bank 2 at all.
-
-This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine!
-
-<descrip>
-
- <tag><tt/RAM:/ Main memory area</tag>
- From $800 to $BEFF (45.75 KB)
-
- <tag><tt/LC:/ Language Card memory area</tag>
- From $D000 to $DFFF (4 KB)
-
- <tag><tt/STARTADDRESS:/ Program start address</tag>
- Variable (default: $800)
-
- <tag><tt/HEADER:/ Binary file header</tag>
- DOS 3.3 header (address and length)
-
-</descrip><p>
-
-
-
-<sect>ProDOS 8 system programs<p>
-
-ProDOS 8 system programs are always loaded to the start address $2000.
-For cc65 programs this means that the 6 KB from $800 to $2000 are
-by default unused. There are however several options to make use of that memory
-range.
-
-
-<sect1>LOADER.SYSTEM<p>
-
-The easiest (and for really large programs in fact the only) way to have a cc65
-program use the memory from $800 to $2000 is to link it as binary
-(as opposed to system) program using the linker configuration
-<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address
-$800 and load it with <bf/LOADER.SYSTEM - an Apple ][
-ProDOS 8 loader for cc65 programs/. The program then works like a system program
-(i.e. quits to the ProDOS dispatcher).
-
-Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
-program to load under name <program>.SYSTEM as a system program. For
-example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/.
-
-
-<sect1>Heap<p>
-
-If the cc65 program can be successfully linked as system program using the linker
-configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but
-uses the heap either explicitly or implicitly (i.e. by loading a driver) then
-the memory from $800 to $2000 can be added to the heap by calling
-<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
-
-
-<sect1>ProDOS 8 I/O buffers<p>
-
-ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
-these buffers are allocated by the cc65 runtime system on the heap using
-<tt/posix_memalign()/. While this is generally the best solution it means quite
-some overhead for (especially rather small) cc65 programs which do open files
-but don't make use of the heap otherwise.
-
-The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation
-module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and
-the program start address for the 1 KB I/O buffers. For system programs (with
-start address $2000) this results in up to 6 I/O buffers and thus up to 6
-concurrently open files.
-
-While using <tt/_heapadd()/ as described in the section above together with the
-default I/O buffer allocation basically yields the same placement of I/O buffers
-in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code
-size - and thus program file size - of more than 1400 bytes.
-
-Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command
-line like this:
-
-<tscreen><verb>
-cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o
-</verb></tscreen>
-
-
-
-<sect>Platform specific header files<p>
-
-Programs containing enhanced Apple //e specific code may use the
-<tt/apple2enh.h/ header file.
-
-
-<sect1>Enhanced Apple //e specific functions<p>
-
-The functions listed below are special for the enhanced Apple //e. See
-the <htmlurl url="funcref.html" name="function reference"> for declaration and
-usage.
-
-<itemize>
-<item>_auxtype
-<item>_dos_type
-<item>_filetype
-<item>get_ostype
-<item>rebootafterexit
-<item>ser_apple2_slot
-<item>textframe
-<item>textframexy
-<item>tgi_apple2_mix
-<item>videomode
-</itemize>
-
-
-<sect1>Hardware access<p>
-
-There's currently no support for direct hardware access. This does not mean
-you cannot do it, it just means that there's no help.
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-<descrip>
-
- <tag><tt/a2e.lo.tgi (apple2_40_48_16)/</tag>
- This driver features a resolution of 40×48 with 16 colors.
-
- The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
- function clears the corresponding area at the bottom of the screen.
-
- <tag><tt/a2e.hi.tgi (apple2_280_192_8)/</tag>
- This driver features a resolution of 280×192 with 8 colors and two
- hires pages. Note that programs using this driver will have to be linked
- with <tt/--start-addr $4000/ to reserve the first hires page or with
- <tt/--start-addr $6000/ to reserve both hires pages.
-
- Note that the second hires page is only available if the text display is not in
- 80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/
- before installing the driver.
-
- The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The
- function doesn't clear the corresponding area at the bottom of the screen.
-
- In memory constrained situations the memory from $803 to $1FFF
- can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/
- at the beginning of <tt/main()/. Doing so is beneficial even if the program
- doesn't use the the heap explicitly because loading the driver (and in fact
- already opening the driver file) uses the heap implicitly.
-
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
-
- <tag><tt/a2e.auxmem.emd (apple2_auxmem)/</tag>
- Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended
- 80-Column Text Card.
-
- Note that this driver doesn't check for the actual existence of the memory
- and that it doesn't check for ProDOS 8 RAM disk content!
-
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/a2e.stdjoy.joy (apple2_stdjoy)/</tag>
- Supports up to two standard analog joysticks connected to the game port of
- the enhanced Apple //e.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-<descrip>
-
- <tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag>
- Driver for the AppleMouse II Card. Searches all Apple II slots
- for an AppleMouse II Card compatible firmware. The default bounding
- box is [0..279,0..191].
-
- Note that the enhanced Apple //e default mouse callbacks support
- text mode only.
-
-</descrip><p>
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/a2e.ssc.ser (apple2_ssc)/</tag>
- Driver for the Apple II Super Serial Card. Supports up to 19200 baud,
- hardware flow control (RTS/CTS) and interrupt driven receives. Note
- that because of the peculiarities of the 6551 chip transmits are not
- interrupt driven, and the transceiver blocks if the receiver asserts
- flow control because of a full buffer.
-
- The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to
- <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/
- succeeds for all Apple II slots, but <tt/ser_open()/ fails with
- <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
-
-</descrip><p>
-
-
-
-<sect>Limitations<p>
-
-
-<sect1>DOS 3.3<p>
-
-Although the standard binaries generated by the linker for the enhanced Apple //e
-generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
-BASIC.SYSTEM) there are some limitations for DOS 3.3:
-
-<descrip>
-
- <tag>Disk File I/O</tag>
- There's no disk file I/O support. Any attempt to use it yields an error with
- <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers
- are in general not functional as they depend on disk file I/O. However they
- may be converted to statically linked drivers using the co65 object-file
- converter.
-
- <tag/Interrupts/
- There's no <tt/interruptor/ support. Any attempt to use it yields the message
- 'Failed to alloc interrupt' on program startup. This implicitly means that
- <tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on
- interrupts.
-
-</descrip><p>
-
-
-<sect1>Direct console I/O<p>
-
-<descrip>
-
- <tag/Color/
- The enhanced Apple //e has no color text mode. Therefore the functions
- <htmlurl url="funcref-205.html" name="textcolor()">,
- <htmlurl url="funcref-68.html" name="bgcolor()"> and
- <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect.
-
- <tag/Cursor/
- The enhanced Apple //e has no hardware cursor. Therefore the function
- <htmlurl url="funcref-88.html" name="cursor()"> has no effect.
-
-</descrip><p>
-
-
-
-<sect>Other hints<p>
-
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
-]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Function keys<p>
-
-These are defined to be OpenApple + number key.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the enhanced Apple //e uses routines marked as
-<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be
-written as simple machine language subroutines and will be called
-automatically by the interrupt handler code when they are linked into a
-program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl
-url="ca65.html" name="assembler manual">.
-
-
-<sect1>DIO<p>
-
-<descrip>
-
- <tag/Drive ID/
- The function <htmlurl url="dio-1.html" name="dio_open()"> has the single
- parameter <tt/device/ to identify the device to be opened. Therefore an
- Apple II slot and drive pair is mapped to that <tt/drive_id/ according
- to the formula
-
- <tscreen>
- device = slot + (drive - 1) * 8
- </tscreen>
-
- so that for example slot 6 drive 2 is mapped to <tt/device/ 14.
-
- <tag/Sector count/
- The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns
- the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
- disk it simply always returns 280 (which is only correct for a 140 KB disk).
- This condition is indicated by the <tt/_oserror/ value 82.
-
-</descrip><p>
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the archiver, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von
-Bassewitz. For usage of the binaries and/or sources the following conditions
-do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
-
-
+++ /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.
-
-Please note that Atari specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
-reference">. Even functions marked as "platform dependent" may be available on
-more than one platform. Please see the function reference for more
-information.
-
-
-<sect>Binary format<p>
-
-The standard binary output format generated by the linker for the
-Atari target is a machine language program with a standard executable
-header (FF FF <2 byte start address> <2 bytes end address>
-[program bytes]). These values are calculated in the crt0.s
-file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep
-this in mind if you create a custom linker config file and start
-moving segments around (see section
-<ref name="Reserving a memory area inside the program" id="memhole">).
-You can override this behaviour by creating your own crt0.s file and
-linking it into your program. A run vector is added to the end of the
-file ($02E0 <run vector>) and is calculated using
-__STARTUP_LOAD__ in crt0.s.
-
-
-<sect>Memory layout<p>
-
-The default linker script assumes that the BASIC ROM is disabled (or
-the BASIC cartridge unplugged). This gives a usable memory range from
-$2E00 - $BC1F. The library startup code examines the
-current memory configuration, which depends on the size of the
-installed memory and cartridges present, by inspecting the value in
-the MEMTOP ($2E5) variable. Then the initial stack pointer,
-which indicates the upper bound of memory used, is adjusted. The
-default load address of $2E00 was chosen to accommodate having
-a DOS loaded and a driver that resides in low memory such as the 850
-R: handler. You can override this behaviour by creating a custom
-linker config file or by using the "--start-addr" cl65 command line
-argument or the "--start-addr" or "-S" ld65 command line arguments.
-
-Special locations:
-
-<descrip>
- <tag/Text screen/
- The text screen depends on the installed memory size and cartridges
- and can be obtained from the SAVMSC variable ($58).
-
- <tag/Stack/
- The C runtime stack is located at MEMTOP and grows downwards,
- regardless of how your linker config file is setup. This
- accommodates the different memory configurations of the Atari
- machines, as well as having a cartridge installed. You can override
- this behaviour by writing your own crt0.s file and linking it to
- your program (see also <ref name="Final note"
- id="memhole_final_note">).
-
- <tag/Heap/
- The C heap is located at the end of the program and grows towards the C
- runtime stack.
-
-</descrip><p>
-
-
-
-<sect>Platform specific header files<p>
-
-Programs containing Atari specific code may use the <tt/atari.h/
-header file.
-
-
-<sect1>Atari specific functions<p>
-
-The functions and global variable listed below are special for the Atari.
-See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage.
-
-<itemize>
-<item>get_ostype
-<item>get_tv
-<item>_dos_type
-<item>_gtia_mkcolor
-<item>_getcolor
-<item>_getdefdev
-<item>_graphics
-<item>_rest_vecs
-<item>_save_vecs
-<item>_scroll
-<item>_setcolor
-<item>_setcolor_low
-</itemize>
-
-
-<sect1>Hardware access<p>
-
-The following pseudo variables declared in the <tt/atari.h/ header
-file do allow access to hardware located in the address space. Some
-variables are structures, accessing the struct fields will access the
-chip registers.
-
-<descrip>
-
- <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag>
- The <tt/GTIA_READ/ structure allows read access to the GTIA. The
- <tt/GTIA_WRITE/ structure allows write access to the GTIA.
- See the <tt/_gtia.h/ header file located in the include directory
- for the declaration of the structure.
-
- <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag>
- The <tt/POKEY_READ/ structure allows read access to the POKEY. The
- <tt/POKEY_WRITE/ structure allows write access to the POKEY.
- See the <tt/_pokey.h/ header file located in the include directory
- for the declaration of the structure.
-
- <tag><tt/ANTIC/</tag>
- The <tt/ANTIC/ structure allows read access to the ANTIC.
- See the <tt/_antic.h/ header file located in the include directory
- for the declaration of the structure.
-
- <tag><tt/PIA/</tag>
- The <tt/PIA/ structure allows read access to the PIA 6520.
- See the <tt/_pia.h/ header file located in the include directory
- for the declaration of the structure.
-
-</descrip><p>
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-<descrip>
-
- <tag><tt/atari10.tgi (atari_10)/</tag>
-
- <tag><tt/atr10p2.tgi (atari_10p2)/</tag>
-
- <tag><tt/atari11.tgi (atari_11)/</tag>
-
- <tag><tt/atari14.tgi (atari_14)/</tag>
-
- <tag><tt/atari15.tgi (atari_15)/</tag>
-
- <tag><tt/atr15p2.tgi (atari_15p2)/</tag>
-
- <tag><tt/atari3.tgi (atari_3)/</tag>
-
- <tag><tt/atari4.tgi (atari_4)/</tag>
-
- <tag><tt/atari5.tgi (atari_5)/</tag>
-
- <tag><tt/atari6.tgi (atari_6)/</tag>
-
- <tag><tt/atari7.tgi (atari_7)/</tag>
-
- <tag><tt/atari8.tgi (atari_8)/</tag>
-
- <tag><tt/atr8p2.tgi (atari_8p2)/</tag>
-
- <tag><tt/atari9.tgi (atari_9)/</tag>
-
- <tag><tt/atr9p2.tgi (atari_9p2)/</tag>
-
-</descrip><p>
-
-Many graphics modes require more memory than the text screen which is
-in effect when the program starts up. Therefore the programmer has to
-tell the program beforehand the memory requirements of the graphics
-modes the program intends to use.
-This can be done by using the __RESERVED_MEMORY__ linker config
-variable. The number specified there describes the number of bytes to
-subtract from the top of available memory as seen from the runtime
-library. This memory is then used by the screen buffer.
-
-The numbers for the different graphics modes presented below should
-only be seen as a rule of thumb. Since the screen buffer memory needs
-to start at specific boundaries, the numbers depend on the current top
-of available memory.
-The following numbers were determined by a BASIC program.
-
-<table>
-<tabular ca="rr">
-graphics mode|reserved memory@<hline>
-0|1@
-1|1@
-2|1@
-3|1@
-4|1@
-5|182@
-6|1182@
-7|3198@
-8|7120@
-9|7146@
-10|7146@
-11|7146@
-12|162@
-13|1@
-14|3278@
-15|7120@
-16|1@
-17|1@
-18|1@
-19|1@
-20|1@
-21|184@
-22|1192@
-23|3208@
-24|7146@
-25|7146@
-26|7146@
-27|7146@
-28|162@
-29|1@
-30|3304@
-31|7146
-</tabular>
-<caption>reserved memory required for different graphics modes
-</table>
-
-The values of "1" are needed because the graphics command crashes if
-it doesn't have at least one byte available. This seems to be a bug of
-the Atari ROM code.
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
-
- <tag><tt/atr130xe.emd (atari_130xe)/</tag>
-
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/ataristd.joy (atari_stdjoy)/</tag>
- Supports up to four standard joysticks connected to the joystick ports of
- the Atari.
-
- <tag><tt/atarim8.joy (atari_multijoy)/</tag>
- Supports up to eight standard joysticks connected to a MultiJoy adapter.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist). There is a static driver you can use.
-
-
-<sect1>RS232 device drivers<p>
-
-Currently there are no RS232 loadable drivers available for the Atari
-platform. There is a static driver you can use.
-
-
-<sect>Limitations<p>
-
-
-<sect>DIO implementation<label id="dio"><p>
-
-The Atari supports disk drives with either 128 or 256 byte sectors.
-The first three sectors of any disk are always 128 bytes long though. This is
-because the system can only boot from 128 bytes sectors.
-
-Therefore the DIO read and write functions transfer only 128 bytes
-for sectors 1 to 3, regardless of the type of diskette.
-
-
-<sect>CONIO implementation<label id="conio"><p>
-
-The console I/O is speed optimized therefore support for XEP80 hardware
-or f80.com software is missing. Of course you may use stdio.h functions.
-
-
-<sect>Other hints<p>
-
-
-<sect1>Function keys<p>
-
-Function keys are mapped to Atari + number key.
-
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/ when DOS supports it.
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Leading and trailing spaces around an argument are ignored.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 16 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Interrupts<p>
-
-The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the VBI handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-<sect1>Reserving a memory area inside a program<label id="memhole"><p>
-
-The Atari 130XE maps its additional memory into CPU memory in 16K
-chunks at address $4000 to $7FFF. One might want to
-prevent this memory area from being used by cc65. Other reasons to
-prevent the use of some memory area could be to reserve space for the
-buffers for display lists and screen memory.
-<p>
-The Atari executable format allows holes inside a program, e.g. one
-part loads into $2E00 to $3FFF, going below the reserved
-memory area (assuming a reserved area from $4000 to
-$7FFF), and another part loads into $8000 to
-$BC1F.
-<p>
-Each load chunk of the executable starts with a 4 byte header which
-defines its load address and size. In the following linker scripts
-these headers are named HEADER and SECHDR (for the MEMORY layout), and
-accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout).
-<p>
-<sect2>Low code and high data example<p>
-Goal: Create an executable with 2 load chunks which doesn't use the
-memory area from $4000 to $7FFF. The CODE segment of
-the program should go below $4000 and the DATA and RODATA
-segments should go above $7FFF.
-<p>
-The main problem is that the EXE header generated by the cc65 runtime
-lib is wrong. It defines a single load chunk with the sizes/addresses
-of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user
-program).
-<p>
-The contents of the EXE header come from the EXEHDR segment, which is
-defined in crt0.s. This cannot be changed without modifying and
-recompiling the cc65 atari runtime lib. Therefore the original EXE
-header must be discarded. It will be replaced by a user created
-one. The discarding is done by assigning the EXEHDR segment to the
-BANK memory area. The BANK memory area is discarded in the new linker
-script (written to file "").
-<p>
-The user needs to create a customized linker config file which adds
-new memory areas and segments to hold the new EXE header and the
-header data for the second load chunk. Also an assembly source file
-needs to be created which defines the contents of the new EXE header
-and the second load chunk header.
-<p>
-<p>
-This is an example of a modified cc65 Atari linker configuration file
-(split.cfg):
-<tscreen><verb>
-SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- __RESERVED_MEMORY__: value = $0000, weak = yes;
-}
-FEATURES {
- STARTADDRESS: default = $2E00;
-}
-MEMORY {
- ZP: start = $82, size = $7E, type = rw, define = yes;
-
- HEADER: start = $0000, size = $6, file = %O; # first load chunk
- RAMLO: start = %S, size = $4000 - %S, file = %O;
-
- BANK: start = $4000, size = $4000, file = "";
-
- SECHDR: start = $0000, size = $4, file = %O; # second load chunk
- RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
-}
-SEGMENTS {
- EXEHDR: load = BANK, type = ro;
-
- NEXEHDR: load = HEADER, type = ro; # first load chunk
- STARTUP: load = RAMLO, type = ro, define = yes;
- LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes;
- INIT: load = RAMLO, type = ro, optional = yes;
- CODE: load = RAMLO, type = ro, define = yes;
-
- CHKHDR: load = SECHDR, type = ro; # second load chunk
- RODATA: load = RAM, type = ro, define = yes;
- DATA: load = RAM, type = rw, define = yes;
- BSS: load = RAM, type = bss, define = yes;
- ZPSAVE: load = RAM, type = bss, define = yes;
-
- ZEROPAGE: load = ZP, type = zp;
- AUTOSTRT: load = RAM, type = ro; # defines program entry point
-}
-FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
-}
-</verb></tscreen>
-<p>
-
-A new memory area BANK was added which describes the reserved area.
-It gets loaded with the contents of the old EXEHDR segment. But the
-memory area isn't written to the output file. This way the contents of
-the EXEHDR segment get discarded.
-<p>
-The newly added NEXEHDR segment defines the correct EXE header. It
-puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the
-segments containing only code, into load chunk #1 (RAMLO memory area).
-<p>
-The header for the second load chunk comes from the new CHKHDR
-segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load
-chunk #2 (RAM memory area).
-<p>
-<p>
-The contents of the new NEXEHDR and CHKHDR segments come from this
-file (split.s):
-<tscreen><verb>
- .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__
- .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__
-
- .segment "NEXEHDR"
- .word $FFFF
- .word __STARTUP_LOAD__
- .word __CODE_LOAD__ + __CODE_SIZE__ - 1
-
- .segment "CHKHDR"
- .word __RODATA_LOAD__
- .word __BSS_LOAD__ - 1
-</verb></tscreen>
-<p>
-Compile with
-<tscreen><verb>
-cl65 -t atari -C split.cfg -o prog.com prog.c split.s
-</verb></tscreen>
-
-<sect2>Low data and high code example<p>
-
-
-Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT,
-CODE, BSS, ZPSAVE into high memory (split2.cfg):
-
-<tscreen><verb>
-SYMBOLS {
- __STACKSIZE__ = $800; # 2K stack
- __RESERVED_MEMORY__: value = $0000, weak = yes;
-}
-FEATURES {
- STARTADDRESS: default = $2E00;
-}
-MEMORY {
- ZP: start = $82, size = $7E, type = rw, define = yes;
-
- HEADER: start = $0000, size = $6, file = %O; # first load chunk
- RAMLO: start = %S, size = $4000 - %S, file = %O;
-
- BANK: start = $4000, size = $4000, file = "";
-
- SECHDR: start = $0000, size = $4, file = %O; # second load chunk
- RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F
-}
-SEGMENTS {
- EXEHDR: load = BANK, type = ro; # discarded old EXE header
-
- NEXEHDR: load = HEADER, type = ro; # first load chunk
- RODATA: load = RAMLO, type = ro, define = yes;
- DATA: load = RAMLO, type = rw, define = yes;
-
- CHKHDR: load = SECHDR, type = ro; # second load chunk
- STARTUP: load = RAM, type = ro, define = yes;
- INIT: load = RAM, type = ro, optional = yes;
- CODE: load = RAM, type = ro, define = yes;
- ZPSAVE: load = RAM, type = bss, define = yes;
- BSS: load = RAM, type = bss, define = yes;
-
- ZEROPAGE: load = ZP, type = zp;
- AUTOSTRT: load = RAM, type = ro; # defines program entry point
-}
-FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- CONDES: segment = RODATA,
- type = destructor,
- label = __DESTRUCTOR_TABLE__,
- count = __DESTRUCTOR_COUNT__;
-}
-</verb></tscreen>
-
-New contents for NEXEHDR and CHKHDR are needed (split2.s):
-<tscreen><verb>
- .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__
- .import __DATA_LOAD__, __RODATA_LOAD__
-
- .segment "NEXEHDR"
- .word $FFFF
- .word __RODATA_LOAD__
- .word __DATA_LOAD__ + __DATA_SIZE__ - 1
-
- .segment "CHKHDR"
- .word __STARTUP_LOAD__
- .word __ZPSAVE_LOAD__ - 1
-</verb></tscreen>
-
-Compile with
-<tscreen><verb>
-cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s
-</verb></tscreen>
-
-<sect2>Final note<label id="memhole_final_note"><p>
-
-There are two other memory areas which don't appear directly in the
-linker script. They are the stack and the heap.
-
-The cc65 runtime lib places the stack location at the end of available
-memory. This is dynamically set from the MEMTOP system variable at
-startup. The heap is located in the area between the end of the BSS
-segment and the top of the stack as defined by __STACKSIZE__.
-
-If BSS and/or the stack shouldn't stay at the end of the program,
-some parts of the cc65 runtime lib need to be replaced/modified.
-
-common/_heap.s defines the location of the heap and atari/crt0.s
-defines the location of the stack by initializing sp.
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org"> or <htmlurl url="mailto:chris@groessler.org"
-name="chris@groessler.org"> ).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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)/</tag>
- This driver was written by Greg King and Stefan Haubenthal.
- It features a resolution of 228×200 with a palette of two colors that
- can be chosen from the Atmos's eight colors. The driver supports a third
- palette-"color" that actually "flips" the pixel (it becomes the other color)
- that is on the screen under the graphics cursor.
-
- <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag>
- This driver was written by Stefan Haubenthal and Greg King.
- It features a resolution of 240×200 with black and white colors.
- It is the default graphics driver for the Atmos.
-
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-No extended memory drivers are currently available for the Atmos.
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/atmos-pase.joy (atmos_pase)/</tag>
- Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the Atmos.
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/atmos-acia.ser (atmos_acia)/</tag>
- Driver for the Telestrat integrated serial controller and the Atmos with a
- serial add-on.
- Note that because of the peculiarities of the 6551 chip together with the
- use of the NMI, transmits are not interrupt driven, and the transceiver
- blocks if the receiver asserts flow control because of a full buffer.
-
-</descrip><p>
-
-
-
-<sect>Limitations<label id="limitations"><p>
-
-<sect1>Disk I/O<p>
-
-The existing library for the Atmos doesn't implement C file
-I/O. There is one hack for the <tt/write()/ routine in
-place, which will make functions work that write to <tt/stdout/
-(like <tt/printf()/). However, this function has some shortcomings which
-won't be fixed, because it's going to be replaced anyway.
-
-To be more concrete, this limitation means that you cannot use any of the
-following functions (and a few others):
-
-<itemize>
-<item>fclose
-<item>fopen
-<item>fread
-<item>fprintf
-<item>fputc
-<item>fscanf
-<item>fwrite
-<item>...
-</itemize>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Function keys<p>
-
-These are defined to be FUNCT + number key.
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- CALL#500:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Interrupts<p>
-
-The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
-
-
+++ /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_640_200_2)/</tag>
- This driver was written by Maciej Witkowiak. It uses the 80 column display
- and features a resolution of 640*200 with two colors and an adjustable
- palette (that means that the two colors can be chosen out of the 16 VDC
- colors).
-
- <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag>
- This driver was written by Maciej Witkowiak. This driver uses the 80 column
- display and features a resolution of 640*480 with two colors and an
- adjustable palette (that means that the two colors can be chosen out of the
- 16 VDC colors). The driver requires 64KB VDC RAM.
-</descrip><p>
-
-Note: The colors are translated from definitions in headers to correct VDC values
-so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are
-missing on VDC and are translated to the two colors missing from VIC palette.
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
-
- <tag><tt/c128-georam.emd (c128_georam)/</tag>
- A driver for the GeoRam cartridge. The driver will always assume 2048 pages
- of 256 bytes each. There are no checks, so if your program knows better,
- just go ahead.
-
- <tag><tt/c128-ram.emd (c128_ram)/</tag>
- An extended memory driver for the RAM in page 1. The common memory area is
- excluded, so this driver supports 251 pages of 256 bytes each.
-
- <tag><tt/c128-ram2.emd (c128_ram2)/</tag>
-
- An extended memory driver for the RAM in pages 1-3. The common memory area
- is excluded, so this driver supports up to 731 pages of 256 bytes each. The
- driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM
- in pages 2+3 is autodetected, but it's larger and there are not many
- machines with RAM in banks 2+3, so it has been made a separate driver. The
- additional code was contributed by Marco van den Heuvel.
-
- <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag>
- A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
- Will test the hardware for the available RAM.
-
- <tag><tt/c128-reu.emd (c128_reu)/</tag>
- A driver for the CBM REUs. The driver will determine from the connected REU
- if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
- but since there are no range checks, the application can use more memory if
- it has better knowledge about the hardware than the driver.
-
- <tag><tt/c128-vdc.emd (c128_vdc)/</tag>
- A driver for the VDC memory of the C128 written and contributed by Maciej
- Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers
- 64 or 256 pages of 256 bytes each. Note: This driver is incompatible with
- any of the graphics drivers using the VDC!
-
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag>
- Driver for the Protovision 4-player adapter originally written by Groepaz
- for the C64 and converted for the C128 by me. See <htmlurl
- url="http://www.protovision-online.de/hardw/hardwstart.htm"
- name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
- building instructions. Up to four joysticks are supported.
-
- <tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag>
- Supports up to two joysticks connected to the standard joysticks port of
- the C128.
-
-</descrip><p>
-
-
-
-<sect1>Mouse drivers<p>
-
-<descrip>
-
- <tag><tt/c128-1351.mou (c128_1351)/</tag>
- Supports a standard mouse connected to port #0 of the C128.
-
- <tag><tt/c128-joy.mou (c128_joymouse)/</tag>
- Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
- #1 of the C128.
-
- <tag><tt/c128-pot.mou (c128_potmouse)/</tag>
- Supports a potentiometer device e.g. Koala Pad connected to port #1 of
- the C128.
-
-</descrip><p>
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/c128-swlink.ser (c128_swlink)/</tag>
- Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
- control (RTS/CTS) and interrupt driven receives. Note that because of the
- peculiarities of the 6551 chip together with the use of the NMI, transmits
- are not interrupt driven, and the transceiver blocks if the receiver asserts
- flow control because of a full buffer.
-
- The driver uses the RS232 variables and buffers of the kernal (buffers at
- $C00 and $D00).
-
-</descrip><p>
-
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the C128 uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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)/</tag>
- A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125
- pages with 256 bytes each if the machine is equipped with 64K of memory
- (a Plus/4 or a memory extended C16/116).
-
-</descrip><p>
-
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag>
- Supports up to two joysticks connected to the standard joysticks port of
- the Commodore 16/116.
-
-</descrip><p>
-
-
-
-<sect1>Mouse drivers<p>
-
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist).
-
-
-<sect1>RS232 device drivers<p>
-
-The Commodore 16 does not have a builtin ACIA and no RS232 extensions are
-known. For this reason, there are no RS232 drivers available. Please note that
-the standard Plus/4 driver will <em>not</em> run together with the C16
-library, because the latter does not support interrupts needed by the driver.
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the C16 uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
-
-
-
+++ /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 builtin config file for the Commodore 64,
-which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The
-c64 package comes with additional secondary linker config files, which are
-used via <tt/-C <configfile>/.
-
-
-<sect1>builtin config file<p>
-
-The builtin configuration is tailored to C programs. It supplies the load
-address and a small BASIC stub that starts the compiled program using a SYS
-command.
-
-
-<sect1><tt/c64-asm.cfg/<p>
-
-This configuration is made for assembler programmers who don't need a special
-setup. The default start address is $801. It can be changed with the
-linker command line option <tt/--start-addr/. All standard segments with the
-exception of <tt/zeropage/ are written to the output file and a two byte load
-address is prepended.
-
-To use this config file, assemble with <tt/-t c64/ and link with <tt/-C
-c64-asm.cfg/. The former will make sure that correct character translation is
-in effect, while the latter supplies the actual config. When using <tt/cl65/,
-use both command line options.
-
-Sample command line for <tt/cl65/:
-
-<tscreen><verb>
-cl65 -o file.prg -t c64 -C c64-asm.cfg source.s
-</verb></tscreen>
-
-To generate code that loads to $C000:
-
-<tscreen><verb>
-cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s
-</verb></tscreen>
-
-It is also possible to add a small BASIC header to the program, that uses SYS
-to jump to the program entry point (which is the start of the code segment).
-The advantage is that the program can be started using RUN.
-
-To generate a program with a BASIC SYS header, use
-
-<tscreen><verb>
-cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s
-</verb></tscreen>
-
-Please note that in this case a changed start address doesn't make sense,
-since the program must be loaded to the BASIC start address.
-
-
-<sect>Platform specific header files<p>
-
-Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/
-header files. Using the later may be an option when writing code for more than
-one CBM platform, since it includes <tt/c64.h/ and declares several functions
-common to all CBM platforms.
-
-
-<sect1>C64 specific functions<p>
-
-The functions listed below are special for the C64. See the <htmlurl
-url="funcref.html" name="function reference"> for declaration and usage.
-
-<itemize>
-<item>get_ostype
-</itemize>
-
-
-<sect1>CBM specific functions<p>
-
-Some functions are available for all (or at least most) of the Commodore
-machines. See the <htmlurl url="funcref.html" name="function reference"> for
-declaration and usage.
-
-<itemize>
-<item>cbm_close
-<item>cbm_closedir
-<item>cbm_k_setlfs
-<item>cbm_k_setnam
-<item>cbm_k_load
-<item>cbm_k_save
-<item>cbm_k_open
-<item>cbm_k_close
-<item>cbm_k_readst
-<item>cbm_k_chkin
-<item>cbm_k_ckout
-<item>cbm_k_basin
-<item>cbm_k_bsout
-<item>cbm_k_clrch
-<item>cbm_load
-<item>cbm_open
-<item>cbm_opendir
-<item>cbm_read
-<item>cbm_readdir
-<item>cbm_save
-<item>cbm_write
-<item>get_tv
-</itemize>
-
-
-<sect1>Hardware access<p>
-
-The following pseudo variables declared in the <tt/c64.h/ header file do allow
-access to hardware located in the address space. Some variables are
-structures, accessing the struct fields will access the chip registers.
-
-<descrip>
-
- <tag><tt/VIC/</tag>
- The <tt/VIC/ structure allows access to the VIC II (the graphics
- controller). See the <tt/_vic2.h/ header file located in the include
- directory for the declaration of the structure.
-
- <tag><tt/SID/</tag>
- The <tt/SID/ structure allows access to the SID (the sound interface
- device). See the <tt/_sid.h/ header file located in the include directory
- for the declaration of the structure.
-
- <tag><tt/CIA1, CIA2/</tag>
- Access to the two CIA (complex interface adapter) chips is available via
- the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables
- is explained in <tt/_6526.h/.
-
- <tag><tt/COLOR_RAM/</tag>
- A character array that mirrors the color RAM of the C64 at $D800.
-
-</descrip><p>
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-<em>Note:</em> All available graphics drivers for the TGI interface will use
-the space below the I/O area and kernal ROM, so you can have hires graphics in
-the standard setup without any memory loss or need for a changed
-configuration.
-
-<descrip>
- <tag><tt/c64-hi.tgi (c64_320_200_2)/</tag>
- This driver features a resolution of 320*200 with two colors and an
- adjustable palette (that means that the two colors can be chosen out of a
- palette of the 16 C64 colors).
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
-
- <tag><tt/c64-c256k.emd (c64_c256k)/</tag>
- A driver for the C64 256K memory expansion. This driver offers 768 pages of
- 256 bytes each. Written and contributed by Marco van den Heuvel.
-
- <tag><tt/c64-dqbb.emd (c64_dqbb)/</tag>
- A driver for the Double Quick Brown Box cartridge. This driver offers
- 64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel.
-
- <tag><tt/c64-georam.emd (c64_georam)/</tag>
- A driver for the Berkeley Softworks GeoRam cartridge. The driver will
- determine the available RAM from the connected cartridge. It supports 64KB
- up to 2048KB of RAM.
-
- <tag><tt/c64-isepic.emd (c64_isepic)/</tag>
- A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256
- bytes each. Written and contributed by Marco van den Heuvel.
-
- <tag><tt/c64-ram.emd (c64_ram)/</tag>
- A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48
- 256 byte pages. Please note that this driver is incompatible with any of the
- graphics drivers!
-
- <tag><tt/c64-ramcart.emd (c64_ramcart)/</tag>
- A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak.
- Will test the hardware for the available RAM.
-
- <tag><tt/c64-reu.emd (c64_reu)/</tag>
- A driver for the CBM REUs. The driver will determine from the connected REU
- if it supports 128KB of RAM or more. In the latter case, 256KB are assumed,
- but since there are no range checks, the application can use more memory if
- it has better knowledge about the hardware than the driver.
-
- <tag><tt/c64-vdc.emd (c64_vdc)/</tag>
- A driver for the VDC memory of the C128. Written and contributed by Maciej
- Witkowiak. Can be used if the program is running in C64 mode of the C128.
- Autodetects the amount of memory available (16 or 64K) and offers 64 or 256
- pages of 256 bytes each.
-
- <tag><tt/dtv-himem.emd (dtv_himem)/</tag>
- A driver for the C64 D2TV (the second or PAL version). This driver offers
- indeed 7680 pages of 256 bytes each.
-
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag>
- Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See
- <htmlurl url="http://www.digitalexcess.de/downloads/productions.php"
- name="http://www.digitalexcess.de/downloads/productions.php"> on
- instructions how to build one. Up to four joysticks are supported.
-
- <tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag>
- Driver for the Protovision 4-player adapter contributed by Groepaz. See
- <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
- name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
- building instructions. Up to four joysticks are supported.
-
- <tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag>
- Supports up to two standard joysticks connected to the joysticks port of
- the C64.
-
- <tag><tt/c64-numpad.joy (c64_numpad)/</tag>
- Supports one joystick emulated by the numberpad of the C128 in C64 mode,
- the firebutton is labeled &dquot;5&dquot; and ENTER.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-<descrip>
-
- <tag><tt/c64-1351.mou (c64_1351)/</tag>
- Supports a standard mouse connected to port #0 of the C64.
-
- <tag><tt/c64-joy.mou (c64_joymouse)/</tag>
- Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port
- #1 of the C64.
-
- <tag><tt/c64-pot.mou (c64_potmouse)/</tag>
- Supports a potentiometer device e.g. Koala Pad connected to port #1 of
- the C64.
-
-</descrip><p>
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/c64-swlink.ser (c64_swlink)/</tag>
- Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow
- control (RTS/CTS) and interrupt driven receives. Note that because of the
- peculiarities of the 6551 chip together with the use of the NMI, transmits
- are not interrupt driven, and the transceiver blocks if the receiver asserts
- flow control because of a full buffer.
-
-</descrip><p>
-
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Escape code<p>
-
-For an Esc press CTRL and [ key.
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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
- --forget-inc-paths Forget include search paths
- --help Help (this text)
- --ignore-case Ignore case of symbols
- --include-dir dir Set an include directory search path
- --large-alignment Don't warn about large alignments
- --listing name Create a listing file if assembly was ok
- --list-bytes n Maximum number of bytes per listing line
- --macpack-dir dir Set a macro package directory
- --memory-model model Set the memory model
- --pagelength n Set the page length for the listing
- --relax-checks Relax some checks (see docs)
- --smart Enable smart mode
- --target sys Set the target system
- --verbose Increase verbosity
- --version Print the assembler version
----------------------------------------------------------------------------
-</verb></tscreen>
-
-
-<sect1>Command line options in detail<p>
-
-Here is a description of all the command line options:
-
-<descrip>
-
- <label id="option--bin-include-dir">
- <tag><tt>--bin-include-dir dir</tt></tag>
-
- Name a directory which is searched for binary include files. The option
- may be used more than once to specify more than one directory to search. The
- current directory is always searched first before considering any
- additional directories. See also the section about <ref id="search-paths"
- name="search paths">.
-
-
- <label id="option--cpu">
- <tag><tt>--cpu type</tt></tag>
-
- Set the default for the CPU type. The option takes a parameter, which
- may be one of
-
- 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280
-
- The sunplus cpu is not available in the freeware version, because the
- instruction set is "proprietary and confidential".
-
-
- <label id="option-create-dep">
- <tag><tt>--create-dep name</tt></tag>
-
- Tells the assembler to generate a file containing the dependency list for
- the assembled module in makefile syntax. The output is written to a file
- with the given name. The output does not include files passed via debug
- information to the assembler.
-
-
- <label id="option-create-full-dep">
- <tag><tt>--create-full-dep name</tt></tag>
-
- Tells the assembler to generate a file containing the dependency list for
- the assembled module in makefile syntax. The output is written to a file
- with the given name. The output does include files passed via debug
- information to the assembler.
-
-
- <tag><tt>-d, --debug</tt></tag>
-
- Enables debug mode, something that should not be needed for mere
- mortals:-)
-
-
- <label id="option--feature">
- <tag><tt>--feature name</tt></tag>
-
- Enable an emulation feature. This is identical as using <tt/.FEATURE/
- in the source with two exceptions: Feature names must be lower case, and
- each feature must be specified by using an extra <tt/--feature/ option,
- comma separated lists are not allowed.
-
- See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt>
- command for a list of emulation features.
-
-
- <label id="option--forget-inc-paths">
- <tag><tt>--forget-inc-paths</tt></tag>
-
- Forget the builtin include paths. This is most useful when building
- customized assembler modules, in which case the standard header files should
- be ignored.
-
-
- <label id="option-g">
- <tag><tt>-g, --debug-info</tt></tag>
-
- When this option (or the equivalent control command <tt/.DEBUGINFO/) is
- used, the assembler will add a section to the object file that contains
- all symbols (including local ones) together with the symbol values and
- source file positions. The linker will put these additional symbols into
- the VICE label file, so even local symbols can be seen in the VICE
- monitor.
-
-
- <label id="option-h">
- <tag><tt>-h, --help</tt></tag>
-
- Print the short option summary shown above.
-
-
- <label id="option-i">
- <tag><tt>-i, --ignore-case</tt></tag>
-
- This option makes the assembler case insensitive on identifiers and labels.
- This option will override the default, but may itself be overridden by the
- <tt><ref id=".CASE" name=".CASE"></tt> control command.
-
-
- <label id="option-l">
- <tag><tt>-l name, --listing name</tt></tag>
-
- Generate an assembler listing with the given name. A listing file will
- never be generated in case of assembly errors.
-
-
- <label id="option--large-alignment">
- <tag><tt>--large-alignment</tt></tag>
-
- Disable warnings about a large combined alignment. See the discussion of the
- <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for futher information.
-
-
- <label id="option--list-bytes">
- <tag><tt>--list-bytes n</tt></tag>
-
- Set the maximum number of bytes printed in the listing for one line of
- input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive
- for more information. The value zero can be used to encode an unlimited
- number of printed bytes.
-
-
- <label id="option--macpack-dir">
- <tag><tt>--macpack-dir dir</tt></tag>
-
- This options allows to specify a directory containing macro files that are
- used instead of the builtin images when a <tt><ref id=".MACPACK"
- name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt>
- was specified, a <tt>.mac</tt> extension is added to the package name and
- the resulting file is loaded from the given directory. This is most useful
- when debugging the builtin macro packages.
-
-
- <label id="option-mm">
- <tag><tt>-mm model, --memory-model model</tt></tag>
-
- Define the default memory model. Possible model specifiers are near, far and
- huge.
-
-
- <label id="option-o">
- <tag><tt>-o name</tt></tag>
-
- The default output name is the name of the input file with the extension
- replaced by ".o". If you don't like that, you may give another name with
- the -o option. The output file will be placed in the same directory as
- the source file, or, if -o is given, the full path in this name is used.
-
-
- <label id="option--pagelength">
- <tag><tt>--pagelength n</tt></tag>
-
- sets the length of a listing page in lines. See the <tt><ref
- id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information.
-
-
- <label id="option--relax-checks">
- <tag><tt>--relax-checks</tt></tag>
-
- Relax some checks done by the assembler. This will allow code that is an
- error in most cases and flagged as such by the assembler, but can be valid
- in special situations.
-
- Examples are:
-<itemize>
-<item>Short branches between two different segments.
-<item>Byte sized address loads where the address is not a zeropage address.
-</itemize>
-
-
- <label id="option-s">
- <tag><tt>-s, --smart-mode</tt></tag>
-
- In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt>
- pseudo instruction) the assembler will track usage of the <tt/REP/ and
- <tt/SEP/ instructions in 65816 mode and update the operand sizes
- accordingly. If the operand of such an instruction cannot be evaluated by
- the assembler (for example, because the operand is an imported symbol), a
- warning is issued.
-
- Beware: Since the assembler cannot trace the execution flow this may
- lead to false results in some cases. If in doubt, use the .ixx and .axx
- instructions to tell the assembler about the current settings. Smart
- mode is off by default.
-
-
- <label id="option-t">
- <tag><tt>-t sys, --target sys</tt></tag>
-
- Set the target system. This will enable translation of character strings and
- character constants into the character set of the target platform. The
- default for the target system is "none", which means that no translation
- will take place. The assembler supports the same target systems as the
- compiler, see there for a list.
-
- Depending on the target, the default CPU type is also set. This can be
- overriden by using the <tt/<ref id="option--cpu" name="--cpu">/ option.
-
-
- <label id="option-v">
- <tag><tt>-v, --verbose</tt></tag>
-
- Increase the assembler verbosity. Usually only needed for debugging
- purposes. You may use this option more than one time for even more
- verbose output.
-
-
- <label id="option-D">
- <tag><tt>-D</tt></tag>
-
- This option allows you to define symbols on the command line. Without a
- value, the symbol is defined with the value zero. When giving a value,
- you may use the '$' prefix for hexadecimal symbols. Please note
- that for some operating systems, '$' has a special meaning, so
- you may have to quote the expression.
-
-
- <label id="option-I">
- <tag><tt>-I dir, --include-dir dir</tt></tag>
-
- Name a directory which is searched for include files. The option may be
- used more than once to specify more than one directory to search. The
- current directory is always searched first before considering any
- additional directories. See also the section about <ref id="search-paths"
- name="search paths">.
-
-
- <label id="option-U">
- <tag><tt>-U, --auto-import</tt></tag>
-
- Mark symbols that are not defined in the sources as imported symbols. This
- should be used with care since it delays error messages about typos and such
- until the linker is run. The compiler uses the equivalent of this switch
- (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported
- symbols for the runtime library. However, the compiler is supposed to
- generate code that runs through the assembler without problems, something
- which is not always true for assembler programmers.
-
-
- <label id="option-V">
- <tag><tt>-V, --version</tt></tag>
-
- Print the version number of the assembler. If you send any suggestions
- or bugfixes, please include the version number.
-
-
- <label id="option-W">
- <tag><tt>-Wn</tt></tag>
-
- Set the warning level for the assembler. Using -W2 the assembler will
- even warn about such things like unused imported symbols. The default
- warning level is 1, and it would probably be silly to set it to
- something lower.
-
-</descrip>
-<p>
-
-
-
-<sect>Search paths<label id="search-paths"><p>
-
-Normal include files are searched in the following places:
-
-<enum>
-<item>The current directory.
-<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt>
- on Linux systems.
-<item>The value of the environment variable <tt/CA65_INC/ if it is defined.
-<item>A subdirectory named <tt/asminc/ of the directory defined in the
- environment variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option
-on the command line.
-</enum>
-
-Binary include files are searched in the following places:
-
-<enum>
-<item>The current directory.
-<item>Any directory added with the <tt/<ref id="option--bin-include-dir"
-name="--bin-include-dir">/ option on the command line.
-</enum>
-
-
-
-<sect>Input format<p>
-
-<sect1>Assembler syntax<p>
-
-The assembler accepts the standard 6502/65816 assembler syntax. One line may
-contain a label (which is identified by a colon), and, in addition to the
-label, an assembler mnemonic, a macro, or a control command (see section <ref
-id="control-commands" name="Control Commands"> for supported control
-commands). Alternatively, the line may contain a symbol definition using
-the '=' token. Everything after a semicolon is handled as a comment (that is,
-it is ignored).
-
-Here are some examples for valid input lines:
-
-<tscreen><verb>
- Label: ; A label and a comment
- lda #$20 ; A 6502 instruction plus comment
- L1: ldx #$20 ; Same with label
- L2: .byte "Hello world" ; Label plus control command
- mymac $20 ; Macro expansion
- MySym = 3*L1 ; Symbol definition
- MaSym = Label ; Another symbol
-</verb></tscreen>
-
-The assembler accepts
-
-<itemize>
-<item>all valid 6502 mnemonics when in 6502 mode (the default or after the
- <tt><ref id=".P02" name=".P02"></tt> command was given).
-<item>all valid 6502 mnemonics plus a set of illegal instructions when in
- <ref id="6502X-mode" name="6502X mode">.
-<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the
- <tt><ref id=".PSC02" name=".PSC02"></tt> command was given).
-<item>all valid 65C02 mnemonics when in 65C02 mode (after the
- <tt><ref id=".PC02" name=".PC02"></tt> command was given).
-<item>all valid 65618 mnemonics when in 65816 mode (after the
- <tt><ref id=".P816" name=".P816"></tt> command was given).
-<item>all valid SunPlus mnemonics when in SunPlus mode (after the
- <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given).
-</itemize>
-
-
-<sect1>65816 mode<p>
-
-In 65816 mode several aliases are accepted in addition to the official
-mnemonics:
-
-<tscreen><verb>
- BGE is an alias for BCS
- BLT is an alias for BCC
- CPA is an alias for CMP
- DEA is an alias for DEC A
- INA is an alias for INC A
- SWA is an alias for XBA
- TAD is an alias for TCD
- TAS is an alias for TCS
- TDA is an alias for TDC
- TSA is an alias for TSC
-</verb></tscreen>
-
-
-
-<sect1>6502X mode<label id="6502X-mode"><p>
-
-6502X mode is an extension to the normal 6502 mode. In this mode, several
-mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since
-these instructions are illegal, there are no official mnemonics for them. The
-unofficial ones are taken from <htmlurl
-url="http://www.oxyron.de/html/opcodes02.html"
-name="http://www.oxyron.de/html/opcodes02.html">. Please note that only the
-ones marked as "stable" are supported. The following table uses information
-from the mentioned web page, for more information, see there.
-
-<itemize>
-<item><tt>ALR: A:=(A and #{imm})/2;</tt>
-<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B.
-<item><tt>ARR: A:=(A and #{imm})/2;</tt>
-<item><tt>AXS: X:=A and X-#{imm};</tt>
-<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt>
-<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt>
-<item><tt>LAS: A,X,S:={adr} and S;</tt>
-<item><tt>LAX: A,X:={adr};</tt>
-<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt>
-<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt>
-<item><tt>SAX: {adr}:=A and X;</tt>
-<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt>
-<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt>
-</itemize>
-
-
-
-<sect1>sweet16 mode<label id="sweet16-mode"><p>
-
-SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak
-for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can
-generate code for this pseudo CPU when switched into sweet16 mode. The
-following is special in sweet16 mode:
-
-<itemize>
-
-<item>The '@' character denotes indirect addressing and is no longer available
-for cheap local labels. If you need cheap local labels, you will have to
-switch to another lead character using the <tt/<ref id=".LOCALCHAR"
-name=".LOCALCHAR">/ command.
-
-<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode,
-these identifiers are reserved words.
-
-</itemize>
-
-Please note that the assembler does neither supply the interpreter needed for
-SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers,
-nor does it call the interpreter. All this must be done by your program. Apple
-][ programmers do probably know how to use sweet16 mode.
-
-For more information about SWEET 16, see
-<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm"
-name="http://www.6502.org/source/interpreters/sweet16.htm">.
-
-
-<sect1>Number format<p>
-
-For literal values, the assembler accepts the widely used number formats: A
-preceding '$' or a trailing 'h' denotes a hex value, a preceding '%'
-denotes a binary value, and a bare number is interpreted as a decimal. There
-are currently no octal values and no floats.
-
-
-<sect1>Conditional assembly<p>
-
-Please note that when using the conditional directives (<tt/.IF/ and friends),
-the input must consist of valid assembler tokens, even in <tt/.IF/ branches
-that are not assembled. The reason for this behaviour is that the assembler
-must still be able to detect the ending tokens (like <tt/.ENDIF/), so
-conversion of the input stream into tokens still takes place. As a consequence
-conditional assembly directives may <bf/not/ be used to prevent normal text
-(used as a comment or similar) from being assembled. <p>
-
-
-<sect>Expressions<p>
-
-
-<sect1>Expression evaluation<p>
-
-All expressions are evaluated with (at least) 32 bit precision. An
-expression may contain constant values and any combination of internal and
-external symbols. Expressions that cannot be evaluated at assembly time
-are stored inside the object file for evaluation by the linker.
-Expressions referencing imported symbols must always be evaluated by the
-linker.
-
-
-<sect1>Size of an expression result<p>
-
-Sometimes, the assembler must know about the size of the value that is the
-result of an expression. This is usually the case, if a decision has to be
-made, to generate a zero page or an absolute memory references. In this
-case, the assembler has to make some assumptions about the result of an
-expression:
-
-<itemize>
-<item> If the result of an expression is constant, the actual value is
- checked to see if it's a byte sized expression or not.
-<item> If the expression is explicitly casted to a byte sized expression by
- one of the '>', '<' or '^' operators, it is a byte expression.
-<item> If this is not the case, and the expression contains a symbol,
- explicitly declared as zero page symbol (by one of the .importzp or
- .exportzp instructions), then the whole expression is assumed to be
- byte sized.
-<item> If the expression contains symbols that are not defined, and these
- symbols are local symbols, the enclosing scopes are searched for a
- symbol with the same name. If one exists and this symbol is defined,
- its attributes are used to determine the result size.
-<item> In all other cases the expression is assumed to be word sized.
-</itemize>
-
-Note: If the assembler is not able to evaluate the expression at assembly
-time, the linker will evaluate it and check for range errors as soon as
-the result is known.
-
-
-<sect1>Boolean expressions<p>
-
-In the context of a boolean expression, any non zero value is evaluated as
-true, any other value to false. The result of a boolean expression is 1 if
-it's true, and zero if it's false. There are boolean operators with extreme
-low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/
-operators are shortcut operators. That is, if the result of the expression is
-already known, after evaluating the left hand side, the right hand side is
-not evaluated.
-
-
-<sect1>Constant expressions<p>
-
-Sometimes an expression must evaluate to a constant without looking at any
-further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command
-that decides if parts of the code are assembled or not. An expression used in
-the <tt/.IF/ command cannot reference a symbol defined later, because the
-decision about the <tt/.IF/ must be made at the point when it is read. If the
-expression used in such a context contains only constant numerical values,
-there is no problem. When unresolvable symbols are involved it may get harder
-for the assembler to determine if the expression is actually constant, and it
-is even possible to create expressions that aren't recognized as constant.
-Simplifying the expressions will often help.
-
-In cases where the result of the expression is not needed immediately, the
-assembler will delay evaluation until all input is read, at which point all
-symbols are known. So using arbitrary complex constant expressions is no
-problem in most cases.
-
-
-
-<sect1>Available operators<label id="operators"><p>
-
-<table>
-<tabular ca="clc">
-<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline>
-| Built-in string functions| 0@
-||~@
-| Built-in pseudo-variables| 1@
-| Built-in pseudo-functions| 1@
-+| Unary positive| 1@
--| Unary negative| 1@
-˜<newline>
-.BITNOT| Unary bitwise not| 1@
-<<newline>
-.LOBYTE| Unary low-byte operator| 1@
-><newline>
-.HIBYTE| Unary high-byte operator| 1@
-^<newline>
-.BANKBYTE| Unary bank-byte operator| 1@
-||~@
-*| Multiplication| 2@
-/| Division| 2@
-.MOD| Modulo operator| 2@
-&<newline>
-.BITAND| Bitwise and| 2@
-^<newline>
-.BITXOR| Binary bitwise xor| 2@
-<<<newline>
-.SHL| Shift-left operator| 2@
->><newline>
-.SHR| Shift-right operator| 2@
-||~@
-+| Binary addition| 3@
--| Binary subtraction| 3@
-|<newline>
-.BITOR| Bitwise or| 3@
-||~@
-= | Compare operator (equal)| 4@
-<>| Compare operator (not equal)| 4@
-<| Compare operator (less)| 4@
->| Compare operator (greater)| 4@
-<=| Compare operator (less or equal)| 4@
->=| Compare operator (greater or equal)| 4@
-||~@
-&&<newline>
-.AND| Boolean and| 5@
-.XOR| Boolean xor| 5@
-||~@
-||<newline>
-.OR| Boolean or| 6@
-||~@
-!<newline>
-.NOT| Boolean not| 7@<hline>
-</tabular>
-<caption>Available operators, sorted by precedence
-</table>
-
-To force a specific order of evaluation, parentheses may be used, as usual.
-
-
-
-<sect>Symbols and labels<p>
-
-A symbol or label is an identifier that starts with a letter and is followed
-by letters and digits. Depending on some features enabled (see
-<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>,
-<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and
-<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>)
-other characters may be present. Use of identifiers consisting of a single
-character will not work in all cases, because some of these identifiers are
-reserved keywords (for example "A" is not a valid identifier for a label,
-because it is the keyword for the accumulator).
-
-The assembler allows you to use symbols instead of naked values to make
-the source more readable. There are a lot of different ways to define and
-use symbols and labels, giving a lot of flexibility.
-
-<sect1>Numeric constants<p>
-
-Numeric constants are defined using the equal sign or the label assignment
-operator. After doing
-
-<tscreen><verb>
- two = 2
-</verb></tscreen>
-
-may use the symbol "two" in every place where a number is expected, and it is
-evaluated to the value 2 in this context. The label assignment operator is
-almost identical, but causes the symbol to be marked as a label, so it may be
-handled differently in a debugger:
-
-<tscreen><verb>
- io := $d000
-</verb></tscreen>
-
-The right side can of course be an expression:
-
-<tscreen><verb>
- four = two * two
-</verb></tscreen>
-
-
-<label id="variables">
-<sect1>Numeric variables<p>
-
-Within macros and other control structures (<tt><ref id=".REPEAT"
-name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of
-variable. This can be achieved by the <tt>.SET</tt> operator. It creates a
-symbol that may get assigned a different value later:
-
-<tscreen><verb>
- four .set 4
- lda #four ; Loads 4 into A
- four .set 3
- lda #four ; Loads 3 into A
-</verb></tscreen>
-
-Since the value of the symbol can change later, it must be possible to
-evaluate it when used (no delayed evaluation as with normal symbols). So the
-expression used as the value must be constant.
-
-Following is an example for a macro that generates a different label each time
-it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function
-and a numeric variable named <tt>lcount</tt>.
-
-<tscreen><verb>
- .lcount .set 0 ; Initialize the counter
-
- .macro genlab
- .ident (.sprintf ("L%04X", lcount)):
- lcount .set lcount + 1
- .endmacro
-</verb></tscreen>
-
-
-<sect1>Standard labels<p>
-
-A label is defined by writing the name of the label at the start of the line
-(before any instruction mnemonic, macro or pseudo directive), followed by a
-colon. This will declare a symbol with the given name and the value of the
-current program counter.
-
-
-<sect1>Local labels and symbols<p>
-
-Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to
-create regions of code where the names of labels and symbols are local to this
-region. They are not known outside of this region and cannot be accessed from
-there. Such regions may be nested like PROCEDUREs in Pascal.
-
-See the description of the <tt><ref id=".PROC" name=".PROC"></tt>
-directive for more information.
-
-
-<sect1>Cheap local labels<p>
-
-Cheap local labels are defined like standard labels, but the name of the
-label must begin with a special symbol (usually '@', but this can be
-changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt>
-directive).
-
-Cheap local labels are visible only between two non cheap labels. As soon as a
-standard symbol is encountered (this may also be a local symbol if inside a
-region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the
-cheap local symbol goes out of scope.
-
-You may use cheap local labels as an easy way to reuse common label
-names like "Loop". Here is an example:
-
-<tscreen><verb>
- Clear: lda #$00 ; Global label
- ldy #$20
- @Loop: sta Mem,y ; Local label
- dey
- bne @Loop ; Ok
- rts
- Sub: ... ; New global label
- bne @Loop ; ERROR: Unknown identifier!
-</verb></tscreen>
-
-<sect1>Unnamed labels<p>
-
-If you really want to write messy code, there are also unnamed labels. These
-labels do not have a name (you guessed that already, didn't you?). A colon is
-used to mark the absence of the name.
-
-Unnamed labels may be accessed by using the colon plus several minus or plus
-characters as a label designator. Using the '-' characters will create a back
-reference (use the n'th label backwards), using '+' will create a forward
-reference (use the n'th label in forward direction). An example will help to
-understand this:
-
-<tscreen><verb>
- : lda (ptr1),y ; #1
- cmp (ptr2),y
- bne :+ ; -> #2
- tax
- beq :+++ ; -> #4
- iny
- bne :- ; -> #1
- inc ptr1+1
- inc ptr2+1
- bne :- ; -> #1
-
- : bcs :+ ; #2 -> #3
- ldx #$FF
- rts
-
- : ldx #$01 ; #3
- : rts ; #4
-</verb></tscreen>
-
-As you can see from the example, unnamed labels will make even short
-sections of code hard to understand, because you have to count labels
-to find branch targets (this is the reason why I for my part do
-prefer the "cheap" local labels). Nevertheless, unnamed labels are
-convenient in some situations, so it's your decision.
-
-<bf/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not
-unnamed ones, so scopes don't have an effect on unnamed labels.
-
-
-
-<sect1>Using macros to define labels and constants<p>
-
-While there are drawbacks with this approach, it may be handy in a few rare
-situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible
-to define symbols or constants that may be used elsewhere. One of the
-advantages is that you can use it to define string constants (this is not
-possible with the other symbol types).
-
-Please note: <tt/.DEFINE/ style macros do token replacements on a low level,
-so the names do not adhere to scoping, diagnostics may be misleading, there
-are no symbols to look up in the map file, and there is no debug info.
-Especially the first problem in the list can lead to very nasty programming
-errors. Because of these problems, the general advice is, <bf/NOT/ do use
-<tt/.DEFINE/ if you don't have to.
-
-Example:
-
-<tscreen><verb>
- .DEFINE two 2
- .DEFINE version "SOS V2.3"
-
- four = two * two ; Ok
- .byte version ; Ok
-
- .PROC ; Start local scope
- two = 3 ; Will give "2 = 3" - invalid!
- .ENDPROC
-</verb></tscreen>
-
-
-<sect1>Symbols and <tt>.DEBUGINFO</tt><p>
-
-If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref
-id="option-g" name="-g"> is given on the command line), global, local and
-cheap local labels are written to the object file and will be available in the
-symbol file via the linker. Unnamed labels are not written to the object file,
-because they don't have a name which would allow to access them.
-
-
-
-<sect>Scopes<label id="scopes"><p>
-
-ca65 implements several sorts of scopes for symbols.
-
-<sect1>Global scope<p>
-
-All (non cheap local) symbols that are declared outside of any nested scopes
-are in global scope.
-
-
-<sect1>Cheap locals<p>
-
-A special scope is the scope for cheap local symbols. It lasts from one non
-local symbol to the next one, without any provisions made by the programmer.
-All other scopes differ in usage but use the same concept internally.
-
-
-<sect1>Generic nested scopes<p>
-
-A nested scoped for generic use is started with <tt/<ref id=".SCOPE"
-name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/.
-The scope can have a name, in which case it is accessible from the outside by
-using <ref id="scopesyntax" name="explicit scopes">. If the scope does not
-have a name, all symbols created within the scope are local to the scope, and
-aren't accessible from the outside.
-
-A nested scope can access symbols from the local or from enclosing scopes by
-name without using explicit scope names. In some cases there may be
-ambiguities, for example if there is a reference to a local symbol that is not
-yet defined, but a symbol with the same name exists in outer scopes:
-
-<tscreen><verb>
- .scope outer
- foo = 2
- .scope inner
- lda #foo
- foo = 3
- .endscope
- .endscope
-</verb></tscreen>
-
-In the example above, the <tt/lda/ instruction will load the value 3 into the
-accumulator, because <tt/foo/ is redefined in the scope. However:
-
-<tscreen><verb>
- .scope outer
- foo = $1234
- .scope inner
- lda foo,x
- foo = $12
- .endscope
- .endscope
-</verb></tscreen>
-
-Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the
-assembler that <tt/foo/ is a zeropage symbol when translating the instruction,
-absolute mode is used instead. In fact, the assembler will not use absolute
-mode by default, but it will search through the enclosing scopes for a symbol
-with the given name. If one is found, the address size of this symbol is used.
-This may lead to errors:
-
-<tscreen><verb>
- .scope outer
- foo = $12
- .scope inner
- lda foo,x
- foo = $1234
- .endscope
- .endscope
-</verb></tscreen>
-
-In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/
-instruction, it will search for an already defined symbol <tt/foo/. It will
-find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a
-zeropage symbol. So the assembler will use zeropage addressing mode. If
-<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change
-the address in the <tt/lda/ instruction already translated, but since the new
-value needs absolute addressing mode, this fails, and an error message "Range
-error" is output.
-
-Of course the most simple solution for the problem is to move the definition
-of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be
-rare cases when this cannot be done. In these cases, you can use one of the
-address size override operators:
-
-<tscreen><verb>
- .scope outer
- foo = $12
- .scope inner
- lda a:foo,x
- foo = $1234
- .endscope
- .endscope
-</verb></tscreen>
-
-This will cause the <tt/lda/ instruction to be translated using absolute
-addressing mode, which means changing the symbol reference later does not
-cause any errors.
-
-
-<sect1>Nested procedures<p>
-
-A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It
-differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a
-name, and a it will introduce a symbol with this name in the enclosing scope.
-So
-
-<tscreen><verb>
- .proc foo
- ...
- .endproc
-</verb></tscreen>
-
-is actually the same as
-
-<tscreen><verb>
- foo:
- .scope foo
- ...
- .endscope
-</verb></tscreen>
-
-This is the reason why a procedure must have a name. If you want a scope
-without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/.
-
-<bf/Note:/ As you can see from the example above, scopes and symbols live in
-different namespaces. There can be a symbol named <tt/foo/ and a scope named
-<tt/foo/ without any conflicts (but see the section titled <ref
-id="scopesearch" name=""Scope search order"">).
-
-
-<sect1>Structs, unions and enums<p>
-
-Structs, unions and enums are explained in a <ref id="structs" name="separate
-section">, I do only cover them here, because if they are declared with a
-name, they open a nested scope, similar to <tt/<ref id=".SCOPE"
-name=".SCOPE">/. However, when no name is specified, the behaviour is
-different: In this case, no new scope will be opened, symbols declared within
-a struct, union, or enum declaration will then be added to the enclosing scope
-instead.
-
-
-<sect1>Explicit scope specification<label id="scopesyntax"><p>
-
-Accessing symbols from other scopes is possible by using an explicit scope
-specification, provided that the scope where the symbol lives in has a name.
-The namespace token (<tt/::/) is used to access other scopes:
-
-<tscreen><verb>
- .scope foo
- bar: .word 0
- .endscope
-
- ...
- lda foo::bar ; Access foo in scope bar
-</verb></tscreen>
-
-The only way to deny access to a scope from the outside is to declare a scope
-without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command).
-
-A special syntax is used to specify the global scope: If a symbol or scope is
-preceded by the namespace token, the global scope is searched:
-
-<tscreen><verb>
- bar = 3
-
- .scope foo
- bar = 2
- lda #::bar ; Access the global bar (which is 3)
- .endscope
-</verb></tscreen>
-
-
-<sect1>Scope search order<label id="scopesearch"><p>
-
-The assembler searches for a scope in a similar way as for a symbol. First, it
-looks in the current scope, and then it walks up the enclosing scopes until
-the scope is found.
-
-However, one important thing to note when using explicit scope syntax is, that
-a symbol may be accessed before it is defined, but a scope may <bf/not/ be
-used without a preceding definition. This means that in the following
-example:
-
-<tscreen><verb>
- .scope foo
- bar = 3
- .endscope
-
- .scope outer
- lda #foo::bar ; Will load 3, not 2!
- .scope foo
- bar = 2
- .endscope
- .endscope
-</verb></tscreen>
-
-the reference to the scope <tt/foo/ will use the global scope, and not the
-local one, because the local one is not visible at the point where it is
-referenced.
-
-Things get more complex if a complete chain of scopes is specified:
-
-<tscreen><verb>
- .scope foo
- .scope outer
- .scope inner
- bar = 1
- .endscope
- .endscope
- .scope another
- .scope nested
- lda #outer::inner::bar ; 1
- .endscope
- .endscope
- .endscope
-
- .scope outer
- .scope inner
- bar = 2
- .endscope
- .endscope
-</verb></tscreen>
-
-When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the
-assembler will first search in the local scope for a scope named <tt/outer/.
-Since none is found, the enclosing scope (<tt/another/) is checked. There is
-still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally
-scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in
-this scope, the assembler looks for a symbol named <tt/bar/.
-
-Please note that once the anchor scope is found, all following scopes
-(<tt/inner/ in this case) are expected to be found exactly in this scope. The
-assembler will search the scope tree only for the first scope (if it is not
-anchored in the root scope). Starting from there on, there is no flexibility,
-so if the scope named <tt/outer/ found by the assembler does not contain a
-scope named <tt/inner/, this would be an error, even if such a pair does exist
-(one level up in global scope).
-
-Ambiguities that may be introduced by this search algorithm may be removed by
-anchoring the scope specification in the global scope. In the example above,
-if you want to access the "other" symbol <tt/bar/, you would have to write:
-
-<tscreen><verb>
- .scope foo
- .scope outer
- .scope inner
- bar = 1
- .endscope
- .endscope
- .scope another
- .scope nested
- lda #::outer::inner::bar ; 2
- .endscope
- .endscope
- .endscope
-
- .scope outer
- .scope inner
- bar = 2
- .endscope
- .endscope
-</verb></tscreen>
-
-
-<sect>Address sizes and memory models<label id="address-sizes"><p>
-
-<sect1>Address sizes<p>
-
-ca65 assigns each segment and each symbol an address size. This is true, even
-if the symbol is not used as an address. You may also think of a value range
-of the symbol instead of an address size.
-
-Possible address sizes are:
-
-<itemize>
-<item>Zeropage or direct (8 bits)
-<item>Absolute (16 bits)
-<item>Far (24 bits)
-<item>Long (32 bits)
-</itemize>
-
-Since the assembler uses default address sizes for the segments and symbols,
-it is usually not necessary to override the default behaviour. In cases, where
-it is necessary, the following keywords may be used to specify address sizes:
-
-<itemize>
-<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits).
-<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits).
-<item>FAR for far addressing (24 bits).
-<item>LONG or DWORD for long addressing (32 bits).
-</itemize>
-
-
-<sect1>Address sizes of segments<p>
-
-The assembler assigns an address size to each segment. Since the
-representation of a label within this segment is "segment start + offset",
-labels will inherit the address size of the segment they are declared in.
-
-The address size of a segment may be changed, by using an optional address
-size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for
-an explanation on how this is done.
-
-
-<sect1>Address sizes of symbols<p>
-
-
-
-
-<sect1>Memory models<p>
-
-The default address size of a segment depends on the memory model used. Since
-labels inherit the address size from the segment they are declared in,
-changing the memory model is an easy way to change the address size of many
-symbols at once.
-
-
-
-
-<sect>Pseudo variables<label id="pseudo-variables"><p>
-
-Pseudo variables are readable in all cases, and in some special cases also
-writable.
-
-<sect1><tt>*</tt><p>
-
- Reading this pseudo variable will return the program counter at the start
- of the current input line.
-
- Assignment to this variable is possible when <tt/<ref id=".FEATURE"
- name=".FEATURE pc_assignment">/ is used. Note: You should not use
- assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead.
-
-
-<sect1><tt>.CPU</tt><label id=".CPU"><p>
-
- Reading this pseudo variable will give a constant integer value that
- tells which CPU is currently enabled. It can also tell which instruction
- set the CPU is able to translate. The value read from the pseudo variable
- should be further examined by using one of the constants defined by the
- "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/).
-
- It may be used to replace the .IFPxx pseudo instructions or to construct
- even more complex expressions.
-
- Example:
-
- <tscreen><verb>
- .macpack cpu
- .if (.cpu .bitand CPU_ISET_65816)
- phx
- phy
- .else
- txa
- pha
- tya
- pha
- .endif
- </verb></tscreen>
-
-
-<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p>
-
- This builtin pseudo variable is only available in macros. It is replaced by
- the actual number of parameters that were given in the macro invocation.
-
- Example:
-
- <tscreen><verb>
- .macro foo arg1, arg2, arg3
- .if .paramcount <> 3
- .error "Too few parameters for macro foo"
- .endif
- ...
- .endmacro
- </verb></tscreen>
-
- See section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.TIME</tt><label id=".TIME"><p>
-
- Reading this pseudo variable will give a constant integer value that
- represents the current time in POSIX standard (as seconds since the
- Epoch).
-
- It may be used to encode the time of translation somewhere in the created
- code.
-
- Example:
-
- <tscreen><verb>
- .dword .time ; Place time here
- </verb></tscreen>
-
-
-<sect1><tt>.VERSION</tt><label id=".VERSION"><p>
-
- Reading this pseudo variable will give the assembler version according to
- the following formula:
-
- VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH
-
- It may be used to encode the assembler version or check the assembler for
- special features not available with older versions.
-
- Example:
-
- Version 2.11.1 of the assembler will return $2B1 as numerical constant when
- reading the pseudo variable <tt/.VERSION/.
-
-
-
-<sect>Pseudo functions<label id="pseudo-functions"><p>
-
-Pseudo functions expect their arguments in parenthesis, and they have a result,
-either a string or an expression.
-
-
-<sect1><tt>.BANK</tt><label id=".BANK"><p>
-
- The <tt/.BANK/ function is used to support systems with banked memory. The
- argument is an expression with exactly one segment reference - usually a
- label. The function result is the value of the <tt/bank/ attribute assigned
- to the run memory area of the segment. Please see the linker documentation
- for more information about memory areas and their attributes.
-
- The value of <tt/.BANK/ can be used to switch memory so that a memory bank
- containing specific data is available.
-
- The <tt/bank/ attribute is a 32 bit integer and so is the result of the
- <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE"
- name=".LOBYTE"></tt> or similar functions to address just part of it.
-
- Please note that <tt/.BANK/ will always get evaluated in the link stage, so
- an expression containing <tt/.BANK/ can never be used where a constant known
- result is expected (for example with <tt/.RES/).
-
- Example:
-
- <tscreen><verb>
- .segment "BANK1"
- .proc banked_func_1
- ...
- .endproc
-
- .segment "BANK2"
- .proc banked_func_2
- ...
- .endproc
-
- .proc bank_table
- .addr banked_func_1
- .byte <.BANK (banked_func_1)
-
- .addr banked_func_2
- .byte <.BANK (banked_func_2)
- .endproc
- </verb></tscreen>
-
-
-
-<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p>
-
- The function returns the bank byte (that is, bits 16-23) of its argument.
- It works identical to the '^' operator.
-
- See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>,
- <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>
-
-
-<sect1><tt>.BLANK</tt><label id=".BLANK"><p>
-
- Builtin function. The function evaluates its argument in braces and yields
- "false" if the argument is non blank (there is an argument), and "true" if
- there is no argument. The token list that makes up the function argument
- may optionally be enclosed in curly braces. This allows the inclusion of
- tokens that would otherwise terminate the list (the closing right
- parenthesis). The curly braces are not considered part of the list, a list
- just consisting of curly braces is considered to be empty.
-
- As an example, the <tt/.IFBLANK/ statement may be replaced by
-
- <tscreen><verb>
- .if .blank({arg})
- </verb></tscreen>
-
-
-
-<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p>
-
- Builtin string function. The function allows to concatenate a list of string
- constants separated by commas. The result is a string constant that is the
- concatenation of all arguments. This function is most useful in macros and
- when used together with the <tt/.STRING/ builtin function. The function may
- be used in any case where a string constant is expected.
-
- Example:
-
- <tscreen><verb>
- .include .concat ("myheader", ".", "inc")
- </verb></tscreen>
-
- This is the same as the command
-
- <tscreen><verb>
- .include "myheader.inc"
- </verb></tscreen>
-
-
-<sect1><tt>.CONST</tt><label id=".CONST"><p>
-
- Builtin function. The function evaluates its argument in braces and
- yields "true" if the argument is a constant expression (that is, an
- expression that yields a constant value at assembly time) and "false"
- otherwise. As an example, the .IFCONST statement may be replaced by
-
- <tscreen><verb>
- .if .const(a + 3)
- </verb></tscreen>
-
-
-<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p>
-
- The function returns the high byte (that is, bits 8-15) of its argument.
- It works identical to the '>' operator.
-
- See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>,
- <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt>
-
-
-<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p>
-
- The function returns the high word (that is, bits 16-31) of its argument.
-
- See: <tt><ref id=".LOWORD" name=".LOWORD"></tt>
-
-
-<sect1><tt>.IDENT</tt><label id=".IDENT"><p>
-
- The function expects a string as its argument, and converts this argument
- into an identifier. If the string starts with the current <tt/<ref
- id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local
- identifier, otherwise it will be converted into a normal identifier.
-
- Example:
-
- <tscreen><verb>
- .macro makelabel arg1, arg2
- .ident (.concat (arg1, arg2)):
- .endmacro
-
- makelabel "foo", "bar"
-
- .word foobar ; Valid label
- </verb></tscreen>
-
-
-<sect1><tt>.LEFT</tt><label id=".LEFT"><p>
-
- Builtin function. Extracts the left part of a given token list.
-
- Syntax:
-
- <tscreen><verb>
- .LEFT (<int expr>, <token list>)
- </verb></tscreen>
-
- The first integer expression gives the number of tokens to extract from
- the token list. The second argument is the token list itself. The token
- list may optionally be enclosed into curly braces. This allows the
- inclusion of tokens that would otherwise terminate the list (the closing
- right paren in the given case).
-
- Example:
-
- To check in a macro if the given argument has a '#' as first token
- (immediate addressing mode), use something like this:
-
- <tscreen><verb>
- .macro ldax arg
- ...
- .if (.match (.left (1, {arg}), #))
-
- ; ldax called with immediate operand
- ...
-
- .endif
- ...
- .endmacro
- </verb></tscreen>
-
- See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT"
- name=".RIGHT"></tt> builtin functions.
-
-
-<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p>
-
- The function returns the low byte (that is, bits 0-7) of its argument.
- It works identical to the '<' operator.
-
- See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>,
- <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt>
-
-
-<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p>
-
- The function returns the low word (that is, bits 0-15) of its argument.
-
- See: <tt><ref id=".HIWORD" name=".HIWORD"></tt>
-
-
-<sect1><tt>.MATCH</tt><label id=".MATCH"><p>
-
- Builtin function. Matches two token lists against each other. This is
- most useful within macros, since macros are not stored as strings, but
- as lists of tokens.
-
- The syntax is
-
- <tscreen><verb>
- .MATCH(<token list #1>, <token list #2>)
- </verb></tscreen>
-
- Both token list may contain arbitrary tokens with the exception of the
- terminator token (comma resp. right parenthesis) and
-
- <itemize>
- <item>end-of-line
- <item>end-of-file
- </itemize>
-
- The token lists may optionally be enclosed into curly braces. This allows
- the inclusion of tokens that would otherwise terminate the list (the closing
- right paren in the given case). Often a macro parameter is used for any of
- the token lists.
-
- Please note that the function does only compare tokens, not token
- attributes. So any number is equal to any other number, regardless of the
- actual value. The same is true for strings. If you need to compare tokens
- <em/and/ token attributes, use the <tt><ref id=".XMATCH"
- name=".XMATCH"></tt> function.
-
- Example:
-
- Assume the macro <tt/ASR/, that will shift right the accumulator by one,
- while honoring the sign bit. The builtin processor instructions will allow
- an optional "A" for accu addressing for instructions like <tt/ROL/ and
- <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function
- to check for this and print and error for invalid calls.
-
- <tscreen><verb>
- .macro asr arg
-
- .if (.not .blank(arg)) .and (.not .match ({arg}, a))
- .error "Syntax error"
- .endif
-
- cmp #$80 ; Bit 7 into carry
- lsr a ; Shift carry into bit 7
-
- .endmacro
- </verb></tscreen>
-
- The macro will only accept no arguments, or one argument that must be the
- reserved keyword "A".
-
- See: <tt><ref id=".XMATCH" name=".XMATCH"></tt>
-
-
-<sect1><tt>.MAX</tt><label id=".MAX"><p>
-
- Builtin function. The result is the larger of two values.
-
- The syntax is
-
- <tscreen><verb>
- .MAX (<value #1>, <value #2>)
- </verb></tscreen>
-
- Example:
-
- <tscreen><verb>
- ; Reserve space for the larger of two data blocks
- savearea: .max (.sizeof (foo), .sizeof (bar))
- </verb></tscreen>
-
- See: <tt><ref id=".MIN" name=".MIN"></tt>
-
-
-<sect1><tt>.MID</tt><label id=".MID"><p>
-
- Builtin function. Takes a starting index, a count and a token list as
- arguments. Will return part of the token list.
-
- Syntax:
-
- <tscreen><verb>
- .MID (<int expr>, <int expr>, <token list>)
- </verb></tscreen>
-
- The first integer expression gives the starting token in the list (the first
- token has index 0). The second integer expression gives the number of tokens
- to extract from the token list. The third argument is the token list itself.
- The token list may optionally be enclosed into curly braces. This allows the
- inclusion of tokens that would otherwise terminate the list (the closing
- right paren in the given case).
-
- Example:
-
- To check in a macro if the given argument has a '<tt/#/' as first token
- (immediate addressing mode), use something like this:
-
- <tscreen><verb>
- .macro ldax arg
- ...
- .if (.match (.mid (0, 1, {arg}), #))
-
- ; ldax called with immediate operand
- ...
-
- .endif
- ...
- .endmacro
- </verb></tscreen>
-
- See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT"
- name=".RIGHT"></tt> builtin functions.
-
-
-<sect1><tt>.MIN</tt><label id=".MIN"><p>
-
- Builtin function. The result is the smaller of two values.
-
- The syntax is
-
- <tscreen><verb>
- .MIN (<value #1>, <value #2>)
- </verb></tscreen>
-
- Example:
-
- <tscreen><verb>
- ; Reserve space for some data, but 256 bytes minimum
- savearea: .min (.sizeof (foo), 256)
- </verb></tscreen>
-
- See: <tt><ref id=".MAX" name=".MAX"></tt>
-
-
-<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p>
-
- Builtin function. The function expects an identifier as argument in braces.
- The argument is evaluated, and the function yields "true" if the identifier
- is a symbol that has already been referenced somewhere in the source file up
- to the current position. Otherwise the function yields false. As an example,
- the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by
-
- <tscreen><verb>
- .if .referenced(a)
- </verb></tscreen>
-
- See: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
-
-
-<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p>
-
- Builtin function. Extracts the right part of a given token list.
-
- Syntax:
-
- <tscreen><verb>
- .RIGHT (<int expr>, <token list>)
- </verb></tscreen>
-
- The first integer expression gives the number of tokens to extract from the
- token list. The second argument is the token list itself. The token list
- may optionally be enclosed into curly braces. This allows the inclusion of
- tokens that would otherwise terminate the list (the closing right paren in
- the given case).
-
- See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID"
- name=".MID"></tt> builtin functions.
-
-
-<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p>
-
- <tt/.SIZEOF/ is a pseudo function that returns the size of its argument. The
- argument can be a struct/union, a struct member, a procedure, or a label. In
- case of a procedure or label, its size is defined by the amount of data
- placed in the segment where the label is relative to. If a line of code
- switches segments (for example in a macro) data placed in other segments
- does not count for the size.
-
- Please note that a symbol or scope must exist, before it is used together with
- <tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes).
- A scope has preference over a symbol with the same name, so if the last part
- of a name represents both, a scope and a symbol, the scope is chosen over the
- symbol.
-
- After the following code:
-
- <tscreen><verb>
- .struct Point ; Struct size = 4
- xcoord .word
- ycoord .word
- .endstruct
-
- P: .tag Point ; Declare a point
- @P: .tag Point ; Declare another point
-
- .code
- .proc Code
- nop
- .proc Inner
- nop
- .endproc
- nop
- .endproc
-
- .proc Data
- .data ; Segment switch!!!
- .res 4
- .endproc
- </verb></tscreen>
-
- <descrip>
- <tag><tt/.sizeof(Point)/</tag>
- will have the value 4, because this is the size of struct <tt/Point/.
-
- <tag><tt/.sizeof(Point::xcoord)/</tag>
- will have the value 2, because this is the size of the member <tt/xcoord/
- in struct <tt/Point/.
-
- <tag><tt/.sizeof(P)/</tag>
- will have the value 4, this is the size of the data declared on the same
- source line as the label <tt/P/, which is in the same segment that <tt/P/
- is relative to.
-
- <tag><tt/.sizeof(@P)/</tag>
- will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/
- does also work for cheap local symbols.
-
- <tag><tt/.sizeof(Code)/</tag>
- will have the value 3, since this is amount of data emitted into the code
- segment, the segment that was active when <tt/Code/ was entered. Note that
- this value includes the amount of data emitted in child scopes (in this
- case <tt/Code::Inner/).
-
- <tag><tt/.sizeof(Code::Inner)/</tag>
- will have the value 1 as expected.
-
- <tag><tt/.sizeof(Data)/</tag>
- will have the value 0. Data is emitted within the scope <tt/Data/, but since
- the segment is switched after entry, this data is emitted into another
- segment.
- </descrip>
-
-
-<sect1><tt>.STRAT</tt><label id=".STRAT"><p>
-
- Builtin function. The function accepts a string and an index as
- arguments and returns the value of the character at the given position
- as an integer value. The index is zero based.
-
- Example:
-
- <tscreen><verb>
- .macro M Arg
- ; Check if the argument string starts with '#'
- .if (.strat (Arg, 0) = '#')
- ...
- .endif
- .endmacro
- </verb></tscreen>
-
-
-<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p>
-
- Builtin function. It expects a format string as first argument. The number
- and type of the following arguments depend on the format string. The format
- string is similar to the one of the C <tt/printf/ function. Missing things
- are: Length modifiers, variable width.
-
- The result of the function is a string.
-
- Example:
-
- <tscreen><verb>
- num = 3
-
- ; Generate an identifier:
- .ident (.sprintf ("%s%03d", "label", num)):
- </verb></tscreen>
-
-
-<sect1><tt>.STRING</tt><label id=".STRING"><p>
-
- Builtin function. The function accepts an argument in braces and converts
- this argument into a string constant. The argument may be an identifier, or
- a constant numeric value.
-
- Since you can use a string in the first place, the use of the function may
- not be obvious. However, it is useful in macros, or more complex setups.
-
- Example:
-
- <tscreen><verb>
- ; Emulate other assemblers:
- .macro section name
- .segment .string(name)
- .endmacro
- </verb></tscreen>
-
-
-<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p>
-
- Builtin function. The function accepts a string argument in braces and
- evaluates to the length of the string.
-
- Example:
-
- The following macro encodes a string as a pascal style string with
- a leading length byte.
-
- <tscreen><verb>
- .macro PString Arg
- .byte .strlen(Arg), Arg
- .endmacro
- </verb></tscreen>
-
-
-<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p>
-
- Builtin function. The function accepts a token list in braces. The function
- result is the number of tokens given as argument. The token list may
- optionally be enclosed into curly braces which are not considered part of
- the list and not counted. Enclosement in curly braces allows the inclusion
- of tokens that would otherwise terminate the list (the closing right paren
- in the given case).
-
- Example:
-
- The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as
- with the normal 6502 instructions). To translate it into two separate 8 bit
- load instructions, the '#' token has to get stripped from the argument:
-
- <tscreen><verb>
- .macro ldax arg
- .if (.match (.mid (0, 1, {arg}), #))
- ; ldax called with immediate operand
- lda #<(.right (.tcount ({arg})-1, {arg}))
- ldx #>(.right (.tcount ({arg})-1, {arg}))
- .else
- ...
- .endif
- .endmacro
- </verb></tscreen>
-
-
-<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p>
-
- Builtin function. Matches two token lists against each other. This is
- most useful within macros, since macros are not stored as strings, but
- as lists of tokens.
-
- The syntax is
-
- <tscreen><verb>
- .XMATCH(<token list #1>, <token list #2>)
- </verb></tscreen>
-
- Both token list may contain arbitrary tokens with the exception of the
- terminator token (comma resp. right parenthesis) and
-
- <itemize>
- <item>end-of-line
- <item>end-of-file
- </itemize>
-
- The token lists may optionally be enclosed into curly braces. This allows
- the inclusion of tokens that would otherwise terminate the list (the closing
- right paren in the given case). Often a macro parameter is used for any of
- the token lists.
-
- The function compares tokens <em/and/ token values. If you need a function
- that just compares the type of tokens, have a look at the <tt><ref
- id=".MATCH" name=".MATCH"></tt> function.
-
- See: <tt><ref id=".MATCH" name=".MATCH"></tt>
-
-
-
-<sect>Control commands<label id="control-commands"><p>
-
-Here's a list of all control commands and a description, what they do:
-
-
-<sect1><tt>.A16</tt><label id=".A16"><p>
-
- Valid only in 65816 mode. Switch the accumulator to 16 bit.
-
- Note: This command will not emit any code, it will tell the assembler to
- create 16 bit operands for immediate accumulator addressing mode.
-
- See also: <tt><ref id=".SMART" name=".SMART"></tt>
-
-
-<sect1><tt>.A8</tt><label id=".A8"><p>
-
- Valid only in 65816 mode. Switch the accumulator to 8 bit.
-
- Note: This command will not emit any code, it will tell the assembler to
- create 8 bit operands for immediate accu addressing mode.
-
- See also: <tt><ref id=".SMART" name=".SMART"></tt>
-
-
-<sect1><tt>.ADDR</tt><label id=".ADDR"><p>
-
- Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and
- may be used for better readability if the data words are address values. In
- 65816 mode, the address is forced to be 16 bit wide to fit into the current
- segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command
- must be followed by a sequence of (not necessarily constant) expressions.
-
- Example:
-
- <tscreen><verb>
- .addr $0D00, $AF13, _Clear
- </verb></tscreen>
-
- See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD"
- name=".WORD"></tt>
-
-
-<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p>
-
- Align data to a given boundary. The command expects a constant integer
- argument in the range 1 ... 65536, plus an optional second argument
- in byte range. If there is a second argument, it is used as fill value,
- otherwise the value defined in the linker configuration file is used
- (the default for this value is zero).
-
- <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of
- the final address of the segment. <tt/.ALIGN/ cannot insert a variable
- number of bytes, since that would break address calculations within the
- module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple
- of the alignment, because that allows the number of fill bytes to be
- calculated in advance by the assembler. You are therefore required to
- specify a matching alignment for the segment in the linker config. The
- linker will output a warning if the alignment of the segment is less than
- what is necessary to have a correct alignment in the object file.
-
- Example:
-
- <tscreen><verb>
- .align 256
- </verb></tscreen>
-
- Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/
- commands with different arguments. To allow the assembler to calculate the
- number of fill bytes in advance, the alignment of the segment must be a
- multiple of each of the alignment factors. This may result in unexpectedly
- large alignments for the segment within the module.
-
- Example:
-
- <tscreen><verb>
- .align 15
- .byte 15
- .align 18
- .byte 18
- </verb></tscreen>
-
- For the assembler to be able to align correctly, the segment must be aligned
- to the least common multiple of 15 and 18 which is 90. The assembler will
- calculate this automatically and will mark the segment with this value.
-
- Unfortunately, the combined alignment may get rather large without the user
- knowing about it, wasting space in the final executable. If we add another
- alignment to the example above
-
- <tscreen><verb>
- .align 15
- .byte 15
- .align 18
- .byte 18
- .align 251
- .byte 0
- </verb></tscreen>
-
- the assembler will force a segment alignment to the least common multiple of
- 15, 18 and 251 - which is 22590. To protect the user against errors, the
- assembler will issue a warning when the combined alignment exceeds 256. The
- command line option <tt><ref id="option--large-alignment"
- name="--large-alignment"></tt> will disable this warning.
-
- Please note that with alignments that are a power of two (which were the
- only alignments possible in older versions of the assembler), the problem is
- less severe, because the least common multiple of powers to the same base is
- always the larger one.
-
-
-
-<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p>
-
- Define a string with a trailing zero.
-
- Example:
-
- <tscreen><verb>
- Msg: .asciiz "Hello world"
- </verb></tscreen>
-
- This will put the string "Hello world" followed by a binary zero into
- the current segment. There may be more strings separated by commas, but
- the binary zero is only appended once (after the last one).
-
-
-<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p>
-
- Add an assertion. The command is followed by an expression, an action
- specifier, and an optional message that is output in case the assertion
- fails. If no message was given, the string "Assertion failed" is used. The
- action specifier may be one of <tt/warning/, <tt/error/, <tt/ldwarning/ or
- <tt/lderror/. In the former two cases, the assertion is evaluated by the
- assembler if possible, and in any case, it's also passed to the linker in
- the object file (if one is generated). The linker will then evaluate the
- expression when segment placement has been done.
-
- Example:
-
- <tscreen><verb>
- .assert * = $8000, error, "Code not at $8000"
- </verb></tscreen>
-
- The example assertion will check that the current location is at $8000,
- when the output file is written, and abort with an error if this is not
- the case. More complex expressions are possible. The action specifier
- <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs
- an error message. In the latter case, generation of the output file is
- suppressed in both the assembler and linker.
-
-
-<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p>
-
- Is followed by a plus or a minus character. When switched on (using a
- +), undefined symbols are automatically marked as import instead of
- giving errors. When switched off (which is the default so this does not
- make much sense), this does not happen and an error message is
- displayed. The state of the autoimport flag is evaluated when the
- complete source was translated, before outputting actual code, so it is
- <em/not/ possible to switch this feature on or off for separate sections
- of code. The last setting is used for all symbols.
-
- You should probably not use this switch because it delays error
- messages about undefined symbols until the link stage. The cc65
- compiler (which is supposed to produce correct assembler code in all
- circumstances, something which is not true for most assembler
- programmers) will insert this command to avoid importing each and every
- routine from the runtime library.
-
- Example:
-
- <tscreen><verb>
- .autoimport + ; Switch on auto import
- </verb></tscreen>
-
-<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p>
-
- Define byte sized data by extracting only the bank byte (that is, bits 16-23) from
- each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
- the operator '^' prepended to each expression in its list.
-
- Example:
-
- <tscreen><verb>
- .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
-
- TableLookupLo: .lobytes MyTable
- TableLookupHi: .hibytes MyTable
- TableLookupBank: .bankbytes MyTable
- </verb></tscreen>
-
- which is equivalent to
-
- <tscreen><verb>
- TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
- TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
- TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3
- </verb></tscreen>
-
- See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
- <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>,
- <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>
-
-
-<sect1><tt>.BSS</tt><label id=".BSS"><p>
-
- Switch to the BSS segment. The name of the BSS segment is always "BSS",
- so this is a shortcut for
-
- <tscreen><verb>
- .segment "BSS"
- </verb></tscreen>
-
- See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
-
-
-<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p>
-
- Define byte sized data. Must be followed by a sequence of (byte ranged)
- expressions or strings.
-
- Example:
-
- <tscreen><verb>
- .byte "Hello "
- .byt "world", $0D, $00
- </verb></tscreen>
-
-
-<sect1><tt>.CASE</tt><label id=".CASE"><p>
-
- Switch on or off case sensitivity on identifiers. The default is off
- (that is, identifiers are case sensitive), but may be changed by the
- -i switch on the command line.
- The command must be followed by a '+' or '-' character to switch the
- option on or off respectively.
-
- Example:
-
- <tscreen><verb>
- .case - ; Identifiers are not case sensitive
- </verb></tscreen>
-
-
-<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p>
-
- Apply a custom mapping for characters. The command is followed by two
- numbers. The first one is the index of the source character (range 1..255),
- the second one is the mapping (range 0..255). The mapping applies to all
- character and string constants when they generate output, and overrides a
- mapping table specified with the <tt><ref id="option-t" name="-t"></tt>
- command line switch.
-
- Example:
-
- <tscreen><verb>
- .charmap $41, $61 ; Map 'A' to 'a'
- </verb></tscreen>
-
-
-<sect1><tt>.CODE</tt><label id=".CODE"><p>
-
- Switch to the CODE segment. The name of the CODE segment is always
- "CODE", so this is a shortcut for
-
- <tscreen><verb>
- .segment "CODE"
- </verb></tscreen>
-
- See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
-
-
-<sect1><tt>.CONDES</tt><label id=".CONDES"><p>
-
- Export a symbol and mark it in a special way. The linker is able to build
- tables of all such symbols. This may be used to automatically create a list
- of functions needed to initialize linked library modules.
-
- Note: The linker has a feature to build a table of marked routines, but it
- is your code that must call these routines, so just declaring a symbol with
- <tt/.CONDES/ does nothing by itself.
-
- All symbols are exported as an absolute (16 bit) symbol. You don't need to
- use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this
- is implied by <tt/.CONDES/.
-
- <tt/.CONDES/ is followed by the type, which may be <tt/constructor/,
- <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as
- specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/).
- The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
- id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
- name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/
- with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/.
-
- After the type, an optional priority may be specified. Higher numeric values
- mean higher priority. If no priority is given, the default priority of 7 is
- used. Be careful when assigning priorities to your own module constructors
- so they won't interfere with the ones in the cc65 library.
-
- Example:
-
- <tscreen><verb>
- .condes ModuleInit, constructor
- .condes ModInit, 0, 16
- </verb></tscreen>
-
- See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
- id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
- name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes"
- name="Module constructors/destructors"> explaining the feature in more
- detail.
-
-
-<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p>
-
- Export a symbol and mark it as a module constructor. This may be used
- together with the linker to build a table of constructor subroutines that
- are called by the startup code.
-
- Note: The linker has a feature to build a table of marked routines, but it
- is your code that must call these routines, so just declaring a symbol as
- constructor does nothing by itself.
-
- A constructor is always exported as an absolute (16 bit) symbol. You don't
- need to use an additional <tt/.export/ statement, this is implied by
- <tt/.constructor/. It may have an optional priority that is separated by a
- comma. Higher numeric values mean a higher priority. If no priority is
- given, the default priority of 7 is used. Be careful when assigning
- priorities to your own module constructors so they won't interfere with the
- ones in the cc65 library.
-
- Example:
-
- <tscreen><verb>
- .constructor ModuleInit
- .constructor ModInit, 16
- </verb></tscreen>
-
- See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref
- id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section
- <ref id="condes" name="Module constructors/destructors"> explaining the
- feature in more detail.
-
-
-<sect1><tt>.DATA</tt><label id=".DATA"><p>
-
- Switch to the DATA segment. The name of the DATA segment is always
- "DATA", so this is a shortcut for
-
- <tscreen><verb>
- .segment "DATA"
- </verb></tscreen>
-
- See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
-
-
-<sect1><tt>.DBYT</tt><label id=".DBYT"><p>
-
- Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to
- create word sized data in native 65XX format). Must be followed by a
- sequence of (word ranged) expressions.
-
- Example:
-
- <tscreen><verb>
- .dbyt $1234, $4512
- </verb></tscreen>
-
- This will emit the bytes
-
- <tscreen><verb>
- $12 $34 $45 $12
- </verb></tscreen>
-
- into the current segment in that order.
-
-
-<sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p>
-
- Switch on or off debug info generation. The default is off (that is,
- the object file will not contain debug infos), but may be changed by the
- -g switch on the command line.
- The command must be followed by a '+' or '-' character to switch the
- option on or off respectively.
-
- Example:
-
- <tscreen><verb>
- .debuginfo + ; Generate debug info
- </verb></tscreen>
-
-
-<sect1><tt>.DEFINE</tt><label id=".DEFINE"><p>
-
- Start a define style macro definition. The command is followed by an
- identifier (the macro name) and optionally by a list of formal arguments
- in braces.
-
- Please note that <tt/.DEFINE/ shares most disadvantages with its C
- counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you
- don't have to.
-
- See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and
- section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.DELMAC, .DELMACRO</tt><label id=".DELMACRO"><p>
-
- Delete a classic macro (defined with <tt><ref id=".MACRO"
- name=".MACRO"></tt>) . The command is followed by the name of an
- existing macro. Its definition will be deleted together with the name.
- If necessary, another macro with this name may be defined later.
-
- See: <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>,
- <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>,
- <tt><ref id=".MACRO" name=".MACRO"></tt>
-
- See also section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p>
-
- Builtin function. The function expects an identifier as argument in braces.
- The argument is evaluated, and the function yields "true" if the identifier
- is a symbol that is already defined somewhere in the source file up to the
- current position. Otherwise the function yields false. As an example, the
- <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by
-
- <tscreen><verb>
- .if .defined(a)
- </verb></tscreen>
-
-
-<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p>
-
- Export a symbol and mark it as a module destructor. This may be used
- together with the linker to build a table of destructor subroutines that
- are called by the startup code.
-
- Note: The linker has a feature to build a table of marked routines, but it
- is your code that must call these routines, so just declaring a symbol as
- constructor does nothing by itself.
-
- A destructor is always exported as an absolute (16 bit) symbol. You don't
- need to use an additional <tt/.export/ statement, this is implied by
- <tt/.destructor/. It may have an optional priority that is separated by a
- comma. Higher numerical values mean a higher priority. If no priority is
- given, the default priority of 7 is used. Be careful when assigning
- priorities to your own module destructors so they won't interfere with the
- ones in the cc65 library.
-
- Example:
-
- <tscreen><verb>
- .destructor ModuleDone
- .destructor ModDone, 16
- </verb></tscreen>
-
- See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref
- id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate
- section <ref id="condes" name="Module constructors/destructors"> explaining
- the feature in more detail.
-
-
-<sect1><tt>.DWORD</tt><label id=".DWORD"><p>
-
- Define dword sized data (4 bytes) Must be followed by a sequence of
- expressions.
-
- Example:
-
- <tscreen><verb>
- .dword $12344512, $12FA489
- </verb></tscreen>
-
-
-<sect1><tt>.ELSE</tt><label id=".ELSE"><p>
-
- Conditional assembly: Reverse the current condition.
-
-
-<sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p>
-
- Conditional assembly: Reverse current condition and test a new one.
-
-
-<sect1><tt>.END</tt><label id=".END"><p>
-
- Forced end of assembly. Assembly stops at this point, even if the command
- is read from an include file.
-
-
-<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p>
-
- End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration.
-
-
-<sect1><tt>.ENDIF</tt><label id=".ENDIF"><p>
-
- Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or
- <tt><ref id=".ELSE" name=".ELSE"></tt> branch.
-
-
-<sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p>
-
- Marks the end of a macro definition.
-
- See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>,
- <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>,
- <tt><ref id=".MACRO" name=".MACRO"></tt>
-
- See also section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p>
-
- End of local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>).
-
-
-<sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p>
-
- End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block.
-
-
-<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p>
-
- End of local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/).
-
-
-<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p>
-
- Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/
- command and the separate section named <ref id="structs" name=""Structs
- and unions"">.
-
-
-<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p>
-
- Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/
- command and the separate section named <ref id="structs" name=""Structs
- and unions"">.
-
-
-<sect1><tt>.ENUM</tt><label id=".ENUM"><p>
-
- Start an enumeration. This directive is very similar to the C <tt/enum/
- keyword. If a name is given, a new scope is created for the enumeration,
- otherwise the enumeration members are placed in the enclosing scope.
-
- In the enumeration body, symbols are declared. The first symbol has a value
- of zero, and each following symbol will get the value of the preceding plus
- one. This behaviour may be overridden by an explicit assignment. Two symbols
- may have the same value.
-
- Example:
-
- <tscreen><verb>
- .enum errorcodes
- no_error
- file_error
- parse_error
- .endenum
- </verb></tscreen>
-
- Above example will create a new scope named <tt/errorcodes/ with three
- symbols in it that get the values 0, 1 and 2 respectively. Another way
- to write this would have been:
-
- <tscreen><verb>
- .scope errorcodes
- no_error = 0
- file_error = 1
- parse_error = 2
- .endscope
- </verb></tscreen>
-
- Please note that explicit scoping must be used to access the identifiers:
-
- <tscreen><verb>
- .word errorcodes::no_error
- </verb></tscreen>
-
- A more complex example:
-
- <tscreen><verb>
- .enum
- EUNKNOWN = -1
- EOK
- EFILE
- EBUSY
- EAGAIN
- EWOULDBLOCK = EAGAIN
- .endenum
- </verb></tscreen>
-
- In this example, the enumeration does not have a name, which means that the
- members will be visible in the enclosing scope and can be used in this scope
- without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1.
- The value for the following members is incremented by one, so <tt/EOK/ would
- be zero and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EGAIN/, so it has an
- override for the value using an already defined symbol.
-
-
-<sect1><tt>.ERROR</tt><label id=".ERROR"><p>
-
- Force an assembly error. The assembler will output an error message
- preceded by "User error". Assembly is continued but no object file will
- generated.
-
- This command may be used to check for initial conditions that must be
- set before assembling a source file.
-
- Example:
-
- <tscreen><verb>
- .if foo = 1
- ...
- .elseif bar = 1
- ...
- .else
- .error "Must define foo or bar!"
- .endif
- </verb></tscreen>
-
- See also: <tt><ref id=".FATAL" name=".FATAL"></tt>,
- <tt><ref id=".OUT" name=".OUT"></tt>,
- <tt><ref id=".WARNING" name=".WARNING"></tt>
-
-
-<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p>
-
- Abort a macro expansion immediately. This command is often useful in
- recursive macros.
-
- See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>,
- <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>,
- <tt><ref id=".MACRO" name=".MACRO"></tt>
-
- See also section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p>
-
- Make symbols accessible from other modules. Must be followed by a comma
- separated list of symbols to export, with each one optionally followed by an
- address specification and (also optional) an assignment. Using an additional
- assignment in the export statement allows to define and export a symbol in
- one statement. The default is to export the symbol with the address size it
- actually has. The assembler will issue a warning, if the symbol is exported
- with an address size smaller than the actual address size.
-
- Examples:
-
- <tscreen><verb>
- .export foo
- .export bar: far
- .export foobar: far = foo * bar
- .export baz := foobar, zap: far = baz - bar
- </verb></tscreen>
-
- As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the
- symbols as a label.
-
- See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt>
-
-
-<sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p>
-
- Make symbols accessible from other modules. Must be followed by a comma
- separated list of symbols to export. The exported symbols are explicitly
- marked as zero page symbols. An assignment may be included in the
- <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one
- statement.
-
- Examples:
-
- <tscreen><verb>
- .exportzp foo, bar
- .exportzp baz := $02
- </verb></tscreen>
-
- See: <tt><ref id=".EXPORT" name=".EXPORT"></tt>
-
-
-<sect1><tt>.FARADDR</tt><label id=".FARADDR"><p>
-
- Define far (24 bit) address data. The command must be followed by a
- sequence of (not necessarily constant) expressions.
-
- Example:
-
- <tscreen><verb>
- .faraddr DrawCircle, DrawRectangle, DrawHexagon
- </verb></tscreen>
-
- See: <tt><ref id=".ADDR" name=".ADDR"></tt>
-
-
-<sect1><tt>.FATAL</tt><label id=".FATAL"><p>
-
- Force an assembly error and terminate assembly. The assembler will output an
- error message preceded by "User error" and will terminate assembly
- immediately.
-
- This command may be used to check for initial conditions that must be
- set before assembling a source file.
-
- Example:
-
- <tscreen><verb>
- .if foo = 1
- ...
- .elseif bar = 1
- ...
- .else
- .fatal "Must define foo or bar!"
- .endif
- </verb></tscreen>
-
- See also: <tt><ref id=".ERROR" name=".ERROR"></tt>,
- <tt><ref id=".OUT" name=".OUT"></tt>,
- <tt><ref id=".WARNING" name=".WARNING"></tt>
-
-
-<sect1><tt>.FEATURE</tt><label id=".FEATURE"><p>
-
- This directive may be used to enable one or more compatibility features
- of the assembler. While the use of <tt/.FEATURE/ should be avoided when
- possible, it may be useful when porting sources written for other
- assemblers. There is no way to switch a feature off, once you have
- enabled it, so using
-
- <tscreen><verb>
- .FEATURE xxx
- </verb></tscreen>
-
- will enable the feature until end of assembly is reached.
-
- The following features are available:
-
- <descrip>
-
- <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag>
-
- Accept the at character (`@') as a valid character in identifiers. The
- at character is not allowed to start an identifier, even with this
- feature enabled.
-
- <tag><tt>c_comments</tt><label id="c_comments"></tag>
-
- Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right
- comment terminators. Note that C comments may not be nested. There's also a
- pitfall when using C like comments: All statements must be terminated by
- "end-of-line". Using C like comments, it is possible to hide the newline,
- which results in error messages. See the following non working example:
-
- <tscreen><verb>
- lda #$00 /* This comment hides the newline
-*/ sta $82
- </verb></tscreen>
-
- <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag>
-
- Accept the dollar sign (`$') as a valid character in identifiers. The
- dollar character is not allowed to start an identifier, even with this
- feature enabled.
-
- <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag>
-
- The dollar sign may be used as an alias for the star (`*'), which
- gives the value of the current PC in expressions.
- Note: Assignment to the pseudo variable is not allowed.
-
- <tag><tt>force_range</tt><label id="force_range"></tag>
-
- Force expressions into their valid range for immediate addressing and
- storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and
- <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one,
- since it will completely disable error checks.
-
- <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag>
-
- Allow labels without a trailing colon. These labels are only accepted,
- if they start at the beginning of a line (no leading white space).
-
- <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag>
-
- Accept the dot (`.') as the first character of an identifier. This may be
- used for example to create macro names that start with a dot emulating
- control directives of other assemblers. Note however, that none of the
- reserved keywords built into the assembler, that starts with a dot, may be
- overridden. When using this feature, you may also get into trouble if
- later versions of the assembler define new keywords starting with a dot.
-
- <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag>
-
- Accept single quotes as well as double quotes as terminators for char
- constants.
-
- <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag>
-
- Accept single quotes as well as double quotes as terminators for string
- constants.
-
- <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag>
-
- Accept single quoted character constants where the terminating quote is
- missing.
- <tscreen><verb>
- lda #'a
- </verb></tscreen>
- <bf/Note:/ This does not work in conjunction with <tt/.FEATURE
- loose_string_term/, since in this case the input would be ambiguous.
-
- <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag>
-
- This feature makes relocatable/absolute mode local to the current segment.
- Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in
- effect will only enable absolute mode for the current segment. Dito for
- <tt><ref id=".RELOC" name=".RELOC"></tt>.
-
- <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag>
-
- Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/
- is enabled). Such an assignment is handled identical to the <tt><ref
- id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just
- removing the lines with the assignments may also be an option when porting
- code written for older assemblers).
-
- <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag>
-
- Allow the use of instructions names as names for macros and symbols. This
- makes it possible to "overload" instructions by defining a macro with the
- same name. This does also make it possible to introduce hard to find errors
- in your code, so be careful!
-
- <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag>
-
- Allow underlines within numeric constants. These may be used for grouping
- the digits of numbers for easier reading.
- Example:
- <tscreen><verb>
- .feature underline_in_numbers
- .word %1100001110100101
- .word %1100_0011_1010_0101 ; Identical but easier to read
- </verb></tscreen>
-
- </descrip>
-
- It is also possible to specify features on the command line using the
- <tt><ref id="option--feature" name="--feature"></tt> command line option.
- This is useful when translating sources written for older assemblers, when
- you don't want to change the source code.
-
- As an example, to translate sources written for Andre Fachats xa65
- assembler, the features
-
- <verb>
- labels_without_colons, pc_assignment, loose_char_term
- </verb>
-
- may be helpful. They do not make ca65 completely compatible, so you may not
- be able to translate the sources without changes, even when enabling these
- features. However, I have found several sources that translate without
- problems when enabling these features on the command line.
-
-
-<sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p>
-
- Insert an option string into the object file. There are two forms of
- this command, one specifies the option by a keyword, the second
- specifies it as a number. Since usage of the second one needs knowledge
- of the internal encoding, its use is not recommended and I will only
- describe the first form here.
-
- The command is followed by one of the keywords
-
- <tscreen><verb>
- author
- comment
- compiler
- </verb></tscreen>
-
- a comma and a string. The option is written into the object file
- together with the string value. This is currently unidirectional and
- there is no way to actually use these options once they are in the
- object file.
-
- Examples:
-
- <tscreen><verb>
- .fileopt comment, "Code stolen from my brother"
- .fileopt compiler, "BASIC 2.0"
- .fopt author, "J. R. User"
- </verb></tscreen>
-
-
-<sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p>
-
- Import an absolute symbol from another module. The command is followed by a
- comma separated list of symbols to import. The command is similar to <tt>
- <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always
- written to the generated object file, even if the symbol is never referenced
- (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import
- references for unused symbols).
-
- Example:
-
- <tscreen><verb>
- .forceimport needthisone, needthistoo
- </verb></tscreen>
-
- See: <tt><ref id=".IMPORT" name=".IMPORT"></tt>
-
-
-<sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p>
-
- Declare symbols as global. Must be followed by a comma separated list of
- symbols to declare. Symbols from the list, that are defined somewhere in the
- source, are exported, all others are imported. Additional <tt><ref
- id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT"
- name=".EXPORT"></tt> commands for the same symbol are allowed.
-
- Example:
-
- <tscreen><verb>
- .global foo, bar
- </verb></tscreen>
-
-
-<sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p>
-
- Declare symbols as global. Must be followed by a comma separated list of
- symbols to declare. Symbols from the list, that are defined somewhere in the
- source, are exported, all others are imported. Additional <tt><ref
- id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP"
- name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols
- in the list are explicitly marked as zero page symbols.
-
- Example:
-
- <tscreen><verb>
- .globalzp foo, bar
- </verb></tscreen>
-
-<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p>
-
- Define byte sized data by extracting only the high byte (that is, bits 8-15) from
- each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
- the operator '>' prepended to each expression in its list.
-
- Example:
-
- <tscreen><verb>
- .lobytes $1234, $2345, $3456, $4567
- .hibytes $fedc, $edcb, $dcba, $cba9
- </verb></tscreen>
-
- which is equivalent to
-
- <tscreen><verb>
- .byte $34, $45, $56, $67
- .byte $fe, $ed, $dc, $cb
- </verb></tscreen>
-
- Example:
-
- <tscreen><verb>
- .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
-
- TableLookupLo: .lobytes MyTable
- TableLookupHi: .hibytes MyTable
- </verb></tscreen>
-
- which is equivalent to
-
- <tscreen><verb>
- TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
- TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
- </verb></tscreen>
-
- See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
- <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>,
- <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt>
-
-
-<sect1><tt>.I16</tt><label id=".I16"><p>
-
- Valid only in 65816 mode. Switch the index registers to 16 bit.
-
- Note: This command will not emit any code, it will tell the assembler to
- create 16 bit operands for immediate operands.
-
- See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART"
- name=".SMART"></tt> commands.
-
-
-<sect1><tt>.I8</tt><label id=".I8"><p>
-
- Valid only in 65816 mode. Switch the index registers to 8 bit.
-
- Note: This command will not emit any code, it will tell the assembler to
- create 8 bit operands for immediate operands.
-
- See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART"
- name=".SMART"></tt> commands.
-
-
-<sect1><tt>.IF</tt><label id=".IF"><p>
-
- Conditional assembly: Evaluate an expression and switch assembler output
- on or off depending on the expression. The expression must be a constant
- expression, that is, all operands must be defined.
-
- A expression value of zero evaluates to FALSE, any other value evaluates
- to TRUE.
-
-
-<sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p>
-
- Conditional assembly: Check if there are any remaining tokens in this line,
- and evaluate to FALSE if this is the case, and to TRUE otherwise. If the
- condition is not true, further lines are not assembled until an <tt><ref
- id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
- <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive.
-
- This command is often used to check if a macro parameter was given. Since an
- empty macro parameter will evaluate to nothing, the condition will evaluate
- to TRUE if an empty parameter was given.
-
- Example:
-
- <tscreen><verb>
- .macro arg1, arg2
- .ifblank arg2
- lda #arg1
- .else
- lda #arg2
- .endif
- .endmacro
- </verb></tscreen>
-
- See also: <tt><ref id=".BLANK" name=".BLANK"></tt>
-
-
-<sect1><tt>.IFCONST</tt><label id=".IFCONST"><p>
-
- Conditional assembly: Evaluate an expression and switch assembler output
- on or off depending on the constness of the expression.
-
- A const expression evaluates to to TRUE, a non const expression (one
- containing an imported or currently undefined symbol) evaluates to
- FALSE.
-
- See also: <tt><ref id=".CONST" name=".CONST"></tt>
-
-
-<sect1><tt>.IFDEF</tt><label id=".IFDEF"><p>
-
- Conditional assembly: Check if a symbol is defined. Must be followed by
- a symbol name. The condition is true if the the given symbol is already
- defined, and false otherwise.
-
- See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
-
-
-<sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p>
-
- Conditional assembly: Check if there are any remaining tokens in this line,
- and evaluate to TRUE if this is the case, and to FALSE otherwise. If the
- condition is not true, further lines are not assembled until an <tt><ref
- id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or
- <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive.
-
- This command is often used to check if a macro parameter was given.
- Since an empty macro parameter will evaluate to nothing, the condition
- will evaluate to FALSE if an empty parameter was given.
-
- Example:
-
- <tscreen><verb>
- .macro arg1, arg2
- lda #arg1
- .ifnblank arg2
- lda #arg2
- .endif
- .endmacro
- </verb></tscreen>
-
- See also: <tt><ref id=".BLANK" name=".BLANK"></tt>
-
-
-<sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p>
-
- Conditional assembly: Check if a symbol is defined. Must be followed by
- a symbol name. The condition is true if the the given symbol is not
- defined, and false otherwise.
-
- See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt>
-
-
-<sect1><tt>.IFNREF</tt><label id=".IFNREF"><p>
-
- Conditional assembly: Check if a symbol is referenced. Must be followed
- by a symbol name. The condition is true if if the the given symbol was
- not referenced before, and false otherwise.
-
- See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt>
-
-
-<sect1><tt>.IFP02</tt><label id=".IFP02"><p>
-
- Conditional assembly: Check if the assembler is currently in 6502 mode
- (see <tt><ref id=".P02" name=".P02"></tt> command).
-
-
-<sect1><tt>.IFP816</tt><label id=".IFP816"><p>
-
- Conditional assembly: Check if the assembler is currently in 65816 mode
- (see <tt><ref id=".P816" name=".P816"></tt> command).
-
-
-<sect1><tt>.IFPC02</tt><label id=".IFPC02"><p>
-
- Conditional assembly: Check if the assembler is currently in 65C02 mode
- (see <tt><ref id=".PC02" name=".PC02"></tt> command).
-
-
-<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p>
-
- Conditional assembly: Check if the assembler is currently in 65SC02 mode
- (see <tt><ref id=".PSC02" name=".PSC02"></tt> command).
-
-
-<sect1><tt>.IFREF</tt><label id=".IFREF"><p>
-
- Conditional assembly: Check if a symbol is referenced. Must be followed
- by a symbol name. The condition is true if if the the given symbol was
- referenced before, and false otherwise.
-
- This command may be used to build subroutine libraries in include files
- (you may use separate object modules for this purpose too).
-
- Example:
-
- <tscreen><verb>
- .ifref ToHex ; If someone used this subroutine
- ToHex: tay ; Define subroutine
- lda HexTab,y
- rts
- .endif
- </verb></tscreen>
-
- See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt>
-
-
-<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p>
-
- Import a symbol from another module. The command is followed by a comma
- separated list of symbols to import, with each one optionally followed by
- an address specification.
-
- Example:
-
- <tscreen><verb>
- .import foo
- .import bar: zeropage
- </verb></tscreen>
-
- See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt>
-
-
-<sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p>
-
- Import a symbol from another module. The command is followed by a comma
- separated list of symbols to import. The symbols are explicitly imported
- as zero page symbols (that is, symbols with values in byte range).
-
- Example:
-
- <tscreen><verb>
- .importzp foo, bar
- </verb></tscreen>
-
- See: <tt><ref id=".IMPORT" name=".IMPORT"></tt>
-
-
-<sect1><tt>.INCBIN</tt><label id=".INCBIN"><p>
-
- Include a file as binary data. The command expects a string argument
- that is the name of a file to include literally in the current segment.
- In addition to that, a start offset and a size value may be specified,
- separated by commas. If no size is specified, all of the file from the
- start offset to end-of-file is used. If no start position is specified
- either, zero is assumed (which means that the whole file is inserted).
-
- Example:
-
- <tscreen><verb>
- ; Include whole file
- .incbin "sprites.dat"
-
- ; Include file starting at offset 256
- .incbin "music.dat", $100
-
- ; Read 100 bytes starting at offset 200
- .incbin "graphics.dat", 200, 100
- </verb></tscreen>
-
-
-<sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p>
-
- Include another file. Include files may be nested up to a depth of 16.
-
- Example:
-
- <tscreen><verb>
- .include "subs.inc"
- </verb></tscreen>
-
-
-<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p>
-
- Export a symbol and mark it as an interruptor. This may be used together
- with the linker to build a table of interruptor subroutines that are called
- in an interrupt.
-
- Note: The linker has a feature to build a table of marked routines, but it
- is your code that must call these routines, so just declaring a symbol as
- interruptor does nothing by itself.
-
- An interruptor is always exported as an absolute (16 bit) symbol. You don't
- need to use an additional <tt/.export/ statement, this is implied by
- <tt/.interruptor/. It may have an optional priority that is separated by a
- comma. Higher numeric values mean a higher priority. If no priority is
- given, the default priority of 7 is used. Be careful when assigning
- priorities to your own module constructors so they won't interfere with the
- ones in the cc65 library.
-
- Example:
-
- <tscreen><verb>
- .interruptor IrqHandler
- .interruptor Handler, 16
- </verb></tscreen>
-
- See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate
- section <ref id="condes" name="Module constructors/destructors"> explaining
- the feature in more detail.
-
-
-<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p>
-
- Switch on or off line continuations using the backslash character
- before a newline. The option is off by default.
- Note: Line continuations do not work in a comment. A backslash at the
- end of a comment is treated as part of the comment and does not trigger
- line continuation.
- The command must be followed by a '+' or '-' character to switch the
- option on or off respectively.
-
- Example:
-
- <tscreen><verb>
- .linecont + ; Allow line continuations
-
- lda \
- #$20 ; This is legal now
- </verb></tscreen>
-
-
-<sect1><tt>.LIST</tt><label id=".LIST"><p>
-
- Enable output to the listing. The command must be followed by a boolean
- switch ("on", "off", "+" or "-") and will enable or disable listing
- output.
- The option has no effect if the listing is not enabled by the command line
- switch -l. If -l is used, an internal counter is set to 1. Lines are output
- to the listing file, if the counter is greater than zero, and suppressed if
- the counter is zero. Each use of <tt/.LIST/ will increment or decrement the
- counter.
-
- Example:
-
- <tscreen><verb>
- .list on ; Enable listing output
- </verb></tscreen>
-
-
-<sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p>
-
- Set, how many bytes are shown in the listing for one source line. The
- default is 12, so the listing will show only the first 12 bytes for any
- source line that generates more than 12 bytes of code or data.
- The directive needs an argument, which is either "unlimited", or an
- integer constant in the range 4..255.
-
- Examples:
-
- <tscreen><verb>
- .listbytes unlimited ; List all bytes
- .listbytes 12 ; List the first 12 bytes
- .incbin "data.bin" ; Include large binary file
- </verb></tscreen>
-
-
-<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p>
-
- Define byte sized data by extracting only the low byte (that is, bits 0-7) from
- each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with
- the operator '<' prepended to each expression in its list.
-
- Example:
-
- <tscreen><verb>
- .lobytes $1234, $2345, $3456, $4567
- .hibytes $fedc, $edcb, $dcba, $cba9
- </verb></tscreen>
-
- which is equivalent to
-
- <tscreen><verb>
- .byte $34, $45, $56, $67
- .byte $fe, $ed, $dc, $cb
- </verb></tscreen>
-
- Example:
-
- <tscreen><verb>
- .define MyTable TableItem0, TableItem1, TableItem2, TableItem3
-
- TableLookupLo: .lobytes MyTable
- TableLookupHi: .hibytes MyTable
- </verb></tscreen>
-
- which is equivalent to
-
- <tscreen><verb>
- TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3
- TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3
- </verb></tscreen>
-
- See also: <tt><ref id=".BYTE" name=".BYTE"></tt>,
- <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>,
- <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt>
-
-
-<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p>
-
- This command may only be used inside a macro definition. It declares a
- list of identifiers as local to the macro expansion.
-
- A problem when using macros are labels: Since they don't change their name,
- you get a "duplicate symbol" error if the macro is expanded the second time.
- Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their
- name mapped to an internal unique name (<tt/___ABCD__/) with each macro
- invocation.
-
- Some other assemblers start a new lexical block inside a macro expansion.
- This has some drawbacks however, since that will not allow <em/any/ symbol
- to be visible outside a macro, a feature that is sometimes useful. The
- <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way
- to address the problem.
-
- You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside
- a macro.
-
-
-<sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p>
-
- Defines the character that start "cheap" local labels. You may use one
- of '@' and '?' as start character. The default is '@'.
-
- Cheap local labels are labels that are visible only between two non
- cheap labels. This way you can reuse identifiers like "<tt/loop/" without
- using explicit lexical nesting.
-
- Example:
-
- <tscreen><verb>
- .localchar '?'
-
- Clear: lda #$00 ; Global label
- ?Loop: sta Mem,y ; Local label
- dey
- bne ?Loop ; Ok
- rts
- Sub: ... ; New global label
- bne ?Loop ; ERROR: Unknown identifier!
- </verb></tscreen>
-
-
-<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p>
-
- Insert a predefined macro package. The command is followed by an
- identifier specifying the macro package to insert. Available macro
- packages are:
-
- <tscreen><verb>
- atari Defines the scrcode macro.
- cbm Defines the scrcode macro.
- cpu Defines constants for the .CPU variable.
- generic Defines generic macros like add and sub.
- longbranch Defines conditional long jump macros.
- </verb></tscreen>
-
- Including a macro package twice, or including a macro package that
- redefines already existing macros will lead to an error.
-
- Example:
-
- <tscreen><verb>
- .macpack longbranch ; Include macro package
-
- cmp #$20 ; Set condition codes
- jne Label ; Jump long on condition
- </verb></tscreen>
-
- Macro packages are explained in more detail in section <ref
- id="macropackages" name="Macro packages">.
-
-
-<sect1><tt>.MAC, .MACRO</tt><label id=".MACRO"><p>
-
- Start a classic macro definition. The command is followed by an identifier
- (the macro name) and optionally by a comma separated list of identifiers
- that are macro parameters. A macro definition is terminated by <tt><ref
- id=".ENDMACRO" name=".ENDMACRO"></tt>.
-
- Example:
-
- <tscreen><verb>
- .macro ldax arg ; Define macro ldax
- lda arg
- ldx arg+1
- </verb></tscreen>
-
- See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>,
- <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>,
- <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>
-
- See also section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.ORG</tt><label id=".ORG"><p>
-
- Start a section of absolute code. The command is followed by a constant
- expression that gives the new PC counter location for which the code is
- assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to
- relocatable code.
-
- By default, absolute/relocatable mode is global (valid even when switching
- segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt>
- it can be made segment local.
-
- Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing
- code at a specific address is the job of the linker, not the assembler, so
- there is usually no reason to assemble code to a specific address.
-
- Example:
-
- <tscreen><verb>
- .org $7FF ; Emit code starting at $7FF
- </verb></tscreen>
-
-
-<sect1><tt>.OUT</tt><label id=".OUT"><p>
-
- Output a string to the console without producing an error. This command
- is similar to <tt/.ERROR/, however, it does not force an assembler error
- that prevents the creation of an object file.
-
- Example:
-
- <tscreen><verb>
- .out "This code was written by the codebuster(tm)"
- </verb></tscreen>
-
- See also: <tt><ref id=".ERROR" name=".ERROR"></tt>,
- <tt><ref id=".FATAL" name=".FATAL"></tt>,
- <tt><ref id=".WARNING" name=".WARNING"></tt>
-
-
-<sect1><tt>.P02</tt><label id=".P02"><p>
-
- Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816
- instructions. This is the default if not overridden by the
- <tt><ref id="option--cpu" name="--cpu"></tt> command line option.
-
- See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
-
-
-<sect1><tt>.P816</tt><label id=".P816"><p>
-
- Enable the 65816 instruction set. This is a superset of the 65SC02 and
- 6502 instruction sets.
-
- See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt>
-
-
-<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p>
-
- Set the page length for the listing. Must be followed by an integer
- constant. The value may be "unlimited", or in the range 32 to 127. The
- statement has no effect if no listing is generated. The default value is -1
- (unlimited) but may be overridden by the <tt/--pagelength/ command line
- option. Beware: Since ca65 is a one pass assembler, the listing is generated
- after assembly is complete, you cannot use multiple line lengths with one
- source. Instead, the value set with the last <tt/.PAGELENGTH/ is used.
-
- Examples:
-
- <tscreen><verb>
- .pagelength 66 ; Use 66 lines per listing page
-
- .pagelength unlimited ; Unlimited page length
- </verb></tscreen>
-
-
-<sect1><tt>.PC02</tt><label id=".PC02"><p>
-
- Enable the 65C02 instructions set. This instruction set includes all
- 6502 and 65SC02 instructions.
-
- See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
-
-
-<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p>
-
- Pop the last CPU setting from the stack, and activate it.
-
- This command will switch back to the CPU that was last pushed onto the CPU
- stack using the <tt><ref id=".PUSHCPU" name=".PUSHCPU"></tt> command, and
- remove this entry from the stack.
-
- The assembler will print an error message if the CPU stack is empty when
- this command is issued.
-
- See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".PUSHCPU"
- name=".PUSHCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt>
-
-
-<sect1><tt>.POPSEG</tt><label id=".POPSEG"><p>
-
- Pop the last pushed segment from the stack, and set it.
-
- This command will switch back to the segment that was last pushed onto the
- segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt>
- command, and remove this entry from the stack.
-
- The assembler will print an error message if the segment stack is empty
- when this command is issued.
-
- See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt>
-
-
-<sect1><tt>.PROC</tt><label id=".PROC"><p>
-
- Start a nested lexical level with the given name and adds a symbol with this
- name to the enclosing scope. All new symbols from now on are in the local
- lexical level and are accessible from outside only via <ref id="scopesyntax"
- name="explicit scope specification">. Symbols defined outside this local
- level may be accessed as long as their names are not used for new symbols
- inside the level. Symbols names in other lexical levels do not clash, so you
- may use the same names for identifiers. The lexical level ends when the
- <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels
- may be nested up to a depth of 16 (this is an artificial limit to protect
- against errors in the source).
-
- Note: Macro names are always in the global level and in a separate name
- space. There is no special reason for this, it's just that I've never
- had any need for local macro definitions.
-
- Example:
-
- <tscreen><verb>
- .proc Clear ; Define Clear subroutine, start new level
- lda #$00
- L1: sta Mem,y ; L1 is local and does not cause a
- ; duplicate symbol error if used in other
- ; places
- dey
- bne L1 ; Reference local symbol
- rts
- .endproc ; Leave lexical level
- </verb></tscreen>
-
- See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE"
- name=".SCOPE">/
-
-
-<sect1><tt>.PSC02</tt><label id=".PSC02"><p>
-
- Enable the 65SC02 instructions set. This instruction set includes all
- 6502 instructions.
-
- See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02"
- name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt>
-
-
-<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p>
-
- Push the currently active CPU onto a stack. The stack has a size of 8
- entries.
-
- <tt/.PUSHCPU/ allows together with <tt><ref id=".POPCPU"
- name=".POPCPU"></tt> to switch to another CPU and to restore the old CPU
- later, without knowledge of the current CPU setting.
-
- The assembler will print an error message if the CPU stack is already full,
- when this command is issued.
-
- See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".POPCPU"
- name=".POPCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt>
-
-
-<sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p>
-
- Push the currently active segment onto a stack. The entries on the stack
- include the name of the segment and the segment type. The stack has a size
- of 16 entries.
-
- <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt>
- to switch to another segment and to restore the old segment later, without
- even knowing the name and type of the current segment.
-
- The assembler will print an error message if the segment stack is already
- full, when this command is issued.
-
- See: <tt><ref id=".POPSEG" name=".POPSEG"></tt>
-
-
-<sect1><tt>.RELOC</tt><label id=".RELOC"><p>
-
- Switch back to relocatable mode. See the <tt><ref id=".ORG"
- name=".ORG"></tt> command.
-
-
-<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p>
-
- Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT"
- name=".ENDREPEAT"></tt> constant number of times. The command is followed by
- a constant expression that tells how many times the commands in the body
- should get repeated. Optionally, a comma and an identifier may be specified.
- If this identifier is found in the body of the repeat statement, it is
- replaced by the current repeat count (starting with zero for the first time
- the body is repeated).
-
- <tt/.REPEAT/ statements may be nested. If you use the same repeat count
- identifier for a nested <tt/.REPEAT/ statement, the one from the inner
- level will be used, not the one from the outer level.
-
- Example:
-
- The following macro will emit a string that is "encrypted" in that all
- characters of the string are XORed by the value $55.
-
- <tscreen><verb>
- .macro Crypt Arg
- .repeat .strlen(Arg), I
- .byte .strat(Arg, I) ^ $55
- .endrep
- .endmacro
- </verb></tscreen>
-
- See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt>
-
-
-<sect1><tt>.RES</tt><label id=".RES"><p>
-
- Reserve storage. The command is followed by one or two constant
- expressions. The first one is mandatory and defines, how many bytes of
- storage should be defined. The second, optional expression must by a
- constant byte value that will be used as value of the data. If there
- is no fill value given, the linker will use the value defined in the
- linker configuration file (default: zero).
-
- Example:
-
- <tscreen><verb>
- ; Reserve 12 bytes of memory with value $AA
- .res 12, $AA
- </verb></tscreen>
-
-
-<sect1><tt>.RODATA</tt><label id=".RODATA"><p>
-
- Switch to the RODATA segment. The name of the RODATA segment is always
- "RODATA", so this is a shortcut for
-
- <tscreen><verb>
- .segment "RODATA"
- </verb></tscreen>
-
- The RODATA segment is a segment that is used by the compiler for
- readonly data like string constants.
-
- See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command.
-
-
-<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p>
-
- Start a nested lexical level with the given name. All new symbols from now
- on are in the local lexical level and are accessible from outside only via
- <ref id="scopesyntax" name="explicit scope specification">. Symbols defined
- outside this local level may be accessed as long as their names are not used
- for new symbols inside the level. Symbols names in other lexical levels do
- not clash, so you may use the same names for identifiers. The lexical level
- ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is
- read. Lexical levels may be nested up to a depth of 16 (this is an
- artificial limit to protect against errors in the source).
-
- Note: Macro names are always in the global level and in a separate name
- space. There is no special reason for this, it's just that I've never
- had any need for local macro definitions.
-
- Example:
-
- <tscreen><verb>
- .scope Error ; Start new scope named Error
- None = 0 ; No error
- File = 1 ; File error
- Parse = 2 ; Parse error
- .endscope ; Close lexical level
-
- ...
- lda #Error::File ; Use symbol from scope Error
- </verb></tscreen>
-
- See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC"
- name=".PROC">/
-
-
-<sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p>
-
- Switch to another segment. Code and data is always emitted into a
- segment, that is, a named section of data. The default segment is
- "CODE". There may be up to 254 different segments per object file
- (and up to 65534 per executable). There are shortcut commands for
- the most common segments ("CODE", "DATA" and "BSS").
-
- The command is followed by a string containing the segment name (there are
- some constraints for the name - as a rule of thumb use only those segment
- names that would also be valid identifiers). There may also be an optional
- address size separated by a colon. See the section covering <tt/<ref
- id="address-sizes" name="address sizes">/ for more information.
-
- The default address size for a segment depends on the memory model specified
- on the command line. The default is "absolute", which means that you don't
- have to use an address size modifier in most cases.
-
- "absolute" means that the is a segment with 16 bit (absolute) addressing.
- That is, the segment will reside somewhere in core memory outside the zero
- page. "zeropage" (8 bit) means that the segment will be placed in the zero
- page and direct (short) addressing is possible for data in this segment.
-
- Beware: Only labels in a segment with the zeropage attribute are marked
- as reachable by short addressing. The `*' (PC counter) operator will
- work as in other segments and will create absolute variable values.
-
- Please note that a segment cannot have two different address sizes. A
- segment specified as zeropage cannot be declared as being absolute later.
-
- Examples:
-
- <tscreen><verb>
- .segment "ROM2" ; Switch to ROM2 segment
- .segment "ZP2": zeropage ; New direct segment
- .segment "ZP2" ; Ok, will use last attribute
- .segment "ZP2": absolute ; Error, redecl mismatch
- </verb></tscreen>
-
- See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE"
- name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref
- id=".RODATA" name=".RODATA"></tt>
-
-
-<sect1><tt>.SET</tt><label id=".SET"><p>
-
- <tt/.SET/ is used to assign a value to a variable. See <ref id="variables"
- name="Numeric variables"> for a full description.
-
-
-<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p>
-
- Switch the CPU instruction set. The command is followed by a string that
- specifies the CPU. Possible values are those that can also be supplied to
- the <tt><ref id="option--cpu" name="--cpu"></tt> command line option,
- namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please
- note that support for the sunplus CPU is not available in the freeware
- version, because the instruction set of the sunplus CPU is "proprietary
- and confidential".
-
- See: <tt><ref id=".CPU" name=".CPU"></tt>,
- <tt><ref id=".IFP02" name=".IFP02"></tt>,
- <tt><ref id=".IFP816" name=".IFP816"></tt>,
- <tt><ref id=".IFPC02" name=".IFPC02"></tt>,
- <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>,
- <tt><ref id=".P02" name=".P02"></tt>,
- <tt><ref id=".P816" name=".P816"></tt>,
- <tt><ref id=".PC02" name=".PC02"></tt>,
- <tt><ref id=".PSC02" name=".PSC02"></tt>
-
-
-<sect1><tt>.SMART</tt><label id=".SMART"><p>
-
- Switch on or off smart mode. The command must be followed by a '+' or '-'
- character to switch the option on or off respectively. The default is off
- (that is, the assembler doesn't try to be smart), but this default may be
- changed by the -s switch on the command line.
-
- In smart mode the assembler will do the following:
-
- <itemize>
- <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode
- and update the operand sizes accordingly. If the operand of such an
- instruction cannot be evaluated by the assembler (for example, because
- the operand is an imported symbol), a warning is issued. Beware: Since
- the assembler cannot trace the execution flow this may lead to false
- results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/
- instructions to tell the assembler about the current settings.
- <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is
- used within a procedure declared as <tt/far/, or if the procedure has
- no explicit address specification, but it is <tt/far/ because of the
- memory model used.
- </itemize>
-
- Example:
-
- <tscreen><verb>
- .smart ; Be smart
- .smart - ; Stop being smart
- </verb></tscreen>
-
- See: <tt><ref id=".A16" name=".A16"></tt>,
- <tt><ref id=".A8" name=".A8"></tt>,
- <tt><ref id=".I16" name=".I16"></tt>,
- <tt><ref id=".I8" name=".I8"></tt>
-
-
-<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p>
-
- Starts a struct definition. Structs are covered in a separate section named
- <ref id="structs" name=""Structs and unions"">.
-
- See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
- <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
- <tt><ref id=".UNION" name=".UNION"></tt>
-
-
-<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p>
-
- Enable the SunPlus instructions set. This command will not work in the
- freeware version of the assembler, because the instruction set is
- "proprietary and confidential".
-
- See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02"
- name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and
- <tt><ref id=".P816" name=".P816"></tt>
-
-
-<sect1><tt>.TAG</tt><label id=".TAG"><p>
-
- Allocate space for a struct or union.
-
- Example:
-
- <tscreen><verb>
- .struct Point
- xcoord .word
- ycoord .word
- .endstruct
-
- .bss
- .tag Point ; Allocate 4 bytes
- </verb></tscreen>
-
-
-<sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p>
-
- Delete a define style macro definition. The command is followed by an
- identifier which specifies the name of the macro to delete. Macro
- replacement is switched of when reading the token following the command
- (otherwise the macro name would be replaced by its replacement list).
-
- See also the <tt><ref id=".DEFINE" name=".DEFINE"></tt> command and
- section <ref id="macros" name="Macros">.
-
-
-<sect1><tt>.UNION</tt><label id=".UNION"><p>
-
- Starts a union definition. Unions are covered in a separate section named
- <ref id="structs" name=""Structs and unions"">.
-
- See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
- <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
- <tt><ref id=".STRUCT" name=".STRUCT"></tt>
-
-
-<sect1><tt>.WARNING</tt><label id=".WARNING"><p>
-
- Force an assembly warning. The assembler will output a warning message
- preceded by "User warning". This warning will always be output, even if
- other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt>
- command line option.
-
- This command may be used to output possible problems when assembling
- the source file.
-
- Example:
-
- <tscreen><verb>
- .macro jne target
- .local L1
- .ifndef target
- .warning "Forward jump in jne, cannot optimize!"
- beq L1
- jmp target
- L1:
- .else
- ...
- .endif
- .endmacro
- </verb></tscreen>
-
- See also: <tt><ref id=".ERROR" name=".ERROR"></tt>,
- <tt><ref id=".FATAL" name=".FATAL"></tt>,
- <tt><ref id=".OUT" name=".OUT"></tt>
-
-
-<sect1><tt>.WORD</tt><label id=".WORD"><p>
-
- Define word sized data. Must be followed by a sequence of (word ranged,
- but not necessarily constant) expressions.
-
- Example:
-
- <tscreen><verb>
- .word $0D00, $AF13, _Clear
- </verb></tscreen>
-
-
-<sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p>
-
- Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment.
- The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a
- shortcut for
-
- <tscreen><verb>
- .segment "ZEROPAGE", zeropage
- </verb></tscreen>
-
- Because of the "zeropage" attribute, labels declared in this segment are
- addressed using direct addressing mode if possible. You <em/must/ instruct
- the linker to place this segment somewhere in the address range 0..$FF
- otherwise you will get errors.
-
- See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt>
-
-
-
-<sect>Macros<label id="macros"><p>
-
-
-<sect1>Introduction<p>
-
-Macros may be thought of as "parametrized super instructions". Macros are
-sequences of tokens that have a name. If that name is used in the source
-file, the macro is "expanded", that is, it is replaced by the tokens that
-were specified when the macro was defined.
-
-
-<sect1>Macros without parameters<p>
-
-In its simplest form, a macro does not have parameters. Here's an
-example:
-
-<tscreen><verb>
- .macro asr ; Arithmetic shift right
- cmp #$80 ; Put bit 7 into carry
- ror ; Rotate right with carry
- .endmacro
-</verb></tscreen>
-
-The macro above consists of two real instructions, that are inserted into
-the code, whenever the macro is expanded. Macro expansion is simply done
-by using the name, like this:
-
-<tscreen><verb>
- lda $2010
- asr
- sta $2010
-</verb></tscreen>
-
-
-<sect1>Parametrized macros<p>
-
-When using macro parameters, macros can be even more useful:
-
-<tscreen><verb>
- .macro inc16 addr
- clc
- lda addr
- adc #$01
- sta addr
- lda addr+1
- adc #$00
- sta addr+1
- .endmacro
-</verb></tscreen>
-
-When calling the macro, you may give a parameter, and each occurrence of
-the name "addr" in the macro definition will be replaced by the given
-parameter. So
-
-<tscreen><verb>
- inc16 $1000
-</verb></tscreen>
-
-will be expanded to
-
-<tscreen><verb>
- clc
- lda $1000
- adc #$01
- sta $1000
- lda $1000+1
- adc #$00
- sta $1000+1
-</verb></tscreen>
-
-A macro may have more than one parameter, in this case, the parameters
-are separated by commas. You are free to give less parameters than the
-macro actually takes in the definition. You may also leave intermediate
-parameters empty. Empty parameters are replaced by empty space (that is,
-they are removed when the macro is expanded). If you have a look at our
-macro definition above, you will see, that replacing the "addr" parameter
-by nothing will lead to wrong code in most lines. To help you, writing
-macros with a variable parameter list, there are some control commands:
-
-<tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and
-returns true, if there are any tokens on the remainder of the line. Since
-empty parameters are replaced by nothing, this may be used to test if a given
-parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the
-opposite.
-
-Look at this example:
-
-<tscreen><verb>
- .macro ldaxy a, x, y
- .ifnblank a
- lda #a
- .endif
- .ifnblank x
- ldx #x
- .endif
- .ifnblank y
- ldy #y
- .endif
- .endmacro
-</verb></tscreen>
-
-This macro may be called as follows:
-
-<tscreen><verb>
- ldaxy 1, 2, 3 ; Load all three registers
-
- ldaxy 1, , 3 ; Load only a and y
-
- ldaxy , , 3 ; Load y only
-</verb></tscreen>
-
-There's another helper command for determining, which macro parameters are
-valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is
-replaced by the parameter count given, <em/including/ intermediate empty macro
-parameters:
-
-<tscreen><verb>
- ldaxy 1 ; .PARAMCOUNT = 1
- ldaxy 1,,3 ; .PARAMCOUNT = 3
- ldaxy 1,2 ; .PARAMCOUNT = 2
- ldaxy 1, ; .PARAMCOUNT = 2
- ldaxy 1,2,3 ; .PARAMCOUNT = 3
-</verb></tscreen>
-
-Macro parameters may optionally be enclosed into curly braces. This allows the
-inclusion of tokens that would otherwise terminate the parameter (the comma in
-case of a macro parameter).
-
-<tscreen><verb>
- .macro foo arg1, arg2
- ...
- .endmacro
-
- foo ($00,x) ; Two parameters passed
- foo {($00,x)} ; One parameter passed
-</verb></tscreen>
-
-In the first case, the macro is called with two parameters: '<tt/($00/'
-and 'x)'. The comma is not passed to the macro, since it is part of the
-calling sequence, not the parameters.
-
-In the second case, '($00,x)' is passed to the macro, this time
-including the comma.
-
-
-<sect1>Detecting parameter types<p>
-
-Sometimes it is nice to write a macro that acts differently depending on the
-type of the argument supplied. An example would be a macro that loads a 16 bit
-value from either an immediate operand, or from memory. The <tt/<ref
-id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/
-functions will allow you to do exactly this:
-
-<tscreen><verb>
- .macro ldax arg
- .if (.match (.left (1, {arg}), #))
- ; immediate mode
- lda #<(.right (.tcount ({arg})-1, {arg}))
- ldx #>(.right (.tcount ({arg})-1, {arg}))
- .else
- ; assume absolute or zero page
- lda arg
- ldx 1+(arg)
- .endif
- .endmacro
-</verb></tscreen>
-
-Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to
-check if its argument begins with a hash mark. If so, two immediate loads are
-emitted, Otherwise a load from an absolute zero page memory location is
-assumed. Please note how the curly braces are used to enclose parameters to
-pseudo functions handling token lists. This is necessary, because the token
-lists may include commas or parens, which would be treated by the assembler
-as end-of-list.
-
-The macro can be used as
-
-<tscreen><verb>
- foo: .word $5678
- ...
- ldax #$1234 ; X=$12, A=$34
- ...
- ldax foo ; X=$56, A=$78
-</verb></tscreen>
-
-
-<sect1>Recursive macros<p>
-
-Macros may be used recursively:
-
-<tscreen><verb>
- .macro push r1, r2, r3
- lda r1
- pha
- .if .paramcount > 1
- push r2, r3
- .endif
- .endmacro
-</verb></tscreen>
-
-There's also a special macro to help writing recursive macros: <tt><ref
-id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion
-immediately:
-
-<tscreen><verb>
- .macro push r1, r2, r3, r4, r5, r6, r7
- .ifblank r1
- ; First parameter is empty
- .exitmacro
- .else
- lda r1
- pha
- .endif
- push r2, r3, r4, r5, r6, r7
- .endmacro
-</verb></tscreen>
-
-When expanding this macro, the expansion will push all given parameters
-until an empty one is encountered. The macro may be called like this:
-
-<tscreen><verb>
- push $20, $21, $32 ; Push 3 ZP locations
- push $21 ; Push one ZP location
-</verb></tscreen>
-
-
-<sect1>Local symbols inside macros<p>
-
-Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and
-<tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need?
-Have a look at the inc16 macro above. Here is it again:
-
-<tscreen><verb>
- .macro inc16 addr
- clc
- lda addr
- adc #$01
- sta addr
- lda addr+1
- adc #$00
- sta addr+1
- .endmacro
-</verb></tscreen>
-
-If you have a closer look at the code, you will notice, that it could be
-written more efficiently, like this:
-
-<tscreen><verb>
- .macro inc16 addr
- inc addr
- bne Skip
- inc addr+1
- Skip:
- .endmacro
-</verb></tscreen>
-
-But imagine what happens, if you use this macro twice? Since the label "Skip"
-has the same name both times, you get a "duplicate symbol" error. Without a
-way to circumvent this problem, macros are not as useful, as they could be.
-One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>.
-It declares one or more symbols as local to the macro expansion. The names of
-local variables are replaced by a unique name in each separate macro
-expansion. So we can solve the problem above by using <tt/.LOCAL/:
-
-<tscreen><verb>
- .macro inc16 addr
- .local Skip ; Make Skip a local symbol
- inc addr
- bne Skip
- inc addr+1
- Skip: ; Not visible outside
- .endmacro
-</verb></tscreen>
-
-Another solution is of course to start a new lexical block inside the macro
-that hides any labels:
-
-<tscreen><verb>
- .macro inc16 addr
- .proc
- inc addr
- bne Skip
- inc addr+1
- Skip:
- .endproc
- .endmacro
-</verb></tscreen>
-
-
-<sect1>C style macros<p>
-
-Starting with version 2.5 of the assembler, there is a second macro type
-available: C style macros using the <tt/.DEFINE/ directive. These macros are
-similar to the classic macro type described above, but behaviour is sometimes
-different:
-
-<itemize>
-
-<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not
- span more than a line. You may use line continuation (see <tt><ref
- id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over
- more than one line for increased readability, but the macro itself
- may not contain an end-of-line token.
-
-<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share
- the name space with classic macros, but they are detected and replaced
- at the scanner level. While classic macros may be used in every place,
- where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE"
- name=".DEFINE"></tt> style macros are allowed anywhere in a line. So
- they are more versatile in some situations.
-
-<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take
- parameters. While classic macros may have empty parameters, this is
- not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros.
- For this macro type, the number of actual parameters must match
- exactly the number of formal parameters.
-
- To make this possible, formal parameters are enclosed in braces when
- defining the macro. If there are no parameters, the empty braces may
- be omitted.
-
-<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not
- contain end-of-line tokens, there are things that cannot be done. They
- may not contain several processor instructions for example. So, while
- some things may be done with both macro types, each type has special
- usages. The types complement each other.
-
-</itemize>
-
-Let's look at a few examples to make the advantages and disadvantages
-clear.
-
-To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the
-following <tt/.DEFINE/:
-
-<tscreen><verb>
- .define EQU =
-
- foo EQU $1234 ; This is accepted now
-</verb></tscreen>
-
-You may use the directive to define string constants used elsewhere:
-
-<tscreen><verb>
- ; Define the version number
- .define VERSION "12.3a"
-
- ; ... and use it
- .asciiz VERSION
-</verb></tscreen>
-
-Macros with parameters may also be useful:
-
-<tscreen><verb>
- .define DEBUG(message) .out message
-
- DEBUG "Assembling include file #3"
-</verb></tscreen>
-
-Note that, while formal parameters have to be placed in braces, this is
-not true for the actual parameters. Beware: Since the assembler cannot
-detect the end of one parameter, only the first token is used. If you
-don't like that, use classic macros instead:
-
-<tscreen><verb>
- .macro DEBUG message
- .out message
- .endmacro
-</verb></tscreen>
-
-(This is an example where a problem can be solved with both macro types).
-
-
-<sect1>Characters in macros<p>
-
-When using the <ref id="option-t" name="-t"> option, characters are translated
-into the target character set of the specific machine. However, this happens
-as late as possible. This means that strings are translated if they are part
-of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ"
-name=".ASCIIZ"></tt> command. Characters are translated as soon as they are
-used as part of an expression.
-
-This behaviour is very intuitive outside of macros but may be confusing when
-doing more complex macros. If you compare characters against numeric values,
-be sure to take the translation into account.
-
-
-<sect1>Deleting macros<p>
-
-Macros can be deleted. This will not work if the macro that should be deleted
-is currently expanded as in the following non working example:
-
-<tscreen><verb>
- .macro notworking
- .delmacro notworking
- .endmacro
-
- notworking ; Will not work
-</verb></tscreen>
-
-The commands to delete classic and define style macros differ. Classic macros
-can be deleted by use of <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, while
-for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref
-id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example:
-
-<tscreen><verb>
- .define value 1
- .macro mac
- .byte 2
- .endmacro
-
- .byte value ; Emit one byte with value 1
- mac ; Emit another byte with value 2
-
- .undefine value
- .delmacro mac
-
- .byte value ; Error: Unknown identifier
- mac ; Error: Missing ":"
-</verb></tscreen>
-
-A separate command for <tt>.DEFINE</tt> style macros was necessary, because
-the name of such a macro is replaced by its replacement list on a very low
-level. To get the actual name, macro replacement has to be switched off when
-reading the argument to <tt>.UNDEFINE</tt>. This does also mean that the
-argument to <tt>.UNDEFINE</tt> is not allowed to come from another
-<tt>.DEFINE</tt>. All this is not necessary for classic macros, so having two
-different commands increases flexibility.
-
-
-<sect>Macro packages<label id="macropackages"><p>
-
-Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined
-macro packages may be included with just one command. Available macro packages
-are:
-
-
-<sect1><tt>.MACPACK generic</tt><p>
-
-This macro package defines macros that are useful in almost any program.
-Currently defined macros are:
-
-<tscreen><verb>
- .macro add Arg
- clc
- adc Arg
- .endmacro
-
- .macro sub Arg
- sec
- sbc Arg
- .endmacro
-
- .macro bge Arg
- bcs Arg
- .endmacro
-
- .macro blt Arg
- bcc Arg
- .endmacro
-
- .macro bgt Arg
- .local L
- beq L
- bcs Arg
- L:
- .endmacro
-
- .macro ble Arg
- beq Arg
- bcc Arg
- .endmacro
-</verb></tscreen>
-
-
-<sect1><tt>.MACPACK longbranch</tt><p>
-
-This macro package defines long conditional jumps. They are named like the
-short counterpart but with the 'b' replaced by a 'j'. Here is a sample
-definition for the "<tt/jeq/" macro, the other macros are built using the same
-scheme:
-
-<tscreen><verb>
- .macro jeq Target
- .if .def(Target) .and ((*+2)-(Target) <= 127)
- beq Target
- .else
- bne *+5
- jmp Target
- .endif
- .endmacro
-</verb></tscreen>
-
-All macros expand to a short branch, if the label is already defined (back
-jump) and is reachable with a short jump. Otherwise the macro expands to a
-conditional branch with the branch condition inverted, followed by an absolute
-jump to the actual branch target.
-
-The package defines the following macros:
-
-<tscreen><verb>
- jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc
-</verb></tscreen>
-
-
-
-<sect1><tt>.MACPACK atari</tt><p>
-
-The atari macro package will define a macro named <tt/scrcode/. It takes a
-string as argument and places this string into memory translated into screen
-codes.
-
-
-<sect1><tt>.MACPACK cbm</tt><p>
-
-The cbm macro package will define a macro named <tt/scrcode/. It takes a
-string as argument and places this string into memory translated into screen
-codes.
-
-
-<sect1><tt>.MACPACK cpu</tt><p>
-
-This macro package does not define any macros but constants used to examine
-the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For
-each supported CPU a constant similar to
-
-<tscreen><verb>
- CPU_6502
- CPU_65SC02
- CPU_65C02
- CPU_65816
- CPU_SUNPLUS
- CPU_SWEET16
- CPU_HUC6280
-</verb></tscreen>
-
-is defined. These constants may be used to determine the exact type of the
-currently enabled CPU. In addition to that, for each CPU instruction set,
-another constant is defined:
-
-<tscreen><verb>
- CPU_ISET_6502
- CPU_ISET_65SC02
- CPU_ISET_65C02
- CPU_ISET_65816
- CPU_ISET_SUNPLUS
- CPU_ISET_SWEET16
- CPU_ISET_HUC6280
-</verb></tscreen>
-
-The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
-be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the
-currently enabled CPU supports a specific instruction set. For example the
-65C02 supports all instructions of the 65SC02 CPU, so it has the
-<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/
-bit. Using
-
-<tscreen><verb>
- .if (.cpu .bitand CPU_ISET_65SC02)
- lda (sp)
- .else
- ldy #$00
- lda (sp),y
- .endif
-</verb></tscreen>
-
-it is possible to determine if the
-
-<tscreen><verb>
- lda (sp)
-</verb></tscreen>
-
-instruction is supported, which is the case for the 65SC02, 65C02 and 65816
-CPUs (the latter two are upwards compatible to the 65SC02).
-
-
-
-<sect>Predefined constants<label id="predefined-constants"><p>
-
-For better orthogonality, the assembler defines similar symbols as the
-compiler, depending on the target system selected:
-
-<itemize>
-<item><tt/__APPLE2__/ - Target system is <tt/apple2/
-<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
-<item><tt/__ATARI__/ - Target system is <tt/atari/
-<item><tt/__ATMOS__/ - Target system is <tt/atmos/
-<item><tt/__BBC__/ - Target system is <tt/bbc/
-<item><tt/__C128__/ - Target system is <tt/c128/
-<item><tt/__C16__/ - Target system is <tt/c16/
-<item><tt/__C64__/ - Target system is <tt/c64/
-<item><tt/__CBM__/ - Target is a Commodore system
-<item><tt/__CBM510__/ - Target system is <tt/cbm510/
-<item><tt/__CBM610__/ - Target system is <tt/cbm610/
-<item><tt/__GEOS__/ - Target system is <tt/geos/
-<item><tt/__LUNIX__/ - Target system is <tt/lunix/
-<item><tt/__NES__/ - Target system is <tt/nes/
-<item><tt/__PET__/ - Target system is <tt/pet/
-<item><tt/__PLUS4__/ - Target system is <tt/plus4/
-<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/
-<item><tt/__VIC20__/ - Target system is <tt/vic20/
-</itemize>
-
-
-<sect>Structs and unions<label id="structs"><p>
-
-<sect1>Structs and unions Overview<p>
-
-Structs and unions are special forms of <ref id="scopes" name="scopes">. They
-are to some degree comparable to their C counterparts. Both have a list of
-members. Each member allocates storage and may optionally have a name, which,
-in case of a struct, is the offset from the beginning and, in case of a union,
-is always zero.
-
-
-<sect1>Declaration<p>
-
-Here is an example for a very simple struct with two members and a total size
-of 4 bytes:
-
-<tscreen><verb>
- .struct Point
- xcoord .word
- ycoord .word
- .endstruct
-</verb></tscreen>
-
-A union shares the total space between all its members, its size is the same
-as that of the largest member. The offset of all members relative to the union
-is zero.
-
-<tscreen><verb>
- .union Entry
- index .word
- ptr .addr
- .endunion
-</verb></tscreen>
-
-A struct or union must not necessarily have a name. If it is anonymous, no
-local scope is opened, the identifiers used to name the members are placed
-into the current scope instead.
-
-A struct may contain unnamed members and definitions of local structs. The
-storage allocators may contain a multiplier, as in the example below:
-
-<tscreen><verb>
- .struct Circle
- .struct Point
- .word 2 ; Allocate two words
- .endstruct
- Radius .word
- .endstruct
-</verb></tscreen>
-
-
-<sect1>The <tt/.TAG/ keyword<p>
-
-Using the <ref id=".TAG" name=".TAG"> keyword, it is possible to reserve space
-for an already defined struct or unions within another struct:
-
-<tscreen><verb>
- .struct Point
- xcoord .word
- ycoord .word
- .endstruct
-
- .struct Circle
- Origin .tag Point
- Radius .byte
- .endstruct
-</verb></tscreen>
-
-Space for a struct or union may be allocated using the <ref id=".TAG"
-name=".TAG"> directive.
-
-<tscreen><verb>
- C: .tag Circle
-</verb></tscreen>
-
-Currently, members are just offsets from the start of the struct or union. To
-access a field of a struct, the member offset has to be added to the address
-of the struct itself:
-
-<tscreen><verb>
- lda C+Circle::Radius ; Load circle radius into A
-</verb></tscreen>
-
-This may change in a future version of the assembler.
-
-
-<sect1>Limitations<p>
-
-Structs and unions are currently implemented as nested symbol tables (in fact,
-they were a by-product of the improved scoping rules). Currently, the
-assembler has no idea of types. This means that the <ref id=".TAG"
-name=".TAG"> keyword will only allocate space. You won't be able to initialize
-variables declared with <ref id=".TAG" name=".TAG">, and adding an embedded
-structure to another structure with <ref id=".TAG" name=".TAG"> will not make
-this structure accessible by using the '::' operator.
-
-
-
-<sect>Module constructors/destructors<label id="condes"><p>
-
-<em>Note:</em> This section applies mostly to C programs, so the explanation
-below uses examples from the C libraries. However, the feature may also be
-useful for assembler programs.
-
-
-<sect1>Module constructors/destructors Overview<p>
-
-Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
-name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a
-special way. The linker is able to generate tables with all functions of a
-specific type. Such a table will <em>only</em> include symbols from object
-files that are linked into a specific executable. This may be used to add
-initialization and cleanup code for library modules, or a table of interrupt
-handler functions.
-
-The C heap functions are an example where module initialization code is used.
-All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few
-variables that contain the start and the end of the heap, pointers to the free
-list and so on. Since the end of the heap depends on the size and start of the
-stack, it must be initialized at runtime. However, initializing these
-variables for programs that do not use the heap are a waste of time and
-memory.
-
-So the central module defines a function that contains initialization code and
-exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if)
-this module is added to an executable by the linker, the initialization
-function will be placed into the table of constructors by the linker. The C
-startup code will call all constructors before <tt/main/ and all destructors
-after <tt/main/, so without any further work, the heap initialization code is
-called once the module is linked in.
-
-While it would be possible to add explicit calls to initialization functions
-in the startup code, the new approach has several advantages:
-
-<enum>
-<item>
-If a module is not included, the initialization code is not linked in and not
-called. So you don't pay for things you don't need.
-
-<item>
-Adding another library that needs initialization does not mean that the
-startup code has to be changed. Before we had module constructors and
-destructors, the startup code for all systems had to be adjusted to call the
-new initialization code.
-
-<item>
-The feature saves memory: Each additional initialization function needs just
-two bytes in the table (a pointer to the function).
-
-</enum>
-
-
-<sect1>Calling order<p>
-
-The symbols are sorted in increasing priority order by the linker when using
-one of the builtin linker configurations, so the functions with lower
-priorities come first and are followed by those with higher priorities. The C
-library runtime subroutine that walks over the function tables calls the
-functions starting from the top of the table - which means that functions with
-a high priority are called first.
-
-So when using the C runtime, functions are called with high priority functions
-first, followed by low priority functions.
-
-
-<sect1>Pitfalls<p>
-
-When using these special symbols, please take care of the following:
-
-<itemize>
-
-<item>
-The linker will only generate function tables, it will not generate code to
-call these functions. If you're using the feature in some other than the
-existing C environments, you have to write code to call all functions in a
-linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules
-in the C runtime for an example on how to do this.
-
-<item>
-The linker will only add addresses of functions that are in modules linked to
-the executable. This means that you have to be careful where to place the
-condes functions. If initialization or an irq handler is needed for a group of
-functions, be sure to place the function into a module that is linked in
-regardless of which function is called by the user.
-
-<item>
-The linker will generate the tables only when requested to do so by the
-<tt/FEATURE CONDES/ statement in the linker config file. Each table has to
-be requested separately.
-
-<item>
-Constructors and destructors may have priorities. These priorities determine
-the order of the functions in the table. If your initialization or cleanup code
-does depend on other initialization or cleanup code, you have to choose the
-priority for the functions accordingly.
-
-<item>
-Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref
-id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR"
-name=".INTERRUPTOR"></tt> statements, there is also a more generic command:
-<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an
-additional type. Predefined types are 0 (constructor), 1 (destructor) and 2
-(interruptor). The linker generates a separate table for each type on request.
-
-</itemize>
-
-
-<sect>Porting sources from other assemblers<p>
-
-Sometimes it is necessary to port code written for older assemblers to ca65.
-In some cases, this can be done without any changes to the source code by
-using the emulation features of ca65 (see <tt><ref id=".FEATURE"
-name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the
-source code.
-
-Probably the biggest difference is the handling of the <tt><ref id=".ORG"
-name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is
-done by the linker. Most other assemblers generate absolute code, placement is
-done within the assembler and there is no external linker.
-
-In general it is not a good idea to write new code using the emulation
-features of the assembler, but there may be situations where even this rule is
-not valid.
-
-<sect1>TASS<p>
-
-You need to use some of the ca65 emulation features to simulate the behaviour
-of such simple assemblers.
-
-<enum>
-<item>Prepare your sourcecode like this:
-
-<tscreen><verb>
- ; if you want TASS style labels without colons
- .feature labels_without_colons
-
- ; if you want TASS style character constants
- ; ("a" instead of the default 'a')
- .feature loose_char_term
-
- .word *+2 ; the cbm load address
-
- [yourcode here]
-</verb></tscreen>
-
-notice that the two emulation features are mostly useful for porting
-sources originally written in/for TASS, they are not needed for the
-actual "simple assembler operation" and are not recommended if you are
-writing new code from scratch.
-
-<item>Replace all program counter assignments (which are not possible in ca65
-by default, and the respective emulation feature works different from what
-you'd expect) by another way to skip to memory locations, for example the
-<tt><ref id=".RES" name=".RES"></tt> directive.
-
-<tscreen><verb>
- ; *=$2000
- .res $2000-* ; reserve memory up to $2000
-</verb></tscreen>
-
-Please note that other than the original TASS, ca65 can never move the program
-counter backwards - think of it as if you are assembling to disk with TASS.
-
-<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be
-rewritten to match ca65 syntax. Most importantly notice that due to the lack
-of <tt/.goto/, everything involving loops must be replaced by
-<tt><ref id=".REPEAT" name=".REPEAT"></tt>.
-
-<item>To assemble code to a different address than it is executed at, use the
-<tt><ref id=".ORG" name=".ORG"></tt> directive instead of
-<tt/.offs/-constructs.
-
-<tscreen><verb>
- .org $1800
-
- [floppy code here]
-
- .reloc ; back to normal
-</verb></tscreen>
-
-<item>Then assemble like this:
-
-<tscreen><verb>
- cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg
-</verb></tscreen>
-
-Note that you need to use the actual start address minus two, since two bytes
-are used for the cbm load address.
-
-</enum>
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the assembler, if you find any bugs, or if
-you're doing something interesting with the assembler, I would be glad to
-hear from you. Feel free to contact me by email
-(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von
-Bassewitz. For usage of the binaries and/or sources the following
-conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
-
-
+++ /dev/null
-<!doctype linuxdoc system>
-
-<article>
-<title>ca65html Users Guide
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2007-10-2
-
-<abstract>
-ca65html is an assembly-source-to-HTML converter. It is very useful if you
-want to publish your assembler sources in the web.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Overview<p>
-
-ca65html converts assembly source files written for use with the <tt/<url
-url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone
-tool written in PERL; and as such, it does not understand the structure of
-assembler sources in the same depth as ca65 does, so it may fail in very rare
-cases. In all other cases, it generates very nice output.
-
-
-<sect>Usage<p>
-
-
-<sect1>Command line option overview<p>
-
-The HTML converter accepts the following options:
-
-<tscreen><verb>
----------------------------------------------------------------------------
-Usage: ca65html [options] file ...
-Options:
- --bgcolor c Use background color c instead of #FFFFFF
- --colorize Add color highlights to the output
- --commentcolor c Use color c for comments instead of #B22222
- --crefs Generate references to the C source file(s)
- --ctrlcolor c Use color c for directives instead of #228B22
- --cvttabs Convert tabs to spaces in the output
- --help This text
- --htmldir dir Specify directory for HTML files
- --indexcols n Use n columns on index page (default 6)
- --indexname file Use file for the index file instead of index.html
- --indexpage Create an index page
- --indextitle title Use title as the index title instead of Index
- --keywordcolor c Use color c for keywords instead of #A020F0
- --linelabels Generate a linexxx HTML label for each line
- --linenumbers Add line numbers to the output
- --linkstyle style Use the given link style
- --replaceext Replace source extension instead of appending .html
- --textcolor c Use text color c instead of #000000
- --verbose Be more verbose
----------------------------------------------------------------------------
-</verb></tscreen>
-
-
-<sect1>Command line options in detail<p>
-
-Here is a description of all the command line options:
-
-<descrip>
-
- <tag><tt>--bgcolor c</tt></tag>
-
- Set the background color. The argument c must be a valid HTML color, usually
- given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the
- respective red, green, and blue parts as two-digit hex values. The default is
- <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the
- generated HTML output.
-
-
- <tag><tt>--colorize</tt></tag>
-
- Colorize the output. The converter outputs processor instructions, assembler
- control commands, and comments in different colors.
-
-
- <tag><tt>--commentcolor c</tt></tag>
-
- Set the color used for comments. The argument c must be a valid HTML color,
- usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
- the respective red, green, and blue parts as two-digit hex values. The
- default is <tt/#B22222/ (red).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
-
- <tag><tt>--crefs</tt></tag>
-
- Generate references to the C file, when a <tt/.dbg/ command is found with a
- file name. The converter assumes that the C source was also converted into
- HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and
- lives in the same directory as the assembler file. If the <tt/.dbg/
- directive specifies a line, a link to the correct line in the C file is
- generated, using a label in the form <tt/linexxx/, as it is created by
- <tt/c2html/ by use of the <tt/-n/ option.
-
-
- <tag><tt>--commentcolor c</tt></tag>
-
- Set the color used for assembler control commands. The argument c must be a
- valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
- where r, g, and b are the respective red, green, and blue parts as two-digit
- hex values. The default is <tt/#228B22/ (green).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
-
- <tag><tt>--cvttabs</tt></tag>
-
- Convert tabs in the input into spaces in the output, assuming the standard
- tab width of 8. This is useful if the <tt/--linenumbers/ option is used to
- retain the indentation.
-
-
- <tag><tt>--help</tt></tag>
-
- Print the command line option summary shown above.
-
-
- <tag><tt>--htmldir dir</tt></tag>
-
- Specify an output directory for the generated HTML files.
-
-
- <tag><tt>--indexcols n</tt></tag>
-
- Use n columns on the index page. This option has no effect if used without
- <tt/--indexpage/.
-
-
- <tag><tt>--indexname name</tt></tag>
-
- Use another index file name instead of <tt/index.html/. This option has no
- effect if used without <tt/--indexpage/.
-
-
- <tag><tt>--indexpage</tt></tag>
-
- Causes the converter to generate an index page listing file names, and all
- exports found in the converted files.
-
-
- <tag><tt>--indextitle title</tt></tag>
-
- Use "title" as the title of the index page. This option has no effect if
- used without <tt/--indexpage/.
-
-
- <tag><tt>--keywordcolor c</tt></tag>
-
- Set the color used for processor instructions. The argument c must be a
- valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
- where r, g, and b are the respective red, green, and blue parts as two-digit
- hex values. The default is <tt/#A020F0/ (purple).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
- <tag><tt>--linelabels</tt></tag>
-
- Generate a label for each line using the name <tt/linexxx/ where xxx is the
- number of the line.
-
- Note: The converter will not make use of this label. Use this option if you
- have other HTML pages referencing the converted assembler file.
-
-
- <tag><tt>--linenumbers</tt></tag>
-
- Generate line numbers on the left side of the output.
-
-
- <tag><tt>--linkstyle n</tt></tag>
-
- Influences the style used when generating links for imports. If n is zero
- (the default), the converter creates a link to the actual symbol if it is
- defined somewhere in the input files. If not, it creates a link to the
- <tt/.import/ statement. If n is one, the converter will always generate a
- HTML link to the <tt/.import/ statement.
-
-
- <tag><tt>--replaceext</tt></tag>
-
- Replace the file extension of the input file instead of appending <tt/.html/
- when generating the output file name.
-
-
- <tag><tt>--textcolor c</tt></tag>
-
- Set the color for normal text. The argument c must be a valid HTML color,
- usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
- the respective red, green, and blue parts as two-digit hex values. The
- default is <tt/#000000/ (black). This color is used in the <tt/<body>/
- of the generated HTML output.
-
-
- <tag><tt>--verbose</tt></tag>
-
- Increase the converter verbosity. Without this option, ca65html is quiet
- when working. If you have a slow machine and lots of files to convert, you
- might like a little bit more progress information.
-
-</descrip>
-<p>
-
-
-<sect>Peculiarities<p>
-
-<sect1>Cross links<p>
-
-Since ca65html is able to generate links between modules, the best way to use
-it is to supply all modules to it in one run, instead of running each file
-separately through it.
-
-
-<sect1>Include files<p>
-
-For now, ca65html will not read files included with <tt/.include/. Specifying
-the include files as normal input files on the command line works in many
-cases.
-
-
-<sect1>Conversion errors<p>
-
-Since ca65html does not really parse the input, but does most of its work
-applying text patterns, it doesn't know anything about scoping and advanced
-features of the assembler. This means that it might miss a label. And, it
-might choose the wrong color for an item, in rare cases. Because it's just a
-tool for displaying sources in a nice form, I think that's OK. Anyway, if you
-find a conversion problem, you can send me a short piece of example input code.
-If possible, I will fix it.
-
-
-<sect1>Colorization<p>
-
-While having colors in the output looks really nice, it has one drawback:
-
-<enum>
-
-<item>Because lots of <tt/<span>/ tags are created in the output,
-the size of the output file literally will explode. It seems to be the price
-that you have to pay for color.
-
-</enum>
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the converter, if you find any bugs, or if you're
-doing something interesting with the assembler, I would be glad to hear from
-you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the
-following conditions apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
-
-
+++ /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">
-Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org">
-<date>2006-05-22
-
-<abstract>
-An overview over the Commodore 510 runtime system as it is implemented for the
-cc65 C compiler.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Overview<p>
-
-This file contains an overview of the CBM 510 runtime system as it comes with
-the cc65 C compiler. It describes the memory layout, CBM 510 specific header
-files, available drivers, and any pitfalls specific to that platform.
-
-Please note that CBM 510 specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
-reference">. Even functions marked as "platform dependent" may be available on
-more than one platform. Please see the function reference for more
-information.
-
-In addition to the Commodore 510 (named P128 in the U.S.), no other
-machines are supported by this cc65 target.
-
-
-
-<sect>Binary format<p>
-
-The standard binary output format generated by the linker for the Commodore
-510 target is a machine language program with a one line BASIC stub, which
-transfers control to the machine language running in bank 0. This means that a
-program can be loaded as BASIC program and started with RUN. It is of course
-possible to change this behaviour by using a modified startup file and linker
-config.
-
-
-
-<sect>Memory layout<p>
-
-cc65 generated programs for the Commodore 510 run in bank 0, the memory bank
-reserved for BASIC programs. Since there are no ROMs in this memory bank,
-kernal subroutines are either emulated or called by bank switching, which has
-the disadvantage of being slow compared to a direct call.
-
-The default memory configuration for the CBM 510 allocates all memory between
-$0002 and $FFF0 in bank 0 for the compiled program. Some space
-in low memory is lost, because a separate hardware stack is set up in page 1,
-and the kernal replacement functions need some more memory locations. A few
-more pages are lost in high memory, because the runtime sets up a copy of the
-character ROM, a text screen and a CBM compatible jump table at $FF81.
-The main startup code is located at $0400, so about 54K of the complete
-bank are actually usable for applications.
-
-Special locations:
-
-<descrip>
- <tag/Stack/
- The C runtime stack is located at $FF81 and growing downwards.
-
- <tag/Heap/
- The C heap is located at the end of the program and grows towards the C
- runtime stack.
-</descrip><p>
-
-
-
-<sect>Platform specific header files<p>
-
-Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or
-<tt/cbm.h/ header files. Using the later may be an option when writing code
-for more than one CBM platform, since it includes <tt/cbm510.h/ and declares
-several functions common to all CBM platforms.
-
-<sect1>CBM 510 specific functions<p>
-
-The functions listed below are special for the CBM 510. See the <htmlurl
-url="funcref.html" name="function reference"> for declaration and usage.
-
-<itemize>
-<item>peekbsys
-<item>peekwsys
-<item>pokebsys
-<item>pokewsys
-</itemize>
-
-
-<sect1>CBM specific functions<p>
-
-Some functions are available for all (or at least most) of the Commodore
-machines. See the <htmlurl url="funcref.html" name="function reference"> for
-declaration and usage.
-
-
-<itemize>
-<item>cbm_close
-<item>cbm_closedir
-<item>cbm_k_setlfs
-<item>cbm_k_setnam
-<item>cbm_k_load
-<item>cbm_k_save
-<item>cbm_k_open
-<item>cbm_k_close
-<item>cbm_k_readst
-<item>cbm_k_chkin
-<item>cbm_k_ckout
-<item>cbm_k_basin
-<item>cbm_k_bsout
-<item>cbm_k_clrch
-<item>cbm_load
-<item>cbm_open
-<item>cbm_opendir
-<item>cbm_read
-<item>cbm_readdir
-<item>cbm_save
-<item>cbm_write
-<item>get_tv
-</itemize>
-
-
-
-<sect1>Hardware access<p>
-
-The following pseudo variables declared in the <tt/cbm510.h/ header file do
-allow access to hardware located in the address space. Some variables are
-structures, accessing the struct fields will access the chip registers.
-
-<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can
-therefore not be accessed like on other platforms. Please use one of the
-<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to
-access the I/O chips. Direct reads and writes to the structures named below
-will <em>not</em> work!
-
-<descrip>
-
- <tag><tt/VIC/</tag>
- The <tt/VIC/ structure allows access to the VIC II (the graphics
- controller). See the <tt/_vic2.h/ header file located in the include
- directory for the declaration of the structure.
-
- <tag><tt/SID/</tag>
- The <tt/SID/ structure allows access to the SID (the sound interface
- device). See the <tt/_sid.h/ header file located in the include directory
- for the declaration of the structure.
-
- <tag><tt/ACIA/</tag>
- Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable.
- See the <tt/_6551.h/ header file located in the include directory for the
- declaration of the structure.
-
- <tag><tt/CIA/</tag>
- Access to the CIA chip is available via the <tt/CIA/ variable. See the
- <tt/_6526.h/ header file located in the include directory for the
- declaration of the structure.
-
- <tag><tt/TPI1, TPI2/</tag>
- The two 6525 triport chips may be accessed by using this variable. See the
- <tt/_6525.h/ header file located in the include directory for the
- declaration of the structure.
-
-</descrip><p>
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-No graphics drivers are currently available for the Commodore 510.
-
-
-<sect1>Extended memory drivers<p>
-
-<descrip>
- <tag><tt/cbm510-ram.emd (cbm510_ram)/</tag>
- A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes
- each.
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag>
- Supports up to two standard joysticks connected to the joysticks port of
- the Commodore 510.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the Commodore 510.
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/cbm510-std.ser (cbm510_stdser)/</tag>
- Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to
- 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives.
- Note that because of the peculiarities of the 6551 chip transmits are not
- interrupt driven, and the transceiver blocks if the receiver asserts flow
- control because of a full buffer.
-
-</descrip><p>
-
-
-<sect>Limitations<label id="limitations"><p>
-
-
-<sect1>Kernal and hardware access<p>
-
-Since the program runs in bank 0, and the kernal and all I/O chips are located
-in bank 15, calling ROM routines or accessing hardware needs special code. The
-cc65 runtime implements wrappers for all functions in the kernal jump table.
-While this simplifies things, it should be noted that the wrappers do have
-quite an impact on performance: A cross bank call has an extra 300µs
-penalty added by the wrapper.
-
-<sect1>Interrupts<p>
-
-Compiled programs contain an interrupt handler that runs in the program bank.
-This has several advantages, one of them being performance (see cross bank
-call overhead mentioned above). However, this introduces one problem:
-Interrupts are lost while the CPU executes code in the kernal bank. As a
-result, the clock may go wrong and (worse) serial interrupts may get lost.
-
-Since the cc65 runtime does only call the kernal for disk I/O, this means that
-a program should not do file I/O while it depends on interrupts.
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line argument passing is currently not supported for the Commodore
-510.
-
-
-<sect1>Program return code<p>
-
-The program return code (signed char) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupt handlers<p>
-
-The runtime for the Commodore 510 uses routines marked as <tt/.INTERRUPTOR/
-for interrupt handlers. Such routines must be written as simple machine
-language subroutines and will be called automatically by the interrupt handler
-code when they are linked into a program. See the discussion of the
-<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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)/</tag>
- A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes
- each.
-</descrip><p>
-
-
-<sect1>Joystick drivers<p>
-
-The Commodore 610 is a business machine and doesn't have joystick ports. There
-are no drivers for the non existing ports available.
-
-
-
-<sect1>Mouse drivers<p>
-
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist).
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/cbm610-std.ser (cbm610_stdser)/</tag>
- Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to
- 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives.
- Note that because of the peculiarities of the 6551 chip transmits are not
- interrupt driven, and the transceiver blocks if the receiver asserts flow
- control because of a full buffer.
-
-</descrip><p>
-
-
-<sect>Limitations<label id="limitations"><p>
-
-
-<sect1>Kernal and hardware access<p>
-
-Since the program runs in bank 1, and the kernal and all I/O chips are located
-in bank 15, calling ROM routines or accessing hardware needs special code. The
-cc65 runtime implements wrappers for all functions in the kernal jump table.
-While this simplifies things, it should be noted that the wrappers do have
-quite an impact on performance: A cross bank call has an extra 300µs
-penalty added by the wrapper.
-
-<sect1>Interrupts<p>
-
-Compiled programs contain an interrupt handler that runs in the program bank.
-This has several advantages, one of them being performance (see cross bank
-call overhead mentioned above). However, this introduces one problem:
-Interrupts are lost while the CPU executes code in the kernal bank. As a
-result, the clock may go wrong and (worse) serial interrupts may get lost.
-
-Since the cc65 runtime does only call the kernal for disk I/O, this means that
-a program should not do file I/O while it depends on interrupts.
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line argument passing is currently not supported for the Commodore
-610.
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupt handlers<p>
-
-The runtime for the Commodore 610 uses routines marked as <tt/.INTERRUPTOR/
-for interrupt handlers. Such routines must be written as simple machine
-language subroutines and will be called automatically by the interrupt handler
-code when they are linked into a program. See the discussion of the
-<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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
- --forget-inc-paths Forget include search paths
- --help Help (this text)
- --include-dir dir Set an include directory search path
- --list-opt-steps List all optimizer steps and exit
- --list-warnings List available warning types for -W
- --local-strings Emit string literals immediately
- --memory-model model Set the memory model
- --register-space b Set space available for register variables
- --register-vars Enable register variables
- --rodata-name seg Set the name of the RODATA segment
- --signed-chars Default characters are signed
- --standard std Language standard (c89, c99, cc65)
- --static-locals Make local variables static
- --target sys Set the target system
- --verbose Increase verbosity
- --version Print the compiler version number
- --writable-strings Make string literals writable
----------------------------------------------------------------------------
-</verb></tscreen>
-
-
-<sect1>Command line options in detail<p>
-
-Here is a description of all the command line options:
-
-<descrip>
-
- <label id="option-bss-name">
- <tag><tt>--bss-name seg</tt></tag>
-
- Set the name of the bss segment. See also <tt/<ref id="pragma-bss-name"
- name="#pragma bss-name">/.
-
-
- <label id="option-check-stack">
- <tag><tt>--check-stack</tt></tag>
-
- Tells the compiler to generate code that checks for stack overflows. See
- <tt/<ref id="pragma-check-stack" name="#pragma check-stack">/ for an
- explanation of this feature.
-
-
- <label id="option-code-name">
- <tag><tt>--code-name seg</tt></tag>
-
- Set the name of the code segment. See also <tt/<ref id="pragma-code-name"
- name="#pragma code-name">/
-
-
- <label id="option-codesize">
- <tag><tt>--codesize x</tt></tag>
-
- This options allows finer control about speed vs. size decisions in the code
- generation and optimization phases. It gives the allowed size increase
- factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when
- using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/-O --codesize 200/).
-
-
- <label id="option--cpu">
- <tag><tt>--cpu CPU</tt></tag>
-
- Set the CPU, the compiler generates code for. You may specify "6502" or
- "65C02" as the CPU. The default depends on the selected target (see option
- <tt/<ref id="option-t" name="-t">/). It is the 6502 CPU for most targets or
- if no target has been set. Specifying 65C02 will use a few 65C02
- instructions when generating code. Don't expect too much from this option:
- In most cases the difference in size and speed is just 1-2%.
-
-
- <label id="option-create-dep">
- <tag><tt>--create-dep name</tt></tag>
-
- Tells the compiler to generate a file containing the dependency list for the
- compiled module in makefile syntax. The output is written to a file with the
- given name. The output does not include system include files (in angle
- brackets).
-
-
- <label id="option-create-full-dep">
- <tag><tt>--create-full-dep name</tt></tag>
-
- Tells the compiler to generate a file containing the dependency list for the
- compiled module in makefile syntax. The output is written to a file with the
- given name. The output does include system include files (in angle
- brackets).
-
-
- <label id="option-data-name">
- <tag><tt>--data-name seg</tt></tag>
-
- Set the name of the data segment. See also <tt/<ref id="pragma-data-name"
- name="#pragma data-name">/
-
-
- <tag><tt>-d, --debug</tt></tag>
-
- Enables debug mode, something that should not be needed for mere
- mortals:-)
-
-
- <label id="option-dep-target">
- <tag><tt>--dep-target target</tt></tag>
-
- When generating a dependency file, don't use the actual output file as the
- target of the dependency, but the file specified with this option. The
- option has no effect if neither <tt/<ref id="option-create-dep"
- name="--create-dep">/ nor <tt/<ref id="option-create-full-dep"
- name="--create-full-dep">/ is specified.
-
-
- <tag><tt>-D sym[=definition]</tt></tag>
-
- Define a macro on the command line. If no definition is given, the macro
- is defined to the value "1".
-
-
- <tag><tt>--forget-inc-paths</tt></tag>
-
- Forget the builtin include paths. This is most useful when building
- customized C or runtime libraries, in which case the standard header
- files should be ignored.
-
-
- <tag><tt>-g, --debug-info</tt></tag>
-
- This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the
- generated assembler code. This will cause the assembler to include all
- symbols in a special section in the object file.
-
-
- <tag><tt>-h, --help</tt></tag>
-
- Print the short option summary shown above.
-
-
- <label id="option-list-warnings">
- <tag><tt>--list-warnings</tt></tag>
-
- List the names of warning types available for use with <tt><ref
- id="option-W" name="-W"></tt>.
-
-
- <label id="option-local-strings">
- <tag><tt>--local-strings</tt></tag>
-
- Emit string literals into the rodata segment as soon as they're encountered
- in the source (even if you do nothing but get the sizeof those strings). The
- default is to keep string literals until end of assembly, merge read only
- literals if possible, and then output the literals into the data or rodata
- segment that is active at that point. Use of this option prevents merging of
- duplicate strings, but the options that change the name of one of the data
- segments will work.
-
- You can also use <tt><ref id="pragma-local-strings"
- name="#pragma local-strings"></tt> for fine grained control.
-
-
- <tag><tt>-o name</tt></tag>
-
- Specify the name of the output file. If you don't specify a name, the
- name of the C input file is used, with the extension replaced by ".s".
-
-
- <label id="option-register-vars">
- <tag><tt>-r, --register-vars</tt></tag>
-
- <tt/-r/ will make the compiler honor the <tt/register/ keyword. Local
- variables may be placed in registers (which are actually zero page
- locations). There is some overhead involved with register variables, since
- the old contents of the registers must be saved and restored. Since register
- variables are of limited use without the optimizer, there is also a combined
- switch: <tt/-Or/ will enable both, the optimizer and register variables.
-
- For more information about register variables see <ref id="register-vars"
- name="register variables">.
-
- The compiler setting can also be changed within the source file by using
- <tt/<ref id="pragma-register-vars" name="#pragma register-vars">/.
-
-
- <label id="option-register-space">
- <tag><tt>--register-space</tt></tag>
-
- This option takes a numeric parameter and is used to specify, how much
- zero page register space is available. Please note that just giving this
- option will not increase or decrease by itself, it will just tell the
- compiler about the available space. You will have to allocate that space
- yourself using an assembler module with the necessary allocations, and a
- linker configuration that matches the assembler module. The default value
- for this option is 6 (bytes).
-
- If you don't know what all this means, please don't use this option.
-
-
- <label id="option-rodata-name">
- <tag><tt>--rodata-name seg</tt></tag>
-
- Set the name of the rodata segment (the segment used for readonly data).
- See also <tt/<ref id="pragma-rodata-name" name="#pragma rodata-name">/
-
- <label id="option-signed-chars">
- <tag><tt>-j, --signed-chars</tt></tag>
-
- Using this option, you can make the default characters signed. Since the
- 6502 has no provisions for sign extending characters (which is needed on
- almost any load operation), this will make the code larger and slower. A
- better way is to declare characters explicitly as "signed" if needed. You
- can also use <tt><ref id="pragma-signed-chars"
- name="#pragma signed-chars"></tt> for better control of this option.
-
-
- <label id="option--standard">
- <tag><tt>--standard std</tt></tag>
-
- This option allows to set the language standard supported. The argument is
- one of
- <descrip>
- <tag/c89/
- This disables anything that is illegal in C89/C90. Among those things
- are <tt>//</tt> comments and the non-standard keywords without
- underscores. Please note that cc65 is not a fully C89 compliant compiler
- despite this option. A few more things (like floats) are missing.
-
- <tag/c99/
- This enables a few features from the C99 standard. With this option,
- <tt>//</tt> comments are allowed. It will also cause warnings and even
- errors in a few situations that are allowed with <tt/--standard c89/.
- For example, a call to a function without a prototype is an error in
- this mode.
-
- <tag/cc65/
- This is the default mode. It is like c99 mode, but additional features
- are enabled. Among these are "void data", non-standard keywords without
- the underlines, unnamed function parameters and the requirement for
- main() to return an int.
- </descrip>
-
- Please note that the compiler does not support the C99 standard and never
- will. c99 mode is actually c89 mode with a few selected C99 extensions.
-
-
- <label id="option-t">
- <tag><tt>-t target, --target target</tt></tag>
-
- This option is used to set the target system. The target system determines
- the character set that is used for strings and character constants and the
- default CPU. The CPU setting can be overriden by use of the <tt/<ref
- id="option--cpu" name="--cpu">/ option.
-
- The following target systems are supported:
-
- <itemize>
- <item>none
- <item>apple2
- <item>apple2enh
- <item>atari
- <item>atmos
- <item>c16 (works also for the c116 with memory up to 32K)
- <item>c64
- <item>c128
- <item>cbm510 (CBM-II series with 40 column video)
- <item>cbm610 (all CBM-II II computers with 80 column video)
- <item>geos-apple
- <item>geos-cbm
- <item>lunix
- <item>lynx
- <item>nes
- <item>pet (all CBM PET systems except the 2001)
- <item>plus4
- <item>supervision
- <item>vic20
- </itemize>
-
- <tag><tt>-v, --verbose</tt></tag>
-
- Using this option, the compiler will be somewhat more verbose if errors
- or warnings are encountered.
-
-
- <label id="option-writable-strings">
- <tag><tt>--writable-strings</tt></tag>
-
- Make string literals writable by placing them into the data segment instead
- of the rodata segment. You can also use <tt><ref id="pragma-writable-strings"
- name="#pragma writable-strings"></tt> to control this option from within
- the source file.
-
-
- <label id="option-static-locals">
- <tag><tt>-Cl, --static-locals</tt></tag>
-
- Use static storage for local variables instead of storage on the stack.
- Since the stack is emulated in software, this gives shorter and usually
- faster code, but the code is no longer reentrant. The difference between
- <tt/-Cl/ and declaring local variables as static yourself is, that
- initializer code is executed each time, the function is entered. So when
- using
-
- <tscreen><verb>
- void f (void)
- {
- unsigned a = 1;
- ...
- }
- </verb></tscreen>
-
- the variable <tt/a/ will always have the value <tt/1/ when entering the
- function and using <tt/-Cl/, while in
-
- <tscreen><verb>
- void f (void)
- {
- static unsigned a = 1;
- ....
- }
- </verb></tscreen>
-
- the variable <tt/a/ will have the value <tt/1/ only the first time that the
- function is entered, and will keep the old value from one call of the
- function to the next.
-
- You may also use <tt><ref id="pragma-static-locals"
- name="#pragma static-locals"></tt> to change this setting in your
- sources.
-
-
- <label id="option-include-dir">
- <tag><tt>-I dir, --include-dir dir</tt></tag>
-
- Set a directory where the compiler searches for include files. You may
- use this option multiple times to add more than one directory to the
- search list.
-
-
- <label id="option-O">
- <tag><tt>-O, -Oi, -Or, -Os</tt></tag>
-
- Enable an optimizer run over the produced code.
-
- Using <tt/-Oi/, the code generator will inline some code where otherwise a
- runtime functions would have been called, even if the generated code is
- larger. This will not only remove the overhead for a function call, but will
- make the code visible for the optimizer. <tt/-Oi/ is an alias for
- <tt/-O --codesize 200/.
-
- <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local
- variables may be placed in registers (which are actually zero page
- locations). See also the <tt/<ref id="option-register-vars"
- name="--register-vars">/ command line option, and the <ref
- id="register-vars" name="discussion of register variables"> below.
-
- Using <tt/-Os/ will force the compiler to inline some known functions from
- the C library like strlen. Note: This has two consequences:
- <p>
- <itemize>
- <item>You may not use names of standard C functions in your own code. If you
- do that, your program is not standard compliant anyway, but using
- <tt/-Os/ will actually break things.
- <p>
- <item>The inlined string and memory functions will not handle strings or
- memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/
- functions will not work with values outside the char. range (such as
- <tt/EOF/).
- <p>
- </itemize>
- <p>
- It is possible to concatenate the modifiers for <tt/-O/. For example, to
- enable register variables and inlining of known functions, you may use
- <tt/-Ors/.
-
-
- <tag><tt>-T, --add-source</tt></tag>
-
- This include the source code as comments in the generated code. This is
- normally not needed.
-
-
- <tag><tt>-V, --version</tt></tag>
-
- Print the version number of the compiler. When submitting a bug report,
- please include the operating system you're using, and the compiler
- version.
-
-
- <label id="option-W">
- <tag><tt>-W name[,name]</tt></tag>
-
- This option allows to control warnings generated by the compiler. It is
- followed by a comma separated list of warnings that should be enabled or
- disabled. To disable a warning, its name is prefixed by a minus sign. If
- no such prefix exists, or the name is prefixed by a plus sign, the warning
- is enabled.
-
- The following warning names are currently recognized:
- <descrip>
- <tag><tt/const-comparison/</tag>
- Warn if the result of a comparison is constant.
- <tag><tt/error/</tag>
- Treat all warnings as errors.
- <tag><tt/no-effect/</tag>
- Warn about statements that don't have an effect.
- <tag><tt/struct-param/</tag>
- Warn when passing structs by value.
- <tag><tt/unknown-pragma/</tag>
- Warn about known #pragmas.
- <tag><tt/unused-label/</tag>
- Warn about unused labels.
- <tag><tt/unused-param/</tag>
- Warn about unused function parameters.
- <tag><tt/unused-var/</tag>
- Warn about unused variables.
- </descrip>
-
- The full list of available warning names may be retrieved by using the
- option <tt><ref id="option-list-warnings" name="--list-warnings"></tt>.
-
- You may also use <tt><ref id="pragma-warn" name="#pragma warn"></tt> to
- control this setting for smaller pieces of code from within your code.
-
-</descrip><p>
-
-
-<sect>Input and output<p>
-
-The compiler will accept one C file per invocation and create a file with
-the same base name, but with the extension replaced by ".s". The output
-file contains assembler code suitable for the use with the ca65 macro
-assembler.
-
-Include files in single quotes are searched in the following places:
-<enum>
-<item>The current directory.
-<item>The value of the environment variable <tt/CC65_INC/ if it is defined.
-<item>Any directory added with the <tt/-I/ option on the command line.
-</enum>
-
-Include files in angle brackets are searched in the following places:
-<enum>
-<item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on
- Linux systems.
-<item>The value of the environment variable <tt/CC65_INC/ if it is defined.
-<item>A subdirectory named <tt/include/ of the directory defined in the
- environment variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt/-I/ option on the command line.
-</enum>
-
-
-
-<sect>Differences to the ISO standard<p>
-
-Apart from the things listed below, the compiler does support additional
-keywords, has several functions in the standard headers with names outside the
-reserved namespace and a few syntax extensions. All these can be disabled with
-the <tt><ref id="option--standard" name="--standard"></tt> command line
-option. Its use for maximum standards compatibility is advised.
-
-Here is a list of differences between the language, the compiler accepts,
-and the one defined by the ISO standard:
-
-<itemize>
-
-<item> The datatypes "float" and "double" are not available.
- <p>
-<item> C Functions may not return structs (or unions), and structs may not
- be passed as parameters by value. However, struct assignment *is*
- possible.
- <p>
-<item> Part of the C library is available only with fastcall calling
- conventions (see below). It means that you must not mix pointers to
- those functions with pointers to user-written, not-fastcall functions.
- <p>
-<item> The <tt/volatile/ keyword doesn't have an effect. This is not as bad
- as it sounds, since the 6502 has so few registers that it isn't
- possible to keep values in registers anyway.
- <p>
-</itemize>
-
-There may be some more minor differences I'm currently not aware of. The
-biggest problem is the missing float data type. With this limitation in
-mind, you should be able to write fairly portable code.
-
-
-
-<sect>Extensions<p>
-
-This cc65 version has some extensions to the ISO C standard.
-
-<itemize>
-
-<item> The compiler allows to insert assembler statements into the output
- file. The syntax is
-
- <tscreen><verb>
- asm (<string literal>[, optional parameters]) ;
- </verb></tscreen>
- or
- <tscreen><verb>
- __asm__ (<string literal>[, optional parameters]) ;
- </verb></tscreen>
-
- The first form is in the user namespace and is disabled if the <tt/-A/
- switch is given.
-
- There is a whole section covering inline assembler statements,
- <ref id="inline-asm" name="see there">.
- <p>
-
-<item> There is a special calling convention named "fastcall".
- The syntax for a function declaration using fastcall is
-
- <tscreen><verb>
- <return type> fastcall <function name> (<parameter list>)
- </verb></tscreen>
- or
- <tscreen><verb>
- <return type> __fastcall__ <function name> (<parameter list>)
- </verb></tscreen>
- An example would be
- <tscreen><verb>
- void __fastcall__ f (unsigned char c)
- </verb></tscreen>
- The first form of the fastcall keyword is in the user namespace and can
- therefore be disabled with the <tt><ref id="option--standard"
- name="--standard"></tt> command line option.
-
- For functions declared as <tt/fastcall/, the rightmost parameter is not
- pushed on the stack but left in the primary register when the function
- is called. This will reduce the cost when calling assembler functions
- significantly, especially when the function itself is rather small.
- <p>
-
-<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
- Both refer to the primary register that is used by the compiler to
- evaluate expressions or return function results. <tt/__AX__/ is of
- type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
- respectively. The pseudo variables may be used as lvalue and rvalue as
- every other variable. They are most useful together with short
- sequences of assembler code. For example, the macro
-
- <tscreen><verb>
- #define hi(x) \
- (__AX__ = (x), \
- asm ("txa"), \
- asm ("ldx #$00"), \
- __AX__)
- </verb></tscreen>
-
- will give the high byte of any unsigned value.
- <p>
-
-<item> Inside a function, the identifier <tt/__func__/ gives the name of the
- current function as a string. Outside of functions, <tt/__func__/ is
- undefined.
- Example:
-
- <tscreen><verb>
- #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
- </verb></tscreen>
-
- The macro will print the name of the current function plus a given
- string.
- <p>
-
-<item> cc65 allows the initialization of <tt/void/ variables. This may be
- used to create variable structures that are more compatible with
- interfaces written for assembler languages. Here is an example:
-
- <tscreen><verb>
- void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 };
- </verb></tscreen>
-
- This will be translated as follows:
-
- <tscreen><verb>
- _GCmd:
- .byte 3
- .word $2000
- .word $3000
- </verb></tscreen>
-
- Since the variable is of type <tt/void/ you may not use it as is.
- However, taking the address of the variable results in a <tt/void*/
- which may be passed to any function expecting a pointer.
-
- See the <url url="geos.html" name="GEOS library document"> for examples
- on how to use this feature.
- <p>
-
-<item> cc65 implements flexible array struct members as defined in the C99 ISO
- standard. As an extension, these fields may be initialized. There are
- several exceptions, however (which is probably the reason why the
- standard does not define this feature, because it is highly
- unorthogonal). Flexible array members cannot be initialized ...
-
- <itemize>
- <item>... when defining an array of structs with flexible
- members.
- <item>... if such a struct is a member field of another struct
- which is not the last field.
- <item>... if the struct which contains a flexible array member is
- declared as <tt/register/, and the size and compiler settings
- do allow the compiler actually to place the struct into the
- register bank in the zero page.
- </itemize>
-
- Please note that -- as defined in the ISO C standard -- the <tt/sizeof/
- operator returns the struct size with the flexible array member having
- size zero, even if it is initialized.
- <p>
-
-</itemize>
-<p>
-
-
-<sect>Predefined macros<p>
-
-The compiler defines several macros at startup:
-
-<descrip>
- <tag><tt>__APPLE2__</tt></tag>
-
- This macro is defined if the target is the Apple ][ (-t apple2).
-
- <tag><tt>__APPLE2ENH__</tt></tag>
-
- This macro is defined if the target is the enhanced Apple //e (-t apple2enh).
-
- <tag><tt>__ATARI__</tt></tag>
-
- This macro is defined if the target is one of the Atari computers
- (400/800/130XL/800XL).
-
- <tag><tt>__ATMOS__</tt></tag>
-
- This macro is defined if the target is the Oric Atmos (-t atmos).
-
- <tag><tt>__C128__</tt></tag>
-
- This macro is defined if the target is the c128 (-t c128).
-
- <tag><tt>__C16__</tt></tag>
-
- This macro is defined if the target is the c16 (-t c16).
-
- <tag><tt>__C64__</tt></tag>
-
- This macro is defined if the target is the c64 (-t c64).
-
- <tag><tt>__CBM__</tt></tag>
-
- This macro is defined if the target system is one of the CBM targets.
-
- <tag><tt>__CBM510__</tt></tag>
-
- This macro is defined if the target is the CBM 500 series of computers.
-
- <tag><tt>__CBM610__</tt></tag>
-
- This macro is defined if the target is one of the CBM 600/700 family of
- computers (called B series in the US).
-
- <tag><tt>__CC65__</tt></tag>
-
- This macro is always defined. Its value is the version number of the
- compiler in hex. For example, version 2.10.1 of the compiler has this macro
- defined as <tt/0x02A1/.
-
- <tag><tt>__CC65_STD__</tt></tag>
-
- This macro is defined to one of the following depending on the <tt><ref
- id="option--standard" name="--standard"></tt> command line option:
- <itemize>
- <item><tt/__CC65_STD_C89__/
- <item><tt/__CC65_STD_C99__/
- <item><tt/__CC65_STD_CC65__/
- </itemize>
-
- <tag><tt>__DATE__</tt></tag>
-
- This macro expands to the date of translation of the preprocessing
- translation unit in the form "Mmm dd yyyy".
-
- <tag><tt>__FILE__</tt></tag>
-
- This macro expands to a string containing the name of the C source file.
-
- <tag><tt>__GEOS__</tt></tag>
-
- This macro is defined if you are compiling for the GEOS system (-t geos).
-
- <tag><tt>__LINE__</tt></tag>
-
- This macro expands to the current line number.
-
- <tag><tt>__LUNIX__</tt></tag>
-
- This macro is defined if you are compiling for the LUnix system (-t lunix).
-
- <tag><tt>__LYNX__</tt></tag>
-
- This macro is defined if the target is the Atari Lynx (-t lynx).
-
- <tag><tt>__NES__</tt></tag>
-
- This macro is defined if the target is the NES (-t nes).
-
- <tag><tt>__OPT__</tt></tag>
-
- Is defined if the compiler was called with the <tt/-O/ command line option.
-
- <tag><tt>__OPT_i__</tt></tag>
-
- Is defined if the compiler was called with the <tt/-Oi/ command line option.
-
- <tag><tt>__OPT_r__</tt></tag>
-
- Is defined if the compiler was called with the <tt/-Or/ command line option.
-
- <tag><tt>__OPT_s__</tt></tag>
-
- Is defined if the compiler was called with the <tt/-Os/ command line option.
-
- <tag><tt>__PET__</tt></tag>
-
- This macro is defined if the target is the PET family of computers (-t pet).
-
- <tag><tt>__PLUS4__</tt></tag>
-
- This macro is defined if the target is the plus/4 (-t plus4).
-
- <tag><tt>__STDC_HOSTED__</tt></tag>
-
- This macro is expands to the integer constant 1.
-
- <tag><tt>__SUPERVISION__</tt></tag>
-
- This macro is defined if the target is the supervision (-t supervision).
-
- <tag><tt>__TIME__</tt></tag>
-
- This macro expands to the time of translation of the preprocessing
- translation unit in the form "hh:mm:ss".
-
- <tag><tt>__VIC20__</tt></tag>
-
- This macro is defined if the target is the vic20 (-t vic20).
-</descrip>
-
-
-<sect>#pragmas<label id="pragmas"><p>
-
-The compiler understands some pragmas that may be used to change code
-generation and other stuff. Some of these pragmas understand a special form:
-If the first parameter is <tt/push/, the old value is saved onto a stack
-before changing it. The value may later be restored by using the <tt/pop/
-parameter with the <tt/#pragma/.
-
-<sect1><tt>#pragma bss-name ([push,] <name>)</tt><label id="pragma-bss-name"><p>
-
- This pragma changes the name used for the BSS segment (the BSS segment
- is used to store uninitialized data). The argument is a string enclosed
- in double quotes.
-
- Note: The default linker configuration file does only map the standard
- segments. If you use other segments, you have to create a new linker
- configuration file.
-
- Beware: The startup code will zero only the default BSS segment. If you
- use another BSS segment, you have to do that yourself, otherwise
- uninitialized variables do not have the value zero.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
- Example:
- <tscreen><verb>
- #pragma bss-name ("MyBSS")
- </verb></tscreen>
-
-
-<sect1><tt>#pragma charmap (<index>, <code>)</tt><label id="pragma-charmap"><p>
-
- Each literal string and each literal character in the source is translated
- by use of a translation table. This translation table is preset when the
- compiler is started depending on the target system, for example to map
- ISO-8859-1 characters into PETSCII if the target is a commodore machine.
-
- This pragma allows to change entries in the translation table, so the
- translation for individual characters, or even the complete table may be
- adjusted.
-
- Both arguments are assumed to be unsigned characters with a valid range of
- 1-255.
-
- Beware of two pitfalls:
-
- <itemize>
- <item>The character index is actually the code of the character in the
- C source, so character mappings do always depend on the source
- character set. This means that <tt/#pragma charmap/ is not
- portable -- it depends on the build environment.
- <item>While it is possible to use character literals as indices, the
- result may be somewhat unexpected, since character literals are
- itself translated. For this reason I would suggest to avoid
- character literals and use numeric character codes instead.
- </itemize>
-
- Example:
- <tscreen><verb>
- /* Use a space wherever an 'a' occurs in ISO-8859-1 source */
- #pragma charmap (0x61, 0x20);
- </verb></tscreen>
-
-
-<sect1><tt>#pragma check-stack ([push,] on|off)</tt><label id="pragma-check-stack"><p>
-
- Tells the compiler to insert calls to a stack checking subroutine to detect
- stack overflows. The stack checking code will lead to somewhat larger and
- slower programs, so you may want to use this pragma when debugging your
- program and switch it off for the release version. If a stack overflow is
- detected, the program is aborted.
-
- If the argument is "off", stack checks are disabled (the default), otherwise
- they're enabled.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-<sect1><tt>#pragma code-name ([push,] <name>)</tt><label id="pragma-code-name"><p>
-
- This pragma changes the name used for the CODE segment (the CODE segment
- is used to store executable code). The argument is a string enclosed in
- double quotes.
-
- Note: The default linker configuration file does only map the standard
- segments. If you use other segments, you have to create a new linker
- configuration file.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
- Example:
- <tscreen><verb>
- #pragma code-name ("MyCODE")
- </verb></tscreen>
-
-
-<sect1><tt>#pragma codesize ([push,] <int>)</tt><label id="pragma-codesize"><p>
-
- This pragma allows finer control about speed vs. size decisions in the code
- generation and optimization phase. It gives the allowed size increase factor
- (in percent). The default is can be changed by use of the <tt/<ref
- id="option-codesize" name="--codesize">/ compiler option.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma data-name ([push,] <name>)</tt><label id="pragma-data-name"><p>
-
- This pragma changes the name used for the DATA segment (the DATA segment
- is used to store initialized data). The argument is a string enclosed in
- double quotes.
-
- Note: The default linker configuration file does only map the standard
- segments. If you use other segments, you have to create a new linker
- configuration file.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
- Example:
- <tscreen><verb>
- #pragma data-name ("MyDATA")
- </verb></tscreen>
-
-
-<sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p>
-
- When "on", emit string literals to the data segment when they're encountered
- in the source. The default ("off") is to keep string literals until end of
- assembly, merge read only literals if possible, and then output the literals
- into the data or rodata segment that is active at that point.
-
- Using this <tt/#pragma/ it is possible to control the behaviour from within
- the source. When <tt/#pragma local-strings/ is active, string literals are
- output immediately, which means that they go into the currently active data
- or rodata segment, but cannot be merged. When inactive, string literals are
- remembered and output as a whole when translation is finished.
-
-
-<sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p>
-
- Switch optimization on or off. If the argument is "off", optimization is
- disabled, otherwise it is enabled. Please note that this pragma only effects
- whole functions. The setting in effect when the function is encountered will
- determine if the generated code is optimized or not.
-
- Optimization and code generation is also controlled by the <ref
- id="pragma-codesize" name="codesize pragma">.
-
- The default is "off", but may be changed with the <tt/<ref name="-O"
- id="option-O">/ compiler option.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma rodata-name ([push,] <name>)</tt><label id="pragma-rodata-name"><p>
-
- This pragma changes the name used for the RODATA segment (the RODATA
- segment is used to store readonly data). The argument is a string
- enclosed in double quotes.
-
- Note: The default linker configuration file does only map the standard
- segments. If you use other segments, you have to create a new linker
- configuration file.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
- Example:
- <tscreen><verb>
- #pragma rodata-name ("MyRODATA")
- </verb></tscreen>
-
-
-<sect1><tt>#pragma regvaraddr ([push,] on|off)</tt><label id="pragma-regvaraddr"><p>
-
- The compiler does not allow to take the address of register variables.
- The regvaraddr pragma changes this. Taking the address of a register
- variable is allowed after using this pragma with "on" as argument.
- Using "off" as an argument switches back to the default behaviour.
-
- Beware: The C standard does not allow taking the address of a variable
- declared as register. So your programs become non-portable if you use
- this pragma. In addition, your program may not work. This is usually the
- case if a subroutine is called with the address of a register variable,
- and this subroutine (or a subroutine called from there) uses
- register variables. So be careful with this #pragma.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
- Example:
- <tscreen><verb>
- #pragma regvaraddr(on) /* Allow taking the address
- * of register variables
- */
- </verb></tscreen>
-
-
-<sect1><tt>#pragma register-vars ([push,] on|off)</tt><label id="pragma-register-vars"><p>
-
- Enables or disables use of register variables. If register variables are
- disabled (the default), the <tt/register/ keyword is ignored. Register
- variables are explained in more detail in <ref id="register-vars" name="a separate
- chapter">.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma signed-chars ([push,] on|off)</tt><label id="pragma-signed-chars"><p>
-
- Changes the signedness of the default character type. If the argument is
- "on", default characters are signed, otherwise characters are unsigned. The
- compiler default is to make characters unsigned since this creates a lot
- better code. This default may be overridden by the <tt/<ref
- name="--signed-chars" id="option-signed-chars">/ command line option.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma static-locals ([push,] on|off)</tt><label id="pragma-static-locals"<p>
-
- Use variables in the bss segment instead of variables on the stack. This
- pragma changes the default set by the compiler option <tt/<ref
- name="--static-locals" id="option-static-locals">/. If the argument is "on",
- local variables are allocated in the BSS segment, leading to shorter and in
- most cases faster, but non-reentrant code.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma warn (name, [push,] on|off)</tt><label id="pragma-warn"><p>
-
- Switch compiler warnings on or off. "name" is the name of a warning (see the
- <tt/<ref name="-W" id="option-W">/ compiler option for a list). The name is
- either followed by "pop", which restores the last pushed state, or by "on" or
- "off", optionally preceeded by "push" to push the current state before
- changing it.
-
- Example:
- <tscreen><verb>
- /* Don't warn about the unused parameter in function func */
- #pragma warn (unused-param, push, off)
- static int func (int unused)
- {
- return 0;
- }
- #pragma warn (unused-param, pop)
- </verb></tscreen>
-
-<sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p>
-
- Changes the storage location of string literals. For historical reasons,
- the C standard defines that string literals are of type "char[]", but
- writing to such a literal causes undefined behaviour. Most compilers
- (including cc65) place string literals in the read-only data segment, which
- may cause problems with old C code that writes to string literals.
-
- Using this pragma (or the corresponding command line option <tt/<ref
- name="--writable-strings" id="option-writable-strings">/) causes the
- literals to be placed in the data segment so they can be written to without
- worry.
-
- The <tt/#pragma/ understands the push and pop parameters as explained above.
-
-
-<sect1><tt>#pragma zpsym (<name>)</tt><p>
-
- Tell the compiler that the -- previously as external declared -- symbol with
- the given name is a zero page symbol (usually from an assembler file).
- The compiler will create a matching import declaration for the assembler.
-
- Example:
- <tscreen><verb>
- extern int foo;
- #pragma zpsym ("foo"); /* foo is in the zeropage */
- </verb></tscreen>
-
-
-
-
-<sect>Register variables<label id="register-vars"><p>
-
-The runtime for all supported platforms has 6 bytes of zero page space
-available for register variables (this could be increased, but I think it's a
-good value). So you can declare register variables up to a total size of 6 per
-function. The compiler will allocate register space on a "first come, first
-served" base and convert any <tt/register/ declarations that exceed the
-available register space silently to <tt/auto/. Parameters can also be
-declared as <tt/register/, this will in fact give slightly shorter code than
-using a register variable.
-
-Since a function must save the current values of the registers on entry and
-restore them on exit, there is an overhead associated with register variables,
-and this overhead is quite high (about 20 bytes per variable). This means that
-just declaring anything as <tt/register/ is not a good idea.
-
-The best use for register variables are pointers, especially those that point
-to structures. The magic number here is about 3 uses of a struct field: If the
-function contains this number or even more, the generated code will be usually
-shorter and faster when using a register variable for the struct pointer. The
-reason for this is that the register variable can in many cases be used as a
-pointer directly. Having a pointer in an auto variable means that this pointer
-must first be copied into a zero page location, before it can be dereferenced.
-
-Second best use for register variables are counters. However, there is not
-much difference in the code generated for counters, so you will need at least
-100 operations on this variable (for example in a loop) to make it worth the
-trouble. The only savings you get here are by the use of a zero page variable
-instead of one on the stack or in the data segment.
-
-Register variables must be explicitly enabled, either by using <tt/<ref
-name="-Or" id="option-O">/ or <tt/<ref name="--register-vars"
-id="option-register-vars">/ on the command line or by use of <tt/<ref
-name="#pragma register-vars" id="pragma-register-vars">/. Register variables
-are only accepted on function top level, register variables declared in
-interior blocks are silently converted to <tt/auto/. With register variables
-disabled, all variables declared as <tt/register/ are actually auto variables.
-
-Please take care when using register variables: While they are helpful and can
-lead to a tremendous speedup when used correctly, improper usage will cause
-bloated code and a slowdown.
-
-
-
-<sect>Inline assembler<label id="inline-asm"><p>
-
-The compiler allows to insert assembler statements into the output file. The
-syntax is
-
-<tscreen><verb>
- asm (<string literal>[, optional parameters]) ;
-</verb></tscreen>
-or
-<tscreen><verb>
- __asm__ (<string literal>[, optional parameters]) ;
-</verb></tscreen>
-<p>
-
-The first form is in the user namespace and is disabled by <tt><ref
-id="option--standard" name="--standard"></tt> if the argument is not <tt/cc65/.
-
-The asm statement may be used inside a function and on global file level. An
-inline assembler statement is a primary expression, so it may also be used as
-part of an expression. Please note however that the result of an expression
-containing just an inline assembler statement is always of type <tt/void/.
-
-The contents of the string literal are preparsed by the compiler and inserted
-into the generated assembly output, so that the can be further processed by
-the backend and especially the optimizer. For this reason, the compiler does
-only allow regular 6502 opcodes to be used with the inline assembler. Pseudo
-instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed,
-even if the ca65 assembler (which is used to translate the generated assembler
-code) would accept them. The builtin inline assembler is not a replacement for
-the full blown macro assembler which comes with the compiler.
-
-Note: Inline assembler statements are subject to all optimizations done by the
-compiler. There is currently no way to protect an inline assembler statement
-from being moved or removed completely by the optimizer. If in doubt, check
-the generated assembler output, or disable optimizations.
-
-The string literal may contain format specifiers from the following list. For
-each format specifier, an argument is expected which is inserted instead of
-the format specifier before passing the assembly code line to the backend.
-
-<itemize>
- <item><tt/%b/ - Numerical 8-bit value
- <item><tt/%w/ - Numerical 16-bit value
- <item><tt/%l/ - Numerical 32-bit value
- <item><tt/%v/ - Assembler name of a global variable or function
- <item><tt/%o/ - Stack offset of a local variable
- <item><tt/%g/ - Assembler name of a C label
- <item><tt/%s/ - The argument is converted to a string
- <item><tt/%%/ - The % sign itself
-</itemize><p>
-
-Using these format specifiers, you can access C <tt/#defines/, variables or
-similar stuff from the inline assembler. For example, to load the value of
-a C <tt/#define/ into the Y register, one would use
-
-<tscreen><verb>
- #define OFFS 23
- __asm__ ("ldy #%b", OFFS);
-</verb></tscreen>
-
-Or, to access a struct member of a static variable:
-
-<tscreen><verb>
- typedef struct {
- unsigned char x;
- unsigned char y;
- unsigned char color;
- } pixel_t;
- static pixel_t pixel;
- __asm__ ("ldy #%b", offsetof(pixel_t, color));
- __asm__ ("lda %v,y", pixel);
-</verb></tscreen>
-<p>
-The next example shows how to use global variables to exchange data between C
-an assembler and how to handle assembler jumps:
-
-<tscreen><verb>
- unsigned char globalSubA, globalSubB, globalSubResult;
-
- /* return a-b, return 255 if b>a */
- unsigned char sub (unsigned char a, unsigned char b)
- {
- globalSubA = a;
- globalSubB = b;
- __asm__ ("sec");
- __asm__ ("lda %v", globalSubA);
- __asm__ ("sbc %v", globalSubB);
- __asm__ ("bcs %g", jumpSubNoError);
- __asm__ ("lda #$FF");
- jumpSubNoError:
- __asm__ ("sta %v", globalSubResult);
- return globalSubResult;
- }
-</verb></tscreen>
-<p>
-
-Arrays can also be accessed:
-
-<tscreen><verb>
- unsigned char globalSquareTable[] = {
- 0, 1, 4, 9, 16, 25, 36, 49, 64, 81,
- 100, 121, 144, 169, 196, 225
- };
- unsigned char globalSquareA, globalSquareResult;
-
- /* return a*a for a<16, else 255 */
- unsigned char square (unsigned char a)
- {
- if (a>15){
- return 255;
- }
- globalSquareA = a;
- __asm__ ("ldx %v", globalSquareA);
- __asm__ ("lda %v,x", globalSquareTable);
- __asm__ ("sta %v", globalSquareResult);
- return globalSquareResult;
- }
-</verb></tscreen>
-<p>
-
-Note: Do not embed the assembler labels that are used as names of global
-variables or functions into your asm statements. Code like this
-
-<tscreen><verb>
- int foo;
- int bar () { return 1; }
- __asm__ ("lda _foo"); /* DON'T DO THAT! */
- ...
- __asm__ ("jsr _bar"); /* DON'T DO THAT EITHER! */
-</verb></tscreen>
-<p>
-
-may stop working if the way, the compiler generates these names is changed in
-a future version. Instead use the format specifiers from the table above:
-
-<tscreen><verb>
- __asm__ ("lda %v", foo); /* OK */
- ...
- __asm__ ("jsr %v", bar); /* OK */
-</verb></tscreen>
-<p>
-
-
-<sect>Implementation-defined behavior<p>
-
-This section describes the behavior of cc65 when the standard describes the
-behavior as implementation-defined.
-
-(to be done)
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the compiler, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-This is the original compiler copyright:
-
-<tscreen><verb>
---------------------------------------------------------------------------
- -*- Mode: Text -*-
-
- This is the copyright notice for RA65, LINK65, LIBR65, and other
- Atari 8-bit programs. Said programs are Copyright 1989, by John R.
- Dunning. All rights reserved, with the following exceptions:
-
- Anyone may copy or redistribute these programs, provided that:
-
- 1: You don't charge anything for the copy. It is permissable to
- charge a nominal fee for media, etc.
-
- 2: All source code and documentation for the programs is made
- available as part of the distribution.
-
- 3: This copyright notice is preserved verbatim, and included in
- the distribution.
-
- You are allowed to modify these programs, and redistribute the
- modified versions, provided that the modifications are clearly noted.
-
- There is NO WARRANTY with this software, it comes as is, and is
- distributed in the hope that it may be useful.
-
- This copyright notice applies to any program which contains
- this text, or the refers to this file.
-
- This copyright notice is based on the one published by the Free
- Software Foundation, sometimes known as the GNU project. The idea
- is the same as theirs, ie the software is free, and is intended to
- stay that way. Everybody has the right to copy, modify, and re-
- distribute this software. Nobody has the right to prevent anyone
- else from copying, modifying or redistributing it.
-
---------------------------------------------------------------------------
-</verb></tscreen>
-
-Small parts of the compiler (parts of the preprocessor and main parser) are
-still covered by this copyright. The main portion is covered by the usual
-cc65 license, which reads:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
+++ /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'
- --forget-inc-paths Forget include search paths (compiler)
- --help Help (this text)
- --include-dir dir Set a compiler include directory path
- --ld-args options Pass options to the linker
- --lib file Link this library
- --lib-path path Specify a library search path
- --list-targets List all available targets
- --listing name Create an assembler listing file
- --list-bytes n Number of bytes per assembler listing line
- --mapfile name Create a map file
- --memory-model model Set the memory model
- --module Link as a module
- --module-id id Specify a module id for the linker
- --o65-model model Override the o65 model
- --obj file Link this object file
- --obj-path path Specify an object file search path
- --register-space b Set space available for register variables
- --register-vars Enable register variables
- --rodata-name seg Set the name of the RODATA segment
- --signed-chars Default characters are signed
- --standard std Language standard (c89, c99, cc65)
- --start-addr addr Set the default start address
- --static-locals Make local variables static
- --target sys Set the target system
- --version Print the version number
- --verbose Verbose mode
- --zeropage-label name Define and export a ZEROPAGE segment label
- --zeropage-name seg Set the name of the ZEROPAGE segment
----------------------------------------------------------------------------
-</verb></tscreen>
-
-Most of the options have the same meaning than the corresponding compiler,
-assembler or linker option. See the documentation for these tools for an
-explanation. If an option is available for more than one of the tools, it
-is set for all tools, where it is available. One example for this is <tt/-v/:
-The compiler, the assembler and the linker are all called with the <tt/-v/
-switch.
-
-There are a few remaining options that control the behaviour of cl65:
-
-<descrip>
-
- <tag><tt>-S</tt></tag>
-
- This option forces cl65 to stop after the assembly step. This means that
- C files are translated into assembler files, but nothing more is done.
- Assembler files, object files and libraries given on the command line
- are ignored.
-
-
- <tag><tt>-c</tt></tag>
-
- This options forces cl65 to stop after the assembly step. This means
- that C and assembler files given on the command line are translated into
- object files, but there is no link step, and object files and libraries
- given on the command line are ignored.
-
-
- <tag><tt>-o name</tt></tag>
-
- The -o option is used for the target name in the final step. This causes
- problems, if the linker will not be called, and there are several input
- files on the command line. In this case, the name given with -o will be
- used for all of them, which makes the option pretty useless. You
- shouldn't use -o when more than one output file is created.
-
-
- <tag><tt>-t sys, --target sys</tt></tag>
-
- The default for this option is different from the compiler and linker in the
- case that the option is missing: While the other tools (compiler, assembler
- and linker) will use the "none" system settings by default, cl65 will use
- the C64 as a target system by default. This was chosen since most people
- seem to use cc65 to develop for the C64.
-
- <tag><tt>-Wa options, --asm-args options</tt></tag>
-
- Pass options directly to the assembler. This may be used to pass options
- that aren't directly supported by cl65. Several options may be separated by
- commas, the commas are replaced by spaces when passing them to the
- assembler. Beware: Passing arguments directly to the assembler may interfere
- with some of the defaults, because cl65 doesn't parse the options passed. So
- if cl65 supports an option by itself, do not pass this option to the
- assembler by means of the <tt/-Wa/ switch.
-
- <tag><tt>-Wc options, --cc-args options</tt></tag>
-
- Pass options directly to the compiler. This may be used to pass options
- that aren't directly supported by cl65. Several options may be separated by
- commas, the commas are replaced by spaces when passing them to the
- compiler. Beware: Passing arguments directly to the compiler may interfere
- with some of the defaults, because cl65 doesn't parse the options passed. So
- if cl65 supports an option by itself, do not pass this option to the
- compiler by means of the <tt/-Wc/ switch.
-
- <tag><tt>-Wl options, --ld-args options</tt></tag>
-
- Pass options directly to the linker. This may be used to pass options that
- aren't directly supported by cl65. Several options may be separated by
- commas, the commas are replaced by spaces when passing them to the linker.
- Beware: Passing arguments directly to the linker may interfere with some of
- the defaults, because cl65 doesn't parse the options passed. So if cl65
- supports an option by itself, do not pass this option to the linker by means
- of the <tt/-Wl/ switch.
-
-</descrip>
-
-
-
-<sect>More usage<p>
-
-Since cl65 was created to simplify the use of the cc65 development
-package, it tries to be smart about several things.
-
-<itemize>
-
-<item> If you don't give a target system on the command line, cl65
- defaults to the C64.
-
-<item> When linking, cl65 will supply the names of the startup file and
- library for the target system to the linker, so you don't have to do
- that.
-
-<item> If the final step is the linker, and the name of the output file was
- not explicitly given, cl65 will use the name of the first input file
- without the extension, provided that the name of this file has an
- extension. So you don't need to name the executable name in most
- cases, just give the name of your "main" file as first input file.
-</itemize>
-
-The command line is parsed from left to right, and the actual processing tool
-(compiler, assembler, ...) is invoked whenever a file name is encountered.
-This means that only the options to the left of a file name are in effect when
-this file is processed. It does also mean that you're able to specify
-different options for different files on the command line. As an example.
-
-<tscreen><verb>
- cl65 -Oirs main.c -O -g module.c
-</verb></tscreen>
-
-translates main.c with full optimization and module.c with less optimization
-and debug info enabled.
-
-The type of an input file is derived from its extension:
-
-<itemize>
-<item>C files: <tt/.c/
-<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
-<item>Object files: <tt/.o/ <tt/.obj/
-<item>Libraries: <tt/.a/, <tt/.lib/
-<item>GEOS resource files: <tt/.grc/
-<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/
-</itemize>
-
-Please note that the program cannot handle input files with unknown file
-extensions.
-
-
-<sect>Examples<p>
-
-The morse trainer software, which consists of one C file (morse.c) and one
-assembler file (irq.s) will need the following separate steps to compile
-into an executable named morse:
-
-<tscreen><verb>
- cc65 -g -Oi -t c64 morse.c
- ca65 -g morse.s
- ca65 -g irq.s
- ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib
-</verb></tscreen>
-
-When using cl65, this is simplified to
-
-<tscreen><verb>
- cl65 -g -Oi morse.c irq.s
-</verb></tscreen>
-
-As a general rule, you may use cl65 instead of cc65 at most times,
-especially in makefiles to build object files directly from C files. Use
-
-<tscreen><verb>
- .c.o:
- cl65 -g -Oi $<
-</verb></tscreen>
-
-to do this.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the utility, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von
-Bassewitz. For usage of the binaries and/or sources the following
-conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the converter, if you find any bugs, or if you're
-doing something interesting with the code, I would be glad to hear from you.
-Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries
-and/or sources the following conditions apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
+++ /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
-
-
-Instructions for compiling cc65 and the ca65 binutils:
-
-
-Linux (and probably most other Unices)
---------------------------------------
-
-Preconditions:
-
-You need the GNU C Compiler, Perl and sgml-tools installed.
-
-The simple way:
-
-From the main directory, use
-
- make -f make/gcc.mak
-
-to build all binaries, libraries and the docs. Use
-
- make -f make/gcc.mak install
-
-to install the files. Check the makefile before doing so and adjust the PREFIX
-variable as you like it.
-
-
-Step by step:
-
-Enter the src/ directory and do a
-
- make -f make/gcc.mak
-
-This will build all executables. You may use
-
- make -f make/gcc.mak strip
-
-to remove debugging information from the binaries.
-
-After that, you need to compile the libraries. Do
-
- cd libsrc; make
-
-HTML docs can be generated with
-
- cd doc; make html
-
-That's it! Installation directories for the RPM packages are
-
- /usr/bin for the binaries
- /usr/lib/cc65/include for include files
- /usr/lib/cc65/lib for libraries and startup files
- /usr/share/doc/cc65-<version> for documentation
-
-When using these directories, you don't need to set the CC65_INC and
-CC65_LIB environment variables. You may also use the /usr/local tree
-for installation, but the compiler and linker have no predefined search
-path for this directory, so you need the environment variables or
-change the search paths in the source.
-
-
-
-DOS using the DJGPP compiler
-----------------------------
-
-Most information in this section was provided by Keith W. Gerdes
-(kwg@netzero.net). Thanks a lot!
-
-The tmpfile() function in DJGPP has a bug and will not open the scratch
-file in binary mode. If you have problems with the archiver (which uses
-the tmpfile() function), you have two choices:
-
- 1. Get a fix from http://www.cartsys.com/eldredge/djgpp-patches.html
- and apply it. This will solve the problem once and forever.
-
- 2. For a temporary solution, in the file binutils/ar65/main.c, add the
- following lines:
-
- At top:
-
- #include <fcntl.h>
-
- At start of main:
-
- _fmode = O_BINARY;
-
- This will switch the default mode to binary and will work around the
- bug.
-
-Keith sent me the following notes how to build the tools on a DOS system
-using DJGPP (add your system type to CFLAGS if needed):
-
--------------------------------------------------------------------------
-
-Here's my current batch file:
-
-cd djgpp_v2\cc65
-
-if exist bin\nul goto ahead
-mkdir bin
-mkdir lib
-:ahead
-
-cd src\common
-make -f make\gcc.mak
-
-cd ..\ar65
-make -f make\gcc.mak
-del ar65
-strip ar65.exe
-move ar65.exe ..\..\bin
-
-cd ..\ca65
-make -f make\gcc.mak
-del ca65
-strip ca65.exe
-move ca65.exe ..\..\bin
-
-cd ..\cc65
-make -f make\gcc.mak
-del cc65
-strip cc65.exe
-move cc65.exe ..\..\bin
-
-cd ..\cl65
-make -f make\gcc.mak
-del cl65
-strip cl65.exe
-move cl65.exe ..\..\bin
-
-cd ..\da65
-make -f make\gcc.mak
-del da65
-strip da65.exe
-move da65.exe ..\..\bin
-
-cd ..\grc
-make -f make\gcc.mak
-del grc
-strip grc.exe
-move grc.exe ..\..\bin
-
-cd ..\ld65
-make -f make\gcc.mak
-del ld65
-strip ld65.exe
-move ld65.exe ..\..\bin
-
-cd ..\od65
-make -f make\gcc.mak
-del od65
-strip od65.exe
-move od65.exe ..\..\bin
-
-cd ..\..
-
-cd libsrc\common
-make "CC=cc65" "CFLAGS=-Osir -g -t none -I../../include" "AS=ca65"
-"AFLAGS=-t none"
-ar65 a common.lib *.o
-move common.lib ..\..\lib
-
-cd ..\runtime
-make "CC=cc65" "CFLAGS=-Osir -g -t none -I../../include" "AS=ca65"
-"AFLAGS=-t none"
-ar65 a runtime.lib *.o
-move runtime.lib ..\..\lib
-
- --
-
-In djgpp.env I use:
-
-+LFN=Y
-
-for the .depend file.
-
- --
-
-And in autoexec.bat I have:
-
-set CC65_INC=E:\djgpp_v2\cc65\include
-set CC65_LIB=E:\djgpp_v2\cc65\lib
-PATH=E:\djgpp_v2\cc65\binutils;%PATH%
-
--------------------------------------------------------------------------
-
-
-OS/2 using the EMX compiler
----------------------------
-
-If you're using OS/2 and have the EMX compiler and some GNU tools
-installed, you may also be able to compile the tools and libraries
-under OS/2. Mirco Miranda (mircomir@libero.it) sent me the following
-notes:
-
-
--------------------------------------------------------------------------
-
-CC65 make facilities V0.3 for OS/2 by Mirco Miranda
-Date: 02/01/2000
-
-OS2HOWTO.TXT... I wrote this very fast... I hope that you can
-understand...
-
-Emx is a porting of gcc under OS/2. I wrote some C code that with
-simply (and few) preprocessor line can be compiled under OS/2 and Linux.
-Now for emx there are projects like P2 that let's add to OS/2 a complete
-Posix.1/SUS-like environment... I think that in the future the porting
-from bsd unix (and I hope linux) environment can be made very easy...
-
-These are the things because I tried to compile CC65 with emx/gcc...
-
-WARNING: at time that as wrote compiling with emx/gcc give some warnings.
-
-
-1. What do you need
--------------------
-
-- emx/gcc 0.9D for OS/2
-
-http://hobbes.nmsu.edu/cgi-bin/h-browse?sh=1&dir=/pub/os2/dev/emx/v0.9d
-
-- gnu make
-
-http://hobbes.nmsu.edu/pub/os2/dev/util/gnumake.zip
-
-- bash
-
-Use (ba)sh coming with this package.
-There are many porting of unix shell for OS/2 and some don't
-work propely.
-
-- and finally the source package of the CC65
- http://www.cc65.org/#Download
- http://www.acc.umu.se/~arvid/cc65_mirror/cc65-sources-2.6.0.tar.gz
-
-I hope that's all! I have the complete emx/gnu tools installed on
-my OS/2 and I haven't test if you need other package. Sorry.
-
-
-2. Setup environment in OS/2
-----------------------------
-
-Unpack source package in a Directory and
-copy the files in src directory of source code.
-
-Install emx 0.9D following the istruction comes with it.
-Emx is well documented and I don't rewrite here emx documentation.
-
-Unpack the gnu make tool and copy make-os2.exe in ...\emx\gnu directory
-then rename it in make.exe
-
-Copy xxsh.exe in ...\emx\gnu directory
-
-
-If you want use my .cmd script (makeos2emx.cmd):
-
-- copy it in src directory
-- edit it and change the emx path(s) according with your(s).
- (set MYEMXPATH=c:\appos2\emx)
-
-else
-
-- add ...\emx\gnu directory on your libpath
-- add ...\emx\gnu directiry on your path
-- set comspec=...\emx\gnu\xxsh.exe
-- run make -f make/gcc.mak in src directory
-- run make in libsrc directory
-
-3. My make files
-----------------
-
-If you use zap command, *.exe are not deleted.
-
-
-4. Author & Disclaimer
-----------------------
-
-Mirco Miranda
-mircomir@libero.it
-ICQ#: 51640305
-
-I haven't tested the generated code of cc65 executables with emx/gcc...
-If you use the cc65 executables compiled with emx/gcc to compile the library,
-please test it before hardly or productivity using.
-
-Safety solution is compile the cc65 executables with Watcom and then
-compile the library using gnu make and gnu (ba)sh coming with this package.
-If you use this last solution you must have only installed emx runtime because
-make.exe and xxsh.exe use it!
-
--------------------------------------------------------------------------
-
-
-
-DOS, Windows, OS/2 using the Watcom Compiler
---------------------------------------------
-
-This is what I'm using. You need the Borland make in addition to the
-Watcom tools, or you have to change the makefile.
-
-1. Copy %WATCOM%\src\startup\wildargv.c from your Watcom directory into
- binutils\common.
-
-2. Enter
-
- make -f make\watcom.mak
-
- in the src/ directory.
-
-3. Use Linux to build the libraries:-) If you don't have Linux, get it
- now! More serious: There is no makefile to build the libraries under
- any of the DOS based operating systems. Use a batch file similar to
- the one above, or rewrite the makefile.
-
-
-
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the disassembler, if you find any bugs, or if
-you're doing something interesting with the assembler, I would be glad to hear
-from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von
-Bassewitz. For usage of the binaries and/or sources the following
-conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
-
-
-
+++ /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
-<!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 linuxdoc system>
-
-<article>
-<title>cc65 Documentation Overview
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2005-8-6
-
-<abstract>
-Main documentation page, contains links to other available stuff.
-</abstract>
-
-<sect>Program documentation<p>
-
-<descrip>
-
- <tag><htmlurl url="ar65.html" name="ar65.html"></tag>
- Describes the ar65 archiver.
-
- <tag><htmlurl url="ca65.html" name="ca65.html"></tag>
- Describes the ca65 macro assembler.
-
- <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag>
- Describes the ca65html assembler-source-to-HTML converter.
-
- <tag><htmlurl url="cc65.html" name="cc65.html"></tag>
- Describes the cc65 C compiler.
-
- <tag><htmlurl url="cl65.html" name="cl65.html"></tag>
- Describes the cl65 compile & link utility.
-
- <tag><htmlurl url="co65.html" name="co65.html"></tag>
- Describes the co65 object-file converter.
-
- <tag><htmlurl url="da65.html" name="da65.html"></tag>
- Describes the da65 6502/65C02 disassembler.
-
- <tag><htmlurl url="grc65.html" name="grc65.html"></tag>
- Describes the GEOS resource compiler (grc65).
-
- <tag><htmlurl url="ld65.html" name="ld65.html"></tag>
- Describes the ld65 linker.
-
- <tag><htmlurl url="od65.html" name="od65.html"></tag>
- Describes the od65 object-file analyzer.
-
- <tag><htmlurl url="sp65.html" name="sp65.html"></tag>
- Describes the sprite and bitmap utility.
-
-</descrip>
-
-
-<sect>Usage<p>
-
-<descrip>
-
- <tag><htmlurl url="intro.html" name="intro.html"></tag>
- Describes the use of the tools, by building a short &dquot;hello world&dquot;
- example.
-
- <tag><htmlurl url="coding.html" name="coding.html"></tag>
- Contains hints on creating the most effective code with cc65.
-
- <tag><htmlurl url="compile.txt" name="compile.txt"></tag>
- How to compile cc65 and the support tools.
-
- <tag><htmlurl url="using-make.html" name="using-make.html"></tag>
- Build programs, using the GNU Make utility.
-
- <tag><htmlurl url="customizing.html" name="customizing.html"></tag>
- How to use the cc65 toolset for a custom hardware platform (a target system
- not currently supported by the cc65 library set).
-
- <tag><htmlurl url="debugging.html" name="debugging.html"></tag>
- Debug programs, using the VICE emulator.
-
-</descrip>
-
-
-<sect>Library information and other references<p>
-
-<descrip>
-
- <tag><htmlurl url="funcref.html" name="funcref.html"></tag>
- A (currently incomplete) function reference.
-
- <tag><htmlurl url="dio.html" name="dio.html"></tag>
- Low-level disk I/O API.
-
- <tag><htmlurl url="geos.html" name="geos.html"></tag>
- The GEOSLib manual.
-
- <tag><htmlurl url="internal.txt" name="internal.txt"></tag>
- A somewhat older text describing several cc65 internals.
-
- <tag><htmlurl url="library.html" name="library.html"></tag>
- An overview over the cc65 runtime and C libraries.
-
- <tag><htmlurl url="smc.html" name="smc.html"></tag>
- Describes Christian Krügers macro package for writing self modifying
- assembler code.
-
- <tag><url name="6502 Binary Relocation Format document"
- url="http://www.6502.org/users/andre/o65/fileformat.html"></tag>
- Describes the o65 file format that is used for dynamically loadable modules
- and LUnix programs.
-
-</descrip>
-
-
-<sect>Platform-specific information<p>
-
-<descrip>
-
- <tag><htmlurl url="apple2.html" name="apple2.html"></tag>
- Topics specific to the Apple ][.
-
- <tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag>
- Topics specific to the enhanced Apple //e.
-
- <tag><htmlurl url="atari.html" name="atari.html"></tag>
- Topics specific to the Atari 8-bit machines.
-
- <tag><htmlurl url="atmos.html" name="atmos.html"></tag>
- Topics specific to the Oric Atmos.
-
- <tag><htmlurl url="c128.html" name="c128.html"></tag>
- Topics specific to the Commodore 128.
-
- <tag><htmlurl url="c16.html" name="c16.html"></tag>
- Topics specific to the Commodore 16/116.
-
- <tag><htmlurl url="c64.html" name="c64.html"></tag>
- Topics specific to the Commodore 64.
-
- <tag><htmlurl url="cbm510.html" name="cbm510.html"></tag>
- Topics specific to the Commodore 510.
-
- <tag><htmlurl url="cbm610.html" name="cbm610.html"></tag>
- Topics specific to the Commodore 610.
-
- <tag><htmlurl url="lynx.html" name="lynx.html"></tag>
- Topics specific to the Atari Lynx Game Console.
-
- <tag><htmlurl url="nes.html" name="nes.html"></tag>
- Topics specific to the Nintendo Entertainment System.
-
- <tag><htmlurl url="pet.html" name="pet.html"></tag>
- Topics specific to the Commodore PET machines.
-
- <tag><htmlurl url="plus4.html" name="plus4.html"></tag>
- Topics specific to the Commodore Plus/4.
-
- <tag><htmlurl url="supervision.html" name="supervision.html"></tag>
- Topics specific to the Supervision Console.
-
- <tag><htmlurl url="vic20.html" name="vic20.html"></tag>
- Topics specific to the Commodore VIC20.
-
-</descrip>
-
-
-<sect>Miscellaneous<p>
-
-<descrip>
-
- <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag>
- Somewhat outdated. Lists the differences between my cc65 releases
- and the original Atari version that was created by J. R. Dunning.
-
- <tag><htmlurl url="BUGS" name="BUGS"></tag>
- Known cc65 bugs.
-
- <tag><htmlurl url="CREDITS" name="CREDITS"></tag>
- Here is who helped with the compiler and other tools.
-
-</descrip>
-
-</article>
-
+++ /dev/null
-
-
- Internals doc for CC65
-
-
-
-Stacks:
--------
-
-The program stack used by programs compiled with CC65 is located in high
-memory. The stack starts there and grows down. Arguments to functions, local
-data etc are allocated on this stack, and deallocated when functions exit.
-
-The program code and data is located in low memory. The heap is located
-between the program code and the stack. The default size for the parameter
-stack is 2K, you may change this for most platforms in the linker
-configuration.
-
-Note: The size of the stack is only needed if you use the heap, or if you
-call the stack checking routine (_stkcheck) from somewhere in your program.
-
-When calling other functions, the return address goes on the normal 6502
-stack, *not* on the parameter stack.
-
-
-
-Registers:
-----------
-
-Since CC65 is a member of the Small-C family of compilers, it uses the notion
-of a 'primary register'. In the CC65 implementation, I used the AX register
-pair as the primary register. Just about everything interesting that the
-library code does is done by somehow getting a value into AX, and then calling
-some routine or other. In places where Small-C would use a secondary
-register, top-of-stack is used, so for instance two argument function like
-integer-multiply work by loading AX, pushing it on the stack, loading the
-second value, and calling the internal function. The stack is popped, and the
-result comes back in AX.
-
-
-
-Calling sequences:
-------------------
-
-C functions are called by pushing their args on the stack, and JSR'ing to the
-entry point. (See ex 1, below) If the function returns a value, it comes back
-in AX. NOTE!!! A potentially significant difference between the CC65
-environment and other C environments is that the CALLEE pops arguments, not
-the CALLER. (This is done so as to generate more compact code) In normal use,
-this doesn't cause any problems, as the normal function entry/exit conventions
-take care of popping the right number of things off the stack, but you may
-have to worry about it when doing things like writing hand-coded assembly
-language routines that take variable numbers of arguments. More about that
-later.
-
-Ex 1: Function call: Assuming 'i' declared int and 'c' declared
- char, the following C code
-
- i = baz(i, c);
-
- in absence of a prototype generates this assembler code. I've added
- the comments.
-
- lda _i ; get 'i', low byte
- ldx _i+1 ; get 'i', hi byte
- jsr pushax ; push it
- lda _c ; get 'c'
- ldx #0 ; fill hi byte with 0
- jsr pushax ; push it
- ldy #4 ; arg size
- jsr _baz ; call the function
- sta _i ; store the result
- stx _i+1
-
- In presence of a prototype, the picture changes slightly, since the
- compiler is able to do some optimizations:
-
- lda _i ; get 'i', low byte
- ldx _i+1 ; get 'i', hi byte
- jsr pushax ; push it
- lda _c ; get 'c'
- jsr pusha ; push it
- jsr _baz ; call the function
- sta _i ; store the result
- stx _i+1
-
-
-Note that the two words of arguments to baz were popped before it exitted.
-The way baz could tell how much to pop was by the argument count in Y at call
-time. Thus, even if baz had been called with 3 args instead of the 2 it was
-expecting, that would not cause stack corruption.
-
-There's another tricky part about all this, though. Note that the args to baz
-are pushed in FORWARD order, ie the order they appear in the C statement.
-That means that if you call a function with a different number of args than it
-was expecting, they wont end up in the right places, ie if you call baz, as
-above, with 3 args, it'll operate on the LAST two, not the first two.
-
-
-
-Symbols:
---------
-
-CC65 does the usual trick of prepending an underbar ('_') to symbol names when
-compiling them into assembler. Therefore if you have a C function named
-'bar', CC65 will define and refer to it as '_bar'.
-
-
-
-Systems:
---------
-
-Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700,
-the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to
-Kevin Ruland, who did the port).
-
-C16: Works with unexpanded or memory expanded C16 and C116 machines.
- However, a maximum of 32KB from the total memory is used. The Plus/4
- target supports up to 64K of memory, but has a small code overhead
- because of the banking routines involved. Apart from this additional
- overhead, the Plus/4 target and the C16 target are the same. 16K
- machines (unexpanded C16) have 12K of memory for C programs available,
- machines with 32K or more have 28K available. The actual amount of
- memory is auto detected.
-
-C64: The program runs in a memory configuration, where only the kernal ROM
- is enabled. The text screen is expected at the usual place ($400), so
- 50K of memory are available to the program.
-
-C128: The startup code will reprogram the MMU, so that only the kernal ROM
- is enabled. This means, there are 41K of memory available to the
- program.
-
-Plus/4: Works with bank switching so 59K of memory are available to the
- program.
-
-CBM 500:
- The C program runs in bank #0 and has a total of 48K memory available.
- This is less than what is available on its bigger brothers (CBM
- 600/700) because the character data and video RAM is placed in the
- execution bank (#0) to allow the use of sprites.
-
-CBM 600/700:
- The C program runs in a separate segment and has almost full 64K of
- memory available.
-
-PET: The startup code will adjust the upper memory limit to the installed
- memory. However, only linear memory is used, this limits the top to
- $8000, so on a 8032 or similar machine, 31K of memory are available to
- the program.
-
-Apple ][:
- The program starts at $803, end of RAM is $95FF, so 35.5K of memory
- (including stack) are available to the program.
-
-Atari: The startup code will adjust the upper memory limit to the installed
- memory detected at runtime. The programmer can adjust the upper memory
- limit by setting the __RESERVED_MEMORY__ variable at link time. The
- given __RESERVED_MEMORY__ value will be subtracted from the upper
- memory limit used by the runtine. This memory could be used as graphics
- memory, for example.
- In the default case (no setting of __RESERVED_MEMORY__) the upper
- memory limit is $9C1F (with Basic cartridge) and $BC1F (without
- cartridge). The program starts at $2E00 by default.
- These values are for a 48K or 64K machine.
-
-Note: The above numbers do not mean that the remaining memory is unusable.
-However, it is not linear memory and must be accessed by other, nonportable
-methods. I'm thinking about a library extension that allows access to the
-additional memory as a far heap, but these routines do not exist until now.
-
-
-
-Inline Assembly:
-----------------
-
-CC65 allows inline assembly by a special keyword named "asm". Inline assembly
-looks like a function call. The string in parenthesis is output in the
-assembler file.
-
-Example, insert a break instruction into the code:
-
- asm ("brk")
-
-Beware: Be careful when inserting inline code since this may collide with
-the work of the optimizer.
-
-
-
-Pseudo variables:
------------------
-
-There are two special variables available named __AX__ and __EAX__. These
-variables must never be declared (this gives an error), but may be used as any
-other variable. However, accessing these variables will access the primary
-register that is used by the compiler to evaluate expressions, return
-functions results and pass parameters.
-
-This feature is useful with inline assembly and macros. For example, a macro
-that reads a CRTC register may be written like this:
-
-#define wr(idx) (__AX__=(idx), \
- asm ("sta $2000"), \
- asm ("lda $2000"), \
- asm ("ldx #$00"), \
- __AX__)
-
+++ /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://www.viceteam.org/">:
-
-Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
-printers, serial port and adapters, stereo sound, disk drives and images, RAM
-expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice,
-and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
-BeOS x86, Acorn RISC OS, and most Unixes.
-
-Compile the tutorial with
-<tscreen><verb>
-cl65 -O -t <sys> hello.c text.s
-</verb></tscreen>
-Substitute the name of a Commodore computer for that <tt/<sys>/:
-<itemize>
-<item><tt/c128/
-<item><tt/c16/
-<item><tt/c64/
-<item><tt/cbm510/
-<item><tt/cbm610/
-<item><tt/pet/
-<item><tt/plus4/
-<item><tt/vic20/
-</itemize>
-
-Start the desired version of the emulator (CBM510 and CBM610 programs run on
-the CBM II [<tt/xcbm2/] emulator).
-
-In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape
-image...</bf>, choose your executable, and click <bf/OK/.
-
-In the Unix versions, hold down the mouse's first button. Move the pointer to
-<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
-executable, and click <bf/Autostart/.
-
-The file has a 14-byte header which corresponds to a PRG-format BASIC program,
-consisting of a single line, similar to this:
-
-<tscreen><code>
-1000 sys2061
-</code></tscreen>
-
-On a real Commodore with attached disk drive, you would type:
-
-<tscreen><verb>
-LOAD "0:HELLO",8
-</verb></tscreen>
-
-for VIC-20/C64, or:
-
-<tscreen><verb>
-DLOAD "HELLO"
-</verb></tscreen>
-
-on PET/CBM II/C128/C16/Plus 4; then, type
-
-<tscreen><verb>
-RUN
-</verb></tscreen>
-
-On a Commodore 128, you can combine those two commands:
-<tscreen><verb>
-RUN "HELLO"
-</verb></tscreen>
-
-The output will appear on a separate line, and you will be returned to a BASIC
-prompt.
-
-
-<sect1>GEOS<p>
-Available at <it/Click Here Software's/ <url
-url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
-
-<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
-It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
-Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be
-controlled by many different types of input devices:
-<itemize>
-<item>keyboard
-<item>joysticks
-<item>mice
-<item>trackballs
-<item>graphics drawing tablets
-<item>light-pens
-</itemize>
-
-The tutorial files are different for GEOS. You will find them "next door," in
-"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
-"<tt/hello1res.grc/".
-
-Compile the tutorial with
-<tscreen><verb>
-cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
-</verb></tscreen>
-Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
-
-Boot the GEOS master disk/image.
-
-<quote>
-When you want to run GEOS in an emulator, you must adjust that emulator so that
-it does a "true drive" emulation. Each emulator has its own way of turning that
-feature on.
-</quote>
-
-<quote>
-VICE even has different ways that depend on which operating system is running
-the emulator.
-<itemize>
-<item>In Windows, you must click on <bf/Options/ (in an always visible menu).
- Then, you must click on <bf/True drive emulation/.
-<item>In Unix, you must <em/hold down/ the second button on your mouse. Move
- the pointer down to <bf/Drive settings/. Then, move the pointer over to
- <bf/Enable true drive emulation/. (If there is a check-mark in front of
- those words, that feature already is turned on -- then, move the pointer
- off of that menu.) Release the mouse button.
-</itemize>
-</quote>
-
-Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you
-should see its icon in the fourth position on the <bf/deskTop/'s directory
-notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
-it to run that program. Click on the <bf/Disk/ icon; put the disk with
-"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little
-icons under the list of file-names to move through that list until you find
-"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon.
-<bf/CONVERT/ will ask you to confirm that you choose the correct file; click
-<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the
-program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
-announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list
-again. This time, click on <bf/Quit/.
-
-(You might need to put the boot disk back into the drive, in order to reload
-<bf/deskTop/. Then, you must swap back to the disk with the tutorial program
-on it, and click on its disk icon [on the right side of the screen].)
-
-Now, you must find <bf/hello1/. Click on the lower left-hand corner of the
-directory notePad. Look at the eight file-positions on each page until you see
-<bf/hello1/. Double-click on its icon.
-
-The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
-reading it.
-
-
-<sect1>Contributions wanted<p>
-
-We need your help! Recommended emulators and instructions for other targets
-are missing. We suggest that you choose emulators with good compatibility.
-Also, being able to run all computers in the target series is good for
-target compatibility testing. A machine-language monitor is almost essential
-for debugging, but a native debugger could be used, as well.
-
-Finally, emulators which run on Unix or Windows would help to reach a wider
-audience.
-
-</article>
+++ /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
- --dump-config name Dump a builtin configuration
- --end-group End a library group
- --force-import sym Force an import of symbol `sym'
- --help Help (this text)
- --lib file Link this library
- --lib-path path Specify a library search path
- --mapfile name Create a map file
- --module-id id Specify a module id
- --obj file Link this object file
- --obj-path path Specify an object file search path
- --start-addr addr Set the default start address
- --start-group Start a library group
- --target sys Set the target system
- --version Print the linker version
----------------------------------------------------------------------------
-</verb></tscreen>
-
-
-<sect1>Command line options in detail<p>
-
-Here is a description of all the command line options:
-
-<descrip>
-
- <label id="option--start-group">
- <tag><tt>-(, --start-group</tt></tag>
-
- Start a library group. The libraries specified within a group are searched
- multiple times to resolve crossreferences within the libraries. Normally,
- crossreferences are only resolved within a library, that is the library is
- searched multiple times. Libraries specified later on the command line
- cannot reference otherwise unreferenced symbols in libraries specified
- earlier, because the linker has already handled them. Library groups are
- a solution for this problem, because the linker will search repeatedly
- through all libraries specified in the group, until all possible open
- symbol references have been satisfied.
-
-
- <tag><tt>-), --end-group</tt></tag>
-
- End a library group. See the explanation of the <tt><ref
- id="option--start-group" name="--start-group"></tt> option.
-
-
- <tag><tt>-h, --help</tt></tag>
-
- Print the short option summary shown above.
-
-
- <label id="option-m">
- <tag><tt>-m name, --mapfile name</tt></tag>
-
- This option (which needs an argument that will used as a filename for
- the generated map file) will cause the linker to generate a map file.
- The map file does contain a detailed overview over the modules used, the
- sizes for the different segments, and a table containing exported
- symbols.
-
-
- <label id="option-o">
- <tag><tt>-o name</tt></tag>
-
- The -o switch is used to give the name of the default output file.
- Depending on your output configuration, this name may NOT be used as
- name for the output file. However, for the builtin configurations, this
- name is used for the output file name.
-
-
- <label id="option-t">
- <tag><tt>-t sys, --target sys</tt></tag>
-
- The argument for the -t switch is the name of the target system. Since this
- switch will activate a builtin configuration, it may not be used together
- with the <tt><ref id="option-C" name="-C"></tt> option. The following target
- systems are currently supported:
-
- <itemize>
- <item>none
- <item>module
- <item>apple2
- <item>apple2enh
- <item>atari
- <item>atmos
- <item>c16 (works also for the c116 with memory up to 32K)
- <item>c64
- <item>c128
- <item>cbm510 (CBM-II series with 40 column video)
- <item>cbm610 (all CBM series-II computers with 80 column video)
- <item>geos-apple
- <item>geos-cbm
- <item>lunix
- <item>lynx
- <item>nes
- <item>pet (all CBM PET systems except the 2001)
- <item>plus4
- <item>supervision
- <item>vic20
- </itemize>
-
- There are a few more targets defined but neither of them is actually
- supported.
-
-
- <tag><tt>-u sym[:addrsize], --force-import sym[:addrsize]</tt></tag>
-
- Force an import of a symbol. While object files are always linked to the
- output file, regardless if there are any references, object modules from
- libraries get only linked in if an import can be satisfied by this module.
- The <tt/--fore-import/ option may be used to add a reference to a symbol and
- as a result force linkage of the module that exports the identifier.
-
- The name of the symbol may optionally be followed by a colon and an address
- size specifier. If no address size is specified, the default address size
- for the target machine is used.
-
- Please note that the symbol name needs to have the internal representation,
- meaning you have to prepend an underline for C identifiers.
-
-
- <label id="option-v">
- <tag><tt>-v, --verbose</tt></tag>
-
- Using the -v option, you may enable more output that may help you to
- locate problems. If an undefined symbol is encountered, -v causes the
- linker to print a detailed list of the references (that is, source file
- and line) for this symbol.
-
-
- <tag><tt>-vm</tt></tag>
-
- Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt>
- (generate map file). Normally the map file will not include empty segments
- and sections, or unreferenced symbols. Using this option, you can force the
- linker to include all this information into the map file.
-
-
- <label id="option-C">
- <tag><tt>-C</tt></tag>
-
- This gives the name of an output config file to use. See section 4 for more
- information about config files. -C may not be used together with <tt><ref
- id="option-t" name="-t"></tt>.
-
-
- <label id="option-D">
- <tag><tt>-D sym=value, --define sym=value</tt></tag>
-
- This option allows to define an external symbol on the command line. Value
- may start with a '$' sign or with <tt/0x/ for hexadecimal values,
- otherwise a leading zero denotes octal values. See also the <ref
- id="SYMBOLS" name="SYMBOLS section"> in the configuration file.
-
-
- <label id="option--lib-path">
- <tag><tt>-L path, --lib-path path</tt></tag>
-
- Specify a library search path. This option may be used more than once. It
- adds a directory to the search path for library files. Libraries specified
- without a path are searched in current directory, in the directory given in
- the <tt/LD65_LIB/ environment variable, and in the list of directories
- specified using <tt/--lib-path/.
-
-
- <tag><tt>-Ln</tt></tag>
-
- This option allows you to create a file that contains all global labels and
- may be loaded into VICE emulator using the <tt/ll/ (load label) command. You
- may use this to debug your code with VICE. Note: Older versions had some
- bugs in the label code. If you have problems, please get the latest VICE
- version.
-
-
- <label id="option-S">
- <tag><tt>-S addr, --start-addr addr</tt></tag>
-
- Using -S you may define the default starting address. If and how this
- address is used depends on the config file in use. For the builtin
- configurations, only the "none", "apple2" and "apple2enh" systems honor an
- explicit start address, all other builtin config provide their own.
-
-
- <tag><tt>-V, --version</tt></tag>
-
- This option print the version number of the linker. If you send any
- suggestions or bugfixes, please include this number.
-
-
- <label id="option--cfg-path">
- <tag><tt>--cfg-path path</tt></tag>
-
- Specify a config file search path. This option may be used more than once.
- It adds a directory to the search path for config files. A config file given
- with the <tt><ref id="option-C" name="-C"></tt> option that has no path in
- its name is searched in the current directory, in the directory given in the
- <tt/LD65_CFG/ environment variable, and in the list of directories specified
- using <tt/--cfg-path/.
-
-
- <label id="option--dbgfile">
- <tag><tt>--dbgfile name</tt></tag>
-
- Specify an output file for debug information. Available information will be
- written to this file. Using the <tt/-g/ option for the compiler and assembler
- will increase the amount of information available. Please note that debug
- information generation is currently being developed, so the format of the
- file and its contents are subject to change without further notice.
-
-
- <tag><tt>--lib file</tt></tag>
-
- Links a library to the output. Use this command line option instead of just
- naming the library file, if the linker is not able to determine the file
- type because of an unusual extension.
-
-
- <tag><tt>--obj file</tt></tag>
-
- Links an object file to the output. Use this command line option instead
- of just naming the object file, if the linker is not able to determine the
- file type because of an unusual extension.
-
-
- <label id="option--obj-path">
- <tag><tt>--obj-path path</tt></tag>
-
- Specify an object file search path. This option may be used more than once.
- It adds a directory to the search path for object files. An object file
- passed to the linker that has no path in its name is searched in current
- directory, in the directory given in the <tt/LD65_OBJ/ environment variable,
- and in the list of directories specified using <tt/--obj-path/.
-
-</descrip>
-
-
-
-<sect>Search paths<p>
-
-Starting with version 2.10 there are now several search paths for files needed
-by the linker: One for libraries, one for object files and one for config
-files.
-
-
-<sect1>Library search path<p>
-
-The library search path contains in this order:
-
-<enum>
-<item>The current directory.
-<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on
- Linux systems.
-<item>The value of the environment variable <tt/LD65_LIB/ if it is defined.
-<item>A subdirectory named <tt/lib/ of the directory defined in the environment
- variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt><ref id="option--lib-path"
- name="--lib-path"></tt> option on the command line.
-</enum>
-
-
-<sect1>Object file search path<p>
-
-The object file search path contains in this order:
-
-<enum>
-<item>The current directory.
-<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on
- Linux systems.
-<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined.
-<item>A subdirectory named <tt/obj/ of the directory defined in the environment
- variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt><ref id="option--obj-path"
- name="--obj-path"></tt> option on the command line.
-</enum>
-
-
-<sect1>Config file search path<p>
-
-The config file search path contains in this order:
-
-<enum>
-<item>The current directory.
-<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on
- Linux systems.
-<item>The value of the environment variable <tt/LD65_CFG/ if it is defined.
-<item>A subdirectory named <tt/cfg/ of the directory defined in the environment
- variable <tt/CC65_HOME/, if it is defined.
-<item>Any directory added with the <tt><ref id="option--cfg-path"
- name="--cfg-path"></tt> option on the command line.
-</enum>
-
-
-
-<sect>Detailed workings<p>
-
-The linker does several things when combining object modules:
-
-First, the command line is parsed from left to right. For each object file
-encountered (object files are recognized by a magic word in the header, so
-the linker does not care about the name), imported and exported
-identifiers are read from the file and inserted in a table. If a library
-name is given (libraries are also recognized by a magic word, there are no
-special naming conventions), all modules in the library are checked if an
-export from this module would satisfy an import from other modules. All
-modules where this is the case are marked. If duplicate identifiers are
-found, the linker issues a warning.
-
-This procedure (parsing and reading from left to right) does mean, that a
-library may only satisfy references for object modules (given directly or from
-a library) named <em/before/ that library. With the command line
-
-<tscreen><verb>
- ld65 crt0.o clib.lib test.o
-</verb></tscreen>
-
-the module test.o may not contain references to modules in the library
-clib.lib. If this is the case, you have to change the order of the modules
-on the command line:
-
-<tscreen><verb>
- ld65 crt0.o test.o clib.lib
-</verb></tscreen>
-
-Step two is, to read the configuration file, and assign start addresses
-for the segments and define any linker symbols (see <ref id="config-files"
-name="Configuration files">).
-
-After that, the linker is ready to produce an output file. Before doing that,
-it checks its data for consistency. That is, it checks for unresolved
-externals (if the output format is not relocatable) and for symbol type
-mismatches (for example a zero page symbol is imported by a module as absolute
-symbol).
-
-Step four is, to write the actual target files. In this step, the linker will
-resolve any expressions contained in the segment data. Circular references are
-also detected in this step (a symbol may have a circular reference that goes
-unnoticed if the symbol is not used).
-
-Step five is to output a map file with a detailed list of all modules,
-segments and symbols encountered.
-
-And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch
-twice, you get a dump of the segment data. However, this may be quite
-unreadable if you're not a developer:-)
-
-
-
-<sect>Configuration files<label id="config-files"><p>
-
-Configuration files are used to describe the layout of the output file(s). Two
-major topics are covered in a config file: The memory layout of the target
-architecture, and the assignment of segments to memory areas. In addition,
-several other attributes may be specified.
-
-Case is ignored for keywords, that is, section or attribute names, but it is
-<em/not/ ignored for names and strings.
-
-
-
-<sect1>Memory areas<p>
-
-Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an
-example (this one describes the usable memory layout of the C64):
-
-<tscreen><verb>
- MEMORY {
- RAM1: start = $0800, size = $9800;
- ROM1: start = $A000, size = $2000;
- RAM2: start = $C000, size = $1000;
- ROM2: start = $E000, size = $2000;
- }
-</verb></tscreen>
-
-As you can see, there are two ram areas and two rom areas. The names
-(before the colon) are arbitrary names that must start with a letter, with
-the remaining characters being letters or digits. The names of the memory
-areas are used when assigning segments. As mentioned above, case is
-significant for these names.
-
-The syntax above is used in all sections of the config file. The name
-(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the
-semicolon specify attributes for this identifier. You may use the equal sign
-to assign values to attributes, and you may use a comma to separate
-attributes, you may also leave both out. But you <em/must/ use a semicolon to
-mark the end of the attributes for one identifier. The section above may also
-have looked like this:
-
-<tscreen><verb>
- # Start of memory section
- MEMORY
- {
- RAM1:
- start $0800
- size $9800;
- ROM1:
- start $A000
- size $2000;
- RAM2:
- start $C000
- size $1000;
- ROM2:
- start $E000
- size $2000;
- }
-</verb></tscreen>
-
-There are of course more attributes for a memory section than just start and
-size. Start and size are mandatory attributes, that means, each memory area
-defined <em/must/ have these attributes given (the linker will check that). I
-will cover other attributes later. As you may have noticed, I've used a
-comment in the example above. Comments start with a hash mark (`#'), the
-remainder of the line is ignored if this character is found.
-
-
-<sect1>Segments<p>
-
-Let's assume you have written a program for your trusty old C64, and you would
-like to run it. For testing purposes, it should run in the <tt/RAM/ area. So
-we will start to assign segments to memory sections in the <tt/SEGMENTS/
-section:
-
-<tscreen><verb>
- SEGMENTS {
- CODE: load = RAM1, type = ro;
- RODATA: load = RAM1, type = ro;
- DATA: load = RAM1, type = rw;
- BSS: load = RAM1, type = bss, define = yes;
- }
-</verb></tscreen>
-
-What we are doing here is telling the linker, that all segments go into the
-<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So
-the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/
-segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/
-segment. Why? Enter the segment type: For each segment specified, you may also
-specify a segment attribute. There are four possible segment attributes:
-
-<tscreen><verb>
- ro means readonly
- rw means read/write
- bss means that this is an uninitialized segment
- zp a zeropage segment
-</verb></tscreen>
-
-So, because we specified that the segment with the name BSS is of type bss,
-the linker knows that this is uninitialized data, and will not write it to an
-output file. This is an important point: For the assembler, the <tt/BSS/
-segment has no special meaning. You specify, which segments have the bss
-attribute when linking. This approach is much more flexible than having one
-fixed bss segment, and is a result of the design decision to supporting an
-arbitrary segment count.
-
-If you specify "<tt/type = bss/" for a segment, the linker will make sure that
-this segment does only contain uninitialized data (that is, zeroes), and issue
-a warning if this is not the case.
-
-For a <tt/bss/ type segment to be useful, it must be cleared somehow by your
-program (this happens usually in the startup code - for example the startup
-code for cc65 generated programs takes care about that). But how does your
-code know, where the segment starts, and how big it is? The linker is able to
-give that information, but you must request it. This is, what we're doing with
-the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each
-segment, where this attribute is true, the linker will export three symbols.
-
-<tscreen><verb>
- __NAME_LOAD__ This is set to the address where the
- segment is loaded.
- __NAME_RUN__ This is set to the run address of the
- segment. We will cover run addresses
- later.
- __NAME_SIZE__ This is set to the segment size.
-</verb></tscreen>
-
-Replace <tt/NAME/ by the name of the segment, in the example above, this would
-be <tt/BSS/. These symbols may be accessed by your code.
-
-Now, as we've configured the linker to write the first three segments and
-create symbols for the last one, there's only one question left: Where does
-the linker put the data? It would be very convenient to have the data in a
-file, wouldn't it?
-
-<sect1>Output files<p>
-
-We don't have any files specified above, and indeed, this is not needed in a
-simple configuration like the one above. There is an additional attribute
-"file" that may be specified for a memory area, that gives a file name to
-write the area data into. If there is no file name given, the linker will
-assign the default file name. This is "a.out" or the one given with the
-<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the
-default behaviour is ok for our purposes, I did not use the attribute in the
-example above. Let's have a look at it now.
-
-The "file" attribute (the keyword may also be written as "FILE" if you like
-that better) takes a string enclosed in double quotes (`"') that specifies the
-file, where the data is written. You may specify the same file several times,
-in that case the data for all memory areas having this file name is written
-into this file, in the order of the memory areas defined in the <tt/MEMORY/
-section. Let's specify some file names in the <tt/MEMORY/ section used above:
-
-<tscreen><verb>
- MEMORY {
- RAM1: start = $0800, size = $9800, file = %O;
- ROM1: start = $A000, size = $2000, file = "rom1.bin";
- RAM2: start = $C000, size = $1000, file = %O;
- ROM2: start = $E000, size = $2000, file = "rom2.bin";
- }
-</verb></tscreen>
-
-The <tt/%O/ used here is a way to specify the default behaviour explicitly:
-<tt/%O/ is replaced by a string (including the quotes) that contains the
-default output name, that is, "a.out" or the name specified with the <tt><ref
-id="option-o" name="-o"></tt> option on the command line. Into this file, the
-linker will first write any segments that go into <tt/RAM1/, and will append
-then the segments for <tt/RAM2/, because the memory areas are given in this
-order. So, for the RAM areas, nothing has really changed.
-
-We've not used the ROM areas, but we will do that below, so we give the file
-names here. Segments that go into <tt/ROM1/ will be written to a file named
-"rom1.bin", and segments that go into <tt/ROM2/ will be written to a file
-named "rom2.bin". The name given on the command line is ignored in both cases.
-
-Assigning an empty file name for a memory area will discard the data written
-to it. This is useful, if the memory area has segments assigned that are empty
-(for example because they are of type bss). In that case, the linker will
-create an empty output file. This may be suppressed by assigning an empty file
-name to that memory area.
-
-The <tt/%O/ sequence is also allowed inside a string. So using
-
-<tscreen><verb>
- MEMORY {
- ROM1: start = $A000, size = $2000, file = "%O-1.bin";
- ROM2: start = $E000, size = $2000, file = "%O-2.bin";
- }
-</verb></tscreen>
-
-would write two files that start with the name of the output file specified on
-the command line, with "-1.bin" and "-2.bin" appended respectively. Because
-'%' is used as an escape char, the sequence "%%" has to be used if a single
-percent sign is required.
-
-<sect1>LOAD and RUN addresses (ROMable code)<p>
-
-Let us look now at a more complex example. Say, you've successfully tested
-your new "Super Operating System" (SOS for short) for the C64, and you
-will now go and replace the ROMs by your own code. When doing that, you
-face a new problem: If the code runs in RAM, we need not to care about
-read/write data. But now, if the code is in ROM, we must care about it.
-Remember the default segments (you may of course specify your own):
-
-<tscreen><verb>
- CODE read only code
- RODATA read only data
- DATA read/write data
- BSS uninitialized data, read/write
-</verb></tscreen>
-
-Since <tt/BSS/ is not initialized, we must not care about it now, but what
-about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was
-explicitly assigned a value. And your program will rely on these values on
-startup. Since there's no other way to remember the contents of the data
-segment, than storing it into one of the ROMs, we have to put it there. But
-unfortunately, ROM is not writable, so we have to copy it into RAM before
-running the actual code.
-
-The linker won't copy the data from ROM into RAM for you (this must be done by
-the startup code of your program), but it has some features that will help you
-in this process.
-
-First, you may not only specify a "<tt/load/" attribute for a segment, but
-also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if
-you don't specify a "<tt/run/" attribute, the linker assumes that load area
-and run area are the same. We will use this feature for our data area:
-
-<tscreen><verb>
- SEGMENTS {
- CODE: load = ROM1, type = ro;
- RODATA: load = ROM2, type = ro;
- DATA: load = ROM2, run = RAM2, type = rw, define = yes;
- BSS: load = RAM2, type = bss, define = yes;
- }
-</verb></tscreen>
-
-Let's have a closer look at this <tt/SEGMENTS/ section. We specify that the
-<tt/CODE/ segment goes into <tt/ROM1/ (the one at $A000). The readonly data
-goes into <tt/ROM2/. Read/write data will be loaded into <tt/ROM2/ but is run
-in <tt/RAM2/. That means that all references to labels in the <tt/DATA/
-segment are relocated to be in <tt/RAM2/, but the segment is written to
-<tt/ROM2/. All your startup code has to do is, to copy the data from its
-location in <tt/ROM2/ to the final location in <tt/RAM2/.
-
-So, how do you know, where the data is located? This is the second point,
-where you get help from the linker. Remember the "<tt/define/" attribute?
-Since we have set this attribute to true, the linker will define three
-external symbols for the data segment that may be accessed from your code:
-
-<tscreen><verb>
- __DATA_LOAD__ This is set to the address where the segment
- is loaded, in this case, it is an address in
- ROM2.
- __DATA_RUN__ This is set to the run address of the segment,
- in this case, it is an address in RAM2.
- __DATA_SIZE__ This is set to the segment size.
-</verb></tscreen>
-
-So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from
-<tt/__DATA_LOAD__/ to <tt/__DATA_RUN__/ before any other routines are called.
-All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/
-by the linker, so things will work properly.
-
-There's a library subroutine called <tt/copydata/ (in a module named
-<tt/copydata.s/) that might be used to do actual copying. Be sure to have a
-look at it's inner workings before using it!
-
-
-<sect1>Other MEMORY area attributes<p>
-
-There are some other attributes not covered above. Before starting the
-reference section, I will discuss the remaining things here.
-
-You may request symbols definitions also for memory areas. This may be
-useful for things like a software stack, or an i/o area.
-
-<tscreen><verb>
- MEMORY {
- STACK: start = $C000, size = $1000, define = yes;
- }
-</verb></tscreen>
-
-This will define some external symbols that may be used in your code:
-
-<tscreen><verb>
- __STACK_START__ This is set to the start of the memory
- area, $C000 in this example.
- __STACK_SIZE__ The size of the area, here $1000.
- __STACK_LAST__ This is NOT the same as START+SIZE.
- Instead, it it defined as the first
- address that is not used by data. If we
- don't define any segments for this area,
- the value will be the same as START.
- __STACK_FILEOFFS__ The binary offset in the output file. This
- is not defined for relocatable output file
- formats (o65).
-</verb></tscreen>
-
-A memory section may also have a type. Valid types are
-
-<tscreen><verb>
- ro for readonly memory
- rw for read/write memory.
-</verb></tscreen>
-
-The linker will assure, that no segment marked as read/write or bss is put
-into a memory area that is marked as readonly.
-
-Unused memory in a memory area may be filled. Use the "<tt/fill = yes/"
-attribute to request this. The default value to fill unused space is zero. If
-you don't like this, you may specify a byte value that is used to fill these
-areas with the "<tt/fillval/" attribute. If there is no "<tt/fillval/"
-attribute for the segment, the "<tt/fillval/" attribute of the memory area (or
-its default) is used instead. This means that the value may also be used to
-fill unfilled areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/
-directives.
-
-The symbol <tt/%S/ may be used to access the default start address (that is,
-the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the
-value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
-option).
-
-To support systems with banked memory, a special attribute named <tt/bank/ is
-available. The attribute value is an arbitrary 32 bit integer. The assembler
-has a builtin function named <tt/.BANK/ which may be used with an argument
-that has a segment reference (for example a symbol). The result of this
-function is the value of the bank attribute for the run memory area of the
-segment.
-
-
-<sect1>Other SEGMENT attributes<p>
-
-Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to
-request this feature. Num must be a power of two. To align all segments on a
-page boundary, use
-
-<tscreen><verb>
- SEGMENTS {
- CODE: load = ROM1, type = ro, align = $100;
- RODATA: load = ROM2, type = ro, align = $100;
- DATA: load = ROM2, run = RAM2, type = rw, define = yes,
- align = $100;
- BSS: load = RAM2, type = bss, define = yes, align = $100;
- }
-</verb></tscreen>
-
-If an alignment is requested, the linker will add enough space to the output
-file, so that the new segment starts at an address that is dividable by the
-given number without a remainder. All addresses are adjusted accordingly. To
-fill the unused space, bytes of zero are used, or, if the memory area has a
-"<tt/fillval/" attribute, that value. Alignment is always needed, if you have
-used the <tt/.ALIGN/ command in the assembler. The alignment of a segment
-must be equal or greater than the alignment used in the <tt/.ALIGN/ command.
-The linker will check that, and issue a warning, if the alignment of a segment
-is lower than the alignment requested in an <tt/.ALIGN/ command of one of the
-modules making up this segment.
-
-For a given segment you may also specify a fixed offset into a memory area or
-a fixed start address. Use this if you want the code to run at a specific
-address (a prominent case is the interrupt vector table which must go at
-address $FFFA). Only one of <tt/ALIGN/ or <tt/OFFSET/ or <tt/START/ may be
-specified. If the directive creates empty space, it will be filled with zero,
-of with the value specified with the "<tt/fillval/" attribute if one is given.
-The linker will warn you if it is not possible to put the code at the
-specified offset (this may happen if other segments in this area are too
-large). Here's an example:
-
-<tscreen><verb>
- SEGMENTS {
- VECTORS: load = ROM2, type = ro, start = $FFFA;
- }
-</verb></tscreen>
-
-or (for the segment definitions from above)
-
-<tscreen><verb>
- SEGMENTS {
- VECTORS: load = ROM2, type = ro, offset = $1FFA;
- }
-</verb></tscreen>
-
-The "<tt/align/", "<tt/start/" and "<tt/offset/" attributes change placement
-of the segment in the run memory area, because this is what is usually
-desired. If load and run memory areas are equal (which is the case if only the
-load memory area has been specified), the attributes will also work. There is
-also an "<tt/align_load/" attribute that may be used to align the start of the
-segment in the load memory area, in case different load and run areas have
-been specified. There are no special attributes to set start or offset for
-just the load memory area.
-
-A "<tt/fillval/" attribute may not only be specified for a memory area, but
-also for a segment. The value must be an integer between 0 and 255. It is used
-as fill value for space reserved by the assemblers <tt/.ALIGN/ and <tt/.RES/
-commands. It is also used as fill value for space between sections (part of a
-segment that comes from one object file) caused by alignment, but not for
-space that preceeds the first section.
-
-To suppress the warning, the linker issues if it encounters a segment that is
-not found in any of the input files, use "<tt/optional=yes/" as additional
-segment attribute. Be careful when using this attribute, because a missing
-segment may be a sign of a problem, and if you're suppressing the warning,
-there is no one left to tell you about it.
-
-<sect1>The FILES section<p>
-
-The <tt/FILES/ section is used to support other formats than straight binary
-(which is the default, so binary output files do not need an explicit entry
-in the <tt/FILES/ section).
-
-The <tt/FILES/ section lists output files and as only attribute the format of
-each output file. Assigning binary format to the default output file would
-look like this:
-
-<tscreen><verb>
- FILES {
- %O: format = bin;
- }
-</verb></tscreen>
-
-The only other available output format is the o65 format specified by Andre
-Fachat (see the <htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html"
-name="6502 binary relocation format specification">). It is defined like this:
-
-<tscreen><verb>
- FILES {
- %O: format = o65;
- }
-</verb></tscreen>
-
-The necessary o65 attributes are defined in a special section labeled
-<tt/FORMAT/.
-
-
-
-<sect1>The FORMAT section<p>
-
-The <tt/FORMAT/ section is used to describe file formats. The default (binary)
-format has currently no attributes, so, while it may be listed in this
-section, the attribute list is empty. The second supported format,
-<htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65">,
-has several attributes that may be defined here.
-
-<tscreen><verb>
- FORMATS {
- o65: os = lunix, version = 0, type = small,
- import = LUNIXKERNEL,
- export = _main;
- }
-</verb></tscreen>
-
-
-
-<sect1>The FEATURES section<label id="FEATURES"><p>
-
-In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the
-linker has features that may be enabled by an additional section labeled
-<tt/FEATURES/.
-
-
-<sect2>The CONDES feature<p>
-
-<tt/CONDES/ is used to tell the linker to emit module constructor/destructor
-tables.
-
-<tscreen><verb>
- FEATURES {
- CONDES: segment = RODATA,
- type = constructor,
- label = __CONSTRUCTOR_TABLE__,
- count = __CONSTRUCTOR_COUNT__;
- }
-</verb></tscreen>
-
-The <tt/CONDES/ feature has several attributes:
-
-<descrip>
-
- <tag><tt>segment</tt></tag>
-
- This attribute tells the linker into which segment the table should be
- placed. If the segment does not exist, it is created.
-
-
- <tag><tt>type</tt></tag>
-
- Describes the type of the routines to place in the table. Type may be one of
- the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or
- a numeric value between 0 and 6.
-
-
- <tag><tt>label</tt></tag>
-
- This specifies the label to use for the table. The label points to the start
- of the table in memory and may be used from within user written code.
-
-
- <tag><tt>count</tt></tag>
-
- This is an optional attribute. If specified, an additional symbol is defined
- by the linker using the given name. The value of this symbol is the number
- of entries (<em/not/ bytes) in the table. While this attribute is optional,
- it is often useful to define it.
-
-
- <tag><tt>order</tt></tag>
-
- Optional attribute that takes one of the keywords <tt/increasing/ or
- <tt/decreasing/ as an argument. Specifies the sorting order of the entries
- within the table. The default is <tt/increasing/, which means that the
- entries are sorted with increasing priority (the first entry has the lowest
- priority). "Priority" is the priority specified when declaring a symbol as
- <tt/.CONDES/ with the assembler, higher values mean higher priority. You may
- change this behaviour by specifying <tt/decreasing/ as the argument, the
- order of entries is reversed in this case.
-
- Please note that the order of entries with equal priority is undefined.
-
- <tag><tt>import</tt></tag>
-
- This attribute defines a valid symbol name, that is added as an import
- to the modules defining a constructor/desctructor of the given type.
- This can be used to force linkage of a module if this module exports the
- requested symbol.
-
-</descrip>
-
-Without specifying the <tt/CONDES/ feature, the linker will not create any
-tables, even if there are <tt/condes/ entries in the object files.
-
-For more information see the <tt/.CONDES/ command in the <htmlurl
-url="ca65.html" name="ca65 manual">.
-
-
-<sect2>The STARTADDRESS feature<p>
-
-<tt/STARTADDRESS/ is used to set the default value for the start address,
-which can be referenced by the <tt/%S/ symbol. The builtin default for the
-linker is $200.
-
-<tscreen><verb>
- FEATURES {
- # Default start address is $1000
- STARTADDRESS: default = $1000;
- }
-</verb></tscreen>
-
-Please note that order is important: The default start address must be defined
-<em/before/ the <tt/%S/ symbol is used in the config file. This does usually
-mean, that the <tt/FEATURES/ section has to go to the top of the config file.
-
-
-
-<sect1>The SYMBOLS section<label id="SYMBOLS"><p>
-
-The configuration file may also be used to define symbols used in the link
-stage or to force symbols imports. This is done in the SYMBOLS section. The
-symbol name is followed by a colon and symbol attributes.
-
-The following symbol attributes are supported:
-
-<descrip>
-
- <tag><tt>addrsize</tt></tag>
-
- The <tt/addrsize/ attribute specifies the address size of the symbol and
- may be one of
-<itemize>
- <item><tt/zp/, <tt/zeropage/ or <tt/direct/
- <item><tt/abs/, <tt/absolute/ or <tt/near/
- <item><tt/far/
- <item><tt/long/ or <tt/dword/.
-</itemize>
-
-Without this attribute, the default address size is <tt/abs/.
-
- <tag><tt>type</tt></tag>
-
- This attribute is mandatory. Its value is one of <tt/export/, <tt/import/ or
- <tt/weak/. <tt/export/ means that the symbol is defined and exported from
- the linker config. <tt/import/ means that an import is generated for this
- symbol, eventually forcing a module that exports this symbol to be included
- in the output. <tt/weak/ is similar as <tt/export/. However, the symbol is
- only defined if it is not defined elsewhere.
-
- <tag><tt>value</tt></tag>
-
- This must only be given for symbols of type <tt/export/ or <tt/weak/. It
- defines the value of the symbol and may be an expression.
-
-</descrip>
-
-The following example defines the stack size for an application, but allows
-the programmer to override the value by specifying <tt/--define
-__STACKSIZE__=xxx/ on the command line.
-
-<tscreen><verb>
- SYMBOLS {
- # Define the stack size for the application
- __STACKSIZE__: type = weak, value = $800;
- }
-</verb></tscreen>
-
-
-
-<sect1>Builtin configurations<p>
-
-The builtin configurations are part of the linker source. They can be retrieved
-with <tt/--dump-config/ and don't have a special format. So if you need a
-special configuration, it's a good idea to start with the builtin configuration
-for your system. In a first step, just replace <tt/-t target/ by <tt/-C
-configfile/. Then go on and modify the config file to suit your needs.
-
-
-
-<sect1>Secondary configurations<p>
-
-Several machine specific binary packages are distributed together with secondary
-configurations (in the cfg directory). These configurations can be used with
-<tt/-C configfile/ too.
-
-
-
-<sect>Special segments<p>
-
-The builtin config files do contain segments that have a special meaning for
-the compiler and the libraries that come with it. If you replace the builtin
-config files, you will need the following information.
-
-<sect1>INIT<p>
-
-The INIT segment is used for initialization code that may be reused once
-execution reaches main() - provided that the program runs in RAM. You
-may for example add the INIT segment to the heap in really memory
-constrained systems.
-
-<sect1>LOWCODE<p>
-
-For the LOWCODE segment, it is guaranteed that it won't be banked out, so it
-is reachable at any time by interrupt handlers or similar.
-
-<sect1>STARTUP<p>
-
-This segment contains the startup code which initializes the C software stack
-and the libraries. It is placed in its own segment because it needs to be
-loaded at the lowest possible program address on several platforms.
-
-<sect1>ZPSAVE<p>
-
-The ZPSAVE segment contains the original values of the zeropage locations used
-by the ZEROPAGE segment. It is placed in its own segment because it must not be
-initialized.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the linker, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von
-Bassewitz. For usage of the binaries and/or sources the following
-conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
+++ /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>atmos
- <item>c16 (works also for the c116 with up to 32K memory)
- <item>c64
- <item>c128
- <item>plus4 (or expanded c16/c116)
- <item>cbm510 (40 column video)
- <item>cbm610 (all CBM series-II computers with 80 column video)
- <item>geos-apple
- <item>geos-cbm
- <item>nes
- <item>pet (all CBM PET systems except the 2001)
- <item>vic20
- </itemize>
-
-The conio.h header file does also include the system specific header files
-which define constants for special characters and keys.
-
-
-
-<sect>Using the joystick - <tt/joystick.h/<p>
-
-For systems that have a joystick, <tt/joystick.h/ will define a subroutine to
-read the current value, including constants to evaluate the result of this
-function. To help in writing portable code, the header file will define the
-symbol <tt/__JOYSTICK__/ on systems that have a joystick.
-
-
-
-<sect>Using a mouse - <tt/mouse.h/<p>
-
-Some target machines support a mouse. Mouse support is currently available for
-the following targets:
-
- <itemize>
- <item>apple2
- <item>apple2enh
- <item>atari
- <item>c64
- <item>c128
- <item>cbm510
- </itemize>
-
-The available functions are declared in <tt/mouse.h/ To help writing portable
-code, the header file will define the symbol <tt/__MOUSE__/ in systems that
-support a mouse.
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-This C runtime library implementation for the cc65 compiler is (C)
-Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries
-and/or sources the following conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
-
-
+++ /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)/</tag>
- A TGI driver for the standard graphics mode (160×102 in 16 colors).
-
- The TGI driver is implemented as an interrupt driven dual buffering device.
- To use it as a single-buffer device set draw page and view page to the same
- value 0 or 1;
-
- The TGI driver has a few Lynx-specific extensions.
-
- Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx
- sprite on screen.
-
- Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen.
-
- Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text
- background color to the index defined by bgindex. If bgindex is 0 then the
- background color is transparent.
-
- To set the framerate of the display hardware call tgi_setframerate(rate) or
- tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per
- second. Actually there is no real reason to use anything else than 75 frames
- per second.
-
- To check if the drawing engine is busy with the previous swap you can
- call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy
-
- To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it
- will wait for the next VBL interrupt and set the draw buffer to the
- view buffer. The draw buffer is also changed to (drawbuffer xor 1).
-
- You can also enable or disable collision detection by a call to
- tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision
- result is located before the sprite structure by default in this driver.
-
- In order to reserve memory for the collision detection buffer you need to
- specify lynx-coll.cfg as the configuration file to the linker.
-
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-No extended memory drivers are currently available for the Lynx.
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag>
- A joystick driver for the standard buttons.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the Lynx.
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag>
- A serial driver for the ComLynx port.
-
- The ComLynx port has Tx and Rx wired together. Every byte is sent
- to all connected Lynxes. Only one Lynx can send at a time. There is no
- protocol created for communication. You are on your own.
-
- If the Lynx returns framing error then it is likely that another Lynx is
- sending data at the same time.
-
- The Lynx can also send a break and receive a break. The Lynx break is
- recognized if the bit is down for 24 bit cycles or more.
-
- To send a break you just set the break bit. The length of the break depends
- on how long this bit is down.
-
- The driver supports the baudrates:
- <itemize>
- <item>62500
- <item>31250
- <item>9600
- <item>7200
- <item>4800
- <item>3600
- <item>2400
- <item>1800
- <item>1200
- <item>600
- <item>300
- <item>150
- <item>134.5
- <item>110
- <item>75
- </itemize>
- The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity
- but the parity bit is included in the calculation. Most of us don't want it
- this way. But there is nothing we can do about it.
-
- The Lynx hardware will always check parity on incoming traffic. Currently
- the driver cannot receive data from standard PC's due to this parity bug.
- For working with Lynx to Lynx communication use EVEN parity.
-
- To send data to standard PC's use MARK or SPACE as parity setting.
-
- There is always only one stop bit. And the data length is always 8 bits.
-
- We have no handshaking available. Even software handshake is impossible
- as ComLynx has only one wire for the data.
-
- Both transmit and receive are interrupt driven.
-
-</descrip><p>
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Cart access<p>
-
-At this point in time there is no support for the cart filesystem yet. I have
-a <tt/lynx-cart-demo/ example project that uses an interrupt driven display,
-has support for the cart filesystem and an abcmusic sound module.
-
-At some point in time we may find a way to rewrite these to fit the way the
-cc65 drivers require. But for the time being you can create less portable
-applications using these Lynx specific modules in <tt/lynx-cart-demo/.
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
-
-
+++ /dev/null
-
-This document is slightly outdated! See cc65.txt and library.txt for a more
-up-to-date discussion.
-
-
-
-Discussion of some of the features/non features of the current cc65 version
----------------------------------------------------------------------------
-
- 1. Copyright
-
- 2. Differences to the original version
-
- 3. Known bugs and limitations
-
- 4. Library
-
- 5. Bugs
-
-
-
-
-1. Copyright
------------
-
-This is the original compiler copyright:
-
---------------------------------------------------------------------------
- -*- 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.
-
---------------------------------------------------------------------------
-
-In acknowledgment of this copyright, I will place my own changes to the
-compiler under the same copyright.
-
-However, since the library and all binutils (assembler, archiver, linker)
-are a complete rewrite, they are covered by another copyright:
-
-
---------------------------------------------------------------------------
-
- CC65 C Library and Binutils
-
- (C) Copyright 1998 Ullrich von Bassewitz
-
- COPYING CONDITIONS
-
-
- 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:
-
- 1. 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.
- 2. Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
- 3. This notice may not be removed or altered from any source
- distribution
-
-
---------------------------------------------------------------------------
-
-I will try to contact John, maybe he is also willing to place his sources
-under a less restrictive copyright, after all these years:-)
-
-
-
-
-2. Differences to the original version
---------------------------------------
-
-This is a list of changes against the cc65 archives. I got the originals
-from:
-
- http://www.umich.edu/~archive/atari/8bit/Languages/Cc65/
-
-
-
- * Removed all assembler code from the compiler. It was unportable because
- it made assumptions about the character set (ATASCII) and made the
- sources hard to read and to debug.
-
- * All programs do return an error code, so they may be used by make. All
- programs try to remove the target file, if there were errors.
-
- * The assembler now checks several error conditions (others still go
- undetected - see "known bugs").
-
- * Removed many bugs from the compiler. One error was invalid code
- produced by the compiler that went through the assembler since the
- assembler did not check for ranges itself.
-
- * Removed many non-portable constructs from the compiler. Code cleanups,
- rewrite of the function headers and more.
-
- * New style function prototypes supported instead of the old K&R syntax.
- The new syntax is a must, that is, the old style syntax is no longer
- understood. As an extension, unnamed parameters may be used to avoid
- warnings about unused parameters.
-
- * New void type. May also be used as a function return type.
-
- * Changed the memory management in the compiler. Use malloc/free instead
- of the old homebrew (and unportable) stuff.
-
- * Default character type is unsigned. This is much more what you want in
- small systems environments, since a char is often used to represent a
- small numerical value, and the integer promotion does the wrong thing
- in those cases. Look at the follwing piece of code:
-
- char c = read_char ();
- switch (c) {
- case 0x80: printf ("c is 0x80\n"); break;
- default: printf ("c is something else\n"); break;
- }
-
- With signed chars, the code above, will *always* run into the default
- selector. c is promoted to int, and since it is signed, 0x80 will get
- promoted to 0xFF80 - which will select the default label. With unsigned
- chars, the code works as intended (but note: the code works for cc65
- but it is non portable anyway, since many other compilers have signed
- chars by default, so be careful! Having unsigned chars is just a
- convenience thing).
-
- * Shorter code when using the builtin operators and the lhs of an expr
- is a constant (e.g. expressions like "c == 0x80" are encoded two
- bytes shorter).
-
- * Some optimizations when pushing constants.
-
- * Character set translation by the compiler. A new -t option was added
- to set the target system type. Use
-
- -t0 For no spefic target system (default)
- -t1 For the atari (does not work completely, since I did not
- have an ATASCII translation table).
- -t2 Target system is C64.
- -t3 Target system is C128.
- -t4 Target system is ACE.
- -t5 Target system is Plus/5.
-
- * Dito for the linker: Allow an option to set the target system and add
- code to the linker to produce different headers and set the correct
- start address.
-
- * Complete rewrite of the C library. See extra chapter.
-
- * Many changes in the runtime library. Splitted it into more than one
- file to allow for smaller executables if not all of the code is needed.
-
- * Allow longer names. Now the first 12 characters are sigificant at the
- expense of some more memory used at runtime.
-
- * String constants are now concatenated in all places. This allows
- things like:
-
- fputs ("Options:\n"
- " -b bomb computer\n"
- " -f format hard disk\n"
- " -k kill init\n",
- stderr);
-
- saving code for more than one call to the function.
-
- * Several new macros are defined:
-
- M6502 This one is old - don't use!
- __CC65__ Use this instead. Defined when compiling with cc65.
- __ATARI__ Defined when the target system is atari.
- __CBM__ Defined when compiling for a CBM system as target.
- __C64__ Defined when the C64 is the target system.
- __C128__ Defined when compiling for the 128.
- __ACE__ Defined when compiling for ACE.
- __PLUS4__ Defined when compiling for the Plus/4.
-
- The __CC65__ macro has the compiler version as its value, version
- 1.0 of the compiler will define this macro as 0x100.
-
- * The -a option is gone.
-
- * The compiler will generate external references (via .globl) only if a
- function is defined as extern in a module, or not defined but called
- from a module. The old behaviour was to generate a reference for every
- function prototype ever seen, which meant that using a header file like
- stdio.h got most of the C library linked in, even if it was never used.
-
- * Many new warnings added (about unused parameters, unused variables,
- compares of unsigneds against zero, function call without prototype
- and much more).
-
- * Added a new compiler option (-W) to suppress all warnings.
-
- * New internal variable __fixargs__ that gives the size of fixed
- arguments, a function takes. This allows to work (somehow) around the
- problem, that cc65 has the "wrong" (that is, pascal) calling order. See
- below ("Known problems") for a discussion.
-
- * The "empty" preprocessor directive ("#" on a line) is now ignored.
-
- * Added a "#error" directive to force user errors.
-
- * Optimization of the code generation. Constant parts of expressions are
- now detected in many places where the old compiler evaluated the
- constants at runtime.
-
- * Allow local static variables (there was code in the original compiler for
- that, but it did not work). Allow also initialization in this case (no
- code for that in the original). Local static variables in the top level
- function block have no penalty, for static variables in nested blocks, the
- compiler generates a jump around the variable space. To eliminate this,
- an assembler/linker with support for segments is needed.
-
- * You cannot return a value from a void function, and must return a value
- in a non-void function. Violations are flagged as an error.
-
- * Typedefs added.
-
- * The nonstandard evaluation of the NOARGC and FIXARGC macros has been
- replaced by a smart algorithm that does the same thing automagically
- and without user help (provided there are function prototypes).
-
- * Function pointers may now be used to call a function without
- dereferencing. Given a function
-
- void f1 (void (*f2) ())
-
- the following was valid before:
-
- (*f2) ();
-
- The ANSI standard allows a second form (because there's no ambiguity)
- which is now also allowed:
-
- f2 ();
-
- * Pointer subtraction was completely messed up and did not work (that is,
- subtraction of a pointer from a pointer produced wrong results).
-
- * Local struct definitions are allowed.
-
- * Check types in assignments, parameters for function calls and more.
-
- * A new long type (32 bit) is available. The integer promotion rules
- are applied if needed. This includes much more type checking and a
- better handling of chars (they are handled as chars, not as ints, in
- all places where this is possible).
-
- * Integer constants now have an associated type, 'U' and 'L' modifers
- may be used.
-
- * The old #asm statement is gone. Instead, there's now a asm ("xxx")
- statement that has the syntax that is defined by the C++ standard
- (the C standard does not define an ASM statement). The string literal
- in parenthesis is inserted in the assembler output. You may also
- use __asm__ instead of asm (see below).
-
- * Allow // comments.
-
- * New compiler option -A (ANSI) that disables several extensions (asm
- directive, // comments, unnamed function parameters) and also defines
- a macro named __STRICT_ANSI__. The header files will exclude some
- non-ANSI functions if __STRICT_ANSI__ is defined (that is, -A is given
- on the command line).
- -A will not disable the __asm__ directive (identifiers starting with
- __ are in the namespace of the implementation).
-
- * Create optimized code if the address of a variable is a constant. This
- may be achieved by constructs like "*(char*)0x200 = 0x01" and is used
- to access absolute memory locations. The compiler detects this case
- also if structs or arrays are involved and generates direct stores and
- fetches.
-
-
-
-3. Known problems
------------------
-
- * No floats.
-
- * Only simple automatic variables may be initialized (no arrays).
-
- * "Wrong" order of arguments on the stack. The arguments are pushed in
- the order, the arguments are parsed. That means that the va_xxx macros
- in stdarg.h are ok (they work as expected), but the fixed parameters of
- a function with a variable argument list do not match and must be
- determined with the (non-standard) va_fix macro.
-
- Using the __fixargs__ kludge, it is possible to write standard conform
- va_xxx macros to work with variable sized argument lists. However, the
- fixed parameters in the function itself usually have the wrong values,
- because the order of the arguments on the stack is reversed compared to
- a stock C compiler. Pushing the args the other way round requires much
- work and a more elaborated intermediate code than cc65 has.
-
- To understand the problem, have a look at this (non working!) sprintf
- function:
-
- int sprintf (char* buf, char* format, ...)
- /* Non working version */
- {
- int count;
- va_list ap;
- va_start (ap, format);
- count = vsprintf (buf, format, ap);
- va_end (ap);
- return count;
- }
-
- The problem here is in the "format" and "buf" parameters. They do (in
- most cases) not contain, what the caller gave us as arguments. To
- access the "real" arguments, use the va_fix macro. It is only valid
- before the first call to va_arg, and takes the va_list and the number
- of the fixed argument as parameters. So the right way would be
-
- int sprintf (char* buf, char* format, ...)
- /* Working version */
- {
- int count;
- va_list ap;
- va_start (ap, format);
- count = vsprintf (va_fix (ap, 1), va_fix (ap, 2), ap);
- va_end (ap);
- return count;
- }
-
- The fixed parameter are obtained by using the va_fix macro with the
- number of the parameter given as second argument. Beware: Since the
- fixed arguments declared are usually one of the additional parameters,
- the following code, which tries to be somewhat portable, does *not*
- work. The assignment will overwrite the other parameters instead,
- causing unexpected results:
-
- int sprintf (char* buf, char* format, ...)
- /* Non working version */
- {
- int count;
- va_list ap;
- va_start (ap, format);
- #ifdef __CC65__
- buf = va_fix (ap, 1);
- format = va_fix (ap, 2);
- #endif
- count = vsprintf (buf, format, ap);
- va_end (ap);
- return count;
- }
-
- To write a portable version of sprintf, use code like this instead:
-
- int sprintf (char* buf, char* format, ...)
- /* Working version */
- {
- int count;
- va_list ap;
- va_start (ap, format);
- #ifdef __CC65__
- count = vsprintf (va_fix (ap, 1), va_fix (ap, 2), ap);
- #else
- count = vsprintf (buf, format, ap);
- #endif
- va_end (ap);
- return count;
- }
-
- I know, va_fix is a kludge, but at least it *is* possible to write
- functions with variable sized argument lists in a comfortable manner.
-
- * The assembler still accepts lots of illegal stuff without an error (and
- creates wrong code). Be careful!
-
- * When starting a compiled program twice on the C64 (or 128), you may get
- other results or the program may even crash. This is because static
- variables do not have their startup values, they were changed in the
- first run.
-
- * There's only *one* symbol table level. It is - via a flag - used for both,
- locals and global symbols. However, if you have variables in nested
- blocks, the names may collide with the ones in the upper block. I will
- probably add real symbol tables some time to remove this problem.
-
- * Variables in nested blocks are handled inefficiently, especially in loops.
- The frame on the stack is allocated and deallocated for each loop
- iteration. There's no way around this, since the compiler has not enough
- memory to hold a complete function body in memory (it would be able to
- backpatch the frame generating code on function entry).
-
-
-
-
-4. Library
-----------
-
-The C library is a complete rewrite and has nothing in common with the old
-Atari stuff. When rewriting the library, I was guided by the following
-rules:
-
- * Use standard conform functions as far as possible. In addition, if
- there's a ANSI-C compatible function, it should act as defined in the
- ANSI standard. If if does not act as defined, this is an error.
-
- * Do not use non-standard functions if the functionality of those
- functions is covered by a standard function. Use exceptions only, if
- there is a non-ANSI function that is very popular (example: itoa).
-
- * Use new style prototpyes and header files.
-
- * Make the library portable. For example, the complete stdio stuff is
- based on only four system dependent functions:
-
- open, read, write, close
-
- So, if you rewrite these functions for a new system, all others
- (printf, fprintf, fgets, fputc ...) will work, too.
-
- * Do not expect a common character set. Unfortunately, I was not able to
- be completely consequent in this respect. C sources are no problem
- since the compiler does character translation, but the assembler
- sources make assumptions about the following characters:
-
- 0 --> code $30
- + --> code $2B
- - --> code $2D
-
- All other functions (especially the isxxx ones) are table driven, so
- only the classification table is system dependent.
-
-
-The first port was for the ACE operating system. The current version has also
-support for the C64, the C128 and the Plus/4 in native mode. The ACE port has
-disk support but no conio module, all others don't have disk support but
-direct console I/O.
-
-Currently the following limitations the are known:
-
- * getwd (ace) does not work. I get an error (carry flag) with an error
- code of zero (aceErrStopped). Maybe my code is wrong...
-
- * The error codes are currently system error codes. They should be
- translated to something system independent. The ace codes are a good
- starting point. However, I don't like the idea, that zero is a valid
- error code, and some other codes are missing ("invalid parameter" and
- more). As soon as this is done, it is also possible to write a
- strerror() function to give more descriptive error messages to the
- user.
-
- * Many functions not very good tested.
-
- * The printf and heap functions are way too big. Rewritting _printf
- and malloc/free in assembler will probably squeeze 2K out of the
- code.
-
- * The isxxx functions do not handle EOF correctly. This is probably
- a permanent restriction, even if it is non-standard. It would require
- extra code in each of the isxxx functions, since EOF is defined as -1
- and cannot be handled effectively with the table approach and 8 bit
- index registers.
-
- * The strcspn, strpbrk and strspn functions have a string length limitation
- of 256 for the second argument. This is usually not a problem since the
- second argument gives a character set, and a character set cannot be
- larger than 256 chars for all known 6502 systems.
-
-
-
-
-5. Bugs
--------
-
-Please note that the compiler and the libraries are beta! Send bug reports to
-uz@cc65.org.
-
-
-
-
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the converter, if you find any bugs, or if you're
-doing something interesting with the code, I would be glad to hear from you.
-Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the
-binaries and/or sources the following conditions apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
-
+++ /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)/</tag>
- Driver for the Protovision 4-player adapter contributed by Groepaz. See
- <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
- name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
- building instructions. Up to two joysticks are supported.
-
- <tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag>
- Driver for the standard PET userport joystick.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the PET.
-
-
-<sect1>RS232 device drivers<p>
-
-No serial drivers are currently available for the PET.
-
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the PET uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-<sect1>Using extended memory<p>
-
-The extended memory at $9000 of the CBM 8x96 may be added to the heap by using
-the following code:
-
-<tscreen><verb>
- /* Check for the existence of RAM */
- if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) {
- /* Add it to the heap */
- _heapadd ((void *) 0x9000, 0x2000);
- }
-</verb></tscreen>
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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)/</tag>
- Supports up to two joysticks connected to the standard joysticks port of
- the Plus/4.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-Currently no drivers available (in fact, the API for loadable mouse drivers
-does not exist).
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/plus4-stdser.ser (plus4_stdser)/</tag>
- Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200
- baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note
- that because of the peculiarities of the 6551 chip transmits are not
- interrupt driven, and the transceiver blocks if the receiver asserts flow
- control because of a full buffer.
-
- You need an adapter to use the builtin port, since the output levels
- available at the user port don't follow the RS232 standard.
-
-</descrip><p>
-
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Interrupts<p>
-
-The runtime for the Plus/4 uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /dev/null
-
-If you have got the source package, see
-
- doc/compile.txt
-
-for instructions how to compile the stuff for the different systems.
-
-
-If you have a binary package: Have a look in the doc directory for
-information on how to use the tools. If the doc dir is mostly empty,
-you will have to install the (separate) documentation package. If you
-are new to cc65, the file intro.txt may be of interest to you.
-
-To avoid having to mess with paths, you may want to set the environment
-variables
-
- CC65_LIB
- and CC65_INC
-
-to the directory containing the libraries and the system include files
-respectively. If you have installed cc65 in C:\cc65 (assuming a DOS or
-Windows system), you should use
-
- set CC65_LIB=c:\cc65\lib
- and set CC65_INC=c:\cc65\include
-
-Unix people probably know, how to translate these lines into the
-appropriate Unix commands:-)
-
-Have fun!
-
-
- Uz
-
-
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the assembler, if you find any bugs, or if
-you're doing something interesting with the assembler, I would be glad to
-hear from you. Feel free to contact me by email
-(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
-
-
-
-<sect>Copyright<p>
-
-sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
-and others. For usage of the binaries and/or sources the following conditions
-do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
-
-
+++ /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>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
+++ /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)/</tag>
- Supports one standard joystick connected to the joysticks port of the VIC20.
-
- <tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy)/</tag>
- Driver for the Protovision 4-player adapter contributed by Groepaz. See
- <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm"
- name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and
- building instructions. Up to three joysticks are supported.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the VIC20.
-
-
-<sect1>RS232 device drivers<p>
-
-No VIC1011 drivers are currently available for the VIC20.
-
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Other hints<p>
-
-<sect1>Escape code<p>
-
-For an Esc press CTRL and [ key.
-
-<sect1>Passing arguments to the program<p>
-
-Command line arguments can be passed to <tt/main()/. Since this is not
-supported by BASIC, the following syntax was chosen:
-
-<tscreen><verb>
- RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
-</verb></tscreen>
-
-<enum>
-<item>Arguments are separated by spaces.
-<item>Arguments may be quoted.
-<item>Leading and trailing spaces around an argument are ignored. Spaces within
- a quoted argument are allowed.
-<item>The first argument passed to <tt/main/ is the program name.
-<item>A maximum number of 10 arguments (including the program name) are
- supported.
-</enum>
-
-
-<sect1>Program return code<p>
-
-The program return code (low byte) is passed back to BASIC by use of the
-<tt/ST/ variable.
-
-
-<sect1>Using extended memory<p>
-
-The extended memory at $A000 may be added to the heap by using the following
-code:
-
-<tscreen><verb>
- /* Check for the existence of RAM */
- if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {<br>
- /* Add it to the heap */
- _heapadd ((void *) 0xA000, 0x2000);
- }
-</verb></tscreen>
-
-
-<sect1>Interrupts<p>
-
-The runtime for the VIC20 uses routines marked as <tt/.INTERRUPTOR/ for
-interrupt handlers. Such routines must be written as simple machine language
-subroutines and will be called automatically by the interrupt handler code
-when they are linked into a program. See the discussion of the <tt/.CONDES/
-feature in the <htmlurl url="ca65.html" name="assembler manual">.
-
-
-
-<sect>Bugs/Feedback<p>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
projects / cc65 / commitdiff